INTEGRATION.md

# VORTEX GOD v1 — Guide d'intégration

## 1. Télécharger le modèle Qwen3 8B GGUF

Dans votre Space Hugging Face, ajoutez ce script de téléchargement au démarrage
(ou dans un `Dockerfile`) :

```bash
mkdir -p /app/models
huggingface-cli download \
  bartowski/Qwen3-8B-Instruct-GGUF \
  Qwen3-8B-Instruct-Q4_K_M.gguf \
  --local-dir /app/models \
  --local-dir-use-symlinks False
```

Modèles alternatifs si la VRAM est insuffisante :
- `Q3_K_M` (~3.5 Go) — légèrement moins précis
- `Q5_K_M` (~5.3 Go) — meilleur si la RAM le permet

## 2. Installer llama-cpp-python avec support CUDA

```bash
CMAKE_ARGS="-DGGML_CUDA=on" \
  pip install llama-cpp-python --no-cache-dir --upgrade
```

> Sur HF Spaces T4, ajouter ceci dans `packages.txt` :
> `libcublas-dev-12-4`

## 3. Variables d'environnement (Secrets HF)

| Variable         | Valeur recommandée                                      |
|------------------|---------------------------------------------------------|
| `USE_LOCAL_LLM`  | `1`                                                     |
| `LLM_MODEL`      | `/app/models/Qwen3-8B-Instruct-Q4_K_M.gguf`            |
| `N_GPU_LAYERS`   | `35`  (T4 Small — ajuster si OOM)                       |
| `N_CTX`          | `4096`                                                  |
| `HF_TOKEN`       | votre token (pour télécharger le modèle)                |
| `SEARXNG_URL`    | URL de votre instance SearXNG (optionnel)               |
| `DATA_DIR`       | `/app/data`                                             |
| `ENERGY_MAX`     | `10000`                                                 |

## 4. Intégrer les nouveaux fichiers dans l'arborescence existante

```
Vortttxx/
├── agents/
│   └── cognitive_engine.py   ← REMPLACER par le nouveau
├── utils/
│   └── web_search.py         ← NOUVEAU fichier
├── tests/
│   └── test_god_bootstrap.py ← NOUVEAU fichier
└── requirements.txt          ← REMPLACER par le nouveau
```

## 5. Modifier app.py pour intégrer la recherche web

Dans le fichier `app.py` existant, ajoutez après les imports :

```python
from utils.web_search import web_search, search_arxiv
```

Puis ajoutez un onglet dans l'interface Gradio :

```python
with gr.TabItem("🌐 Recherche web"):
    search_query = gr.Textbox(label="Requête")
    fetch_toggle = gr.Checkbox(label="Extraire le contenu des pages", value=False)
    arxiv_toggle = gr.Checkbox(label="Rechercher sur arXiv", value=False)
    search_btn   = gr.Button("Rechercher")
    search_out   = gr.Markdown()

    async def do_search(q, fetch, arxiv_mode):
        if arxiv_mode:
            resp = await search_arxiv(q, max_results=5)
        else:
            resp = await web_search(q, max_results=6, fetch_pages=fetch)
        return resp.as_context()

    search_btn.click(fn=do_search, inputs=[search_query, fetch_toggle, arxiv_toggle], outputs=search_out)
```

## 6. Vérifier l'installation

```bash
python tests/test_god_bootstrap.py
```

## 7. Prochaines étapes (roadmap)

| Étape | Fichier à créer              | Priorité |
|-------|------------------------------|----------|
| 2     | `agents/specialized/*.py`    | Haute    |
| 3     | `core/knowledge_graph.py`    | Haute    |
| 4     | `core/rag_engine.py`         | Moyenne  |
| 5     | Système d'évolution agents   | Basse    |

## Notes sur les performances T4

- Qwen3 8B Q4_K_M génère ~15-25 tokens/sec sur T4 avec `n_gpu_layers=35`
- Réduire `N_CTX` à 2048 pour économiser la VRAM si nécessaire
- Le cache LRU (`LLM_CACHE_MAX=256`) évite les appels répétés
- `fetch_pages=False` par défaut pour la recherche web (plus rapide)