Metadata-Version: 2.4
Name: doctum-agent
Version: 0.5.3
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
Requires-Dist: websocket-client<2,>=1.8
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) |

---

## État des clients — 2026-08-08

- `doctum-agent 0.5.3` est le correctif à installer pour l'édition gratuite : il explique à une
  installation ancienne comment se mettre à jour, au lieu d'afficher un faux refus de licence.
  Les versions `0.0.0`, `0.5.0` et `0.5.1` sont retirées du choix automatique de PyPI.
- `doctum-pro 0.1.9` est publié : Linux, macOS et Windows sont signés dans Nexus, et
  `stable/latest.json` propose cette version. Le tag `v0.1.8` reste une livraison incomplète non
  proposée automatiquement.
- L'extension VS Code `0.4.0` garde un historique local par espace de travail. Elle propose soit
  les modèles personnels (édition gratuite), soit la gateway LiteLLM Doctum ; les préréglages ne
  sont appliqués qu'à la demande, pour un compte administrateur vérifié.

Le serveur `doctum-accueil` n'est pas concerné par ces changements de clients : aucun nouveau
déploiement Kubernetes n'est requis pour les utiliser.

### Réglages administrés des éditions payantes

### Choisir BYOK ou Gateway dans Doctum Agent

Après `doctum --connexion toi@exemple.fr`, Doctum conserve seulement un jeton de renouvellement
opaque dans le coffre local `~/.doctum/credentials` (permissions 0600). La clé virtuelle LiteLLM,
les budgets et le catalogue interne restent côté serveur. Choisis ensuite explicitement :

```bash
doctum                         # Agent BYOK local, toujours disponible, sans conteneur
doctum --edition gateway       # Gateway Doctum si abonnement actif et crédits disponibles
```

Quand l'abonnement se termine, Gateway disparaît automatiquement et l'outil revient à BYOK. Quand
l'abonnement est actif mais le solde à zéro, Gateway reste visible mais refuse l'envoi avec un lien
de recharge. `doctum-pro` est distinct : lui seul impose Docker ou Podman et n'accepte jamais BYOK.

Le cockpit `doctum-comptes` est l'autorité des réglages Pro : catalogue de modèles, profils,
niveaux de créativité, politique d'outils et disponibilité RAG. `doctum-accueil` lit ce contrat
versionné avec un jeton de produit interne et ne transmet aux clients que les choix autorisés. Ni
clé de fournisseur, ni budget LiteLLM, ni secret d'administration ne sortent du cluster.

Si le cockpit est temporairement indisponible, la réponse indique `disponible: false` sans
inventer de modèle ou de préréglage ; une session déjà ouverte reste utilisable. Cette intégration
est livrée localement et n'est pas encore déployée.

Quand le catalogue active RAG, l'accueil récupère le `tenant` depuis la facturation après
validation de la clé puis l'impose à la requête vectorielle. Ni la tâche, ni le modèle, ni un
client ne peuvent modifier ce périmètre ; les passages sont toujours encadrés comme données non
fiables avant le raisonnement.

---

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