Metadata-Version: 2.4
Name: doctum-agent
Version: 0.5.2
Summary: Agents de code spécialisés dans le terminal : un modèle LLM par agent, sur n'importe quel back-end.
Author: Yann Smatti
License-Expression: MIT
Project-URL: Homepage, https://github.com/doctum-consilium/doctum-code-agent
Project-URL: Repository, https://github.com/doctum-consilium/doctum-code-agent
Project-URL: Issues, https://github.com/doctum-consilium/doctum-code-agent/issues
Keywords: ai,agent,cli,tui,llm,coding-agent,ollama,litellm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Classifier: Natural Language :: French
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: litellm>=1.40.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: textual>=1.0
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# Doctum Code Agent — l'agent de code spécialisé en cybersécurité

**Ce que c'est.** Un système d'agents de code — chacun sur **son propre modèle LLM**, choisi et
mesuré rôle par rôle — dont la raison d'être est la **cybersécurité** : auditer du code pour ses
failles, imposer le secure-by-default, tracer pour la conformité, épauler une revue de sécurité
autorisée. Le développement assisté n'est qu'une de ses faces.

> **Défensif et autorisé, jamais offensif.** Le produit aide à *trouver et corriger* des failles,
> à sécuriser, à se conformer — pour du code qu'on a le droit d'auditer. Il n'aide pas à attaquer
> des tiers, à contourner une protection, ni à produire un logiciel malveillant. Cette frontière
> est écrite dans les CGU et imposée dans les fiches de rôle **côté serveur**, que le client ne
> peut pas modifier.

Ce dépôt porte le **cœur** (`doctum_agent`) : la boucle d'orchestration, les fiches de rôle,
l'attelage (quel modèle pour quel rôle), le cockpit terminal, et le **service d'accueil** de
l'architecture live. Le client mince en Rust vit dans `doctum-code-agent-rust`. La façade VS Code
vit dans `doctum-ai-ide-mvp`.

---

## Le produit en une page — et comment il se vend

### Les trois piliers de vente

| Pilier | Ce qu'on démontre | Comment on le prouve |
|---|---|---|
| **Cybersécurité** | exécution contrôlée, auditée, révocable | le plan de contrôle serveur (architecture live) |
| **Attelage mesuré** | le bon modèle pour chaque rôle, prouvé | le banc de benchmark, publié |
| **Performance** | plus rapide à réglage égal | le cœur en Rust, chronométré |

### La douve : ce qui a de la valeur, et pourquoi

L'actif du produit **n'est pas le code** de la boucle (quelques centaines de lignes d'orchestration,
réécrites en une semaine par quelqu'un de compétent). C'est **l'attelage mesuré** : quel modèle
tient quel rôle, à quel coût, avec quelle fiabilité — issu de campagnes de benchmark entières
(des centaines d'exécutions, une douzaine de dollars chacune, répétées sur des semaines). Personne
ne peut le refaire sans dépenser ce qu'on a dépensé **et** sans avoir construit le banc qui le
produit.

La protection ne repose donc pas sur l'opacité d'un binaire (un binaire se désassemble), mais sur
le fait que **la douve ne soit pas chez le client** : dans l'architecture live, la boucle et
l'attelage vivent sur le serveur ; le client ne voit que les ordres d'outils à exécuter.

### Deux versions, un seul cœur mesuré

|  | **Basique** (local) | **Cybersécurité** (contrôlé, live) |
|---|---|---|
| Où tourne la boucle | sur la machine du client | sur le serveur, en liaison WebSocket |
| Mode hors ligne | **oui** — repli 7 jours | non, par conception (c'est la garantie) |
| L'attelage | livré signé, en mémoire, marqué au compte | ne quitte **jamais** le serveur |
| Rôles | codeur, relecteur, testeur — généralistes | + auditeur de failles, relecteur sécurité, CVE |
| Audit / politique / masquage des secrets | non | **oui — le plan de contrôle** |
| Public | développeur, petite équipe | client réglementé, exigence de conformité |
| Prix | l'offre courante | **premium**, l'option cybersécurité |

Un seul moteur mesuré derrière les deux : la boucle et l'attelage sont les mêmes, seul change **où**
la boucle s'exécute et **ce que le serveur impose autour**.

### Le business model — comment on facture

La vente passe par la passerelle de facturation (`litellm-gateway-vps`, boutique
`agent.doctumconsilium.com`) :

- **crédit prépayé** (`recharge_10 / 25 / 50`) et **abonnements** (`mensuel_19 / 49`) via Stripe ;
- chaque compte est un **locataire** avec une **clé** et un **plafond** ; aucun compte n'est sans
  plafond, l'administrateur compris. La consommation de modèle est comptée et bornée par le plafond ;
- les **appels de modèle sont facturés au compte du client**, sur sa propre clé (par session, jamais
  une clé globale partagée) ;
- **l'attelage est un service** : il s'améliore à chaque campagne de banc, sans que le client
  réinstalle. C'est ce qui rend le rythme de livraison directement monétisable ;
- **la version cybersécurité facture l'architecture elle-même** : chaque action autorisée par une
  politique avant exécution, piste d'audit infalsifiable, masquage centralisé des secrets, moindre
  privilège, révocation instantanée — ce qu'un binaire local ne peut pas garantir, et ce qu'un
  client réglementé réclame.

Le business model de la plateforme (au sens large, tous produits) est décrit côté passerelle :
`litellm-gateway-vps/docs/modele-economique`.

### L'architecture live, en deux rôles nets

| Côté serveur (la douve, invisible au client) | Côté client (un exécuteur mince) |
|---|---|
| la boucle du contrôleur — quoi faire, dans quel ordre | recevoir un ordre d'outil et l'exécuter **sur sa machine** |
| l'attelage — quel modèle pour quel rôle | lire un fichier, lancer une commande, renvoyer le résultat |
| les fiches de rôle et leurs consignes de sécurité | afficher à l'utilisateur ce qui se passe |
| le RAG cybersécurité (corpus de documents) | *(ne voit ni le corpus, ni les modèles, ni les consignes)* |

Le fil de la session est un **canal WebSocket** : le serveur pilote, le client exécute et rapporte.
Le client ne voit jamais quel modèle a été appelé, avec quelle consigne, ni pourquoi. Le **client
Rust** est idéal ici : quelques milliers de lignes, sans dépendance, démarrage instantané, et
**vide de secret** — même parfaitement désassemblé, il ne livre rien.

> Le récit complet du produit, des arbitrages et de la séquence de livraison :
> [docs/plans/2026-08-04-agent-cyber-live-et-rag.md](docs/plans/2026-08-04-agent-cyber-live-et-rag.md).

---

## Où aller, selon ce que tu cherches

| Tu veux… | Va voir |
|---|---|
| **comprendre le produit et son business model** | cette page, section ci-dessus |
| **l'essayer maintenant** (version basique, local) | [ONBOARDING.md](ONBOARDING.md) |
| **l'exploiter** : ce qui tourne, où, en prod | [INFRASTRUCTURE.md](INFRASTRUCTURE.md) |
| le **client Rust** (version cybersécurité) | dépôt `doctum-code-agent-rust` |
| la **vente / facturation** | dépôt `litellm-gateway-vps` (boutique, crédits, Stripe) |
| **modifier le code**, comprendre l'intérieur | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| savoir **où on en est** | [ROADMAP.md](ROADMAP.md) · [docs/SESSION-STATE.md](docs/SESSION-STATE.md) |

---

# La version basique (locale) — référence d'usage

Tout ce qui suit décrit le socle tel qu'il tourne **en local**, dans le terminal. C'est la version
basique, et c'est aussi le moteur que l'architecture live pilote côté serveur.

```bash
npm install -g @doctum/code-agent     # ou : uv tool install doctum-agent
doctum
```

## Le cockpit

`doctum` ouvre une interface plein écran qui montre, **pendant que ça travaille** :

- **qui parle** — une couleur par agent ;
- **sur quel modèle** — voir l'explorateur tourner sur un petit modèle pendant que l'orchestrateur
  tourne sur un gros ;
- **ce qu'il fait** — chaque appel d'outil et son résultat ;
- **ce que ça coûte** — jetons et dollars, à jour à chaque tour ;
- **ce qu'il attend de vous** — une action sensible **suspend le travail** et affiche la commande
  exacte avec son motif. Rien ne s'exécute avant votre réponse.

| Touche | Effet |
|---|---|
| `Entrée` | envoyer la demande |
| `F2` | **réglages** — modèle de chaque agent, back-ends, politique, budget |
| `F3` | afficher / masquer le panneau latéral |
| `F4` | écrire le journal de la séance sur disque |
| `Ctrl+L` | effacer l'affichage (le journal de séance reste intact) |
| `Ctrl+Q` | quitter |

Dans la modale d'approbation : `o` autorise, `n` ou `Échap` refuse — refuser reste le geste le
plus facile, c'est la réponse sûre.

## Les réglages, sans toucher au YAML

`F2` ouvre quatre onglets : **Agents & modèles**, **Back-ends**, **Clés d'API**,
**Politique & budget**. « Enregistrer » écrit `.doctum/config.yaml` du projet courant. **Aucune clé
n'y figure jamais** : seulement le *nom* de la variable d'environnement.

## Les clés d'API — depuis l'interface, une seule fois

`F2` → **Clés d'API** → `Entrée` sur la ligne du back-end. La saisie est **masquée**, une clé déjà
en place n'est **jamais réaffichée**. Les clés vont dans `~/.doctum/credentials`, en `0600`, **hors
de tout dépôt** — c'est ce qui fait que `doctum` marche depuis n'importe quel répertoire.

Ordre de précédence, du plus fort au plus faible :

| Source | Quand elle gagne |
|---|---|
| `export DOCTUM_LLM_API_KEY=…` | toujours — l'explicite l'emporte |
| `.env` du projet | si l'environnement est muet |
| `~/.doctum/credentials` | le repli, valable partout |

## Installation

**Par npm** (lanceur, installe le socle Python via `uv` au premier démarrage — pas besoin d'avoir
Python) :

```bash
npm install -g @doctum/code-agent && doctum
```

**Par Python, depuis le dépôt privé** (AWS CodeArtifact) :

```bash
bash scripts/installer-prive.sh          # la dernière version
bash scripts/installer-prive.sh 0.5.0    # une version précise
```

> `doctum-agent` existe aussi sur PyPI, mais **c'est un paquet vide** qui ne fait que réserver le
> nom. Toujours `--index-url` (jamais `--extra-index-url`) pour éviter la confusion de dépendances.

**Depuis un wheel GitHub, sans compte AWS** :

```bash
gh release download --repo doctum-consilium/doctum-code-agent --pattern '*.whl'
uv tool install ./doctum_agent-*.whl
```

L'accès au dépôt privé fait l'autorisation : qui n'y a pas accès ne peut rien installer.

## N'importe quel back-end, décrit dans le `.env`

Un **back-end** est un fournisseur de modèles nommé. Son `kind` dit comment l'atteindre :
`litellm` (la passerelle), `lmstudio`, `openai_compatible` (vLLM, TGI, OpenRouter), `ollama`,
`native` (Anthropic, OpenAI, DeepSeek… en direct). **Aucune clé n'est jamais écrite dans un fichier
suivi par git** : le back-end nomme sa variable d'environnement et le socle la lit.

## Les agents livrés, et leur modèle

Chaque agent pointe vers un **rôle**, et chaque rôle vers un couple (back-end, modèle) — c'est
l'**attelage**. Voir le routage réel : `doctum --show-config`.

| Agent | Rôle | Modèle par défaut | Ses outils |
|---|---|---|---|
| `orchestrator` | `orchestrator` | `bedrock-claude-opus-4-6` | tous, dont la délégation |
| `coder` | `coder` | `bedrock-claude-sonnet-4-5` | lecture, écriture, patch, shell |
| `explorer` | `explorer` | `bedrock-qwen3-coder-30b-a3b` | **lecture seule** |
| `reviewer` | `reviewer` | `scw-glm-5.2` | lecture + shell, **pas d'écriture** |
| `tester` | `tester` | `bedrock-claude-haiku-4-5` | lecture + shell |
| `security` | `security` | `bedrock-gpt-oss-safeguard-120b` | lecture + shell |
| `docs` | `docs` | `scw-mistral-medium-3.5` | lecture + écriture |

Un agent qui n'a pas d'outil d'écriture **ne peut pas** écrire, quoi qu'il en décide. La
spécialisation est structurelle, pas déclarative.

## Pourquoi plusieurs modèles, et pas un seul

1. **Le rôle dicte la classe de modèle.** Fouiller un dépôt et concevoir une architecture ne
   demandent pas la même puissance — ni le même prix.
2. **Les erreurs se décorrèlent.** Le relecteur tourne délibérément sur un modèle d'un **autre
   fournisseur** que le codeur : un modèle valide ses propres angles morts (vérifié par un test).
3. **La fenêtre reste propre.** Un délégué ne voit que sa consigne, jamais l'historique du parent.

## Sécurité (du socle lui-même)

- **Prison de chemins** : tout accès est résolu **puis** vérifié sous la racine — liens symboliques
  compris.
- **Classement des commandes**, segment par segment (`ls; rm -rf ~` est refusé).
- **Trois crans** : `read_only`, `workspace_write` (défaut), `full_access` ; **réseau refusé** hors
  `full_access`.
- **Trois verdicts** : autorisé / à confirmer / refusé. L'inconnu **demande** au lieu de bloquer.
- **Budget dur** : tours, jetons et coût, **partagé** avec les délégués.
- Tout contenu tiers (fichier lu, sortie shell, page web, **passage RAG**) est **encadré**
  anti-injection avant d'entrer dans la fenêtre du modèle.

Modèle de menace complet : [docs/SECURITE.md](docs/SECURITE.md).

## Personnaliser sans forker

- **Les modèles** — `.doctum/config.yaml` (surcharge partielle d'un back-end, rôle → modèle,
  `fallback`, `approval_mode`, `max_cost_usd`).
- **Les agents** — `.doctum/agents/<nom>.md` (frontmatter + corps = prompt système ; un fichier qui
  reprend le nom d'un agent livré le **remplace**).
- **La mémoire du projet** — `AGENTS.md`/`CLAUDE.md` (toujours injectés) ;
  `.doctum/microagents/*.md` (injectés seulement si la demande contient un de leurs mots-clés).

## Tests

```bash
bash scripts/ci_local.sh                     # miroir de la CI : tests, ruff, couverture
pytest -q --cov=doctum_agent                 # les tests seuls
```

**Aucun test ne fait d'appel LLM réel, ni la moindre requête réseau.** `LLMClient` accepte une
`completion_fn` injectable ; les tests lui passent un modèle scripté. Toute la boucle est exercée —
délégation, approbations, budget, mémoire, canal live — plus le cockpit via le pilote Textual.

## Documentation

| Document | Niveau | Pour qui |
|---|---|---|
| [ONBOARDING.md](ONBOARDING.md) | prise en main | quiconque veut l'essayer |
| [docs/FONCTIONNALITES.md](docs/FONCTIONNALITES.md) | fonctionnel | ce que l'outil fait |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | technique | qui va modifier le code |
| [INFRASTRUCTURE.md](INFRASTRUCTURE.md) | exploitation | ce qui tourne en prod, et comment diagnostiquer |
| [ROADMAP.md](ROADMAP.md) | journal | ce qui a été livré, quand, et ce qui reste |
| [docs/plans/](docs/plans/) | mémoire | ce qu'on a tenté, pourquoi, et ce qu'on a appris |
