AI Gateway

AI Gateway (Panel → projekt → AI Gateway) to endpoint zgodny z OpenAI, obsługiwany przez aplikację HostBase. Wywołujesz go kluczem bramki hbai_…, a żądania trafiają do dostawcy skonfigurowanego przez Ciebie (BYOK: Anthropic, OpenAI, Mistral albo dowolny serwer OpenAI-compatible). Z dostawcą rozliczasz się bezpośrednio — klucze są szyfrowane AES-256-GCM i nigdy nie trafiają do logów.

Endpointy

POST https://host.ulewicz.space/api/ai/v1/chat/completions
POST https://host.ulewicz.space/api/ai/v1/embeddings
GET  https://host.ulewicz.space/api/ai/v1/models

Authorization: Bearer hbai_...

Modele domyślne: claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5 (przez Anthropic Messages API — tłumaczymy format OpenAI, w tym streaming SSE, narzędzia i obrazy). Dodatkowo gpt-4.1, mistral-large-latest, modele embeddingów (text-embedding-3-small, mistral-embed) oraz dowolne modele własnego endpointu. Jeśli dostawca danego modelu nie jest skonfigurowany, bramka odpowiada HTTP 424 z kodem provider_not_configured.

curl https://host.ulewicz.space/api/ai/v1/chat/completions \
  -H "Authorization: Bearer $HOSTBASE_AI_KEY" -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","stream":true,"messages":[{"role":"user","content":"Cześć!"}]}'

Klucze, limity i budżety

• Klucz ma zakresy (chat, embeddings, models), opcjonalną listę dozwolonych modeli, limit żądań na minutę (domyślnie 60) i miesięczny budżet w USD (szacunek z liczby tokenów). Przechowujemy tylko skrót SHA-256; pełny klucz widać raz.
• Po przekroczeniu limitu bramka zwraca 429 (rate_limit_exceeded lub budget_exceeded). Przy 80% i 100% budżetu dostajesz powiadomienie w panelu.
• Plan Free obejmuje 10 tys. żądań miesięcznie (twardy limit); Pro 500 tys.; Team 5 mln; powyżej — 8 zł netto / mln żądań.

Cache, fallbacki, PII, szablony

• Cache — exact match (model + wiadomości + parametry), TTL w ustawieniach, tylko bez streamingu. Nagłówek Cache-Control: no-cache go omija. Odpowiedź niesie x-hostbase-cache: hit|miss.
• Fallback — reguły model -> zapasowy1, zapasowy2; przy 429/5xx/401 bramka próbuje kolejnych (nagłówek x-hostbase-fallback-from).
• Redakcja PII — PESEL (z sumą kontrolną), e-mail i telefony zamieniane na [PESEL], [EMAIL], [PHONE] przed wysłaniem do dostawcy.
• Szablony promptów — pole hostbase_template (name + variables) w żądaniu dodaje zapisany prompt systemowy/użytkownika ze zmiennymi.
• Logi — model, dostawca, tokeny, opóźnienie, koszt, status; retencja 1–365 dni. Treści promptów nie są zapisywane (opcjonalny 200-znakowy podgląd po redakcji PII).

Vector pipeline (pgvector)

Zakładka Vector pipeline generuje SQL dla wybranej tabeli i kolumny tekstowej: kolumnę vector(N), indeks HNSW, kolejkę pgmq, trigger, funkcje workera, harmonogram pg_cron oraz Edge Function pobierającą embeddingi z bramki. Dołączamy backfill istniejących wierszy i funkcję wyszukiwania:

const { data } = await supabase.rpc("match_documents", {
  query_embedding: embedding, // z POST /api/ai/v1/embeddings
  match_count: 5,
});

Auto Router, polityki danych, narzędzia i evals

• Auto Router — model auto klasyfikuje zadanie (proste / złożone / kod / długi kontekst) regułami, opcjonalnie doprecyzowuje małym modelem, i wybiera z puli skonfigurowanej w Auto Router i polityki najtańszy model spełniający próg jakości (strategia: koszt, zrównoważona, jakość). Przy błędzie lub limicie próbuje kolejnych kandydatów. Nagłówki: x-hostbase-router, x-hostbase-task-class, x-hostbase-saved-usd; raport „zaoszczędzono” jest w panelu.
• Zero Data Retention — flaga projektu lub klucza: brak zapisu podglądów promptów, brak cache, błędy dostawcy zastąpione kodem; w logach zostają metadane. Nagłówek odpowiedzi x-hostbase-zdr: 1.
• Region UE — wyklucza dostawców spoza UE (Mistral i dostawcy oznaczeni „UE”); błąd eu_region_unavailable, gdy żaden nie pasuje.
• Budżet na użytkownika końcowego — nagłówek x-hb-user (lub pole user) agreguje zużycie; po przekroczeniu: 429 user_budget_exceeded.
• Narzędzia — "hostbase_tools": ["web_search", "mcp:nazwa"]: bramka wykonuje wyszukiwanie (Brave BYOK / SearXNG) i narzędzia serwerów MCP w pętli do 4 rund (bez streamingu).
• Evals — zestawy CSV/JSON, uruchomienie na wielu modelach, ocena regułą lub LLM-sędzią, porównanie jakości, kosztu i opóźnień oraz historia.
• Asystent SQL — POST /api/ai/chat z {"mode":"explain_plan"|"suggest_index","sql":"select …"} (tylko odczyt, walidowane przez sql-guard).

curl $BASE/chat/completions -H "Authorization: Bearer $KEY" -H "x-hb-user: user_42" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Streść w jednym zdaniu: ..."}]}'

Management API i MCP

GET    /api/v1/projects/{ref}/ai-gateway
GET    /api/v1/projects/{ref}/ai-gateway/usage?range=24h|7d|30d
GET|POST /api/v1/projects/{ref}/ai-gateway/keys      DELETE .../keys/{id}
GET|PUT|DELETE /api/v1/projects/{ref}/ai-gateway/providers
GET|PUT /api/v1/projects/{ref}/ai-gateway/settings
GET|POST|DELETE /api/v1/projects/{ref}/ai-gateway/evals
GET|POST /api/v1/projects/{ref}/ai-gateway/evals/runs   GET .../runs/{id}
GET    /api/v1/projects/{ref}/ai-gateway/end-users

Narzędzia MCP: get_ai_gateway, get_ai_gateway_usage, list_ai_gateway_keys, create_ai_gateway_key, revoke_ai_gateway_key, set_ai_provider, delete_ai_provider, set_ai_gateway_settings, list_ai_gateway_evals, create_ai_gateway_eval_set, run_ai_gateway_eval, get_ai_gateway_eval_run, get_ai_gateway_end_users.