QIG - État des Lieux & Directions

Date: 25/01/2026 23:00 Status: EN COURS

Ce qui existe aujourd'hui

Architecture actuelle

┌───────────────┐    ┌─────────────┐    ┌────────────────┐
│   User Input  │───►│   Ollama    │───►│  UI Component  │
│  "chercher    │    │   Intent    │    │  (Form ou      │
│   octocat"    │    │   Analysis  │    │   Display)     │
└───────────────┘    └─────────────┘    └────────────────┘
                            │                    │
                            ▼                    ▼
                     ┌─────────────┐    ┌────────────────┐
                     │ connectors  │───►│  API Response  │
                     │    -hub     │    │  (GitHub...)   │
                     └─────────────┘    └────────────────┘

Composants implémentés

Composant	Fichier	Status	Notes
Intent Analysis	`prompts.ts`	OK	Extrait action, entity, connector, search_term
Endpoint Resolution	`client.ts`	OK	KNOWN_ENDPOINTS + fallback
Display Mode	`index.tsx`	OK	Table/cards/list via DisplaySpec
Form Mode	`index.tsx`	PARTIEL	UISpec généré mais pas testé submit
DisplaySpec Normalization	`normalize.ts`	OK	Adapte structure Ollama
Schema Discovery	`client.ts`	INCOMPLET	getSchema() existe mais souvent vide

Flow Display (list/search)

User: "chercher utilisateur octocat"
Ollama: {action: "search", entity: "user", search_term: "octocat", connector: "github"}
resolveEndpoint → /search/users
fetchService → GET /search/users?q=octocat
Response: {total_count: 1086, items: [...]}
Extract data.items
displaySpecPrompt → Ollama génère colonnes/types
normalizeDisplaySpec → Adapte structure
DisplayRenderer → Affiche table

Flow Form (create/update)

User: "créer un projet GitLab"
Ollama: {action: "create", entity: "project", connector: "gitlab"}
uiSpecPrompt → Ollama génère champs
FormRenderer → Affiche form
handleSubmit → POST vers API
(NON TESTÉ en production)

Ce qui manque / Questions ouvertes

1. Utilisation des docs API (OpenAPI/Swagger)

Question: Est-ce qu'on utilise les docs API pour connaître les champs précisément ?

Réponse actuelle:

Partiellement. connectorService.getSchema() existe
Mais souvent retourne {}
Ollama déduit les colonnes depuis le sample de données (pas le schema)

Pour OUTPUT (Display):

// Dans index.tsx ligne 166-173
let schema: any = {};
try {
  if (matchedConnector?.id) {
    schema = await connectorService.getSchema(state.auth.accessToken!, matchedConnector.id) || {};
  }
} catch (e) {
  console.warn("Could not fetch schema:", e);
}

Pour INPUT (Form):

// Dans index.tsx ligne 240-252
const uiSpec = await chatJSON<UISpec>({
  prompt: uiSpecPrompt(
    {...},
    {}, // <-- Schema vide ! "Could be fetched from API"
    state.language
  ),
  system: SYSTEM_PROMPT,
});

Problème: Le schema est rarement rempli, Ollama devine tout depuis:

Le nom de l'entité
Un échantillon de données (display mode)
Ses connaissances générales (form mode)

2. Composants dynamiques vs fixes

Question: Les composants sont-ils dynamiques ou templates fixes ?

Réponse: Hybride

Aspect	Dynamique	Fixe
Structure (quels champs)	Ollama décide	-
Types de champs	Ollama suggère	Set limité (text, select, badge...)
Labels/placeholders	Ollama génère	-
Rendu visuel	-	FormRenderer / DisplayRenderer
Validation	Ollama suggère	Implémentation fixe

Les composants React (FormRenderer, DisplayRenderer) sont fixes, mais leur contenu (champs, colonnes, types) est dynamique.

3. Forms fonctionnels ?

Question: Les formulaires soumettent-ils vraiment les données ?

Réponse: Oui en théorie, non testé en pratique

// handleSubmit existe (ligne 294-319)
const response = await fetchService.execute(state.auth.accessToken, {
  connector,
  method,
  path,
  body: method !== "GET" ? values : undefined,
});

À tester: Créer un repo GitHub, créer un projet GitLab, etc.

Idées & Directions possibles

Option A: Améliorer le schema discovery

Concept: Enrichir connectors-hub pour retourner les vrais schemas OpenAPI

Avantages:

Champs précis (requis, types, validations)
Moins de hallucination Ollama
Formulaires plus robustes

Inconvénients:

Travail côté connectors-hub
Chaque API a un format OpenAPI différent
Maintenance à long terme

Effort: MOYEN-ÉLEVÉ

Option B: Parser OpenAPI on-the-fly

Concept: QIG récupère le swagger.json et le parse lui-même

User Input → Ollama (intent) → Fetch OpenAPI → Parse → Generate UI

Avantages:

Pas de changement connectors-hub
Données toujours fraîches

Inconvénients:

Chaque API structure son OpenAPI différemment
Complexité parsing + normalisation
OpenAPI parfois incomplet ou absent

Effort: MOYEN

Option C: Base de connaissances API statique

Concept: Fichier de config par API connue avec les schemas essentiels

// api-knowledge/github.ts
export const GITHUB_SCHEMAS = {
  user: {
    list: { endpoint: "/users", response: ["login", "id", "avatar_url"] },
    search: { endpoint: "/search/users", params: ["q"], response: ["login", "id"] },
    create: null, // GitHub ne permet pas de créer des users
  },
  repo: {
    create: {
      endpoint: "/user/repos",
      method: "POST",
      fields: [
        { name: "name", type: "string", required: true },
        { name: "description", type: "string" },
        { name: "private", type: "boolean", default: false },
      ]
    }
  }
}

Avantages:

Contrôle total
Pas de dépendance OpenAPI
Prédictible et testable

Inconvénients:

Maintenance manuelle
Ne scale pas pour 100+ APIs
Peut devenir obsolète

Effort: FAIBLE initial, ÉLEVÉ long terme

Option D: Hybrid LLM + Schema hints

Concept: Ollama génère l'UI mais avec des "hints" de schema injectés

Maintenir KNOWN_ENDPOINTS avec schemas basiques
Passer ces hints à Ollama dans le prompt
Ollama "enrichit" avec sa connaissance

// Prompt enrichi
const hints = KNOWN_SCHEMAS[connector]?.[entity] || {};
prompt: displaySpecPrompt(intent, hints, dataSample, language)

Avantages:

Meilleur des deux mondes
Progressive enhancement
Fallback gracieux

Inconvénients:

Deux sources de vérité
Ollama peut ignorer les hints

Effort: FAIBLE-MOYEN

Option E: Focus POC → Demo simple

Concept: Ne pas over-engineer, garder le POC simple

Display fonctionne pour list/search ✓
Form basique pour create
2-3 APIs bien supportées (GitHub, GitLab)
Valider le concept avant d'industrialiser

Avantages:

Rapide à finaliser
Démontre la valeur
Itération basée sur feedback

Inconvénients:

Limitant pour certains use cases
Pas "production-ready"

Effort: MINIMAL

Recommandation

Pour demain, je suggère Option E + Option D progressif:

Finir le POC
- Tester form submit en vrai
- S'assurer que GitHub/GitLab marchent end-to-end
- Documenter les erreurs rencontrées
Ajouter schema hints progressivement
- Enrichir KNOWN_ENDPOINTS avec des infos de schema
- Un connector à la fois
Recueillir le feedback
- Quels use cases sont prioritaires ?
- Quelles APIs sont indispensables ?

Fichiers clés du projet

Fichier	Rôle
`src/routes/index.tsx`	Orchestration principale
`src/lib/ollama/prompts.ts`	Prompts Ollama (intent, uiSpec, displaySpec)
`src/lib/connector/client.ts`	KNOWN_ENDPOINTS + resolveEndpoint
`src/lib/ui-spec/normalize.ts`	Normalisation DisplaySpec
`src/components/form/FormRenderer.tsx`	Rendu formulaires
`src/components/display/`	Rendu display (table, cards, etc.)
`GUIDELINES.md`	Documentation des choix

Erreurs à investiguer demain

(Signalées par l'utilisateur, à détailler lors de la prochaine session)

[ ] Erreurs non spécifiées lors des tests
[ ] Flow complet en browser à valider
[ ] Form submit à tester avec vraie API