# Model Gateway

Model discovery, cataloging, and **agent→provider contracting** harness.
**Beckn Protocol v2-aligned** (catalog + contract layer) and **MCP-native**.

Scope (v1): catalog + discovery + contract lifecycle over your generative-model
providers (OpenRouter, Google Vertex, Runway, …). Transaction-sandbox / live-network
participation (DeDi broadcast, signed callbacks) is a deferred phase.

## What it answers for an agent
- "What models can generate **video** (or image/audio/text)?" — modality search
- "What does model X cost, what are its terms?" — pricing + ToU
- "Block this model for my use, track my usage, and let me rate it / get support" — contract lifecycle

## Quick start
```bash
npm install
npm run migrate
npm run seed        # seeds OpenRouter, Google Vertex, Runway + representative models
npm start           # REST on :8090  (PORT to override)
npm run mcp         # MCP stdio server (tools for agents)
npm test            # 25/25 E2E (catalog + contract lifecycle + MCP)
```

## REST API (Beckn verb → endpoint)
| Beckn v2 | Endpoint | Purpose |
|---|---|---|
| search | `GET /api/search?out=video&cap=video-generation` | search models by modality/capability/provider/price |
| — | `GET /api/models?any=video&io=output` | models supporting modality(ies) |
| — | `GET /api/models/:id` | model detail (Beckn Item: pricing, capabilities, ToU) |
| — | `GET /api/providers` / `GET /api/providers/:id/catalog` | providers + Beckn catalog |
| select | `POST /api/contracts/quote` | quote a contract |
| init | `POST /api/contracts` | create contract (agent blocks a model) |
| — | `POST /api/contracts/:id/block` | activate/block for use |
| status | `GET /api/contracts/:id` | contract + Beckn order view |
| track | `POST /api/contracts/:id/usage` / `GET .../usage` | record/aggregate usage |
| update | `PATCH /api/contracts/:id` | update quota/terms/notes |
| cancel | `POST /api/contracts/:id/cancel` | cancel |
| rating | `POST /api/contracts/:id/rate` | rate the model |
| support | `POST /api/contracts/:id/support` | request support |

## MCP tools (stdio)
`list_providers, list_models, models_by_modality, get_model, get_catalog, quote,
create_contract, block_model, update_contract, cancel_contract, track_usage,
contract_status, rate_model, request_support`

Add to an MCP client:
```json
{ "mcpServers": { "model-gateway": { "command": "node", "args": ["/path/to/src/mcp/server.js"], "env": { "DB_PATH": "/path/to/model-gateway.sqlite" } } } }
```

## Beckn v2 mapping
See `docs/ARCHITECTURE.md`. Provider→BPP, Model→Item, Catalog→Beckn Catalog,
Contract→Order/Fulfillment, Rating/Support/Track→respective Beckn actions.
Payloads are Beckn-shaped so they validate against v2 catalog/contract semantics.

## Contract state machine
`draft → quoted → active → (paused) → completed | cancelled | failed` (+ support overlay).