model-informationdeveloper directory

API & SDK

Documentation version 0.1.0. Schema major 1. Model Information Management Microservice is a reviewed metadata catalog—not an inference proxy.

Quickstart

model-information publishes human-reviewed model names, identifiers, capabilities, prices, and lifecycle. Your application still owns provider keys, adapters, routing, and billing.

  1. Choose hosted reads at https://market-context.org or an exported signed snapshot.
  2. There is no published npm SDK package. Use the repository SDK source after an approved checkout, or HTTP.
  3. Initialize with an app-owned fallback catalog. Never boot on an empty remote.
  4. Read GET /api/v1/manifest, then the pinned snapshot or model list.
  5. Resolve the exact offering and call your existing provider SDK.

Provider keys stay in your app; provider usage is billed by the provider.

TypeScript (repository SDK)

import { ModelCatalogClient, MemoryCache } from './sdk.js';
const client = new ModelCatalogClient({
  origin: 'https://market-context.org',
  cache: new MemoryCache(),
  fallback: appOwnedCatalog,
  trustedKeys,
});
const view = await client.load();

HTTP

GET https://market-context.org/api/v1/manifest
GET https://market-context.org/api/v1/models?maturity=stable&lifecycle=active
GET https://market-context.org/openapi.json

Python helpers are planned. Do not run an invented package install command.

Anonymous public catalog reads work today. Token-enabled onboarding uses server-side MMM_Token when that release exists. Do not put tokens in the browser. Full guide: /developer-guide (plain text).

API reference

Read-only JSON. CORS is anonymous GET/HEAD/OPTIONS on /api/v1/*. Cache-Control max-age=60 on lists; snapshots are immutable. Rate limits return 429 with Retry-After. Errors are stable codes, not stack traces.

  • GET /health/live — process up (200 even with an empty catalog)
  • GET /health and /health/ready — 200 only with a signed current artifact; otherwise 503
  • GET /api/v1/manifest — current signed manifest
  • GET /api/v1/releases — retained releases, newest first
  • GET /api/v1/releases/{release_id}/snapshot — immutable signed bytes
  • GET /api/v1/models — default stable/active; filters q, lab, input, output, maturity, lifecycle, capability; cursor pagination bound to one release
  • GET /api/v1/models/{key} and /api/v1/offerings/{key} — detail; retired records remain 200
  • GET /api/v1/changes?from_release=&to_release= — capped deterministic diff
  • GET /api/v1/schema — catalog tables + JSON Schema
  • GET /openapi.json — OpenAPI 3.1
  • POST /mcp — MCP JSON-RPC (read tools public; price updates need AAL2 admin)

Status codes used: 200, 304, 400, 404, 413, 429, 503. A new provider protocol can require an application/adapter update even when metadata refreshes without a deploy.

Snapshot format

Snapshots are canonical JSON with schema_major 1, content SHA-256, and Ed25519 signatures on the manifest. Consumers must reject unsupported majors, invalid signatures, and oversized snapshots (5,242,880 bytes).

Pricing semantics

Rates include currency, decimal amount, unit, per-quantity, usage metric, conditions, and effective interval. Unknown is not zero. Incomplete estimates must stay labeled incomplete. Catalog prices are not invoices, markups, or tax. Market Glass billing rates are never copied here.

Fallback

Read order: in-memory validated snapshot → validated persistent snapshot → explicit app/bundled fallback. Remote refresh is outside the inference path. Do not clear a working catalog on refresh failure. Retirement knowledge must not resurrect from an older fallback.

Local models

Ollama, LM Studio, and configured OpenAI-compatible discovery stay inside your environment. This site never asks for credentials and does not scan arbitrary public URLs. Localhost on a laptop is not the same as a reachable server.

Provider compatibility

Catalog coverage is separate from adapter support. Metadata can update without an app release only when the installed adapter and schema already understand the protocol.

Self-hosting

Serve signed exports without the publisher stack. Public consumers do not need an SBP or Supabase account. Operator setup is in the repository docs, not this public website.

Versions

Docs 0.1.0. Pin release_id for reproducible reads. Schema major 1 is current; unknown future majors must leave your app on last-known-good data.