Provider Contract

Vista kieruje cały ruch AI przez warstwę Tauri (ServiceResolver). Frontend wywołuje unified_ai_* komendy, które dostarczają wspólny kontrakt dla LLM, STT i TTS.

Rejestr providerów

ServiceResolver::new() buduje registry na podstawie unified_ai/service_resolver/provider_registry.rs:

Kategoria	Providery	Zmienna kolejności
STT	stt-primary, stt-fallback, stt-vistascribe	AI_PROVIDER_ORDER_STT
LLM	llm-primary, llm-fallback	AI_PROVIDER_ORDER_LLM
TTS	tts-primary, tts-fallback	AI_PROVIDER_ORDER_TTS

Każdy provider posiada:

• URL endpointu
• Metodę (Json lub Multipart)
• Klucz API (opcjonalny)
• Typ API (AiApiKind::Responses vs legacy chat)

Zmienne środowiskowe

LLM

Nazwa	Przykład	Uwagi
AI_CHAT_PRIMARY_ENDPOINT	https://api.openai.com/v1/responses	Harmony Responses API
AI_CHAT_PRIMARY_MODEL	gpt-4.1	Model primary
AI_CHAT_FALLBACK_ENDPOINT	https://api.libraxis.cloud/llm/v1/responses	LibrAxis gateway
AI_CHAT_FALLBACK_MODEL	chat	Model fallback
AI_AI_SUGGESTIONS_*	—	Analogiczne pary dla sugestii
AI_SOAP_*	—	Analogiczne pary dla SOAP
AI_MASTER_*	—	Analogiczne pary dla master pipeline

STT

Nazwa	Przykład
AI_TRANSCRIPTION_PRIMARY_ENDPOINT	https://api.openai.com/v1/audio/transcriptions
AI_TRANSCRIPTION_FALLBACK_ENDPOINT	https://api.libraxis.cloud/stt/v1/audio/transcriptions
VISTASCRIBE_URL	http://127.0.0.1:8237

TTS

Nazwa	Uwagi
VOICE_TTS_PRIMARY_*	OpenAI / DeepInfra
VOICE_TTS_FALLBACK_*	Fallback provider
VOICE_DISABLE_TTS	true wyłącza całą gałąź

Klucze dostawców

Zmienna	Host
OPENAI_API_KEY	api.openai.com
LIBRAXIS_API_KEY	*.libraxis.cloud
DEEPINFRA_API_KEY	DeepInfra
OPENROUTER_API_KEY	OpenRouter
COHERE_API_KEY	Cohere

LibrAxis auth

Zmienna	Opis
LIBRAXIS_API_KEY	Klucz API
LIBRAXIS_CLIENT_ID	ID klienta
LIBRAXIS_SESSION_ID	ID sesji
LIBRAXIS_HMAC_SECRET	Sekret HMAC do podpisywania

Health & timeout

Zmienna	Opis
AI_HEALTH_*	Cache statusu providerów
AI_PRIMARY_JSON_TIMEOUT_SECS	Timeout JSON (primary)
AI_FALLBACK_JSON_TIMEOUT_SECS	Timeout JSON (fallback)
AI_PRIMARY_STREAM_TIMEOUT_SECS	Timeout stream (primary)
AI_FALLBACK_STREAM_TIMEOUT_SECS	Timeout stream (fallback)

Autoryzacja i nagłówki

Standardowy przypadek

Resolver dodaje Authorization: Bearer <API_KEY> gdy host odpowiada wpisowi w BASE_HOST_KEY_PAIRS (provider_contract_base.rs).

LibrAxis HMAC

Jeżeli LIBRAXIS_HMAC_SECRET jest ustawiony, request jest podpisywany:

• X-Client-ID
• X-Signature
• X-Timestamp
• X-Session-Id (opcjonalnie)

x-api-key

Preferowany nagłówek dla hostów *.libraxis.cloud. apply_api_key_header wybiera x-api-key, a Bearer jest pomijany (chyba że podpisujemy HMAC).

Kształtowanie payloadów

flowchart LR
    FE[Frontend] -->|withSessionPayload| SI[safeInvoke]
    SI -->|vista_meta.session_context| SR[ServiceResolver]
    SR -->|AiApiKind::Responses| H[Harmony payload]
    SR -->|Legacy| CC[chat completions + harmony_input]

• Responses: payload Harmony (input[], metadata, stream)
• Legacy fallback: chat completions + harmony_input (LibrAxis gateway normalizuje server-side)
• Stream: oczekujemy Harmony eventów (response.delta, response.completed) lub [DONE]

Failover i health cache

• ProviderHealthDecision bazuje na cache (AI_HEALTH_*)
• Po sukcesie przywracamy providera primary
• Logi: ai.provider.call / ai.provider.fail przez secure_logger

Testy i diagnostyka

Komenda	Opis
pnpm smoke:all	STT/LLM/TTS pingi do OpenAI i LibrAxis
pnpm api:libraxis:curl	Test LibrAxis-only
pnpm contract:check	Porównanie require_session z FE service listami
pnpm contract:sync	Sync po dodaniu nowego providera

Known Limitations

Feature	Status	Notes
Request queue persistence	❌	Queue in-memory, restart = utrata pending
TTS smoke tests	⚠️	Minimalne coverage
Fallback edge cases	⚠️	Częściowe SSE/niepoprawny JSON wymagają ręcznych retry
Legacy header cleanup	✅	Tylko x-api-key (lub HMAC)
Harmony normalization	✅	Non-Responses → harmony_input
Provider order	✅	Pełna konfiguracja przez AI_PROVIDER_ORDER_*
HMAC signature	✅	Wspierane dla LibrAxis

Wskazówki dla maintainerów

1. Dodając nowego dostawcę:

   • Zaktualizuj provider_contract_base.rs
   • Zaktualizuj .env.example
   • Odpal pnpm contract:sync
   • Zaktualizuj tę dokumentację

2. Przy zmianach Responses:

   • Upewnij się, że VistaRequest::ensure_chat_responses_format() wspiera nowe pola
   • Sprawdź FE (unifiedAI) dla metadata.tools, previous_response_id

3. Każda zmiana sekretów wymaga:

   • Aktualizacji env-secrets-policy.md
   • Smoke testów