Documentation MiniAgentic — Agent IA local

01 — Essence

Ce qu’est MiniAgentic — agent IA local

Agent CLI local : Ollama, outils Python, et une boucle qui s’arrête dès que le modèle répond en texte. Les commandes / et le shell passent à côté du modèle.

Quatre vérités de l’agent local

Parle à un LLM local via Ollama
Expose des outils fichiers (filesystem + extensions)
Boucle agent IA : message → LLM → tool_calls → résultats → réponse
Mode direct : / et verbes shell bypassent le LLM

Entrypoint

pyproject.toml → miniagentic = "miniagentic.cli:main"

Quand tu tapes miniagentic, Python appelle cli.main — ton agent fichiers local démarre.

Cœur 0.3 : agent IA local + agent fichiers + plugins Python drop-in.

02 — Carte

Carte des modules

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

cli/lancement.pyLancer, router, afficher

agent/agent.pyask · profil · Ollama

agent/registre.pyRegistre nom → fonction

filesystem/espace.pydetect() · ancre session

filesystem/operations/Disque pur · resolve, read…

filesystem/outils/Wrappers LLM + prompt

plugins/chargeur/extensions/*.py · register

cli/commandes//ls · /find · Session

cli/shell/Verbes shell sans LLM

cli/palette/Complétion prompt_toolkit

03 — 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, /extensions…

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

02Registre d’outilsagent.registre + filesystem.outils + plugins

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()Parse args · crée Session

A2

Agent.files(...)Factory : pas un Agent() vide

A3

workspace.detect()-w → env → cwd

A4

profil_du_modele()petit · moyen · grand

A5

default_tools()FS natifs · extensions sauf petit

A6

Agent.__init__model · history · callbacks · max_rounds

A7

Session + bannerPuis _interactive()

démarrage

local

Workspace ≠ sandbox. Ancre les chemins relatifs ; resolve accepte aussi absolu / ~.

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. Aucune heuristique ne reprend la main s’il a répondu en texte.

Tour type

Ajoute le message utilisateur
Allège l’historique si le budget du profil est dépassé
Appelle Ollama avec tools.for_llm()
Des tool_calls → exécution → on recommence
Du texte → on renvoie ce texte et on s’arrête

Un appel d’outil répété à l’identique est signalé. Au deuxième doublon, l’agent force un résumé sans outils. Un JSON d’outil cassé est retenté trois fois.

boucle agent

local

Profils

Petit, moyen, grand

Le nom du modèle Ollama choisit tours, budget et extensions. MINIAGENTIC_PROFIL force l’un des trois mots. Un nom inconnu est grand.

Profil	Détection	Tours	Budget	Extensions
`petit`	1b, 3b, ministral-3	8	24 000 car.	non
`moyen`	7b, 8b, 14b, mistral, llama3.1:8b	16	64 000 car.	oui
`grand`	le reste	40	120 000 car.	oui

Consigne ajoutée au prompt

petit — une intention, pas de relecture après un edit réussi
moyen — lectures groupées, une vérification run ou grep
grand — enchaîne jusqu’au bout, puis une vérification

Ollama Cloud, en option

/model list sépare Local et Cloud. Choisir un nom présent seulement côté Cloud bascule le client (OLLAMA_API_KEY). Le chemin par défaut reste l’Ollama local.

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` — une occurrence exacte
`write`	`write_text`
`mkdir`	`mkdir`
`ls`	`list_entries`
`run`	`run_command` — sans shell, sans pipe

outils fichiers

local

Pas une cage. read, edit, write, mkdir et run acceptent un chemin absolu. Le workspace ancre les relatifs.

Chaîne E

Extensions plug-and-play

Un seul branchement : default_tools → load_tools, sauf en profil petit. Contrat : register(workspace) et un bloc Args: dans la docstring.

E1

extensions_dir()MINIAGENTIC_EXTENSIONS → ./extensions → product/extensions

E2

import dynamiquechaque *.py sauf _*.py

E3

register(workspace)sinon ignoré pour le LLM

E4

tools.extend(*extra)visibles comme tree / read

E5

/extensions reloadou Agent.set_workspace

product/extensions/mon_outil.pycontrat

# Drop-in · hot-reload via /extensions reload
from pathlib import Path
import json

def register(workspace: Path) -> list:
    def count_python_files(where: str = ".") -> str:
        """Compte les .py.

        Args:
            where: Chemin relatif au workspace.
        """
        root = (workspace / where).resolve()
        n = sum(1 for _ in root.rglob("*.py"))
        return json.dumps({"count": n})

    return [count_python_files]

extension

local

Piège fréquent

Fichier sans register → visible dans /extensions list
Mais pas exposé au LLM
Préfixe _ → ignoré au chargement

Exemple inclus

product/extensions/ux_atelier.py

ux_audit_html
ux_design_system
ux_critique
ux_wireframe_spec

Le profil petit ne les charge pas. /extensions reload le dit explicitement.

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`	set_workspace + reload outils
`/tools`	liste registre LLM
`/extensions`	list · reload · dir
`/model /reset /history`	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) n’est pas l’outil run.

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

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 MiniAgentic hors CLI

Exports : Agent, Tools, workspace, extensions_dir, load_tools.

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")  # recharge outils + prompt
agent.reset()                     # nouvelle conversation

api python

local

Glossaire

Vocabulaire MiniAgentic

Agent IA local: LLM + outils qui tournent sur ta machine (pas de cloud) — c’est MiniAgentic
Local AI agent: English name for agent IA local / offline CLI agent
Workspace: Racine des chemins relatifs. Pas une sandbox : un chemin absolu ou un ~ peut en sortir
Profil: petit, moyen ou grand — tours, budget et chargement des extensions
edit: Remplace un extrait exact, une seule fois, sans le préfixe de ligne N|
run: Lance un programme dans l’espace de travail, sans shell et sans pipe
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)
Nudge: Message forcé pour pousser un tool call
Extension: Module extensions/*.py via register()
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 MiniAgentic

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

Installer Retour landing