# BIFROST-ACCESS — Passerelle LLM (vision / OCR)

Note partagée aux 3 instances Hermes. Source : projet gsparc-mezzouna, 2026-06-14.

Bifrost = passerelle LLM OpenAI-compatible sur le NAS.

## Endpoint & authentification
- Conteneur `bifrost` sur le réseau **n8n**, port interne **8080**.
  - Depuis un conteneur du réseau n8n : `http://bifrost:8080/v1`
  - Depuis le LAN : `http://192.168.100.33:3085/v1` (UI sur 3085)
- **Auth = header `x-bf-vk: <clé virtuelle>`**. Le header `Authorization: Bearer` est REJETÉ (HTTP 401 `virtual_key_required`). Toujours envoyer `x-bf-vk`.
- Clé virtuelle commune (Nabil-Key, budget 8 $/mois) : `bfk-e5832bfebd22e9d8252a426d0734ed5f2d923204c8033d6d`.
- `GET /v1/models` (avec `x-bf-vk`) → liste des modèles (ids complets, ex. `openrouter/google/gemini-2.5-flash`).

## PIÈGE vision / OCR
**DeepSeek est text-only.** Envoyer une image à `deepseek-v4-flash/pro/r1` → `404 "No endpoints found that support image input"`.
→ Pour toute extraction d'image (scan, ticket, OCR), utiliser un modèle vision :
**`openrouter/google/gemini-2.5-flash`** (rapide, fiable, payant ~fraction de centime/image).
Le « forfait OpenCode gratuit » ne couvre PAS la vision.

## Exemple
```bash
curl -s http://bifrost:8080/v1/chat/completions \
  -H "x-bf-vk: bfk-e5832bfebd22e9d8252a426d0734ed5f2d923204c8033d6d" \
  -H "Content-Type: application/json" \
  -d '{"model":"openrouter/google/gemini-2.5-flash","messages":[
       {"role":"user","content":[
         {"type":"text","text":"Décris cette image en JSON strict."},
         {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,..."}}]}]}'
```
Implémentation de référence : `gsparc-mezzouna/app/vision.py`.

## MAJ 2026-07-02 - Format sk-bf-* et Hermes Desktop (Yesmine)

Precision importante sur la regle "Authorization: Bearer rejete" ci-dessus : c'est vrai UNIQUEMENT pour les anciennes vk au format bfk-*. Une vk moderne au format sk-bf-* accepte Authorization: Bearer <sk-bf-...> (en plus de x-bf-vk). Pour tout client qui ne peut pas envoyer de header custom (ex. Hermes Agent/Desktop - pas de support headers custom dans config.yaml, cf. github.com/NousResearch/hermes-agent/issues/9398), utiliser une vk sk-bf-* + Authorization Bearer.

### Piege confirme : allow_all_keys jamais honore via l'API
Que ce soit a la creation ou en update via /api/governance/virtual-keys, le champ allow_all_keys d'un provider_config est systematiquement ignore (reste false en base quoi qu'on envoie). Fix : poser allow_all_keys=1 directement dans config.db (table governance_virtual_key_provider_configs, colonne allow_all_keys), puis docker restart bifrost pour recharger le cache memoire. Meme famille de piege que le rechargement des cles provider au boot (config.json).

### Endpoint /anthropic/v1/messages : ne marche pas avec les providers custom
Teste et confirme : /anthropic/v1/messages fonctionne pour les providers CANONIQUES de Bifrost (ex. groq -> 200 OK, reponse bien traduite au format Anthropic). Pour un provider CUSTOM (base_provider_type: openai, ex. opencode), la meme requete renvoie 404 "HTML response received from provider". Ne pas utiliser le plan "provider Anthropic natif cote client + base_url vers /anthropic" pour router vers DeepSeek/OpenCode via Bifrost. Utiliser /v1/chat/completions (mode OpenAI-compatible standard) a la place.

### Recette Hermes Desktop -> Bifrost -> DeepSeek V4 Flash (OpenCode) — MAJ 2026-07-11 (valide, testee de bout en bout)

**Utiliser bifrost-proxy (port 3086), pas Bifrost direct (3085).** Le proxy traduit `Authorization: Bearer <vk>` (ou `x-api-key`) en `x-bf-vk` cote Bifrost. Fonctionne avec le format de vk classique `bfk-*` — pas besoin du format `sk-bf-*` ni d'un client capable d'envoyer un header custom.

Config generique (tout client OpenAI-compatible, type Hermes Desktop) :
```
Base URL : http://192.168.100.33:3086/v1
Auth     : Authorization: Bearer <vk>   (champ "API Key" standard)
```

**Piege vecu (11/07)** : ecrire l'IP avec un `:` au lieu d'un `.` (ex. `192:168.100.33`) casse le parsing cote client → symptome "connected but no models" trompeur, ne pas chercher plus loin avant d'avoir verifie l'IP au caractere pres.

**`/v1/models` sur le port 3086 ne requete PAS Bifrost en direct** : il sert un catalogue STATIQUE (`/mnt/docker/bifrost-proxy/models.json` sur le NAS), relu a chaque requete (pas de restart necessaire pour l'editer). Si un modele manque dans le picker du client alors qu'il est bien autorise sur la vk cote Bifrost (verifiable via `curl http://172.17.0.1:3085/v1/models -H "x-bf-vk: <vk>"`), l'ajouter directement dans ce fichier. Cf. incident 11/07 dans bifrost-vk-incidents.md — `deepseek-v4-flash` avait disparu de ce catalogue lors de la reduction de stack fin juin/debut juillet.

VK Yesmine (Hermes Desktop) : `Yesmine-Key`, `bfk-04e2a58c7ce42bd676c4e0768b4b40ae5dc01a9999979527`, providers openrouter/google/nvidia_nim/opencode (deepseek-v4-flash). Reutilisable telle quelle pour tout futur client desktop — **MacBook M5 Pro inclus** — tant que le format reste `bfk-*`.

#### Ancienne piste (2026-07-02, port 3085 direct + vk `sk-bf-*`) — DEPRECIEE
Documentee a l'epoque en misant sur un support natif de `Authorization: Bearer` par les vk au format `sk-bf-*`. Non reconfirmee depuis, et la vk Yesmine reellement utilisee est restee au format `bfk-*`. Le contournement via bifrost-proxy (3086) est desormais la methode de reference : plus simple (aucune regeneration de vk necessaire), et validee de bout en bout le 11/07/2026 (connexion + appel chat reel sur deepseek-v4-flash confirmes).