botte-secrete

Botte Secrète

RC1 validation reports and reproduction — clean installation checks and a bounded public-source pilot.

Releases: 1.9.0 — latest stable · 2.0.0rc2 — external-pilot pre-release. The RC adds Factory Assurance, independent judging, and evidence gates. Start in observe, consultative, or shadow mode; the private/external holdout remains unproven. See the release notes for limits and installation at the validated commit. main prepares version 1.10.0; the badge below identifies that unreleased candidate, not a published stable release. The Codex plugin guide documents its separately installed Python runtime and Git marketplace catalog.

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.

See it in action: "done" needs evidence

A prepared agent report claims completion. Botte flags the missing evidence; an actual test exposes a defect, and a prepared correction passes all three tests. Follow the replayable demonstration with recorded outputs and an explicit negative control: A11 detects evidence markers but does not authenticate them.

The separate opt-in receipt verifier checks actual artifacts and source hashes against a digest supplied by the trusted test executor; it does not rely on a hash asserted by the agent report.

Understand and inspect the small models

You can inspect the code and the micro-NN weights. Botte's small predictors help choose a route or compare an asset with previous examples. Their output is a hint; it is not evidence that a task is correct or complete.

Mechanism	In plain language	What you can inspect
Micro-NN — small neural network	A small calculator turns numeric features, such as task complexity, into a category or score. Its learned weights and biases are the numbers used in that calculation. It does not generate text.	JSON weights, feature extraction, inference code and training code
k-NN — k-nearest neighbors	Looks for the most similar previously verified examples and uses their outcomes to suggest a result. Asset Quality Memory exposes its neighbors and abstains when support is insufficient.	Comparison and memory code, usage contract and public example

For example, a micro-NN may suggest a local route for a simple task. The k-NN baseline may compare a mesh report with verified meshes from the same family. Deterministic checks and the applicable verification policy remain necessary.

Public files on Hugging Face

Public repository	What is actually available
Botte Nano-NN	Six JSON weight files, readable in the browser and downloadable; for example binary_router.json. The model card declares MIT.
Asset Quality Memory k-NN	A public model card and source links. This k-NN baseline has no neural weight file; its example memory remains project-local and is not published.

Public access was checked without credentials on 14 September 2026. The Hub's six-file micro-NN snapshot is not a synchronized copy of the eleven JSON models in this GitHub source tree. Use the weights and feature contracts from the same version; consult the dated inventory and publication/provenance rules.

Open weights make inspection possible; they do not establish accuracy or production readiness. Read the grounding roadmap for validation requirements. The core source is MIT licensed; the public Hub cards also declare MIT. No private neighbor ledger needs to be shared to understand the algorithm.

Why Botte Secrète?

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.

What it includes

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.

Strategic agent: Monte Cristo

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

Read the agent definition, the usage guide, and the validated report contract.

Quick start

Requirements: Python 3.10 or newer and Git. Use python on Windows.

Install from GitHub

python -m pip install git+https://github.com/zedarvates/botte-secrete.git
python -m skills.cli --help
python -m skills.auto_router.checkup_belt2

Deploy the MCP integration and local policy into a project:

botte bootstrap /path/to/your-project

Bootstrap 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.

Work from a clone

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.

See it work offline

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.

Measured benchmark

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

Code is returned unchanged. JSON compaction preserves every value; logs retain distinct lines and their order. Sizes are UTF-8 bytes, not billed tokens. Reversible originals live only in the current process, until it exits or its store is cleared. The CLI does not provide durable restoration.

python -m skills.universal_compressor.cli compress /path/to/file.log --type log

See the compression integrity and comparison protocol.

Architecture at a glance

flowchart 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.

Safety and system impact

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.

Documentation map

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.

Development

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.py

The 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.

License and author

Released under the MIT License. Created by Sylvain Galliez.