Remove secrets from README

README.md

@@ -0,0 +1,808 @@
+# 📚 AI Research Assistant - Documentation Complète
+
+
+
+
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![Python](https://img.shields.io/badge/python-3.12-green.svg)
+![LangGraph](https://img.shields.io/badge/LangGraph-enabled-orange.svg)
+![ChromaDB](https://img.shields.io/badge/ChromaDB-vectorstore-purple.svg)
+
+## 🎯 Vue d'ensemble
+
+**AI Research Assistant** est un système intelligent de recherche et d'analyse documentaire utilisant LangGraph, plusieurs agents IA spécialisés, et un système de mémoire vectorielle avancé. Le système automatise l'ensemble du processus de recherche : de la collecte d'informations sur le web jusqu'à la génération de rapports de synthèse structurés.
+
+### ✨ Fonctionnalités principales
+
+- 🔍 **Recherche web automatisée** avec extraction de mots-clés intelligente
+- 📄 **Extraction de contenu** depuis des pages web avec parsing avancé
+- 📝 **Génération de résumés** détaillés et structurés
+- 🎯 **Synthèse globale** avec analyse thématique transversale
+- 💾 **Système de mémoire** vectorielle et conversationnelle
+- 🤖 **Orchestration par LLM** via LangGraph
+- 🚫 **Déduplication automatique** des documents
+- ⚡ **Cache intelligent** avec TTL configurable
+
+---
+
+## 🏗️ Architecture du Projet
+
+### Structure des dossiers
+
+```
+langGraphe-ai-research-assistant-main/
+│
+├── config/                      # Configuration globale
+│   ├── settings.py             # Paramètres de l'application
+│   └── prompts.py              # Templates de prompts
+│
+├── src/                         # Code source principal
+│   ├── agents/                 # Agents spécialisés
+│   │   ├── base_agent.py       # Agent de base
+│   │   ├── researcher_agent.py # Recherche web
+│   │   ├── content_extractor_agent.py # Extraction
+│   │   ├── summarizer_agent.py # Résumés
+│   │   └── global_synthesizer_agent.py # Synthèse
+│   │
+│   ├── services/               # Services partagés
+│   │   ├── search_api.py      # APIs de recherche (Tavily, Serper)
+│   │   ├── content_extraction.py # Extraction de contenu web
+│   │   ├── llm_service.py     # Service LLM (Groq)
+│   │   └── text_chunking.py   # Découpage de texte
+│   │
+│   ├── models/                 # Modèles de données
+│   │   ├── research_models.py  # Modèles de recherche
+│   │   ├── document_models.py  # Modèles de documents
+│   │   ├── synthesis_models.py # Modèles de synthèse
+│   │   ├── report_models.py    # Modèles de rapports
+│   │   └── state_models.py     # États du graphe
+│   │
+│   ├── graph/                  # LangGraph
+│   │   └── nodes.py           # Nœuds du graphe
+│   │
+│   ├── core/                   # Fonctionnalités de base
+│   │   └── logging.py         # Configuration des logs
+│   │
+│   ├── memory_system.py        # Système de mémoire vectorielle
+│   ├── memory_integration.py   # Intégration de la mémoire
+│   ├── enhanced_system_prompt.py # Prompts avancés
+│   └── graph.py                # Graphe LangGraph principal
+│
+├── tests/                       # Tests unitaires et d'intégration
+│   ├── test_researcher.py
+│   ├── test_content_extractor_agent.py
+│   ├── test_summarizer_agent.py
+│   └── api_tests.py
+│
+├── logs/                        # Fichiers de logs
+├── .env                         # Variables d'environnement
+├── requirements.txt             # Dépendances Python
+└── README.md                    # Documentation principale
+```
+
+---
+
+## 🔧 Architecture Technique
+
+### Diagramme du Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         UTILISATEUR                             │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    LLM ORCHESTRATEUR                            │
+│              (ChatGroq avec LangGraph)                          │
+│  • Analyse la requête utilisateur                               │
+│  • Décide des outils à utiliser                                 │
+│  • Gère le flow de conversation                                 │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+            ┌──────────────┴──────────────┐
+            │                             │
+            ▼                             ▼                              
+┌─────────────────────┐       ┌─────────────────────┐
+│   RECHERCHE CACHE   │       │  NOUVELLE RECHERCHE │
+│                     │       │                     │
+│ • Vérif. cache 24h  │       │ • Pipeline complet  │
+│ • Recherche mémoire │       │ • 4 agents séquence │
+│ • Topics similaires │       │ • Stockage mémoire  │
+└──────────┬──────────┘       └──────────┬──────────┘
+           │                             │
+           │            ┌────────────────┘
+           │            │
+           ▼            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    SYSTÈME DE MÉMOIRE                           │
+│                                                                 │
+│  ┌─────────────────────┐         ┌──────────────────────┐       │
+│  │  MÉMOIRE VECTORIELLE│         │   MÉMOIRE AGENT      │       │
+│  │  (ChromaDB)         │         │ (Cache + Historique) │       │
+│  │                     │         │                      │       │
+│  │ • Embeddings        │         │ • Conversations      │       │
+│  │ • Recherche top-k   │         │ • Cache recherches   │       │
+│  │ • Déduplication     │◄────────┤ • Topics + keywords  │       │
+│  │ • Persistance       │         │ • Compression auto   │       │
+│  └─────────────────────┘         └──────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+                           │
+                           │
+                           ▼
+                   RAPPORT STRUCTURÉ
+              (Markdown, HTML, Text, JSON)
+
+┌──────────────────────────────────────────────────────────────────┐
+│                   PIPELINE DE RECHERCHE                          │
+│                                                                  │
+│  ┌─────────────┐   ┌─────────────┐   ┌──────────────┐            │
+│  │   AGENT 1   │   │   AGENT 2   │   │   AGENT 3    │            │
+│  │ RESEARCHER  │──►│  EXTRACTOR  │──►│ SUMMARIZER   │            │
+│  │             │   │             │   │              │            │
+│  │ • Tavily    │   │ • Parsing   │   │ • LLM        │            │
+│  │ • Serper    │   │ • Nettoyage │   │ • Chunking   │            │
+│  │ • Keywords  │   │ • Validation│   │ • Points-clés│            │
+│  └─────────────┘   └─────────────┘   └──────┬───────┘            │
+│                                             │                    │
+│                                             ▼                    │
+│                                    ┌──────────────────┐          │
+│                                    │     AGENT 4      │          │
+│                                    │GLOBAL SYNTHESIZER│          │
+│                                    │                  │          │
+│                                    │ • Thèmes         │          │
+│                                    │ • Consensus      │          │
+│                                    │ • Rapport final  │          │
+│                                    └──────────────────┘          │
+└──────────────────────────────────────────────────────────────────┘
+
+```
+
+---
+
+## 🤖 Description des Agents
+
+### 1. 🔍 ResearcherAgent
+**Rôle** : Recherche web et extraction de mots-clés
+
+**Responsabilités** :
+- Extraction automatique de mots-clés via LLM
+- Recherche multi-API (Tavily, Serper)
+- Filtrage et validation des résultats
+- Gestion du rate limiting
+
+**Inputs** :
+```python
+ResearchQuery(
+    topic: str,
+    keywords: List[str],
+    max_results: int = 10,
+    search_depth: str = "basic"
+)
+```
+
+**Outputs** :
+```python
+ResearchOutput(
+    results: List[SearchResult],
+    total_found: int,
+    search_engine: str,
+    search_time: float
+)
+```
+
+### 2. 📄 ContentExtractorAgent
+**Rôle** : Extraction et nettoyage du contenu web
+
+**Responsabilités** :
+- Parsing HTML avec BeautifulSoup
+- Nettoyage et normalisation du texte
+- Détection du type de document
+- Validation de la qualité
+
+**Inputs** :
+```python
+ResearchOutput  # Provient du ResearcherAgent
+```
+
+**Outputs** :
+```python
+ExtractionResult(
+    documents: List[Document],
+    successful_extractions: int,
+    failed_urls: List[str],
+    extraction_stats: Dict
+)
+```
+
+### 3. 📝 SummarizerAgent
+**Rôle** : Génération de résumés détaillés
+
+**Responsabilités** :
+- Découpage intelligent du texte (chunking)
+- Résumés exécutifs et détaillés
+- Extraction de points-clés et arguments
+- Analyse de sentiment et crédibilité
+
+**Inputs** :
+```python
+ExtractionResult  # Provient du ContentExtractorAgent
+```
+
+**Outputs** :
+```python
+SummarizationOutput(
+    summaries: List[DocumentSummary],
+    total_documents: int,
+    average_credibility: float,
+    common_themes: List[str]
+)
+```
+
+### 4. 🎯 GlobalSynthesizerAgent
+**Rôle** : Synthèse globale et génération de rapport
+
+**Responsabilités** :
+- Analyse thématique transversale
+- Identification de consensus et conflits
+- Génération de rapport structuré
+- Export multi-format (Markdown, HTML, Text)
+
+**Inputs** :
+```python
+SummarizationOutput  # Provient du SummarizerAgent
+```
+
+**Outputs** :
+```python
+GlobalSynthesisOutput(
+    final_report: FinalReport,
+    synthesis_metadata: Dict,
+    processing_stats: Dict,
+    formatted_outputs: Dict[str, str]
+)
+```
+
+---
+
+## 💾 Système de Mémoire
+
+### Architecture de la Mémoire
+
+Le système utilise **deux types de mémoire complémentaires** :
+
+#### 1. 🗄️ Mémoire Vectorielle (ChromaDB)
+
+```python
+VectorMemoryManager(
+    persist_directory="./chroma_db",
+    collection_name="research_documents",
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2"
+)
+```
+
+**Fonctionnalités** :
+- **Embeddings** : Modèles HuggingFace pour représentation vectorielle
+- **Recherche sémantique** : Top-K avec scores de similarité cosinus
+- **Déduplication** : Hash MD5 pour éviter les doublons
+- **Persistance** : Stockage permanent sur disque
+- **Nettoyage auto** : Suppression des documents > 30 jours
+
+**Méthodes principales** :
+```python
+# Ajout de documents
+stats = vector_memory.add_documents(
+    documents=[{
+        'content': "...",
+        'title': "...",
+        'url': "..."
+    }],
+    source='research',
+    check_duplicates=True
+)
+
+# Recherche sémantique
+results = vector_memory.semantic_search(
+    query="intelligence artificielle",
+    k=5,
+    filter_dict={'source': 'research'}
+)
+
+# Nettoyage
+deleted = vector_memory.clear_old_documents(days=30)
+```
+
+#### 2. 🧠 Mémoire d'Agent (Cache + Historique)
+
+```python
+AgentMemoryManager(
+    memory_file="./agent_memory.pkl",
+    max_history=100,
+    compression_threshold=50
+)
+```
+
+**Fonctionnalités** :
+- **Historique conversationnel** : Deque avec limite (100 entrées)
+- **Cache des recherches** : TTL 24h par défaut
+- **Keywords tracking** : Association topic → keywords
+- **Compression auto** : Après 50 entrées
+- **Persistance pickle** : Sauvegarde sur disque
+
+**Méthodes principales** :
+```python
+# Ajouter une conversation
+agent_memory.add_conversation(
+    user_message="Résume l'IA",
+    assistant_response="...",
+    metadata={'sources': 5}
+)
+
+# Récupérer du cache
+result = agent_memory.get_research_result(
+    topic="intelligence artificielle",
+    max_age_hours=24
+)
+
+# Topics similaires
+related = agent_memory.get_related_topics(
+    topic="IA dans la santé",
+    threshold=0.5
+)
+```
+
+### 🔗 Système Intégré
+
+```python
+IntegratedMemorySystem()
+```
+
+Combine les deux mémoires pour :
+- Stockage automatique de tous les résultats de recherche
+- Récupération intelligente du contexte
+- Vérification du cache avant nouvelle recherche
+- Enrichissement des réponses avec contexte historique
+
+---
+
+## 🛠️ Installation
+
+### Prérequis
+
+- **Python** : 3.12+
+- **Pip** : version récente
+- **Git** : pour cloner le projet
+
+### Étapes d'installation
+
+```bash
+# 1. Cloner le projet
+git clone https://github.com/votre-repo/ai-research-assistant.git
+cd ai-research-assistant
+
+# 2. Créer un environnement virtuel
+python -m venv venv
+
+# Activer l'environnement
+# Windows
+venv\Scripts\activate
+# Linux/Mac
+source venv/bin/activate
+
+# 3. Installer les dépendances
+pip install -r requirements.txt
+
+# 4. Configurer les variables d'environnement
+cp .env.example .env
+# Éditer .env avec vos clés API
+```
+
+### Configuration `.env`
+
+```env
+# LLM
+GROQ_API_KEY=your_groq_api_key_here
+
+# Search APIs
+TAVILY_API_KEY=your_tavily_api_key_here
+SERPER_API_KEY=your_serper_api_key_here
+
+# Optional
+LOG_LEVEL=INFO
+MAX_RETRIES=3
+TIMEOUT=30
+```
+
+---
+############################################################################
+## 🚀 Utilisation
+
+### Mode CLI Direct
+
+```bash
+# Recherche simple
+python src/graph.py "impact de l'IA sur l'emploi"
+
+# Mode test
+python src/graph.py test
+
+# Statistiques mémoire
+python src/graph.py stats
+```
+
+### Mode Interactif
+
+```python
+from src.graph import app_with_memory, run_test
+
+# Lancer une recherche
+run_test("Résume les énergies renouvelables", "Ma recherche")
+
+# Ou utiliser directement le graphe
+inputs = {"messages": [("user", "Résume l'IA dans la santé")]}
+for state in app_with_memory.stream(inputs, stream_mode="values"):
+    print(state["messages"][-1])
+```
+
+### Mode Menu Interactif
+
+```bash
+python tests/test_memory_system.py
+```
+
+Menu disponible :
+```
+1. Poser une question / Lancer une recherche
+2. Rechercher dans la mémoire
+3. Voir l'historique
+4. Statistiques de la mémoire
+5. Lancer la suite de tests
+6. Réinitialiser la mémoire
+0. Quitter
+```
+
+### Intégration dans votre code
+
+```python
+
+from src.agents.researcher_agent import ResearcherAgent
+from src.agents.content_extractor_agent import ContentExtractorAgent
+from src.agents.summarizer_agent import SummarizerAgent
+from src.agents.global_synthesizer_agent import GlobalSynthesizerAgent
+from src.models.research_models import ResearchQuery
+
+# Initialiser les agents
+researcher = ResearcherAgent()
+extractor = ContentExtractorAgent()
+summarizer = SummarizerAgent()
+synthesizer = GlobalSynthesizerAgent()
+
+# Pipeline complet
+async def recherche_complete(topic: str):
+    # 1. Recherche
+    query = ResearchQuery(
+        topic=topic,
+        keywords=await researcher.extract_keywords_with_llm(topic),
+        max_results=5
+    )
+    research_data = await researcher.process(query)
+    
+    # 2. Extraction
+    extraction_data = await extractor.process_from_research_output(
+        research_output=research_data
+    )
+    
+    # 3. Résumés
+    summarization_data = await summarizer.process_from_extraction_result(
+        extraction_result=extraction_data
+    )
+    
+    # 4. Synthèse
+    synthesis = await synthesizer.process_from_summarization_output(
+        summarization_output=summarization_data
+    )
+    
+    return synthesis.final_report.formatted_outputs['markdown']
+```
+
+---
+
+## 📊 Exemples d'Utilisation
+
+### Exemple 1 : Recherche Simple avec Cache
+
+```python
+# Première recherche (pipeline complet)
+inputs = {
+    "messages": [
+        ("user", "Résume l'impact de l'IA sur le marché du travail")
+    ]
+}
+
+for state in app_with_memory.stream(inputs):
+    print(state["messages"][-1].content)
+
+# Résultat : Pipeline complet exécuté, résultats mis en cache
+
+# Même recherche 10 minutes après (utilise le cache)
+inputs = {
+    "messages": [
+        ("user", "Rappelle-moi ce que tu as trouvé sur l'IA et l'emploi")
+    ]
+}
+
+for state in app_with_memory.stream(inputs):
+    print(state["messages"][-1].content)
+
+# Résultat : Réponse instantanée depuis le cache
+```
+
+### Exemple 2 : Recherche dans la Mémoire
+
+```python
+# Après plusieurs recherches sur l'IA
+inputs = {
+    "messages": [
+        ("user", "Qu'as-tu trouvé sur l'intelligence artificielle ?")
+    ]
+}
+
+# Le LLM utilise automatiquement search_in_memory
+# au lieu de lancer une nouvelle recherche web
+```
+
+### Exemple 3 : Historique et Statistiques
+
+```python
+from src.memory_system import memory_system
+
+# Voir l'historique
+history = list(memory_system.agent_memory.conversation_history)
+for conv in history[-5:]:
+    print(f"{conv['timestamp']}: {conv['user']}")
+
+# Statistiques
+print(f"Documents en mémoire: {memory_system.vector_memory.collection.count()}")
+print(f"Recherches en cache: {len(memory_system.agent_memory.research_cache)}")
+```
+
+### Exemple 4 : Recherche Approfondie
+
+```python
+from src.memory_integration import research_complete_pipeline_with_memory
+
+# Recherche avec plus de sources
+result = research_complete_pipeline_with_memory(
+    topic="énergies renouvelables et transition écologique",
+    max_results=10,  # Plus de sources
+    use_cache=False  # Forcer une nouvelle recherche
+)
+
+print(result)  # Rapport Markdown complet
+```
+
+---
+
+
+## 📝 Logs et Monitoring
+
+### Structure des logs
+
+```
+logs/
+├── agent_researcher.log          # Recherche web
+├── agent_content_extractor.log   # Extraction
+├── agent_summarizer.log          # R��sumés
+├── agent_global_synthesizer.log  # Synthèse
+├── search_manager.log            # APIs de recherche
+├── llm_service.log               # Appels LLM
+└── complete_pipeline.log         # Pipeline complet
+```
+
+### Niveaux de log
+
+```python
+# Dans config/settings.py
+LOG_LEVEL = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+### Exemple de logs
+
+```
+2025-11-18 10:30:15 | INFO | agent_researcher | Recherche pour: "IA emploi"
+2025-11-18 10:30:18 | INFO | agent_researcher | Trouvé 5 sources
+2025-11-18 10:30:20 | INFO | agent_content_extractor | Extraction: 5/5 succès
+2025-11-18 10:30:45 | INFO | agent_summarizer | 5 résumés générés
+2025-11-18 10:31:10 | INFO | agent_global_synthesizer | Rapport: 1250 mots
+2025-11-18 10:31:12 | INFO | memory_system | Stockage en mémoire réussi
+```
+
+---
+
+## ⚙️ Configuration Avancée
+
+### Personnaliser les prompts
+
+```python
+# config/prompts.py
+
+CUSTOM_RESEARCH_PROMPT = """
+Analyse approfondie sur {topic}.
+Focus sur les aspects suivants :
+- Impact économique
+- Implications sociales
+- Perspectives futures
+"""
+
+# Utilisation
+from config.prompts import CUSTOM_RESEARCH_PROMPT
+
+prompt = CUSTOM_RESEARCH_PROMPT.format(topic="IA générative")
+```
+
+### Ajuster les paramètres LLM
+
+```python
+# src/services/llm_service.py
+
+class LLMService:
+    def __init__(self):
+        self.model = ChatGroq(
+            model="llama-3.1-8b-instant",
+            temperature=0.3,      # Créativité (0-1)
+            max_tokens=2048,      # Longueur max
+            top_p=0.9,           # Nucleus sampling
+            frequency_penalty=0.5 # Pénalité répétition
+        )
+```
+
+### Configurer la mémoire vectorielle
+
+```python
+# src/memory_system.py
+
+vector_memory = VectorMemoryManager(
+    persist_directory="./custom_chroma_db",
+    collection_name="my_research_docs",
+    embedding_model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"  # Multilingue
+)
+```
+
+---
+
+## 🔌 Intégration API(Futur)
+
+### REST API (FastAPI)
+
+```python
+# api/main.py
+from fastapi import FastAPI
+from src.graph import app_with_memory
+
+app = FastAPI()
+
+@app.post("/research")
+async def research_endpoint(topic: str, max_results: int = 3):
+    inputs = {"messages": [("user", f"Résume: {topic}")]}
+    result = []
+    
+    for state in app_with_memory.stream(inputs):
+        result.append(state["messages"][-1].content)
+    
+    return {"result": result[-1]}
+```
+
+### WebSocket (temps réel)
+
+```python
+from fastapi import WebSocket
+
+@app.websocket("/ws/research")
+async def websocket_research(websocket: WebSocket):
+    await websocket.accept()
+    
+    while True:
+        data = await websocket.receive_text()
+        inputs = {"messages": [("user", data)]}
+        
+        for state in app_with_memory.stream(inputs):
+            await websocket.send_text(
+                state["messages"][-1].content
+            )
+```
+
+---
+
+## 🐛 Dépannage
+
+### Problèmes courants
+
+#### 1. Erreur de clé API manquante
+
+```
+ValueError: GROQ_API_KEY non définie
+```
+
+**Solution** : Vérifier le fichier `.env` et s'assurer que les clés sont présentes.
+
+
+#### 3. Rate limit atteint
+
+```
+WARNING | llm_service | Rate limit atteint, attente 12s
+```
+
+**Solution** : C'est normal, le système attend automatiquement. Pour éviter :
+- Réduire `max_results`
+
+#### 4. Mémoire saturée
+
+```
+MemoryError: Cannot allocate memory
+```
+
+**Solution** : Nettoyer la mémoire :
+```
+memory_system.vector_memory.clear_old_documents(days=7)
+```
+
+---
+
+```bash
+# Build
+docker build -t ai-research-assistant .
+
+# Run
+docker run -e GROQ_API_KEY=xxx -e TAVILY_API_KEY=yyy ai-research-assistant
+```
+
+### Production (Gunicorn)
+
+```bash
+gunicorn api.main:app --workers 4 --bind 0.0.0.0:8000
+```
+
+---
+
+## 📈 Roadmap
+
+### Version 1.1 (En cours)
+- [ ] Interface web avec Streamlit
+- [ ] Support multilingue complet
+- [ ] Export PDF des rapports
+- [ ] Notifications par email
+
+### Version 2.0 (Futur)
+- [ ] Agents spécialisés par domaine (santé, finance, tech)
+- [ ] Intégration avec bases de données externes
+- [ ] Système de fact-checking automatique
+- [ ] API GraphQL
+
+---
+
+## 🤝 Contribution
+
+Les contributions sont les bienvenues !
+
+---
+
+## 👥 Auteurs
+
+- **Bachir** - *Développeur Principal* - [GitHub](https://github.com/bachir00)
+
+---
+
+## 🙏 Remerciements
+
+- LangChain & LangGraph pour le framework
+- Groq pour l'accès aux LLMs
+- ChromaDB pour le stockage vectoriel
+- Tavily & Serper pour les APIs de recherche
+- La communauté open-source
+
+---
+
+## 📞 Support
+
+- 📧 Email : bassiroukane@esp.sn