vek1-api — contexto
vek1-api — contexto raiz
Backend FastAPI/Python do vek1. Source-of-truth dos modelos de IA + DB writes. Frontend vek1 fala com este serviço via HTTP interno (3 token scopes).
O que é (uma frase)
API RAG conversacional + backing store HTTP do Better Auth + dono de todas as mutations (orders/leads/products/agents/stores/etc.) + integrações externas isoladas (DeepSeek, Ollama, Resend, AbacatePay webhook receiver, ERP stock sync). Function calling consultivo com create_order tool — agente fecha pedido sem intervenção humana.
Onde olhar primeiro
| Quero saber sobre | Lê |
|---|---|
| Stack + estrutura de pastas | architecture.md |
| Catálogo completo de endpoints (auth/app/webhook + públicos) | endpoints.md |
| Decisões técnicas (DeepSeek, bge-m3, psycopg2, slowapi, cache auth) | decisions.md |
| Integrações externas (Ollama, DeepSeek, Resend, AbacatePay) | integrations.md |
| Bugs, traps, race conditions resolvidas | gotchas.md |
| Trajetória / PRs recentes | recent-activity.md |
Localização
- Repo: https://github.com/kodama1/vek1-api
- Clone local:
C:\Users\User\vek1-api\ - Branch principal:
master - Deploy prod:
https://vek1-api.kodama.solutions(VPS Hermes) - Container:
vek1-api(porta 127.0.0.1:8000) +vek1-postgres(5434 exposto pra Vercel) - SSH deploy:
~/.ssh/id_vek1_deploy(aliasgithub-vek1)
Stack resumido
- FastAPI 0.104 + Uvicorn + GZip middleware + slowapi rate limit (opcional)
- Postgres 16 + pgvector 0.8.2 self-hosted (
pgvector/pgvector:pg16) - Ollama
bge-m3(1024 dim) — containervault-ollamareaproveitado - DeepSeek (
deepseek-chat) via SDKopenaicombase_url=https://api.deepseek.com psycopg2-binary+ThreadedConnectionPool(síncrono — handlers síncronos)httpx(Ollama, Resend, AbacatePay outbound, stock sync)- Resend transactional (reset password)
Token scopes
X-Internal-Token(app) — domínios (orders, leads, products, agents, stores, etc.)X-Auth-Token— Better Auth backing store (/internal/auth/*)X-Webhook-Token— fire-and-forget (email, AbacatePay relay, ERP stock sync inbound)
Constant-time compare via hmac.compare_digest. Fallback: app token serve pros 3 se dedicados ausentes.
Routers (per-domain)
main.py carrega cada router com try/except ImportError — falha de import não trava startup, só warn.
| Router | Prefix | Scope | O que faz |
|---|---|---|---|
auth.py |
/internal/auth |
auth | Better Auth backing store (29 endpoints purpose-built) |
orders.py |
/internal/orders + /webhooks |
app + webhook | CRUD orders + state machine + AbacatePay webhook |
leads.py |
/internal/leads |
app | ensure/get/list/patch + events |
agents.py |
/internal/agents + webhook |
app + webhook | CRUD + KB + evolution-instance lookup |
products.py |
/internal |
app | products + documents + product_files |
stores.py |
/internal |
app | stores + company |
dashboard.py |
/internal/dashboard |
app | aggregated stats |
messages.py |
/internal |
app | messages_history + audit_log read |
token_usage.py |
/internal/token-usage |
app | insert/list/summary (billing telemetry) |
email.py |
/internal/email |
webhook | Resend send-reset-password |
stock.py |
/internal/stock + /webhooks/stock-sync |
app + webhook | decrement/restore + ERP sync bidirectional |
Detalhes completos em endpoints.md.
Função /chat (caminho crítico)
rag_service.process_query_with_functions():
- Carrega config do agente (
agents_config.yaml) - Se
lead_id: SELECTlead.profile_summary, injeta como 2ª system message - Monta tools (search_products, get_product_details, filter_products_by_price, create_order, confirm_shipping)
- Loop até 5 iterações: LLM → tool calls → exec → resposta
- Persist em
messages_historycomlead_id(cross-agent/cross-channel lookup) - Skip persistência se
lead_idpresent (vek1 já grava —dd2ac9f)
dry_run: true simula side-effects sem chamar HTTP — usado em tests integration.
Memória long-term por lead
profile_summary(text compact) +profile_embedding(vector 1024) gerados pelo vek1 (lib/leads.ts:buildLeadProfileSummary)- vek1-api injeta no /chat como system message, sem re-fazer dump de history
- Reduz tokens 70-90% vs fetch full conversation
Variáveis de ambiente
DATABASE_URL=postgresql://vek1:<senha>@postgres:5432/vek1
POSTGRES_PASSWORD=<senha>
# LLM + embeddings
DEEPSEEK_API_KEY=sk-...
OPENAI_API_KEY= # vazio — usa DEEPSEEK
OPENAI_BASE_URL=https://api.deepseek.com
OLLAMA_BASE_URL=http://vault-ollama:11434
EMBEDDING_MODEL=bge-m3
# Token scopes
INTERNAL_API_TOKEN=...
INTERNAL_AUTH_TOKEN=...
INTERNAL_WEBHOOK_TOKEN=...
# Email transactional
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=noreply@vek1.app
# Misc
ENVIRONMENT=production
DEBUG=False
LOG_LEVEL=INFO
MAX_FILE_SIZE_MB=10
ALLOWED_EXTENSIONS=pdf,csv
Vide também
- vek1 — frontend Next.js que consome essa API
- infra/vps-hermes — VPS host