# Plan: API pública multi-tenant + monetización por uso

> **Estado: PLANIFICADO, SIN IMPLEMENTAR.** (2026-06-11)
> Este documento existe para retomar el trabajo en una sesión futura sin re-derivar
> el diseño. Todo lo de abajo está decidido tras leer el código actual; ningún
> fichero nuevo se ha escrito aún ni se ha tocado código existente.

---

## 1. Contexto y decisión de producto

Decisión tomada con Juan (sesión 2026-06-11):

- **Forja sigue en la dirección A**: plano de control de gobernanza en runtime
  (guardrails + HITL + auditoría delante del modelo). **No** se hornea seguridad
  en pesos (no alignment training); el módulo `training/` queda como está
  (fine-tuning de tarea, stub Azure ML).
- **Giro de producto**: de consola interna a **producto consumible por terceros**.
  Empresas cliente (*tenants*) consumen por una **API pública `/v1`** un catálogo
  de **agentes gobernados** = modelo LLM + esquema de entrada/salida + guardrails
  + HITL + auditoría. Ese empaquetado es nuestro valor añadido sobre el LLM crudo.
- **Monetización por uso**: cada invocación a la API se mide y tarifica según el
  **plan** del tenant (fee mensual + invocaciones incluidas + precio por
  invocación extra + precio por tokens).
- **Genericidad**: el core ya es genérico (los validadores los elige la política;
  el contenido telco es solo el agente de ejemplo). La genericidad se materializa
  en la plataforma multi-tenant, **no** añadiendo más agentes de ejemplo.

## 2. Arquitectura de la solución

Mismo proceso FastAPI (:8000), tercera cara además de UI y `/api`:

```
UI HTMX (operador)  │  /api (admin interno, sin auth)  │  /v1 (público, API key)
```

Dos registries nuevos con el patrón existente (`registry/yaml_store.py`,
YAML versionado): `tenants/` y `plans/`. Un log nuevo append-only:
`data/usage.jsonl` (eventos de consumo tarificados, estilo CDR).

### Decisiones clave (con su porqué)

| Decisión | Razón |
|---|---|
| API keys `fk_<hex>`; en disco solo SHA-256 (`api_key_hash`); comparación con `hmac.compare_digest` | No guardar secretos en YAML; la clave se muestra una sola vez al crear el tenant. |
| Auth con `HTTPBearer(auto_error=False)` de FastAPI | Botón "Authorize" gratis en `/docs` — la doc OpenAPI es el escaparate del producto. |
| `/v1` ejecuta **siempre la versión activa** del agente (sin parámetro `version`) | La promesa de gobernanza: el cliente consume lo promocionado vía draft→active. |
| Eventos de uso **tarificados al escribirse** (precios congelados en el evento) | Patrón CDR/billing: cambiar tarifas no reescribe el histórico; disputas auditables. |
| Fee por invocación se exime mientras `n_mes < included_invocations`; tokens se facturan siempre | Permite tarificar en el momento del evento (solo necesita contar el mes en curso). |
| `hard_limit: true` en el plan → HTTP 429 al agotar cuota mensual | Sandbox gratuito con corte duro; planes de pago pasan a overage. |
| Propiedad de ejecuciones vía `execution_index.json` (campo `tenant` opcional en cada entrada) | Cero cambios en el dominio `AgentExecution`; el índice ya sobrevive a reinicios y nunca se poda. |
| Capa pública **delega en los handlers internos** de `api/executions.py` | Reuso total: público = auth + ownership + metering + delegación. Sin lógica duplicada. |
| `GET /v1/...` de otro tenant → **404** (no 403) | No revelar existencia de ejecuciones ajenas. |
| Aprobar/rechazar HITL vía `/v1` lo hace **el operador del cliente** | El HITL es parte del producto vendible. El resume no llama al LLM → no genera coste. |
| Dinero en `float` con `round(x, 6)` | Aceptable para MVP; `Decimal`/Stripe en roadmap. |

## 3. Ficheros nuevos (diseño exacto)

### 3.1 Dominio

**`core/src/forja_core/domain/plan.py`** — `PlanVersionMeta = VersionMeta` (alias, como el resto) y:

```python
class PlanDefinition(BaseModel):
    name: str; version: str; owner: str; purpose: str
    state: Literal["active", "deprecated"] = "active"
    monthly_fee_eur: float = Field(default=0.0, ge=0)
    included_invocations: int = Field(default=0, ge=0)
    price_per_invocation_eur: float = Field(default=0.0, ge=0)   # solo overage
    price_per_1k_tokens_in_eur: float = Field(default=0.0, ge=0)
    price_per_1k_tokens_out_eur: float = Field(default=0.0, ge=0)
    hard_limit: bool = False        # True: 429 al agotar included (sandbox)
    updated_at: datetime
```

**`core/src/forja_core/domain/tenant.py`** — `TenantVersionMeta = VersionMeta` y:

```python
class TenantDefinition(BaseModel):
    name: str; version: str; owner: str; purpose: str
    state: Literal["active", "suspended"] = "active"   # suspended → 403 en auth
    plan: str
    api_key_hash: str               # sha256 hex; nunca la clave en claro
    contact_email: str
    allowed_agents: list[str] = []  # vacío = todos los agentes activos
    updated_at: datetime
```

**`core/src/forja_core/domain/usage.py`**:

```python
class UsageEvent(BaseModel):        # una invocación facturable (precios congelados)
    trace_id: UUID; tenant: str; agent_name: str; agent_version: str
    plan: str; status: ExecutionStatus
    tokens_in: int = 0; tokens_out: int = 0
    invocation_fee_eur: float = 0.0; tokens_fee_eur: float = 0.0; cost_eur: float = 0.0
    created_at: datetime

class UsageSummary(BaseModel):      # "la factura" del mes
    tenant: str; plan: str; period: str          # period = "YYYY-MM"
    n_invocations: int; tokens_in: int; tokens_out: int
    included_invocations: int
    usage_cost_eur: float; monthly_fee_eur: float; total_eur: float
```

### 3.2 Registries

**`registry/plan_store.py`** — `FileSystemPlanStore(VersionedYamlStore[PlanDefinition])`,
`kind="plan"`, solo lectura: `list_plans()`, `get_plan(name, version=None)`,
`list_versions(name)`. Calcado de `dataset_store.py`.

**`registry/tenant_store.py`** — `FileSystemTenantStore(VersionedYamlStore[TenantDefinition])`,
`kind="tenant"`, lectura + escritura:
`list_tenants()`, `get_tenant()`, `exists(name) -> bool` (mira `index.yaml`),
`create_tenant(body, message, author)` → `self._upsert_version(body.name, body,
body.version, message, author, set_active=True)`.

**`registry/factory.py`** — añadir `build_tenant_store(settings)` y
`build_plan_store(settings)`.

### 3.3 Config y deps

**`config.py`** — bajo "Persistencia" añadir:
`tenants_dir: Path = Field(default=Path("./tenants"))` y
`plans_dir: Path = Field(default=Path("./plans"))`.

**`api/deps.py`** — `get_tenant_store` / `get_plan_store` con `@lru_cache(maxsize=1)`
+ aliases `TenantStoreDep` / `PlanStoreDep`. (Los tests deben añadirlos a sus
`cache_clear()`.)

### 3.4 Auth — `api/auth.py`

```python
API_KEY_PREFIX = "fk_"
def generate_api_key() -> str: ...      # fk_ + secrets.token_hex(20)
def hash_api_key(key: str) -> str: ...  # hashlib.sha256(...).hexdigest()

_bearer = HTTPBearer(auto_error=False)

def get_current_tenant(credentials, tenants: TenantStoreDep) -> TenantDefinition:
    # sin header → 401 (headers={"WWW-Authenticate": "Bearer"})
    # itera list_tenants() comparando hashes con hmac.compare_digest
    # match con state != "active" → 403 "tenant is suspended"
    # sin match → 401 "invalid API key"

TenantDep = Annotated[TenantDefinition, Depends(get_current_tenant)]
```

### 3.5 Metering — `api/metering.py`

(Convención hermana de `api/persistence.py`; log `data/usage.jsonl`.)

```python
def current_period(now: datetime | None = None) -> str          # "YYYY-MM" en UTC
def append_usage_event(data_dir, event) -> None                 # JSONL append
def read_usage_events(data_dir, tenant=None, period=None) -> list[UsageEvent]
def tokens_from_execution(execution) -> tuple[int, int]
    # suma detail["tokens_in"/"tokens_out"] de los DecisionStep step=="llm_reason"
    # (los pone build_node_llm_reason en runtime/nodes.py); cast int(... or 0) por mypy
def rate_invocation(plan, prior_invocations, tokens_in, tokens_out) -> tuple[float, float]
    # inv_fee = 0 si prior < plan.included_invocations, si no price_per_invocation_eur
    # tok_fee = in/1000*p_in + out/1000*p_out ; round(x, 6)
def build_usage_event(execution, tenant, plan, prior_invocations) -> UsageEvent
def summarize_usage(tenant, plan, period, events) -> UsageSummary
    # usage_cost = Σ cost_eur ; total = monthly_fee + usage_cost
```

### 3.6 Admin — `api/tenants.py`

Dos routers (patrón de `executions.py`): `router` → `/api/tenants`,
`usage_router` → `/api/usage`.

- `POST /api/tenants` — `CreateTenantRequest{name (pattern ^[a-z0-9_]+$ — es nombre
  de directorio), purpose="", plan, contact_email, owner="dashboard",
  allowed_agents=[]}`. Valida plan existe (404) y nombre no existe (409). Genera
  clave, guarda hash, crea v1. Respuesta `TenantCreated` = `TenantPublic` +
  `api_key` en claro (única vez). 201.
- `GET /api/tenants` → `list[TenantPublic]` (sin hash: name, state, plan, purpose,
  contact_email, allowed_agents, updated_at).
- `GET /api/tenants/{name}` → `TenantPublic` | 404.
- `GET /api/usage?period=YYYY-MM` (admin, default mes actual) →
  `list[UsageSummary]` de todos los tenants — la vista de ingresos.

### 3.7 API pública — `api/public.py` (prefix `/v1`, tags=["public"])

Todos los endpoints llevan `TenantDep`. Modelos de respuesta:

- `PricingInfo` — eco de los precios del plan del tenant.
- `CatalogItem` — name, purpose, input_label, input_placeholder, output_schema,
  guardrail_policies (transparencia: la gobernanza se enseña, es el producto),
  model (`agent.llm.model`), version, pricing.
- `PublicInvokeRequest{input: str}` (sin `version`).
- `PublicInvokeResponse{execution: AgentExecution, usage: UsageEvent}`.

Endpoints y mecánica:

| Endpoint | Mecánica |
|---|---|
| `GET /v1/catalog` | agentes `state=="active"` ∧ (allowed_agents vacío ∨ name ∈ allowed) |
| `POST /v1/agents/{name}/invoke` | agente permitido o 404 → plan del tenant (FileNotFoundError → 500 "tenant plan misconfigured") → `events = read_usage_events(tenant, mes)` → si `plan.hard_limit` y `len(events) >= included` → **429** → **delega** en `invoke_agent(...)` interno → `_record_execution(..., tenant=t.name)` (re-graba la entrada del índice con tenant) → `build_usage_event(prior=len(events))` + append → respuesta |
| `GET /v1/executions` | `collect_execution_summaries(...)` filtrado por trace_ids propios (entradas del índice con `tenant == t.name`) |
| `GET /v1/executions/{trace_id}` | ownership o 404 → delega en `get_execution(...)` |
| `POST /v1/executions/{trace_id}/approve` / `reject` | ownership o 404 → delega en `approve_execution`/`reject_execution` (reusa `ApproveRequest`/`RejectRequest`) |
| `GET /v1/usage?period=` | `UsageSummary` del propio tenant (default mes actual) |

### 3.8 Cambios en ficheros existentes

- **`api/executions.py`**: `_record_execution(..., tenant: str | None = None)` —
  si viene, añade `"tenant"` al dict de la entrada del índice. Llamadas existentes
  intactas. (Entradas antiguas sin tenant → `meta.get("tenant")`.)
- **`main.py`**: montar `tenants.router` (`/api/tenants`), `tenants.usage_router`
  (`/api/usage`), `public.router` (`/v1`). Retocar `description` de FastAPI
  (mencionar la API pública).
- **`docker-compose.yml`**: env `TENANTS_DIR=/app/tenants`, `PLANS_DIR=/app/plans`;
  volúmenes `./tenants:/app/tenants:rw` (la API crea tenants) y
  `./plans:/app/plans:ro`.
- **`.env.example`**: `TENANTS_DIR=./tenants`, `PLANS_DIR=./plans`.
- **`tests/integration/conftest.py`**: env `TENANTS_DIR=$tmp/tenants` (¡tmp!,
  los tests crean tenants), `PLANS_DIR=<repo>/plans`; añadir
  `deps.get_tenant_store` y `deps.get_plan_store` a los `cache_clear()`.

## 4. Seeds y fixtures

Los hashes de los `index.yaml` existentes son informales ("feedface", "pending")
→ se pueden escribir seeds a mano sin script.

- **`plans/free`**: 0 €/mes, 100 inv incluidas, todo a 0 €, `hard_limit: true` (sandbox).
- **`plans/builder`**: 49 €/mes, 1.000 inv, overage 0,02 €/inv, 0,004 €/1k in, 0,016 €/1k out.
- **`plans/scale`**: 499 €/mes, 15.000 inv, 0,015 €/inv, 0,0035 €/1k in, 0,014 €/1k out.
  (Cifras ilustrativas: ~pass-through GPT-4o + 30-40 % margen; el fee por
  invocación paga guardrails/HITL/auditoría.)
- **`tenants/acme_demo`**: plan builder, clave demo documentada en README
  `fk_demo_2f7a1c9e4b8d4032a6e1` (calcular sha256 al escribir el YAML:
  `python -c "import hashlib;print(hashlib.sha256(b'fk_demo_2f7a1c9e4b8d4032a6e1').hexdigest())"`).
- **`tests/fixtures/plans/`**: `builder` (precios redondos para asserts, p. ej.
  0,01 €/inv overage, 1 €/1k tokens, included=2) y `sandbox`
  (`included_invocations: 1, hard_limit: true` — abarata el test de cuota).

## 5. Plan de tests (criterio de éxito: `make lint` + `make test-all` verdes)

- **`tests/unit/test_api_tenants.py`** — crear tenant 201 devuelve `fk_...` una
  vez; plan desconocido 404; nombre duplicado 409; listado sin `api_key_hash`.
- **`tests/unit/test_api_public.py`** — sin header 401; clave inválida 401;
  catálogo OK con clave; `allowed_agents` filtra catálogo e invoke (404);
  invoke 200 → evento en `usage.jsonl` + `/v1/usage` n=1; aislamiento (B no ve
  ejecuciones de A: lista vacía y GET por trace 404); cuota dura 429 a la 2ª con
  plan sandbox; tenant suspendido 403 (editar `state:` en el YAML de tmp a mano).
- **`tests/unit/test_metering.py`** — exención included/overage; cálculo tokens;
  `summarize_usage` (totales con monthly_fee); filtro por periodo;
  `tokens_from_execution` desde decision_path.
- **`tests/integration/test_public_api_flow.py`** — assets reales: crear tenant
  (plan builder) → catálogo contiene `incident_analyzer` → invoke escenario SIP →
  `awaiting_approval` + evento con tokens>0 → approve vía `/v1` → `completed` →
  `/v1/usage` con coste>0 → `/api/usage` admin muestra la fila.
- Convención fixtures unit: `patch_settings` autouse con monkeypatch.setenv +
  `cache_clear()` de TODAS las deps usadas (incluidas las dos nuevas).

## 6. Documentación a escribir

- **`docs/monetizacion.md`** (nuevo): modelo de consumo (qué compra el cliente:
  salida validada por esquema + política aplicada + HITL + auditoría, no tokens);
  mecánica de tarificación (CDR congelado, exención included, hard limit); tabla
  de planes; qué se factura y qué no (approve/reject y ejecuciones bloqueadas por
  guardrail a la entrada facturan solo fee de invocación, sin tokens — el bloqueo
  ES el servicio); camino a producción: Stripe (metered billing), `Decimal`,
  rotación/suspensión de claves, rate limiting RPM, OIDC para el admin.
- **README**: sección "API pública para empresas" con quickstart curl usando la
  clave demo (`GET /v1/catalog`, `POST /v1/agents/incident_analyzer/invoke`,
  `GET /v1/usage`) + fila(s) en la tabla de capacidades.
- **ARCHITECTURE.md**: sección tenancy/metering + filas nuevas en la tabla de
  persistencia (tenants/plans YAML versionado; usage.jsonl append-only).
- **`docs/futuro.md`**: Stripe, rate limiting por minuto, rotación/suspensión de
  claves vía API, panel UI "Consume/Billing", SDKs generados de OpenAPI, webhooks
  de HITL para tenants, export CSV de uso.
- **`docs/explicacion.md`**: toque ligero — fila en la tabla de persistencia y
  párrafo "la tercera cara: /v1".

## 7. Descartado a propósito (no re-abrir sin decisión)

- Segundo agente de ejemplo (support_triage): el MockProvider devuelve forma de
  incidente; otro esquema rompería `schema_match` con mock. No necesario para
  demostrar genericidad.
- Panel UI de tenants/uso: el escaparate del MVP es la API + `/docs`. → roadmap.
- Endpoints rotate-key / suspend: la suspensión se honra en auth (estado en YAML);
  gestión vía API → roadmap.
- Auth del admin `/api`: ya estaba en roadmap (OIDC); fuera de alcance.

## 8. Orden de implementación (checklist)

1. [ ] Dominio: `domain/plan.py`, `domain/tenant.py`, `domain/usage.py`
2. [ ] Stores: `registry/plan_store.py`, `registry/tenant_store.py`, factory
3. [ ] `config.py` (2 dirs) + `api/deps.py` (2 getters + aliases)
4. [ ] `api/auth.py` + `api/metering.py`
5. [ ] `api/tenants.py` (admin) + `api/public.py` (/v1)
6. [ ] `_record_execution` con tenant + wiring `main.py` + compose + `.env.example`
7. [ ] Seeds `plans/*`, `tenants/acme_demo` + fixtures de tests
8. [ ] Tests (4 ficheros) + conftest integración
9. [ ] `make lint` y `make test-all` verdes (mypy es `strict`)
10. [ ] Docs (§6)

Para retomar: "implementa docs/plan-api-publica.md" — los pasos 1-9 no requieren
más decisiones; todo lo decidible está decidido arriba.