Master

README.md

@@ -1,165 +1,209 @@
-# MiniCode
-
-> **The coding agent that regulates itself.**
->
-> 15 cybernetic controllers watch your agent in real time —
-> auto-fixing context overflow, tool errors, cost spikes, and irrelevant memory.
-> No other coding agent does this.
-
-[![Tests](https://img.shields.io/badge/tests-737%20passed-brightgreen)]()
-
----
-
-## Why MiniCode
-
-Every AI coding agent hits the same problems: context fills up, tools fail, costs spiral, memory is noise. The industry answer is "better prompts" or "bigger models." We took a different path.
-
-MiniCode wraps the LLM in a **closed-loop cybernetic control system** — PID controllers, Kalman filters, feedback loops — that watches the agent in real time and auto-corrects before you even notice.
-
-```
-Your prompt → Agent Loop → Response
-                  │
-     ┌────────────┼────────────┐
-     │            │            │
-   SENSE       CONTROL        ACT
-   Kalman×5    PID ×4        tools
-   metrics     feedback      budget
+# MiniCode Python
+
+MiniCode Python is the Python implementation in the MiniCode family. It is
+developed in this repository and linked from the main MiniCode repository:
+
+- Main MiniCode repository: [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode)
+- Python repository: [QUSETIONS/MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python)
+- Rust repository: [harkerhand/MiniCode-rs](https://github.com/harkerhand/MiniCode-rs/tree/master)
+- Java repository: [hobbescalvin414-tech/minicode4j](https://github.com/hobbescalvin414-tech/minicode4j/tree/feat/default-ts-ui)
+
+This Python version focuses on a local terminal coding agent with an explicit
+control layer around the model loop. Instead of treating context pressure, tool
+failures, noisy memory, and cost drift as prompt-only problems, the agent
+measures them every turn and feeds those signals back into runtime decisions.
+
+The current repository version is centered on the root package configured in
+`pyproject.toml`:
+
+- active package: `minicode/`
+- active tests: `tests/`
+- active console entrypoint: `minicode-py = minicode.main:main`
+- compatibility/staging mirror: `py-src/minicode/`
+
+The README describes the active root package. The `py-src/` tree is kept aligned
+for reference and migration work, but the installed package and test suite use
+`minicode/`.
+
+## What Changed
+
+This version turns MiniCode from a mostly linear agent loop into a closed-loop
+agent runtime:
+
+```text
+user task
+   |
+   v
+agent loop -----> tools / files / terminal
+   |
+   v
+sensors: context, cost, tool errors, progress, memory quality
+   |
+   v
+controllers: PID, Kalman state observer, prediction, self-healing, routing
+   |
+   v
+actions: compact context, change budget, cap concurrency, inject memory,
+         route models, record reflection, recover from faults
 ```
 
-**It's like ABS for your AI agent.**
-
-| Problem | Traditional Fix | MiniCode |
-|---------|----------------|----------|
-| Context overflow | Retry with bigger window | PID auto-compacts |
-| Tool errors pile up | Restart the session | Self-heals in real time |
-| Cost runs away | Manual budget check | Budget PID throttles |
-| Memory returns noise | Skip memory entirely | Domain filter + LLM curation |
+The important engineering result is not just that these controllers exist. The
+main agent loop now calls the unified `CyberneticOrchestrator` lifecycle:
+
+- `wire_memory()`
+- `wire_healing()`
+- `inject_memories()`
+- `step_start()`
+- `step_end()`
+- `reflect_on_task()`
+
+That keeps controller initialization, memory injection, per-step observation,
+feedback, self-healing, and post-task reflection tied to the same runtime
+surface.
+
+## Core Capabilities
+
+### Cybernetic Control
+
+MiniCode uses a multi-controller runtime:
+
+- `FeedbackController` produces control signals for compaction, concurrency,
+  step limits, token budget, model-level hints, and memory persistence.
+- `ContextCyberneticsOrchestrator` runs context sensing, PID control,
+  prediction, threshold adaptation, and compaction.
+- `AdaptivePIDTuner` retunes PID parameters during longer runs.
+- `StateObserver` estimates hidden runtime state with Kalman filters.
+- `PredictiveController` raises proactive actions before pressure becomes a
+  hard failure.
+- `SelfHealingEngine` detects recoverable faults and delegates recovery.
+- `CostControlLoop` adjusts token-budget behavior from spend signals.
+- `ProgressController` detects stalled or unhealthy task progress.
+- `CyberneticSupervisor` aggregates controller state into a single health view.
+
+### Memory Pipeline
+
+Memory is handled as an adaptive pipeline rather than raw keyword search:
+
+```text
+task + files
+  -> DomainClassifier
+  -> BM25 / indexed retrieval
+  -> optional vector fusion
+  -> LLM reranking
+  -> memory injection
+  -> reflection write-back
+  -> maintenance / decay / conflict handling
+```
 
----
+The active facade is `MemoryPipeline`, wired through `CyberneticOrchestrator`.
+It supports project memory retrieval, prompt injection, task reflection, and
+background maintenance from one interface.
 
-## What It Can Do
+### Agent Loop Integration
 
-Verified with DeepSeek V4 Pro. **10 real coding tasks, zero errors.**
+The main loop in `minicode/agent_loop.py` now applies controller output to live
+runtime knobs:
 
-```
-Create hello.py with hello()        33s  ✓
-Find all files with "cybernetic"    25s  ✓
-Read + summarize README             15s  ✓
-Edit: rename function + change val  39s  ✓
-Multi-step: grep → read → analyze   68s  ✓
-```
-Full results: [`docs/test_results.md`](docs/test_results.md)
+- `limit_max_steps` can reduce the remaining loop budget.
+- `adjust_token_budget` changes the compactor tool-result budget.
+- `reduce_parallelism` caps concurrent tool workers.
+- `adjust_concurrency` updates the scheduler worker cap.
+- `suggest_memory_persistence` flushes working memory.
+- model upgrade/downgrade hints are surfaced to the model switcher layer.
 
----
+The goal is conservative autonomy: controllers can intervene in measurable
+runtime behavior, but the agent still remains inspectable and testable.
 
-## Quick Start
+## Install
 
 ```bash
 git clone https://github.com/QUSETIONS/MiniCode-Python.git
 cd MiniCode-Python
-pip install -e .
-python -m minicode.main
+python -m pip install -e .[dev]
 ```
 
-No API key? Mock mode works out of the box:
+Run the CLI:
+
 ```bash
-MINI_CODE_MODEL_MODE=mock python -m minicode.main
+minicode-py
 ```
 
----
+Or run directly:
 
-## Configuration
-
-```json
-{
-  "model": "your-model",
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://your-endpoint",
-    "ANTHROPIC_AUTH_TOKEN": "your-token"
-  }
-}
+```bash
+python -m minicode.main
 ```
 
----
-
-## The 15 Controllers
-
-Every turn, MiniCode's controllers measure, decide, and act:
-
-| Controller | Job |
-|-----------|-----|
-| **ContextPIDController** | Usage → compaction strength |
-| **BudgetPIDController** | Spending → token budget |
-| **FeedbackController** | System health → 13-dim control signal |
-| **AdaptivePIDTuner** | Auto-tunes PID gains every 20 turns |
-| **StateObserver** | Kalman estimates of 5 hidden states |
-| **SelfHealingEngine** | Detects and recovers 8 fault types |
-| **FeedforwardController** | Pre-configures from task intent |
-| **PredictiveController** | Forecasts and acts before problems hit |
-| **DecouplingController** | Untangles multi-variable interactions |
-| **StabilityMonitor** | Multi-dimensional health scoring |
-| **ProgressController** | Detects task stalling |
-| **DomainClassifier** | Auto-detects frontend/backend/db/devops |
-| **MemoryInjectionController** | PID-controls memory injection rate |
-| **ModelSelectionController** | Risk/cost-driven model selection |
-| **CyberneticSupervisor** | Aggregates all controller states |
+For local smoke tests without a real model provider, use the mock model paths
+covered by the test suite.
 
----
+## Verify
 
-## Memory That Actually Works
+The current root package was verified with:
 
-Not keyword search. A full adaptive pipeline:
-
-```
-Task → DomainClassifier → BM25 + Vector(RRF) → Value Scoring
-  → LLM Reranker (curates top-3 from 15) → Spreading Activation → Inject
+```bash
+python -m compileall -q minicode py-src\minicode tests
+pytest -q
 ```
 
-**80 memories × 20 queries: P@3 0.35 → 0.72, noise 65% → 7%.**
-
-The LLM Reranker uses the same model you're coding with to pick which memories actually matter.
+Latest local result:
 
----
-
-## Terminal Polish
-
-| Feature | Key |
-|---------|-----|
-| Colored diffs | `edit_file` output: +green/-red with word highlights |
-| Multi-line input | `Ctrl+J` — paste code blocks directly |
-| Word editing | `Ctrl+←→` `Ctrl+W` `Ctrl+K` |
-| Visual scrollbar | █ • ▲ ▼ |
-| Bracketed paste | Batch insert, strip control chars |
-| Spinner | `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏` at 8fps |
-| Focus tracking | Auto-refresh on tab switch |
-| Fuzzy complete | `/mem` matches `/memory` |
-
----
-
-## Testing
-
-```bash
-pytest
-# 737 passed, 2 skipped
+```text
+738 passed, 2 skipped, 3 warnings
 ```
 
----
+The remaining warnings are unregistered `pytest.mark.benchmark` markers in the
+memory benchmark tests. They do not indicate failing behavior.
+
+## Repository Map
+
+```text
+minicode/
+  agent_loop.py                 main agent runtime
+  cybernetic_orchestrator.py    controller lifecycle facade
+  context_cybernetics.py        context PID and compaction loop
+  feedback_controller.py        outer-loop control signals
+  self_healing_engine.py        fault detection and recovery
+  memory_pipeline.py            unified memory facade
+  memory_reranker.py            LLM-backed memory curation
+  domain_classifier.py          task/file domain inference
+  model_registry.py             model selection controller
+  progress_controller.py        task health and stall detection
+
+tests/
+  test_agent_flow.py            end-to-end agent loop coverage
+  test_cybernetics_*.py         control-stack tests
+  test_memory_*.py              memory retrieval/injection tests
+
+py-src/
+  minicode/                     staging mirror kept aligned with root package
+
+docs/
+  OPTIMIZATION_SUMMARY.md       full optimization record
+  memory_theory.md              memory/control theory notes
+```
 
-## Theory
+## Version Alignment
 
-The control loop isn't heuristic — it's mathematically grounded:
+This branch is the active GitHub repository version for
+`QUSETIONS/MiniCode-Python`. The root package (`minicode/`) is the canonical
+runtime used by installation and tests. `py-src/minicode/` is retained as a
+secondary source tree for compatibility with earlier project layout, and obvious
+behavioral fixes are mirrored there when needed.
 
-| Concept | Formalization |
-|---------|--------------|
-| PID Stability | V̇ = -(kp/m)·e² < 0 (Lyapunov) |
-| Memory Value | V(m,t,c) = relevance × freshness × utility |
-| State Estimation | 5 Kalman filters, minimum-variance unbiased |
-| Retrieval Fusion | RRF: BM25 + SparseVector cosine |
+The main TypeScript repository can include this repository as
+`external/MiniCode-Python`, but the Python package itself is installed and tested
+from this repository root.
 
-[`docs/memory_theory.md`](docs/memory_theory.md)
+## Design Notes
 
----
+MiniCode is intentionally small enough to inspect, but the runtime is no longer
+a bare model wrapper. The design direction is:
 
-## Acknowledgments
+- observe the agent while it works;
+- convert observations into structured control signals;
+- apply only bounded runtime actions;
+- preserve logs, tests, and explicit artifacts so claims can be checked.
 
-钱学森《工程控制论》(1954) · Wiener *Cybernetics* (1948) · Mem0 / Letta / True Memory
+For the detailed optimization history, see
+[`docs/OPTIMIZATION_SUMMARY.md`](docs/OPTIMIZATION_SUMMARY.md).