Documentation technique

Section 11.5.12 : Documentation technique

🎯 Objectif pédagogique

Rédiger une documentation technique claire et complète pour votre projet IA. Vous serez capable de documenter votre projet de manière professionnelle pour un portfolio et un entretien technique.

La documentation comme preuve de compétence

Marc a un projet déployé. Maintenant, il faut l'expliquer. En entretien, le recruteur ne va pas tester l'application. Il va lire le README, regarder la structure, et juger en 2 minutes si Marc est un développeur sérieux.

Structure du README professionnel

# 🤖 CareerBot Pro — Assistant IA de Reconversion Tech

> Un chatbot intelligent qui aide les professionnels en reconversion
> vers les métiers tech/data/IA. Construit avec OpenAI GPT-4o,
> ChromaDB (RAG), et déployé sur Streamlit.

![Demo CareerBot Pro](docs/demo-screenshot.png)

🔗 **Démo live** : [careerbot-pro.streamlit.app](https://careerbot-pro.streamlit.app)

---

## ✨ Fonctionnalités

- 💬 **Chat contextuel** — Conversations avec mémoire (résumé automatique)
- 📚 **RAG** — Réponses basées sur une base de connaissances vérifiée
- 🔧 **Tools** — Analyse de profil, plans d'action, recherche documentaire
- 🛡️ **Guardrails** — Filtrage d'injections, PII, et hors-sujet
- 📊 **Dashboard** — Métriques d'usage en temps réel
- 🔗 **Automatisations** — Webhooks Make.com (logging, notifications)

## 🏗️ Architecture

\`\`\`
User → Streamlit UI
         ↓
     Guardrails (validation)
         ↓
     Agent RAG (GPT-4o + Function Calling)
       ├─→ Knowledge Base (ChromaDB)
       ├─→ Tools (analyse, plan, recherche)
       └─→ Memory (résumé automatique)
         ↓
     Response → Analytics → Webhooks
\`\`\`

## 🚀 Installation

\`\`\`bash
# Cloner
git clone https://github.com/votre-user/careerbot-pro.git
cd careerbot-pro

# Installer les dépendances
pip install -r requirements.txt

# Configuration
cp .env.example .env
# Éditer .env avec vos clés API

# Indexer la base de connaissances
python -c "from knowledge import KnowledgeBase; KnowledgeBase().index_directory()"

# Lancer
streamlit run app.py
\`\`\`

## 🔧 Stack technique

| Composant | Technologie |
|-----------|-------------|
| LLM | OpenAI GPT-4o-mini / GPT-4o |
| RAG | ChromaDB (embeddings cosine) |
| Frontend | Streamlit 1.40 |
| Automatisations | Make.com (webhooks) |
| Tests | pytest + pytest-cov |
| Déploiement | Streamlit Community Cloud |

## 📈 Métriques (MVP)

- **347** conversations en 2 semaines de test
- **87%** taux de satisfaction
- **6.3** messages moyens par conversation
- **< 3s** temps de réponse moyen

## 🧪 Tests

\`\`\`bash
# Lancer les tests
pytest tests/ -v

# Avec couverture
pytest tests/ --cov=. --cov-report=html
\`\`\`

## 📁 Structure du projet

\`\`\`
├── app.py           # Point d'entrée Streamlit
├── agent.py         # Agent RAG principal
├── config.py        # Configuration centralisée
├── knowledge.py     # Gestion ChromaDB
├── tools.py         # Définition des outils
├── guardrails.py    # Filtres de sécurité
├── analytics.py     # Tracking d'usage
├── tests/           # Suite de tests
└── data/knowledge/  # Documents source
\`\`\`

## 👤 Auteur

**Marc Dupont** — Reconversion Finance → Tech/IA
- Portfolio : [marc-dupont.dev](https://marc-dupont.dev)
- LinkedIn : [linkedin.com/in/marc-dupont](https://linkedin.com/in/marc-dupont)

Documenter les choix techniques

## 🎯 Décisions techniques (ADR)

### Pourquoi GPT-4o-mini et pas Claude ?
- **Coût** : 0.15$/M tokens vs 3$/M tokens pour Claude 3.5 Sonnet
- **Function Calling** : Natif et stable chez OpenAI
- **Latence** : ~1.5s vs ~2.5s pour une réponse typique
- **Fallback** : GPT-4o pour les requêtes complexes

### Pourquoi ChromaDB et pas Pinecone ?
- **Gratuit** et local (pas de compte cloud)
- **Suffisant** pour < 10 000 documents
- **Simple** : pip install, pas de serveur séparé
- **Migration** facile vers Pinecone si besoin de scale

### Pourquoi Streamlit et pas FastAPI + React ?
- **Vitesse de développement** : 10x plus rapide
- **MVP focus** : Prouver le concept, pas la stack
- **Déploiement** : 3 clics vs infra DevOps complète
- **Migration** possible vers FastAPI + React en v2

🏋️ Exercice pratique (25 minutes)

1. →Rédigez le README complet de votre projet
2. →Ajoutez une capture d'écran de l'application
3. →Rédigez 3 ADR pour vos choix techniques principaux
4. →Demandez à quelqu'un de lire votre README : comprend-il le projet en 30 secondes ?