{
  "openapi": "3.1.0",
  "info": {
    "title": "The AI Bench — Planner API",
    "description": "Deterministic local-AI setup recommendations. Given hardware + use case + priority, returns a verdict, top model picks with editorial reasoning, runner + quantization advice, expected speed band, workflow notes, and watchouts. Same logic that powers the web UI at theaibench.ai — verified quarterly. Free to use and cite with attribution.",
    "version": "v1",
    "contact": {
      "name": "The AI Bench",
      "url": "https://theaibench.ai/"
    },
    "license": {
      "name": "Free to cite with attribution",
      "url": "https://theaibench.ai/api/"
    }
  },
  "servers": [
    { "url": "https://theaibench.ai", "description": "Production" }
  ],
  "paths": {
    "/api/v1/plan": {
      "get": {
        "summary": "Get a local-AI setup recommendation",
        "description": "All query parameters are optional; missing values fall back to sensible defaults (Windows · 16 GB VRAM · 32 GB RAM · coding · speed priority · NVIDIA).",
        "operationId": "getPlan",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "description": "Whether the user already owns hardware (`current`) or is planning a new build (`new`).",
            "schema": { "type": "string", "enum": ["current", "new"], "default": "current" }
          },
          {
            "name": "platform",
            "in": "query",
            "description": "Operating platform.",
            "schema": { "type": "string", "enum": ["windows", "windows-laptop", "mac", "linux"], "default": "windows" }
          },
          {
            "name": "vram",
            "in": "query",
            "description": "Dedicated GPU VRAM (PC only). Ignored for Mac and when gpu_family=cpu.",
            "schema": { "type": "string", "enum": ["none", "8", "12", "16", "24", "32plus"], "default": "16" }
          },
          {
            "name": "memory",
            "in": "query",
            "description": "Mac unified memory in GB. Only used when platform=mac.",
            "schema": { "type": "string", "enum": ["16", "24", "32", "64", "96plus"], "default": "32" }
          },
          {
            "name": "ram",
            "in": "query",
            "description": "System RAM (PC only).",
            "schema": { "type": "string", "enum": ["16", "32", "64", "128plus"], "default": "32" }
          },
          {
            "name": "budget",
            "in": "query",
            "description": "USD budget band. Only used when mode=new.",
            "schema": { "type": "string", "enum": ["under1500", "1500to3000", "3000to6000", "6000plus"], "default": "1500to3000" }
          },
          {
            "name": "use_case",
            "in": "query",
            "description": "What the user plans to do.",
            "schema": { "type": "string", "enum": ["coding", "chat", "docs", "image", "agents", "voice"], "default": "coding" }
          },
          {
            "name": "priority",
            "in": "query",
            "description": "What matters most to the user.",
            "schema": { "type": "string", "enum": ["privacy", "speed", "cost"], "default": "speed" }
          },
          {
            "name": "gpu_family",
            "in": "query",
            "description": "GPU family on PC. Ignored for Mac. `cpu` means CPU-only inference (no dedicated GPU).",
            "schema": { "type": "string", "enum": ["nvidia", "amd", "cpu"], "default": "nvidia" }
          }
        ],
        "responses": {
          "200": {
            "description": "A recommendation matching the inputs. Returned when the client sends Accept: application/json or */*.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PlanResponse" }
              }
            }
          },
          "303": {
            "description": "Redirect to the web UI with the planner pre-filled. Returned only when the client sends Accept: text/html (typical browser). Add ?format=json to force JSON from a browser.",
            "headers": {
              "Location": {
                "schema": { "type": "string", "format": "uri" },
                "description": "URL of the main site with the planner state encoded in the hash fragment."
              }
            }
          },
          "400": {
            "description": "One or more parameters are invalid.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidationError" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pick": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Model name as commonly spelled in the community." },
          "why": { "type": "string", "description": "Editorial reasoning — 1 sentence, web-verified quarterly." }
        },
        "required": ["name", "why"]
      },
      "Runner": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "note": { "type": "string" }
        },
        "required": ["name", "note"]
      },
      "PlanResponse": {
        "type": "object",
        "properties": {
          "inputs": {
            "type": "object",
            "description": "Echo of the resolved inputs (including any defaults that were applied)."
          },
          "result": {
            "type": "object",
            "properties": {
              "verdict": { "type": "string", "enum": ["Strong", "Comfortable", "Workable", "Cloud-leaning"] },
              "tier": { "type": "number", "description": "Numeric tier score (0–7 range; 2 decimal places)." },
              "band": { "type": "string", "enum": ["top", "high", "mid", "low"] },
              "title": { "type": "string", "description": "One-line headline matching the verdict + use case." },
              "summary": { "type": "string", "description": "1–3 sentences summarizing the recommendation." },
              "picks": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Pick" },
                "description": "3 top-picked models for the resolved tier band and use case."
              },
              "runner": { "$ref": "#/components/schemas/Runner" },
              "quantization": { "type": "string" },
              "expected_speed": { "type": "string", "description": "Plain-English tok/s band for the user's hardware class." },
              "workflow": { "type": "array", "items": { "type": "string" } },
              "watchouts": { "type": "array", "items": { "type": "string" } },
              "note": { "type": "string", "description": "Local-vs-cloud editorial summary." }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "version": { "type": "string" },
              "dated": { "type": "string", "description": "Pricing + model snapshot date." },
              "source": { "type": "string", "format": "uri" },
              "docs": { "type": "string", "format": "uri" },
              "license": { "type": "string" }
            }
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "enum": ["validation_failed"] },
          "messages": { "type": "array", "items": { "type": "string" } },
          "docs": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}