Français · Documentation · Architecture · Development · Contributing
A local-first control plane for AI coding agents. Botte Secrète routes cheap work to deterministic tools, tiny classifiers, or local models; keeps cloud reasoning for tasks that need it; reduces context and tool output; and exposes the workflow through a Python CLI and MCP.
Example public-safe dashboard snapshot; generated data is illustrative, not live telemetry.
The project is in beta. Its core workflows run locally, but optional local LLM backends, cloud providers, hardware accelerators, and third-party agents remain external systems with their own setup and security boundaries.
Agent workflows often spend expensive model tokens on work that does not need a large model: classifying a request, selecting a tool, deduplicating logs, checking a schema, or recalling an exact result. Botte adds a cheap decision layer before the model call.
flowchart LR
A["Agent task"] --> B["Policy and capability discovery"]
B --> C{"Cheapest capable path"}
C --> D["Rules and deterministic tools"]
C --> E["Micro-NN classifiers"]
C --> F["Local LLM"]
C --> G["Cloud LLM"]
D --> H["Verification"]
E --> H
F --> H
G --> H
H -->|pass| I["Compact result"]
H -->|abstain or fail| C
The default principle is simple: use the least expensive path that can be verified. Local does not mean trusted; model output still passes through structured checks, evidence checks, or an explicit escalation path.
| Area | What it does | Entry point |
|---|---|---|
| Routing | Chooses deterministic, local, or cloud execution | botte route |
| Quality memory | Learns from verified outcomes and explains shadow k-NN advice | botte qa |
| Asset quality | Gates and compares images, textures, meshes, animations, and Godot packages | botte asset-qa |
| Project checkup | Audits policy, directives, metrics, security, and drift | botte doctor |
| Context reduction | Compresses logs, JSON, tool output, and selected context | universal_compressor, context_budget |
| Micro-NN belt | Runs tiny classifiers for routing hints; these are not LLMs | botte belt |
| Local models | Discovers OpenAI-compatible local backends such as LM Studio or Ollama | llm_backends |
| MCP | Exposes routing, discovery, audit, and optimization tools over stdio | botte-mcp |
| Dashboard | Renders public-safe snapshots and local operational views | botte dashboard |
| Strategic outsider | Challenges assumptions shared by blue and red teams before costly decisions | monte_cristo |
Detailed module contracts live in each skills/<name>/SKILL.md. Cross-module
flows and trust boundaries are described in the
architecture guide.
Monte Cristo is Botte Secrète's independent, read-only strategic outsider. Blue-team agents improve a system and red-team agents challenge it; Monte Cristo steps above both when they may share the same inherited assumptions.
Maintained governance schema; it explains authority and approval boundaries, not a runtime trace.
Use it before an expensive architecture reset, research commitment, migration,
or decision shaped by sunk cost. Do not use it for routine code review or a
narrow verified fix. It returns bounded KEEP, REPAIR, REPLACE, RETIRE,
or INVESTIGATE proposals with evidence and a validation gate. It cannot edit,
deploy, purchase, publish, or execute its recommendations; consequential moves
require human approval and a separate implementation agent.
Reproducible CLI capture from the bundled deterministic offline route evaluator; it demonstrates activation wiring, not the quality of open-ended verdicts.
python -m skills.monte_cristo.cli route "Should we replace this inherited architecture?" --material --pretty
python -m skills.monte_cristo.cli template "Reassess the platform direction" --pretty
python -m skills.monte_cristo.cli eval --prettyRead the agent definition, the usage guide, and the validated report contract.
Requirements: Python 3.10 or newer and Git. Use python on Windows.
python -m pip install git+https://github.com/zedarvates/botte-secrete.git
python -m skills.cli --help
python -m skills.auto_router.checkup_belt2Deploy the MCP integration and local policy into a project:
botte bootstrap /path/to/your-projectBootstrap preserves existing MCP servers. It writes project-local configuration
and reports under .botte/; those files may contain machine-specific absolute
paths and should stay out of version control.
git clone https://github.com/zedarvates/botte-secrete.git
cd botte-secrete
python -m pip install -e .
python scripts/run_tests.py -q
python -m skills.checkup.cli .The complete test runner is the source of truth for the current test count. The README intentionally does not freeze that moving number in a badge.
The scripted demo uses fixed events. It does not call an LLM or the network.
python -m skills.demo.cli scripted --speed 0 --no-clear
Fixed offline fixture; this is reproducible demo output, not live project telemetry.
For a real project, use python -m skills.demo.cli live /path/to/project or
botte dashboard /path/to/project --tui. Those views read local event data;
they do not prove savings unless the underlying measurements are present.
The bundled benchmark exercises compression, pruning, context selection, and the micro-NN belt on a fixed synthetic corpus. It is a regression benchmark, not a promise for every repository or workload.
Micro-NN activation follows the
grounding roadmap: no new
model is activated while an existing predictor still lacks an auditable label
source, production verdicts, calibration, and rollback gate. Run checkup or
python -m skills.nn_audit.cli skills/botte_nn --json for the current status.
Asset Factory integrations can use the separate Asset Quality Memory: deterministic integrity and licence gates run first, then a family-isolated, explainable k-NN baseline advises in shadow mode. The bundled mesh report is a complete input example. No raw asset bytes or local paths enter its verified memory.
The existing MIT-licensed Botte Nano-NN repository on Hugging Face hosts a portable snapshot of the micro-NN format. Its source, feature contracts, tests, and maturity status remain authoritative here. Weight publication is blocked unless the offline Hub provenance gate finds a complete, grounded, SHA-256-identical inventory. The separate Asset Quality Memory k-NN repository on Hugging Face documents the shadow-only baseline; private neighbor ledgers stay local. See the publication checklist.
Measured on the bundled synthetic samples; results vary with content. See the visual provenance and regeneration notes.
Reproduce both the benchmark chart and the routing capture:
python scripts/generate_docs_visuals.py
python scripts/benchmark_full.py --jsonCode compression is deliberately conservative and may return the original input when a transformation would expand it. Reversible compression is in-memory by default; durable restoration requires an explicit bounded store.
python -m skills.universal_compressor.cli compress /path/to/file.log --type log
python -m skills.universal_compressor.cli compress /path/to/file.log --type log --reversible --store .private-compressorflowchart TB
Agent["Coding agent or automation"] --> MCP["Botte CLI / MCP tool plane"]
MCP --> Policy["Policy, budget, and safety gates"]
Policy --> Discover["Capabilities and skill discovery"]
Discover --> Route["Router and micro-NN hints"]
Route --> Execute["Deterministic tools, local models, or cloud providers"]
Execute --> Verify["Harness and structured verification"]
Verify --> Observe["Events, metrics, cache, and dashboard"]
Observe -. feedback .-> Route
Target["Target project"] <--> MCP
Local["Local model server"] <--> Execute
Cloud["Optional cloud provider"] <--> Execute
Botte does not own the coding agent, target repository, model server, or cloud provider. See the architecture guide for data flow, trust boundaries, and authoritative modules.
| Surface | Default behavior |
|---|---|
| Network | No network call for deterministic workflows; model and --fresh operations are explicit |
| Telemetry | No product analytics or phone-home telemetry |
| Services | No daemon, startup entry, sudo, or scheduled task installed by default |
| Target projects | Bootstrap merges MCP configuration without replacing unrelated servers |
| Local event data | Stored under the target project's .botte/ when the feature is used |
| Fleet view | Opt-in registry; no filesystem-wide discovery |
| Cloud credentials | Read from the environment by provider adapters; never required for local workflows |
Report vulnerabilities privately as described in SECURITY.md.
| Goal | Document |
|---|---|
| Find the right document | Documentation hub |
| Understand the system | Architecture |
| Develop or test Botte | Development guide |
| Integrate MCP | MCP integration |
| Connect Hermes | Hermes integration |
| Understand the loop optimizer | Loop Optimizer |
| Review changes by release | Changelog |
| Propose a change | Contributing guide |
Documents under docs/plans/, docs/research/, and similarly labelled folders
describe proposals or experiments. They are not automatically current product
contracts.
python scripts/run_tests.py --changed -q
python scripts/pre-commit-check.py --fast
python scripts/test_readme_commands.py
python scripts/check_docs_links.pyThe core is stdlib-first, while installable analyzers and interfaces use the
dependencies declared in pyproject.toml. New public claims should point to a
test, benchmark, schema, or source file that a contributor can inspect.
Released under the MIT License. Created by Sylvain Galliez.
Support options are listed in DONATE.md.