Documentation MiniAgentic — Agent IA local

01 — Essence

Ce qu’est MiniAgentic — agent IA local

Agent CLI local (local AI agent) : LLM via Ollama, outils Python, boucle reason → tool → iterate — plus un mode direct sans LLM.

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/main.pyLancer, router, afficher

agent/core.pyBoucle ask · Ollama · tools

agent/tools.pyRegistre nom → fonction

filesystem/workspace.pydetect() · ancre session

filesystem/ops.pyDisque pur · resolve, read…

filesystem/tools.pyWrappers LLM + prompt

plugins/loader.pyextensions/*.py · register

cli/commands.py/ls · /find · Session

cli/shell.pyVerbes shell sans LLM

cli/slash_palette.pyComplé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 CLImain · console · input · palette · shell

04Commandes directescli.commands — /ls, /tree, /extensions…

03Agent conversationnelagent.core — ask → Ollama → tool_calls

02Registre d’outilsagent.tools + filesystem.tools + plugins

01Moteur filesystem + OSops · 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

build_system_prompt()Anti-hallucination + liste extensions

A5

default_tools()FS natifs + load_tools()

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.

1

read_inputPalette ou input() plain

2

quit / exit / q ?Farewell → fin

3

startswith("/") ?commands.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

Cœur agentique dans agent/core.py · ask().

Tour type

Append message user
_needs_filesystem_tools → evidence ?
_call_llm() avec tools.for_llm()
Si tool_calls → _run_tools → recommencer
Sinon nudge éventuel, puis texte final

Les docstrings Google + Args: = schéma Ollama.

boucle agent

local

Chaîne D

Outils fichiers natifs

Deux couches : tools.py (LLM) vs ops.py (disque pur, aussi utilisé par /).

Outil LLM	Ops
`tree`	`explore_tree`
`find`	`find_paths`
`grep`	`grep_paths`
`read`	`read_text`
`write`	`write_text`
`ls`	`list_entries`

outils fichiers

local

Chaîne E

Extensions plug-and-play

Un seul branchement : default_tools → load_tools. Contrat : register(workspace).

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

count_extensions
largest_files

Chaîne F

Commandes slash

Deuxième chemin vers le disque — sans Ollama. Dispatch dans commands.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 à la boucle LLM. cd met à jour cwd + souvent le workspace agent.

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 → slash_palette.read_line(session)
Complétion : COMMANDS · SUBCOMMANDS · chemins · modèles

Scénario

Bout en bout

« Quels fichiers Python y a-t-il ? » — 16 étapes du shell OS à show_reply.

01

OSscript → cli.main

02

Agent.filesdetect · prompt · tools

03

askneeds_evidence = True

04

Ollamadécide find(*.py)

05

Tools.run→ ops.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 logique de la session de l’agent fichiers
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