Documentation Mini Agentic — Fonctionnement de l’assistant

01 — Essence

Ce qu’est Mini Agentic

Assistant CLI local : Ollama, neuf outils fichiers, une boucle identique pour chaque modèle. Après une écriture sans run réussi, une seule relance, puis le texte est la réponse. Les commandes / et le shell passent à côté du modèle. Le mode en ligne est optionnel et consomme des crédits.

Quatre vérités du mode local

Parle à un LLM local via Ollama
Expose neuf outils fichiers : tree, ls, find, grep, read, edit, write, mkdir, run
Confirmation interactive avant chaque run (par défaut) · mode --read-only
Mode direct : / et verbes shell passent à côté du LLM

Commande

Binaire ou scripts : mini-agentic (alias miniagentic).

Marque affichée : Mini Agentic. Paquet Python : miniagentic. URL : mini-agentic.com.

Cœur 0.3 : agent local, neuf outils fichiers, confirmation avant run par défaut, mode --read-only, pas de chargeur de plugins. Mode en ligne optionnel.

02 — Crédits

Crédits et modèles en ligne

Sur la page Crédits : ce qui fait monter la consommation, un estimateur, le catalogue des modèles en ligne, un sélecteur par intention, des exemples et une FAQ.

Ce que vous y trouvez

Facteurs de consommation (modèle, longueur, contexte, réponse, étapes)
Estimateur : une fourchette, pas le débit réel
Tableau et fiches des modèles réellement appelables en ligne
Conseils pour choisir et pour économiser

Ce qui est fiable

Les tarifs et le catalogue viennent du registre réel du service
L’estimateur utilise le même arrondi que le débit
Seuls les modèles en ligne y figurent — pas les modèles locaux Ollama

03 — Tarifs

Formules et prix

Page Tarifs, aussi résumée sur l’accueil. Le prix est celui de l’abonnement. Les crédits indiquent le volume inclus, pas un second montant en euros.

Formules en ligne : prix mensuel et crédits inclus
Formule locale : usage gratuit sur votre ordinateur, sans crédits en ligne
Pour comprendre la consommation : page Crédits

04 — Compte

Compte et terminal

Le compte sert à se connecter, voir les crédits restants et l’activité. Après mini-agentic login ou /cloud login, le navigateur confirme l’autorisation du terminal.

Compte

Affiche l’usage de la période. Quand les crédits sont épuisés, les nouvelles demandes en ligne s’arrêtent ; le mode sur votre ordinateur continue.

Terminal

Le mot de passe reste dans le navigateur. Le terminal reçoit seulement un jeton de session.

05 — Installer

Installer Mini Agentic

Depuis la section Essayer de l’accueil, ou avec les commandes ci-dessous.

Commandes

macOS : télécharger le DMG sur le site
Linux : curl -fsSL https://mini-agentic.com/install.sh | sh
Windows : irm https://mini-agentic.com/install.ps1 | iex

Ensuite

Mode local : Ollama + un modèle. Mode en ligne : compte, formule, puis connexion du terminal. Détail des modèles et des crédits : page Crédits.

06 — Carte

Carte des modules

Feature-Based sous product/miniagentic/. Survole mentalement : chaque nœud s’allume.

cli/lancement.pyLancer, router, afficher

agent/agent.pyask · Ollama · historique

agent/registre.pyRegistre nom → fonction

filesystem/espace.pydetect() · ancre session

filesystem/operations/Disque pur · resolve, read…

filesystem/outils/Wrappers LLM + prompt

cli/interruption/annule la requête en cours

cli/commandes//ls · /find · Session

cli/shell/Verbes shell sans LLM

cli/palette/Complétion prompt_toolkit

07 — Couches

Cinq couches, bas → haut

Règle : la couche 1 ne connaît pas Ollama. Les couches 4–5 peuvent ignorer le LLM.

05Présentation CLIlancement · console · saisie · palette · shell

04Commandes directescli.commandes — /ls, /tree, /find, /grep, /read

03Agent conversationnelagent/agent.py — ask → Ollama → tool_calls

02Registre d’outilsagent.registre + filesystem.outils

01Moteur filesystem + OSoperations · disque · subprocess

Chaîne A

Démarrage — du binaire au premier prompt

main() → Agent.files() → workspace → prompt → outils → banner → REPL.

A1

cli.main()prompt, -w, --model, --host, --plain

A2

Agent.__init__model · history · 40 tours · 120k

A3

workspace.detect()-w → env → cwd

A4

recharger_fichiers()prompt + neuf outils

A5

Sessionagent + modèle + hôte

A6

catalogue en lignesi le nom est dans MODELES_CLOUD

A7

banner + REPLou one-shot, même routage

démarrage

local

Les outils restent dans le workspace. Un chemin qui en sort est refusé. Un absolu situé dedans est accepté et renvoyé en relatif. Les commandes / ne passent pas par ce filtre. Le shell tapé (hors builtins) utilise le même sandbox que run.

Chaîne B

Boucle interactive — routage d’une ligne

Priorité stricte : vide → quit → / → shell → sinon agent.ask. Une frappe pendant ask annule le tour et enchaîne.

1

read_inputPalette ou input() plain

2

quit / exit / q ?Farewell → fin

3

startswith("/") ?commandes.run — zéro LLM

4

verbe shell ?shell.run — zéro LLM

5

sinonagent.ask — chemin LLM

6

show_replyou show_error

routage

local

Chaîne C

Boucle agent LLM / outils

Toute la boucle est dans agent/agent.py · ask(). Le modèle décide des outils. Après une écriture sans run réussi, une seule relance. Le texte suivant est la réponse. Pas de plan persistant.

Tour type

Ajoute le message utilisateur
Allège l’historique si le JSON dépasse CONTEXT_CHAR_BUDGET (défaut 120 000)
Réécrit le message système avec un bloc ÉTAT
Appelle Ollama avec tools.for_llm()
Des tool_calls → exécution → on recommence
Texte vide : une relance. Texte après écriture sans run réussi : une seule relance

Une signature déjà vue depuis la dernière écriture n’est pas réexécutée. Au deuxième doublon, un dernier appel sans outils clôt. Un JSON d’outil cassé est retenté trois fois. Un HTTP 500 est retenté deux fois après réduction de l’historique. Tours épuisés : un résumé sans outils. cancel retire les messages de la requête.

boucle agent

local

Plafonds

Une boucle, tous les modèles

Le nom du modèle ne change ni les tours, ni le budget, ni les outils. La taille change ce que le modèle arrive à mener. Il n’existe pas de MINIAGENTIC_PROFIL.

Variable	Défaut	Effet
`MAX_TOOL_ROUNDS`	40	tours d’outils, puis un résumé sans outils
`CONTEXT_CHAR_BUDGET`	120 000	les vieux résultats d’outils deviennent `compacté:`
`MAX_MALFORMED_RETRIES`	3	reprises après un JSON d’outil rejeté

Choisir un modèle

1B–3B — explorer, éditer un extrait. Cartographier via /ls, /find, /grep
7B–14B — agent fichiers du quotidien, mêmes plafonds
Plus grand — feature sur plusieurs fichiers. La boucle reste celle du 3B

Le prompt demande de ne pas relire un fichier juste après un edit réussi. Ce n’est pas un filtre du runtime.

Mode en ligne, en option

/model list sépare le local et le catalogue en ligne. Un nom absent des deux listes est refusé. Choisir un nom présent seulement en ligne bascule vers l’API Mini Agentic (/cloud login). Au démarrage, un nom du catalogue part aussi vers Mini Agentic s’il n’est pas installé en local. Le chemin par défaut reste l’Ollama local. Consommation et choix de modèle : page Crédits.

Chaîne D

Outils fichiers natifs

Deux couches : filesystem/outils/ (LLM) vs filesystem/operations/ (disque pur, aussi utilisé par /).

Outil LLM	Ops
`tree`	`explore_tree`
`find`	`find_paths`
`grep`	`grep_paths`
`read`	`read_text`
`edit`	`replace_text` — extrait unique, ou plage de lignes
`write`	`write_text`
`mkdir`	`mkdir`
`ls`	`list_entries`
`run`	`run_command` — shell sandboxed si backend dispo, `&&` et pipes, `cd` éphémère

outils fichiers

local

Cage des outils fichiers. read, edit, write, mkdir, tree, ls, find et grep refusent un chemin hors du workspace. run : confirmation interactive par défaut en CLI (--yes pour sauter) · mode --read-only · sandbox multi-backend (bwrap → macos → docker → podman) lorsqu’un backend est installé. Un échec ne défait pas les fichiers. Détail : page Sécurité.

Chaîne E

Registre d’outils

Neuf closures, les mêmes pour chaque modèle. filesystem_tools les enregistre dans Tools. Ollama lit la signature et le bloc Args:. Il n’y a pas de chargeur de plugins.

E1

filesystem_tools()neuf closures sur le workspace

E2

Tools.addclé = nom de la fonction

E3

for_llm()signature + docstring Args

E4

Tools.runexception → {"error": …}

E5

set_workspacerecharge outils et prompt, oublie la conversation

filesystem/outils/adaptateurs.pysurface

from miniagentic.filesystem.outils.adaptateurs import filesystem_tools

tools = filesystem_tools(".")
tools.names()
# tree find grep read edit write mkdir ls run

# Un chemin hors du workspace :
# {"error": "hors du workspace", "path": "…"}

registre

local

Ce que le registre fait

Un argument inconnu unique est recopié sur l’unique paramètre manquant
Toute exception devient {"error": …}, sans remonter au modèle
/tools liste ces neuf noms, rien d’autre

Garde-fous de la boucle

Signature déjà vue depuis la dernière écriture : pas réexécutée
Deuxième répétition : résumé sans outils
Une écriture vide cet ensemble : le même run après un edit repart

Chaîne F

Commandes slash

Deuxième chemin vers le disque — sans Ollama. Aiguillage dans commandes.run.

Commande	Effet
`/ls /tree /find /grep /read`	filesystem.* direct
`/path` · `cd`	workspace, outils rechargés, conversation oubliée
`/tools`	les neuf noms du registre
`/model /reset /history /export /config`	session / Ollama

commandes /

local

Chaîne G

Shell intégré

Orthogonal au modèle. cd change le dossier, recharge les outils et oublie la conversation. Le shell système (ls, rm, …) passe par le même sandbox que l’outil run (hors builtins).

shell

local

Chaîne H

Saisie et palette

La palette aide à saisir — elle ne route pas. Le routage reste dans _interactive.

read_input

--plain / non-TTY → input()
sinon → palette.read_line(session)
Complétion : COMMANDS · SUBCOMMANDS · chemins · modèles · @chemin
@fichier en début de mot est retiré avant ask. note@mail reste

Scénario

Bout en bout

« Quels fichiers Python y a-t-il ? » — du binaire jusqu’à show_reply, sans forcer un outil si le modèle répond déjà en texte.

01

OSscript → cli.main

02

Agent.filesdetect · prompt · tools

03

askle modèle choisit l’outil

04

Ollamadécide find(*.py)

05

Tools.run→ operations.trouver.find_paths → JSON

06

LLMréponse factuelle → show_reply

bout en bout

local

Variante /find *.py : même disque, zéro LLM, beaucoup plus court.

API

Utiliser Mini Agentic hors CLI

Exports : Agent, Tools, workspace.

script.pyAPI

from miniagentic import Agent

agent = Agent.files(workspace=".", model="ministral-3:3b")
print(agent.ask("Liste les fichiers à la racine"))

agent.set_workspace("~/autre")  # outils + prompt, conversation oubliée
agent.reset()                     # nouvelle conversation

api python

local

Glossaire

Vocabulaire Mini Agentic

Mini Agentic: Marque affichée sur le site et dans le produit. Paquet Python : miniagentic. Commande : mini-agentic
Mode local: LLM + outils sur votre ordinateur via Ollama, sans crédits Mini Agentic
Mode en ligne: Modèles du catalogue servi par l’API Mini Agentic. Consomme des crédits. Commandes CLI : /cloud, login
Crédit: Mesure d’usage en ligne. Ce n’est pas un avoir en euros. Détail : page Crédits
Agent IA local: LLM + outils sur la machine — le cœur de Mini Agentic
Workspace: Racine des outils. Un chemin qui en sort est refusé. Les commandes / ne sont pas filtrées. Le shell du prompt est sandboxed comme run
Plafond: MAX_TOOL_ROUNDS (40) et CONTEXT_CHAR_BUDGET (120 000). Identiques pour tous les modèles
edit: Extrait exact unique, ou plage start_line–end_line. Le préfixe N| n’est pas du code
run: Shell dans le workspace, sandbox multi-backend si disponible. Confirmation interactive par défaut en CLI (sauter avec --yes). && et pipes permis. exit_code + champ sandbox. Un échec ne défait rien
Confirmation run: Invite « Exécuter ? [o/N] » avant chaque outil run. Active par défaut. Désactiver : --yes / MINIAGENTIC_CONFIRM_RUN=0
Lecture seule: --read-only / MINIAGENTIC_READ_ONLY=1 : tree, ls, find, grep, read uniquement — pas d’écriture ni de run
Tool: Fonction Python exposée au LLM via Tools
Tool call: Demande du modèle d’exécuter un outil
Round: Aller-retour LLM (+ outils éventuels)
Relance: Une fois, si des fichiers ont été écrits et qu’aucun run n’a réussi depuis
Mention: @chemin dans la palette. Le @ est retiré avant ask
Session: État CLI (agent + config)
Commande /: Action CLI hors boucle LLM
Shell verb: Premier mot reconnu par shell.py
Plain: Sans couleurs / sans palette
Ollama: Runtime LLM local utilisé par l’agent Mini Agentic

Source textuelle détaillée : ARCHITECTURE.md à la racine du dépôt. Si le code diverge, c’est le code qui fait foi.

Essayer en local Crédits et modèles Retour à l’accueil