nano_agent_team_selfevolve

English (this page) | 中文文档

nano_agent_team_selfevolve is a secondary development branch of nano_agent_team, focused on unattended self-evolution workflows. A multi-agent team — Architect, Researcher, Developer, Tester, Auditor, Reviewer, Historian — collaborates autonomously to analyze the codebase, propose improvements, implement them, pass quality gates, and merge back to main.

For full framework documentation (architecture, TUI/CLI, tool system), see the upstream README.

---

What This Repo Adds

Compared with upstream nano_agent_team, this repo adds the self-evolution loop:

Component	Description
main.py --evolution	Entry point for launching an evolution architect round
evolve.sh	Round-based loop runner: bash evolve.sh [max_rounds] [model]
evolve_session.sh	Full session automation: clean → evolve → record → debug → README → push
src/prompts/evolution_architect.md	Prompt protocol for the Evolution Architect agent
backend/tools/evolution_workspace.py	Branch/worktree lifecycle management
evolution_state.json	Current summarized evolution state
evolution_history.jsonl	Append-only round history log
evolution_reports/	Per-round Markdown reports

---

Session: 20260313_101410

Configuration

Setting	Value
Planned rounds	5
Model	ltcraft/claude-opus-4-6
Timestamp	20260313_101410
Session script	evolve_session.sh
Script phases	Clean → Evolve → Screen Record → Debug → README → Push

Evolution Results

Round	Feature	Type	Verdict	Tests
R1	DataAnalysisTool	FEATURE	PASS	31/31
R2	CodeHealthAnalyzerTool	FEATURE	PASS	45/45
R3	TaskMemoryTool	FEATURE	PASS	27/27
R4	DiagramGeneratorTool	FEATURE	PASS	23/23
R5	—	—	not completed	—

4/5 rounds passed. 126 total tests, all green.

Feature Details

R1 — DataAnalysisTool (backend/tools/data_analysis.py)

• 8 operations: describe, head, tail, filter, sort, groupby, value_counts, corr
• CSV and JSON support via pandas
• Security hardened: whitelist on aggregation functions, regex-based filter parser (no arbitrary df.query())

R2 — CodeHealthAnalyzerTool (backend/tools/code_health.py)

• 5 operations: analyze, imports, structure, complexity, find_issues
• AST-based Python code analysis, zero external dependencies

R3 — TaskMemoryTool (backend/tools/task_memory.py)

• 4 operations: store, search, list, delete
• Persistent JSON storage in .agent_memory/memories.json
• Entry schema: {id, key, value, tags[], description, timestamp}

R4 — DiagramGeneratorTool (backend/tools/diagram_generator.py)

• Operations: generate, validate, save
• 4 Mermaid diagram types: flowchart, sequence, class, mindmap

Files Modified Across Rounds

File	Change
backend/tools/data_analysis.py	NEW
backend/tools/code_health.py	NEW
backend/tools/task_memory.py	NEW
backend/tools/diagram_generator.py	NEW
tests/test_data_analysis.py	NEW (+ debug patch)
tests/test_code_health.py	NEW
tests/test_task_memory.py	NEW
tests/test_diagram_generator.py	NEW
backend/llm/tool_registry.py	All 4 tools registered
main.py	All 4 tools wired via add_tool()
src/tui/agent_bridge.py	All 4 tools wired in both init paths
docs/system_design.md	Changelog entries R1–R4
backend/llm_config.json	Added ltcraft provider

Debug Results

Issues found and fixed:

• backend/llm_config.json: Added the ltcraft provider entry (claude-opus-4-6 via https://ai.ltcraft.cn:12000/v1) to reflect the model actually used during this session.
• tests/test_data_analysis.py: Minor test adjustments during debug phase to align with the security-hardened filter implementation.

Current feature availability:

Feature	Status
DataAnalysisTool	Operational — all 31 tests pass
CodeHealthAnalyzerTool	Operational — all 45 tests pass
TaskMemoryTool	Operational — all 27 tests pass
DiagramGeneratorTool	Operational — all 23 tests pass
python main.py --help	Clean startup, no import errors

---

Quick Start

1. Install

git clone https://github.com/nanoAgentTeam/nano_agent_team_selfevolve.git
cd nano_agent_team_selfevolve
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure

Edit backend/llm_config.json to enable at least one provider. Provide API keys via environment variables:

export DASHSCOPE_API_KEY="your_key"   # Qwen
export OPENAI_API_KEY="your_key"      # OpenAI
export DEEPSEEK_API_KEY="your_key"    # DeepSeek
export MOONSHOT_API_KEY="your_key"    # Moonshot/Kimi
export STEP_API_KEY="your_key"        # StepFun

Or pass a custom key file:

python main.py --keys /path/to/keys.json

3. Run

# Normal agent mode
python main.py "Your mission"

# TUI interactive mode
python tui.py

# Self-evolution mode (3 rounds, default model)
bash evolve.sh 3

# Full session (5 rounds, specified model)
bash evolve_session.sh 5 ltcraft/claude-opus-4-6

4. Stop evolution safely

touch .evolution_stop

The loop checks this flag after each round, cleans it automatically, then exits.

---

Project Structure

nano_agent_team_selfevolve/
├── main.py                        # CLI entry point (--evolution flag)
├── tui.py                         # TUI entry point
├── evolve.sh                      # Round-based evolution loop
├── evolve_session.sh              # Full automated session
├── clean_evolution.sh             # Cleanup script
├── backend/
│   ├── llm/
│   │   ├── tool_registry.py       # Tool registration
│   │   └── providers.py           # LLM provider adapters
│   └── tools/
│       ├── data_analysis.py       # R1: DataAnalysisTool
│       ├── code_health.py         # R2: CodeHealthAnalyzerTool
│       ├── task_memory.py         # R3: TaskMemoryTool
│       ├── diagram_generator.py   # R4: DiagramGeneratorTool
│       └── evolution_workspace.py # Evolution branch lifecycle
├── src/
│   ├── prompts/
│   │   ├── evolution_architect.md # Evolution architect protocol
│   │   └── roles/                 # Sub-agent role prompts
│   └── tui/
│       └── agent_bridge.py        # TUI agent wiring
├── tests/                         # All test files
├── evolution_history.jsonl        # Append-only round history
├── evolution_state.json           # Current evolution state
├── evolution_reports/             # Per-round markdown reports
└── docs/
    └── system_design.md           # Architecture and changelog

---

Supported LLM Providers

Configure in backend/llm_config.json:

Provider	Models
Qwen (Aliyun)	qwen3-max, qwen-plus, qwen-flash
OpenAI	gpt-5.2, gpt-5.1, gpt-5-mini, gpt-5-nano
DeepSeek	deepseek-chat, deepseek-reasoner
Moonshot	kimi-k2.5, kimi-k2-turbo-preview
StepFun	step-3.5-flash
MiniMax	MiniMax-M2.1
xAI	grok-4-1-fast
OpenRouter	stepfun/step-3.5-flash:free
Together	moonshotai/Kimi-K2.5
ltcraft (proxy)	claude-opus-4-6

---

License

Apache License 2.0. See LICENSE.