Skip to content

Commit 2f77135

Browse files
iuiu-pyiuiu-py
committed
fix: normalize OpenAI URLs and document uv workflow
1 parent 106d018 commit 2f77135

10 files changed

Lines changed: 557 additions & 123 deletions

File tree

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,11 @@ Thumbs.db
5353
# MiniCode specific
5454
.mini-code/
5555
minicode_session/
56+
.mini-code-memory/memory.json
57+
.mini-code-memory/pipeline_state.json
58+
.mini-code-memory/MEMORY.md
59+
.mini-code-memory-local/memory.json
60+
.mini-code-memory-local/MEMORY.md
61+
.mini-code-memory/MEMORY.md
62+
.gitignore
63+
.mini-code-memory/MEMORY.md

‎README.md‎

Lines changed: 195 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,10 @@
11
# MiniCode Python
22

3-
<p align="center">
4-
<strong>A self-regulating Python coding agent for local development.</strong>
5-
</p>
6-
7-
<p align="center">
8-
<a href="./README.zh-CN.md">简体中文</a>
9-
·
10-
<a href="https://github.com/LiuMengxuan04/MiniCode">MiniCode Main Repo</a>
11-
·
12-
<a href="https://github.com/QUSETIONS/MiniCode-Python">Python Repo</a>
13-
</p>
14-
15-
<p align="center">
16-
<img alt="Python" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white">
17-
<img alt="Tests" src="https://img.shields.io/badge/tests-738%20passed-brightgreen?style=flat-square">
18-
<img alt="Package" src="https://img.shields.io/badge/package-minicode--py-555?style=flat-square">
19-
</p>
3+
**A self-regulating Python coding agent for local development.**
4+
5+
[简体中文](./README.zh-CN.md) · [MiniCode Main Repo](https://github.com/LiuMengxuan04/MiniCode) · [Python Repo](https://github.com/QUSETIONS/MiniCode-Python)
6+
7+
208

219
MiniCode Python is the Python implementation in the MiniCode family. The main
2210
project is [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode);
@@ -44,14 +32,16 @@ That makes this repository useful as:
4432

4533
## Highlights
4634

47-
| Area | What MiniCode Python Adds |
48-
| --- | --- |
49-
| Runtime control | `CyberneticOrchestrator` coordinates context, cost, feedback, progress, memory, and recovery controllers. |
50-
| Context management | PID-style context pressure handling, compaction, budget adjustment, and predictive guards. |
51-
| Memory | Domain-aware retrieval, optional LLM reranking, prompt injection, reflection write-back, and maintenance. |
52-
| Tool loop | Local file/search/edit/command tools with scheduler-aware execution and error nudges. |
53-
| Recovery | Self-healing paths for context overflow, tool failures, oscillation, and resource pressure. |
54-
| Verification | Focused unit, integration, stress, and cybernetics tests across the active root package. |
35+
36+
| Area | What MiniCode Python Adds |
37+
| ------------------ | --------------------------------------------------------------------------------------------------------- |
38+
| Runtime control | `CyberneticOrchestrator` coordinates context, cost, feedback, progress, memory, and recovery controllers. |
39+
| Context management | PID-style context pressure handling, compaction, budget adjustment, and predictive guards. |
40+
| Memory | Domain-aware retrieval, optional LLM reranking, prompt injection, reflection write-back, and maintenance. |
41+
| Tool loop | Local file/search/edit/command tools with scheduler-aware execution and error nudges. |
42+
| Recovery | Self-healing paths for context overflow, tool failures, oscillation, and resource pressure. |
43+
| Verification | Focused unit, integration, stress, and cybernetics tests across the active root package. |
44+
5545

5646
## Architecture
5747

@@ -68,6 +58,8 @@ flowchart LR
6858
Actions --> Loop
6959
```
7060

61+
62+
7163
The main loop now drives the orchestrator lifecycle directly:
7264

7365
- `wire_memory()`
@@ -85,45 +77,187 @@ surface.
8577

8678
The active package is the root package configured in `pyproject.toml`.
8779

88-
| Path | Role |
89-
| --- | --- |
90-
| `minicode/` | Canonical Python package used by install and tests. |
91-
| `tests/` | Active test suite. |
92-
| `py-src/minicode/` | Compatibility/staging mirror kept aligned for migration work. |
93-
| `docs/OPTIMIZATION_SUMMARY.md` | Full optimization and integration record. |
94-
| `docs/memory_theory.md` | Memory/control theory notes. |
80+
81+
| Path | Role |
82+
| ------------------------------ | ------------------------------------------------------------- |
83+
| `minicode/` | Canonical Python package used by install and tests. |
84+
| `tests/` | Active test suite. |
85+
| `py-src/minicode/` | Compatibility/staging mirror kept aligned for migration work. |
86+
| `docs/OPTIMIZATION_SUMMARY.md` | Full optimization and integration record. |
87+
| `docs/memory_theory.md` | Memory/control theory notes. |
88+
9589

9690
The main TypeScript repository may include this project as
9791
`external/MiniCode-Python`, but this Python package is installed and verified
9892
from this repository root.
9993

10094
## Quick Start
10195

96+
Recommended setup with `uv`:
97+
10298
```bash
103-
git clone https://github.com/QUSETIONS/MiniCode-Python.git
99+
python -m pip install --user uv
100+
```
101+
102+
```bash
103+
git clone https://github.com/iuiu-py/MiniCode-Python.git
104104
cd MiniCode-Python
105-
python -m pip install -e .[dev]
105+
uv sync --extra dev
106106
```
107107

108108
Run the CLI:
109109

110110
```bash
111-
minicode-py
111+
uv run minicode-py
112112
```
113113

114114
Or run the module directly:
115115

116116
```bash
117-
python -m minicode.main
117+
uv run python -m minicode.main
118+
```
119+
120+
If you prefer plain `pip`, use an editable install:
121+
122+
```bash
123+
python -m pip install -e ".[dev]"
124+
```
125+
126+
Then run:
127+
128+
```bash
129+
minicode-py
130+
```
131+
132+
### Run From Any Directory
133+
134+
MiniCode uses the directory where you start the command as the workspace. To use
135+
the current source checkout globally without reinstalling after normal code
136+
changes, create a small launcher script:
137+
138+
```bash
139+
mkdir -p ~/.local/bin
140+
cat > ~/.local/bin/minicode-py <<'SH'
141+
#!/usr/bin/env bash
142+
exec uv run --project /home/zfwang/MiniCode minicode-py "$@"
143+
SH
144+
chmod +x ~/.local/bin/minicode-py
145+
```
146+
147+
Make sure `~/.local/bin` is on your `PATH`, then run MiniCode from any project:
148+
149+
```bash
150+
cd /path/to/your/project
151+
minicode-py
152+
```
153+
154+
This keeps `/home/zfwang/MiniCode` as the MiniCode source project while the
155+
current directory remains the workspace that tools, memory, MCP config, and
156+
permissions use.
157+
158+
Alternatively, install it as an editable `uv` tool:
159+
160+
```bash
161+
uv tool install --editable /home/zfwang/MiniCode
162+
uv tool update-shell
163+
```
164+
165+
Editable tool installs usually pick up Python source changes after restarting
166+
`minicode-py`; reinstall only when entry points, package metadata, or
167+
dependencies change.
168+
169+
## Configuration
170+
171+
MiniCode reads configuration from `~/.mini-code/settings.json`, merged with
172+
process environment variables. Environment variables take precedence, so you can
173+
keep long-lived defaults in the settings file and override them per shell.
174+
175+
You can create the settings file manually:
176+
177+
```bash
178+
mkdir -p ~/.mini-code
179+
$EDITOR ~/.mini-code/settings.json
180+
```
181+
182+
Keep real API keys out of committed files, screenshots, and shared logs.
183+
184+
Anthropic example:
185+
186+
```json
187+
{
188+
"model": "claude-sonnet-4-20250514",
189+
"env": {
190+
"ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
191+
"ANTHROPIC_API_KEY": "sk-ant-...",
192+
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
193+
}
194+
}
195+
```
196+
197+
OpenAI or OpenAI-compatible endpoint example:
198+
199+
```json
200+
{
201+
"model": "gpt-4o",
202+
"env": {
203+
"OPENAI_API_KEY": "sk-...",
204+
"OPENAI_BASE_URL": "https://api.openai.com"
205+
}
206+
}
207+
```
208+
209+
For OpenAI-compatible proxies, `OPENAI_BASE_URL` may be either the provider root
210+
or a versioned base URL:
211+
212+
```json
213+
{
214+
"model": "gpt-4o",
215+
"env": {
216+
"OPENAI_API_KEY": "sk-...",
217+
"OPENAI_BASE_URL": "https://your-provider.example.com/v1"
218+
}
219+
}
220+
```
221+
222+
OpenRouter example:
223+
224+
```json
225+
{
226+
"model": "anthropic/claude-sonnet-4",
227+
"env": {
228+
"OPENROUTER_API_KEY": "sk-or-...",
229+
"OPENROUTER_BASE_URL": "https://openrouter.ai/api"
230+
}
231+
}
232+
```
233+
234+
Custom OpenAI-compatible endpoint example:
235+
236+
```json
237+
{
238+
"model": "my-local-model",
239+
"env": {
240+
"CUSTOM_API_KEY": "local-or-proxy-key",
241+
"CUSTOM_API_BASE_URL": "http://localhost:11434/v1"
242+
}
243+
}
244+
```
245+
246+
You can also use shell exports instead of a settings file:
247+
248+
```bash
249+
export ANTHROPIC_MODEL=claude-sonnet-4-20250514
250+
export ANTHROPIC_API_KEY=sk-ant-...
251+
uv run minicode-py
118252
```
119253

120254
## Verification
121255

122256
The current root package was verified with:
123257

124258
```bash
125-
python -m compileall -q minicode py-src\minicode tests
126-
pytest -q
259+
uv run python -m compileall -q minicode py-src/minicode tests
260+
uv run pytest -q
127261
```
128262

129263
Latest local result:
@@ -137,27 +271,31 @@ tests. They do not indicate failing behavior.
137271

138272
## Core Modules
139273

140-
| Module | Purpose |
141-
| --- | --- |
142-
| `minicode/agent_loop.py` | Main model/tool loop and runtime control integration. |
143-
| `minicode/cybernetic_orchestrator.py` | Facade for controller lifecycle hooks. |
144-
| `minicode/context_cybernetics.py` | Context sensing, PID control, and compaction loop. |
145-
| `minicode/feedback_controller.py` | Outer-loop system-state to control-signal mapping. |
146-
| `minicode/self_healing_engine.py` | Fault detection and recovery delegation. |
147-
| `minicode/memory_pipeline.py` | Unified memory read/inject/write/maintain facade. |
148-
| `minicode/memory_reranker.py` | LLM-backed memory curation. |
149-
| `minicode/domain_classifier.py` | Task and file-domain inference. |
150-
| `minicode/model_registry.py` | Model selection controller. |
151-
| `minicode/progress_controller.py` | Task health and stall detection. |
274+
275+
| Module | Purpose |
276+
| ------------------------------------- | ----------------------------------------------------- |
277+
| `minicode/agent_loop.py` | Main model/tool loop and runtime control integration. |
278+
| `minicode/cybernetic_orchestrator.py` | Facade for controller lifecycle hooks. |
279+
| `minicode/context_cybernetics.py` | Context sensing, PID control, and compaction loop. |
280+
| `minicode/feedback_controller.py` | Outer-loop system-state to control-signal mapping. |
281+
| `minicode/self_healing_engine.py` | Fault detection and recovery delegation. |
282+
| `minicode/memory_pipeline.py` | Unified memory read/inject/write/maintain facade. |
283+
| `minicode/memory_reranker.py` | LLM-backed memory curation. |
284+
| `minicode/domain_classifier.py` | Task and file-domain inference. |
285+
| `minicode/model_registry.py` | Model selection controller. |
286+
| `minicode/progress_controller.py` | Task health and stall detection. |
287+
152288

153289
## MiniCode Family
154290

155-
| Version | Repository | Focus |
156-
| --- | --- | --- |
157-
| TypeScript | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | Mainline terminal agent, TUI, MCP, skills, sessions, context controls. |
158-
| Python | [QUSETIONS/MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python) | Cybernetic Python runtime, memory pipeline, verification-oriented experiments. |
159-
| Rust | [harkerhand/MiniCode-rs](https://github.com/harkerhand/MiniCode-rs/tree/master) | Rust implementation and systems-side experimentation. |
160-
| Java | [hobbescalvin414-tech/minicode4j](https://github.com/hobbescalvin414-tech/minicode4j/tree/feat/default-ts-ui) | Java implementation with a TypeScript-style UI direction. |
291+
292+
| Version | Repository | Focus |
293+
| ---------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
294+
| TypeScript | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | Mainline terminal agent, TUI, MCP, skills, sessions, context controls. |
295+
| Python | [QUSETIONS/MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python) | Cybernetic Python runtime, memory pipeline, verification-oriented experiments. |
296+
| Rust | [harkerhand/MiniCode-rs](https://github.com/harkerhand/MiniCode-rs/tree/master) | Rust implementation and systems-side experimentation. |
297+
| Java | [hobbescalvin414-tech/minicode4j](https://github.com/hobbescalvin414-tech/minicode4j/tree/feat/default-ts-ui) | Java implementation with a TypeScript-style UI direction. |
298+
161299

162300
## Documentation
163301

@@ -172,3 +310,4 @@ tests. They do not indicate failing behavior.
172310
- Apply bounded actions: compact, cap, adjust, recover, reflect.
173311
- Treat verification and evidence as part of the agent runtime.
174312
- Keep the Python implementation useful as both software and research scaffold.
313+

0 commit comments

Comments
 (0)