Metadata-Version: 2.4
Name: robin-quota-client
Version: 0.1.0
Summary: Cliente Python para validar y consumir cuota del Robin Quota Service
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# robin-quota-client

Cliente Python mínimo para integrar cualquier proyecto con el **Robin Quota Service**: validar disponibilidad y consumir cuota.

El `modelBotId` **no es necesario** — el servicio lo resuelve desde la `X-Docker-Api-Key` (`apiServices.modelBotId`). Solo pásalo si usas una key legacy sin bot asociado en BD.

## Instalación

```bash
pip install -e .
# o con tests
pip install -e ".[dev]"
```

## Uso

```python
from robin_quota import QuotaClient, QuotaExceededError

client = QuotaClient(
    api_key="robin_docker_...",
    host="http://localhost:3201",  # test local (npm run dev)
    source="ai-gen-message",
)

# 1. Validar antes de generar mensaje IA
client.ensure_can_send()

# 2. Generar respuesta IA...
# ai_reply = llm.generate(...)

# 3. Consumir cuota (+1)
client.consume(
    idempotency_key="msg-123",
    workflow_room_id="f7027893-08c9-4216-96b2-8998a5b967f6",
    workflow_id="uuid-del-workflow",
    metadata={"origin": "app.ruvic.ai"},
)
```

## Parámetros

### Inicialización (`QuotaClient`)

| Parámetro | Requerido | Descripción |
|-----------|-----------|-------------|
| `api_key` | sí | Docker API key del despliegue |
| `host` | no | URL base (default `http://localhost:3201`) |
| `source` | no | Origen para `consume()` (default `python-agent`) |
| `model_bot_id` | no | Solo keys legacy sin bot en `apiServices` |

### `consume()`

| Parámetro | Requerido | Descripción |
|-----------|-----------|-------------|
| `quantity` | no | Default `1` |
| `idempotency_key` | recomendado | Evita doble conteo en reintentos |
| `workflow_room_id` | no | Contexto/auditoría (`workFlowRoomId`) |
| `workflow_id` | no | Contexto/auditoría (`workFlowId`) |
| `metadata` | no | JSON libre adicional |

### Variables de entorno (opcional)

```bash
export ROBIN_QUOTA_API_KEY=robin_docker_...
export ROBIN_QUOTA_BASE_URL=http://localhost:3201
export ROBIN_QUOTA_SOURCE=ai-gen-message
# ROBIN_QUOTA_MODEL_BOT_ID solo para keys legacy
```

## Tests

```bash
pytest                          # unit tests (mocks)
pytest tests/test_integration.py  # contra localhost:3201 si está corriendo
```
