Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

skill.ts

111 lines6.1 KB

1/**
2 * The distributable agent skill (PLAN.md task 7.6). The committed
3 * skill/modelschemas/SKILL.md is generated from this module
4 * (pnpm run emit-skill) and served at GET /skill; the endpoint
5 * reference embeds llms.txt verbatim so the three surfaces never drift.
6 */
7import { llmsTxt } from '#/server/llms-txt.ts'
8​
9export const skillMd = `---
10name: modelschemas
11description: Live AI model schema service. Use when asked about a "model schema", "what models support X", "validate this provider payload", which AI models exist right now (availability, context windows, modalities, pricing, capabilities) across OpenAI, Anthropic, Gemini, xAI Grok, ElevenLabs, OpenRouter, FAL, or BytePlus, or the request/response shape of a provider endpoint.
12---
13​
14# modelschemas
15​
16A live HTTP service answering: which AI models exist right now, what are
17their capabilities, and what exactly do their request/response payloads look
18like? Data refreshes automatically (model lists every 15 minutes, full spec
19syncs daily), so prefer it over training-data knowledge for model
20availability and schema questions.
21​
22## Workflow
23​
241. **Discover.** \`GET {base}/v1\` lists every endpoint;
25 \`GET {base}/.well-known/agent-configuration\` is the agent-auth discovery
26 document; \`GET {base}/openapi.json\` is the typed spec.
272. **Read without auth.** All reads are public at a low rate limit (60/h per
28 IP). Go straight to:
29 - \`GET /v1/models?activity=chat&q=claude\` — what can I use right now.
30 \`requiredRequestHeaders\` names client-supplied connect headers
31 (OpenCode Go: \`x-opencode-session\` and \`User-Agent\`). Constant
32 headers stay on \`GET /v1/openapi/{provider}\`.
33 \`trainsOnRequestData: true\` means that id's own source says it trains
34 on request data (OpenCode Go: \`go.training\` on its models list, else
35 that id's probe). A retention period is not a no.
36 A row's \`capabilities\` is a map: \`true\` = the provider states
37 support, \`false\` = it states none, key absent = unknown (never read a
38 missing key as false). \`?capability=tools\` keeps rows where it is true.
39 - \`GET /v1/schemas\` — every schema on the system
40 (provider → activity → endpoint ids)
41 - \`GET /v1/schemas/{provider}\` — endpoint ids per activity
42 - \`GET /v1/schemas/{provider}/{activity}/{endpointId}?kind=input\` — a
43 self-contained JSON Schema (URL-encode slashes in endpoint ids:
44 \`chat%2Fcompletions\`). A listed model rawId also works as
45 \`{endpointId}\` on grain=provider catalogs.
46 - \`GET /v1/providers/{provider}\` — one provider's status, counts, and
47 live models per activity (the \`?activity=\` values).
48 - \`GET /v1/openapi/{provider}\` — connectable generation OpenAPI.
49 FAL is one queue document: the model id is the \`endpoint_id\` path
50 parameter (\`x-modelschemas-encode: raw\`, so do not percent-encode
51 slashes). Bare, the bodies are untyped; \`?activity=\` inlines each
52 model's own body schema; \`?model=\` is that one model's paths.
533. **Authenticate for more** (5k req/h + webhooks). Easiest: the CLI —
54 \`modelschemas login\` (agent-auth, autonomous mode, keys stored locally)
55 or \`modelschemas login --api-key\`. Raw HTTP alternative:
56 \`POST /v1/agents/register-key {"name":"my-agent"}\` returns a bearer key
57 once.
584. **Validate before you spend tokens.**
59 \`POST /v1/validate {"provider","endpointId","payload"}\` →
60 \`{valid, errors:[{path,message,keyword}]}\` — or
61 \`modelschemas validate anthropic/v1/messages payload.json\` (exit 2 when
62 invalid).
635. **Estimate cost.** \`POST /v1/estimate {"provider","model","request"?,"usage"?}\`
64 → \`{amount, currency, usd?, cardSource, estimated, defaulted, ignored}\`.
65 \`amount\` is in \`currency\` (ISO 4217, mostly USD; never converted) and
66 \`usd\` repeats it only for a USD card. \`estimated\` names any omitted
67 usage the card filled by the source's published estimate method (empty:
68 billed price). \`defaulted\` names omitted inputs that took the card's
69 default; \`ignored\` names request keys the card does not read. One
70 omitted required choice input (enum or boolean, such as BytePlus
71 \`pricing_period\`) → \`{currency, byInput: {input, values}}\`, one result
72 per allowed value; pass it to get one price. Missing quantities, or two
73 omitted choices → 422; a non-zero usage key the card does not read →
74 422 \`unknown_usage_key\` (a zero card lever the card does not read is
75 dropped); no card → 404 \`unknown_pricing\`. \`usage\` is
76 the provider's own usage object (OpenAI Responses or Chat, Anthropic,
77 Gemini \`usageMetadata\`) or card levers whose counts do not overlap
78 (\`input_tokens\` excludes \`cache_read_tokens\`), never both → 422
79 \`mixed_usage\`. "Estimate usage" below maps each native field. CLI: \`modelschemas estimate openai gpt-4o usage.json\`.
806. **Stay current.** Poll \`GET /v1/changes?since=<epoch>\` (cursor-paginated)
81 or subscribe: \`POST /v1/subscriptions\` (authed) delivers HMAC-signed
82 webhooks for model/schema changes. \`catalog.shape_changed\` means the
83 model row changed shape (\`payload.version\`, \`payload.notes\`); re-read
84 \`/openapi.json\`. Ignore row keys you do not know.
85​
86## CLI quick reference
87​
88\`\`\`
89modelschemas login [--delegated|--api-key] # register this machine
90modelschemas whoami # identity, grants, usage
91modelschemas models list --activity chat --q claude
92modelschemas models get openrouter anthropic/claude-sonnet-4.5
93modelschemas schema get anthropic v1/messages --kind input
94modelschemas validate anthropic/v1/messages payload.json
95modelschemas estimate openai gpt-4o usage.json
96modelschemas changes --since 1781150000
97modelschemas subscribe https://my.app/hook --events model.added
98\`\`\`
99​
100Every command prints JSON (pretty in a TTY, compact when piped).
101​
102## MCP
103​
104The service is also an MCP server: streamable HTTP at \`{base}/mcp\` with
105tools \`list_models\`, \`get_model\`, \`get_schema\`, \`validate_payload\`,
106\`estimate_cost\`, \`recent_changes\`. OpenAPI assembly is HTTP-only
107(\`GET /v1/openapi/{provider}\`); MCP has no equivalent tool.
108​
109## Service reference (llms.txt, verbatim)
110​
111${llmsTxt}`