README.md

📚 AI Research Assistant - Documentation Complète

🎯 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 :

ResearchQuery(
    topic: str,
    keywords: List[str],
    max_results: int = 10,
    search_depth: str = "basic"
)

Outputs :

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 :

ResearchOutput  # Provient du ResearcherAgent

Outputs :

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 :

ExtractionResult  # Provient du ContentExtractorAgent

Outputs :

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 :

SummarizationOutput  # Provient du SummarizerAgent

Outputs :

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)

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 :

# 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)

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 :

# 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é

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

# 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

# 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

# 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

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

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

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

# 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

# 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

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

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

# 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

# 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

# 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

# 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)

# 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)

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)

---

# 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)

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

---

🙏 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