LLM routing

Configure a route

curl -X PUT https://api.tyxter.com/v1/llm-routes \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-haiku-4-5-20251001",
    "api_key": "sk-ant-...",
    "system_prompt": "You handle customer support for ACME store deliveries. Decline unrelated topics politely.",
    "max_tokens": 512,
    "temperature": 0.2,
    "daily_cost_cap_brl": "20.00",
    "handoff_phrases": ["falar com humano", "atendente"]
  }'

One route per environment. Re-submitting replaces the stored key and config. The stored API key is AES-256-GCM sealed; reads only return ••••<last4>.

Request a completion

curl https://api.tyxter.com/v1/llm/completions \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "contact_phone": "+5511999999999",
    "messages": [
      { "role": "user", "content": "Qual o status do pedido 123?" }
    ]
  }'

{
  "object": "llm_completion",
  "content": "Seu pedido 123 saiu para entrega hoje às 14h.",
  "model": "claude-haiku-4-5-20251001",
  "tokens_in": 80,
  "tokens_out": 22,
  "cost_brl": "0.0150",
  "provider_cost_usd_estimate": "0.000190",
  "handoff": false,
  "trace_id": "trc_..."
}

Handoff to human

Before calling the provider, the use case scans the latest user message for any configured handoff phrase. On a match it does not invoke the LLM — it returns handoff: true with an empty content and fires llm.handoff_requested via webhook so your staff console can pick up.

Daily cost cap

When daily_cost_cap_brl is set, the completion use case reads today's UsageRecord spend for llm.tokens.used against the project. Once spend ≥ cap, further completions return 402 llm_cost_cap_reached and llm.cost_cap_reached fires via webhook exactly once per crossing.

Metering

Each successful completion emits a usage_event.created event with meter_id: llm.tokens.used and quantity in 1k-token units (rounded up). The downstream billing pipeline writes a priced UsageRecord against the active rate card.

Delete

Soft-deletes the route. Further completion requests will 404 until you upsert a new one.