robin-quota-client 0.1.0

Cliente Python para validar y consumir cuota del Robin Quota Service

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

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

Uso

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)

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

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