# Game Theory Layer for AI Agents

This API exposes equilibrium-aware primitives so AI agents can compose
game-theoretic strategies without re-deriving the math. LLMs are
structurally bad at multi-round, opponent-modeling problems; we are not.

## Tier 1 — Negotiation
- POST /v1/negotiation/sell/next_offer  [free]
  Sell-side recommender. `pareto_knob` ∈ [0, 1] interpolates between
  deal-rate-max (0) and H2H-margin-max (1). Empirical anchor: SNHP
  rank #1/21 in our NegMAS round-robin tournament; beats Aspiration
  (p=0.011), Split-the-Diff (p=0.014), Fair Demand (p<0.001).
- POST /v1/negotiation/buy/next_offer  [free]
  Buy-side recommender with a defense bundle (Schelling commitment,
  anchor-attack detection). Pass `market_prior` to enable anchor
  detection.
- POST /v1/negotiation/detect_anchor_attack  [free]
  Z-score the seller's opening against a market prior; recommends
  ignore / counter_with_market / walk_away.
- POST /v1/negotiation/declare_first_strike  [free]
  Cryptographic commit to a buyer reservation. Returns an EdDSA-signed
  attestation JWT the buyer shows the seller. Mechanism-design fix for
  the structural buy-side disadvantage (going second in SAO).
- POST /v1/negotiation/reveal_first_strike  [free]
  Reveal the inputs to a previous commitment to obtain the binding offer.
- GET  /v1/keys/trust_anchor  [free]
  Public key for verifying first-strike attestations.

## Tier 2 — Auctions
- POST /v1/auction/bidder/optimal_bid  [free]
  Optimal bid for first-price (BNE), Vickrey (truthful), English ascending.
- POST /v1/auction/seller/optimal_reserve  [free]
  Myerson reserve from virtual-value-zero.
- POST /v1/auction/seller/format_recommendation  [free]
  Picks a format given weights {revenue, speed, transparency}.
- POST /v1/auction/simulate  [free]
  Monte Carlo revenue + efficiency, any of the three formats.

## Tier 3 — Mechanism Design (marketplace operators)
- POST /v1/mechanism/gale_shapley  [free]
  Stable matching via deferred acceptance, with capacities and a
  blocking-pair sanity check.
- POST /v1/mechanism/optimal_auction_design  [free]
  Myerson revenue-optimal mechanism for asymmetric IPV. Per-bidder
  reserves; collapses to second-price-with-reserve under symmetric IPV.
- POST /v1/mechanism/posted_price_optimal  [free]
  Gallego-van Ryzin posted price (static p* + dynamic schedule).

## Cost model
All endpoints are FREE today (math only — NumPy / SciPy, ~50ms p99).
Rate limit: 600/min per key. We do not host or resell LLM calls; if your
agent needs natural-language drafting, do that with your own LLM provider
(see "Drafting messages client-side" below).

## Onboarding (no human in the loop)
- POST /v1/keys
    body: {agent_id, contact_email, intended_use_summary,
           telemetry_consent: bool = false}
    -> {api_key: "gt_*", telemetry_consent, ...}

## Telemetry (opt-in, off by default)
We collect aggregate prior-corpus data ONLY when you opt in. The corpus
warm-starts new agents in the same vertical (e.g. Bayesian priors for
buyer WTP). Default behavior collects nothing.

How to opt in:
1. Pass `telemetry_consent: true` at /v1/keys issuance. Account-level
   consent is set ONCE at issuance and immutable thereafter — to revoke,
   call /v1/telemetry/delete and stop passing share_outcome on future calls.
2. On each recommendation request, pass `share_outcome: true` AND
   `vertical: "<one of the allowlisted enum values>"`. Both gates must
   be true; either one false → no row is written.
3. The successful response carries `X-GT-Recommendation-Id: rec_*`.
   Store it; you'll need it to attach an outcome.
4. After your deal closes (or doesn't), POST /v1/telemetry/report_outcome
   with `{recommendation_id, deal_closed, my_utility, opponent_utility}`.
   MUST be called within the same ISO week as the recommendation — the
   per-week agent-hash bound caps outcome reporting at ~7 days.

What we store:
- An HMAC(pepper, api_key || iso_week) hash of your key, truncated to
  128 bits, base64url. Per-week rotation eliminates cross-time linkability;
  the pepper is a server secret and never leaves the box. Hashes are NOT
  reversible to your key and NOT joinable across weeks.
- Numeric features quantized to a 0.02 grid (50 buckets across [0,1]) to
  shed fingerprint entropy.
- Lists capped at 16 elements at storage; free-text rationale is stripped.
- The vertical you self-declared (allowlisted enum, no free text).

What we do NOT store:
- Wall-clock timestamps (only the hour bucket).
- Your raw api_key (only the per-week hash).
- Free-text fields of any kind.
- IP addresses, user agents, or other request metadata.

GDPR (apply regardless of EU residence):
- DELETE /v1/telemetry/delete  (Article 17: erasure)
    -> {rows_deleted: N}
  Sweeps the last 78 weeks of week-hashes.
- GET /v1/telemetry/export  (Article 15: access)
    -> {rows: [...]}
  Returns every row tied to any of your week-hashes within the same window.

Allowlisted verticals:
  ad_inventory, saas_procurement, cloud_compute, freight_logistics,
  media_licensing, m_and_a_buyside, m_and_a_sellside, real_estate,
  energy_trading, professional_services, marketplace_b2b, other

## Drafting messages client-side (BYOK pattern)
We deliberately do not call LLMs server-side; you bring your own. The
recommended drafting prompt for negotiation reply emails:

  "You are a professional negotiator drafting a brief 3-sentence reply
   email. Tone: <professional|friendly|firm>.
   Their last message: <their email>
   Your constraints: <constraints text>
   You MUST use these exact numbers: <output of next_offer>.
   Draft the reply email. Return ONLY the email body, no preamble."

Hard rule (BATNA guard): refuse to draft if `numbers.recommended_offer`
is below your stated reservation. We enforce this server-side in the
math endpoints; replicate it in your draft-time code.

## Composition examples
1. Buy-side defense → auction:
   detect_anchor_attack → declare_first_strike → seller proposes auction →
   auction.bidder.optimal_bid (Vickrey: bid truthfully).
2. Marketplace operator: mechanism.optimal_auction_design (operator)
   + auction.bidder.optimal_bid (each bidder), same Myerson math, two
   perspectives.

## Honest limitations
- Buy-side: structurally disadvantaged in alternating-offers SAO; best
  achievable margin -0.025 even at the Pareto frontier. Use
  declare_first_strike to recover symmetry.
- Combinatorial / multi-unit auctions, VCG payments: out of scope for v1.
- LLM calls: BYOK (we don't host them).
- Auto-execution: never. We return recommendations; your environment
  delivers offers / places bids. No escrow, no settlement.

## Discovery
- GET /v1/catalog — JSON list of all tools, cost class, stability
- GET /openapi.json — OpenAPI 3.1 spec
- GET /docs — Swagger UI (for human inspection)
- GET /llms.txt — this file