# llmgw Agent Guide

`llmgw` is the Sellpath LLM gateway. Use it for model requests, billing, access control, and tenant-scoped routing.

## Quick Rules

- Use `Authorization: Bearer <api_key>` on all requests.
- Use `/v1/chat/completions` or `/v1/responses` for inference traffic.
- Use `/admin/*` only for platform bootstrap and tenant setup.
- Keep request payloads unique and set `store: false` when you want to avoid cache hits during billing tests.
- For bootstrap, create resources in this order: organization, project, team, service account, user, admin authority, agent, key, model, model group, budget.

## Common Base URLs

- API root: `http://llmgw:8000`
- OpenAPI JSON: `http://llmgw:8000/openapi.json`
- OpenAPI YAML: `http://llmgw:8000/openapi.yaml`
- Human guide: `http://llmgw:8000/docs`

## Full Bootstrap Flow

This is the recommended end-to-end flow for provisioning a tenant in `llmgw`.

### 1. Create an organization

Use the platform master key.

```bash
curl -X POST http://llmgw:8000/admin/orgs \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme"}'
```

Endpoint: `POST /admin/orgs`

### 2. Create a project

```bash
curl -X POST http://llmgw:8000/admin/projects \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_uuid>","name":"Acme Project"}'
```

Endpoint: `POST /admin/projects`

### 3. Create a team

Teams belong to a project.

```bash
curl -X POST http://llmgw:8000/admin/teams \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_uuid>","name":"Sales"}'
```

Endpoint: `POST /admin/teams`

### 4. Create a service account for the project

Service accounts are project-bound non-human identities. They need either a `user_id` or `agent_id`.

```bash
curl -X POST http://llmgw:8000/admin/service-accounts \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_uuid>","name":"Acme SA","user_id":"<user_uuid>"}'
```

Endpoint: `POST /admin/service-accounts`

### 5. Create a user

```bash
curl -X POST http://llmgw:8000/admin/users \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_uuid>","email":"user@example.com","team_id":"<team_uuid>"}'
```

Endpoint: `POST /admin/users`

### 6. Assign admin authority to the user

There is not a separate "set role" endpoint in the current admin CRUD surface. In llmgw, org-admin authority is granted when you create a user key with `org_admin: true`.

```bash
curl -X POST http://llmgw:8000/admin/keys \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_uuid>","user_id":"<user_uuid>","org_admin":true}'
```

Practical rule:
- use the master key to provision the org-admin credential
- bind the credential to a single organization through the project
- treat that credential as the org-admin credential for the tenant

Reference docs:
- [`docs/governance/org-admin-rbac.md`](../docs/governance/org-admin-rbac.md)
- [`docs/api/admin.md`](api/admin.md)

### 7. Add an agent

```bash
curl -X POST http://llmgw:8000/admin/agents \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_uuid>","team_id":"<team_uuid>","owner_user_id":"<user_uuid>","name":"Sales Agent"}'
```

Endpoint: `POST /admin/agents`

### 8. Create credentials for the service account, user, and agent

Use `POST /admin/keys` for human user or agent keys. Use `POST /admin/service-accounts` for service-account credentials.

```bash
curl -X POST http://llmgw:8000/admin/keys \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id":"<project_uuid>",
    "name":"User Key",
    "user_id":"<user_uuid>",
    "org_admin": true,
    "max_budget": 50,
    "duration":"365d"
  }'
```

```bash
curl -X POST http://llmgw:8000/admin/service-accounts \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_uuid>","name":"Service Account","user_id":"<user_uuid>"}'
```

Notes:
- a key can be attached to a `user_id` or `agent_id`
- set `org_admin: true` only for a user key that should manage the tenant
- use the legacy `POST /key/generate` route when you need `models`, `access_group_ids`, `budget_id`, `auto_rotate`, or `rotation_interval`
- set `max_budget` and `duration` when you want bounded bootstrap keys

Endpoints:
- `POST /admin/keys`
- `POST /admin/service-accounts`

### 9. Add a model and a model group

```bash
curl -X POST http://llmgw:8000/admin/models \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":"openai",
    "provider_model_id":"gpt-4o",
    "friendly_name":"gpt-4o",
    "owner_org_id":"<org_uuid>",
    "model_info":{"class":"fast"}
  }'
```

```bash
curl -X POST http://llmgw:8000/admin/model-groups \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id":"<project_uuid>",
    "name":"default-model-group",
    "model_ids":["<model_uuid>"]
  }'
```

Endpoints:
- `POST /admin/models`
- `POST /admin/model-groups`

### 10. Assign budgets

Budgets can be created at the root legacy compatibility route and then queried by budget ID.

```bash
curl -X POST http://llmgw:8000/budget/new \
  -H "Authorization: Bearer $LLMGW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_budget":50,"metadata":{"tenant":"Acme"}}'
```

Then inspect the budget or scope it through the resource you created it for.

Endpoints:
- `POST /budget/new`
- `GET /budget/info`

### 11. Monitor spending

Monitor both the API-side summary and the durable database records.

Useful endpoints:
- `GET /budget/info?budget_id=<budget_uuid>`
- `GET /reporting/summary?organization_budget_id=<budget_uuid>`
- `GET /project/info?project_id=<project_uuid>`
- `GET /user/info?user_id=<user_uuid>`
- `GET /team/info?team_id=<team_uuid>`
- `GET /service-account/info?service_account_id=<service_account_uuid>`
- `GET /agent/daily/activity?agent_id=<agent_uuid>`

Useful database tables:
- `spend_logs`
- `budgets`
- `admin_audit_logs`

### 12. Make inference calls

Use tenant-scoped keys, not the master key.

```bash
curl -X POST http://llmgw:8000/v1/responses \
  -H "Authorization: Bearer $TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","input":"Hello","store":false}'
```

## What Agents Can Do

Agents can use this gateway to:

- create or inspect tenant resources with the master key during bootstrap
- mint tenant-scoped keys for users, agents, and service accounts
- choose a model directly or route through a model group
- limit spend with budgets and access groups
- inspect spend and budget state for debugging or reporting
- make normal inference calls with tenant keys

## Minimal Endpoint Map

- Org management: `GET/POST /admin/orgs`, `GET/PATCH/DELETE /admin/orgs/:id`
- Project management: `GET/POST /admin/projects`, `GET/PATCH/DELETE /admin/projects/:id`
- Team management: `GET/POST /admin/teams`, `GET/PATCH/DELETE /admin/teams/:id`
- User management: `GET/POST /admin/users`, `GET/PATCH/DELETE /admin/users/:id`
- Agent management: `GET/POST /admin/agents`, `GET/PATCH/DELETE /admin/agents/:id`
- Service accounts: `GET/POST /admin/service-accounts`, `GET/PATCH/DELETE /admin/service-accounts/:id`
- Keys: `GET/POST /admin/keys`, `GET/PATCH/DELETE /admin/keys/:id`
- Models: `GET/POST /admin/models`, `GET/PATCH/DELETE /admin/models/:id`
- Model groups: `GET/POST /admin/model-groups`, `GET/PATCH/DELETE /admin/model-groups/:id`
- Budgets: `GET/POST /budget/*`
- Access groups: `POST /access_group/new`
- Legacy key generation: `POST /key/generate`

## Troubleshooting

- `404` on `/projects` usually means you should use `/admin/projects`.
- `404` on `/organization/new` means you are using the legacy compat route instead of the real admin route.
- `500` on service-account creation usually means the project UUID does not exist in llmgw or the user/agent binding is missing.
- If billing tests do not block, make sure the payload is not being cached and the request is not using the master-key bypass.
- If you need the route catalog in machine-readable form, open `/openapi.json`.