testpush / README.md
Bachir00's picture
Remove secrets from README
d7a85d8
# 📚 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