nnn-agent 0.1.0__tar.gz

nnn_agent-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: nnn-agent
+Version: 0.1.0
+Summary: Multi-agent coding system powered by local LLMs
+Author: srivtx
+License: MIT
+Project-URL: Homepage, https://github.com/srivtx/nnn
+Project-URL: Repository, https://github.com/srivtx/nnn
+Project-URL: Issues, https://github.com/srivtx/nnn/issues
+Keywords: ai,agent,llm,coding,multi-agent,local-llm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.0
+Requires-Dist: httpx
+Requires-Dist: rich
+
+# nnn
+
+```
+╻ ╻╻ ╻╻ ╻
+┃┗┫┃┗┫┃┗┫
+╹ ╹╹ ╹╹ ╹
+```
+
+A multi-agent coding system that runs on your local machine. Type a task, and a team of AI agents plans, writes, and tests the code for you.
+
+```
+> create a snake game with pygame
+
+  1. Developer  Create workspace/snake_game.py with a complete snake game using pygame
+  2. BugFixer   Run workspace/snake_game.py with run_command, then fix any errors
+
+  step 1/2 — Developer
+    read_workspace →  workspace/
+    write_file     →  Wrote 2847 chars to workspace/snake_game.py
+
+  step 2/2 — BugFixer
+    run_command    →  (game window opens)
+    ✅ No errors found.
+```
+
+---
+
+## What is this?
+
+**nnn** is a ~1500-line Python project that builds a complete AI agent system from scratch. It uses [LM Studio](https://lmstudio.ai) to run a local language model and connects 5 specialized AI agents that collaborate to complete coding tasks.
+
+The agents:
+
+| Agent           | Job                                       |
+| --------------- | ----------------------------------------- |
+| **Architect**   | Designs system structure and writes plans |
+| **Developer**   | Reads plans and writes working code       |
+| **BugFixer**    | Runs code, finds errors, and fixes them   |
+| **Researcher**  | Analyzes existing code in the workspace   |
+| **WebSearcher** | Searches the internet for documentation   |
+
+They are not separate programs — they are the same AI model called with different instructions and different tools.
+
+---
+
+## Quick Start
+
+### 1. Install LM Studio
+
+Download [LM Studio](https://lmstudio.ai), load any model (Qwen 2.5 Coder 7B or higher recommended), and start the local server.
+
+### 2. Clone and install
+
+```bash
+git clone https://github.com/YOUR_USERNAME/nnn.git
+cd nnn
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### 3. Run
+
+```bash
+nnn
+```
+
+That's it. Type a task and press Enter.
+
+**One-shot mode:**
+
+```bash
+nnn "create a flask API with user login"
+```
+
+---
+
+## How It Works
+
+```
+You type a task
+     ↓
+Orchestrator asks the LLM: "Break this into steps and assign agents"
+     ↓
+LLM returns a JSON plan:  Developer → BugFixer
+     ↓
+Each agent runs in order, using tools (read/write files, run commands)
+     ↓
+You get working code in the workspace/ folder
+```
+
+There is only **one AI model** running. Each "agent" is just the same model called with a different system prompt and a different set of tools. For a deeper explanation, see [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md).
+
+---
+
+## Learn How to Build This
+
+This project comes with **14 step-by-step lessons** that teach you how to build the entire system from scratch. Each lesson adds one concept, and you test it before moving on.
+
+| #   | Lesson                                                  | What you build                                            |
+| --- | ------------------------------------------------------- | --------------------------------------------------------- |
+| 01  | [Talking to an AI Model](docs/01_talking_to_ai.md)      | Send a message to LM Studio and get a reply               |
+| 02  | [Giving the AI a Role](docs/02_giving_the_ai_a_role.md) | System prompts, multi-turn conversation                   |
+| 03  | [Tool Calling](docs/03_tool_calling.md)                 | AI calls real Python functions (read files, run commands) |
+| 04  | [Your First Agent Class](docs/04_your_first_agent.md)   | Package role + tools + loop into a reusable Agent         |
+| 05  | [Multiple Agents](docs/05_multiple_agents.md)           | 2 agents → 3 agents, passing context between them         |
+| 06  | [The Orchestrator](docs/06_the_orchestrator.md)         | AI decides which agents to run and in what order          |
+| 07  | [The Full System](docs/07_the_full_system.md)           | Add remaining tools + WebSearcher + Researcher            |
+| 08  | [Debugging Failures](docs/08_debugging_failures.md)     | Real failure cases and how to fix them                    |
+| 09  | [Speed & Context](docs/09_speed_and_context.md)         | 6 optimizations: caching, streaming, parallel execution   |
+| 10  | [Surgical Editing](docs/10_surgical_editing.md)         | Line-by-line editing tools (edit_lines, insert_code)      |
+| 11  | [Small-Model Safety](docs/11_small_model_safety.md)     | Safety nets for 3-4B models that fail often               |
+| 12  | [CLI & Packaging](docs/12_cli_and_packaging.md)         | Turn it into an installable `nnn` command                 |
+| 13  | [Project Intelligence](docs/13_project_intelligence.md) | Detect language/runtime, auto-install deps, syntax check  |
+| 14  | [Loop Hardening](docs/14_loop_hardening.md)             | Catch stealth errors, duplicate calls, smarter bailout    |
+
+Start at Lesson 01. Each lesson builds on the previous one. By Lesson 14 you have the complete system.
+
+**New to programming?** Start with [docs/BEGINNER_GUIDE.md](docs/BEGINNER_GUIDE.md) instead — it's a gentler introduction.
+
+---
+
+## Project Structure
+
+```
+nnn/
+├── main.py              ← entry point (REPL + one-shot mode)
+├── orchestrator.py      ← plans tasks and delegates to agents
+├── agent.py             ← base Agent class
+├── llm.py               ← LLM bridge (tool-calling loop, streaming, caching)
+├── tools.py             ← all tool implementations (read/write files, run commands, web search)
+├── config.py            ← settings (server URL, token limits, temperatures)
+├── agents/
+│   ├── architect.py     ← system designer
+│   ├── developer.py     ← code writer (with rescue safety nets)
+│   ├── bug_fixer.py     ← run → diagnose → fix → verify
+│   ├── researcher.py    ← code analyzer
+│   └── web_searcher.py  ← internet search
+├── workspace/           ← where agents write code (shared workspace)
+├── docs/                ← 12 step-by-step lessons
+├── pyproject.toml       ← package config
+└── requirements.txt     ← dependencies
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- [LM Studio](https://lmstudio.ai) with any loaded model
+- Recommended: Qwen 2.5 Coder 7B+ or Qwen 3 8B+ for best results
+- Works with 3-4B models too (with safety nets — see Lesson 11)
+
+---
+
+## Configuration
+
+All settings are in `config.py`:
+
+```python
+LM_BASE_URL = "http://localhost:1234/v1"   # LM Studio server
+MAX_TOKENS = 8192                           # max response length
+TEMPERATURE_CODE = 0.3                      # lower = more reliable tool use
+PARALLEL_AGENTS = True                      # run independent agents concurrently
+```
+
+Override with environment variables:
+
+```bash
+LM_BASE_URL=http://192.168.1.5:1234/v1 nnn "build a todo app"
+```
+
+---
+
+## License
+
+MIT

nnn_agent-0.1.0/README.md

@@ -0,0 +1,177 @@
+# nnn
+
+```
+╻ ╻╻ ╻╻ ╻
+┃┗┫┃┗┫┃┗┫
+╹ ╹╹ ╹╹ ╹
+```
+
+A multi-agent coding system that runs on your local machine. Type a task, and a team of AI agents plans, writes, and tests the code for you.
+
+```
+> create a snake game with pygame
+
+  1. Developer  Create workspace/snake_game.py with a complete snake game using pygame
+  2. BugFixer   Run workspace/snake_game.py with run_command, then fix any errors
+
+  step 1/2 — Developer
+    read_workspace →  workspace/
+    write_file     →  Wrote 2847 chars to workspace/snake_game.py
+
+  step 2/2 — BugFixer
+    run_command    →  (game window opens)
+    ✅ No errors found.
+```
+
+---
+
+## What is this?
+
+**nnn** is a ~1500-line Python project that builds a complete AI agent system from scratch. It uses [LM Studio](https://lmstudio.ai) to run a local language model and connects 5 specialized AI agents that collaborate to complete coding tasks.
+
+The agents:
+
+| Agent           | Job                                       |
+| --------------- | ----------------------------------------- |
+| **Architect**   | Designs system structure and writes plans |
+| **Developer**   | Reads plans and writes working code       |
+| **BugFixer**    | Runs code, finds errors, and fixes them   |
+| **Researcher**  | Analyzes existing code in the workspace   |
+| **WebSearcher** | Searches the internet for documentation   |
+
+They are not separate programs — they are the same AI model called with different instructions and different tools.
+
+---
+
+## Quick Start
+
+### 1. Install LM Studio
+
+Download [LM Studio](https://lmstudio.ai), load any model (Qwen 2.5 Coder 7B or higher recommended), and start the local server.
+
+### 2. Clone and install
+
+```bash
+git clone https://github.com/YOUR_USERNAME/nnn.git
+cd nnn
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### 3. Run
+
+```bash
+nnn
+```
+
+That's it. Type a task and press Enter.
+
+**One-shot mode:**
+
+```bash
+nnn "create a flask API with user login"
+```
+
+---
+
+## How It Works
+
+```
+You type a task
+     ↓
+Orchestrator asks the LLM: "Break this into steps and assign agents"
+     ↓
+LLM returns a JSON plan:  Developer → BugFixer
+     ↓
+Each agent runs in order, using tools (read/write files, run commands)
+     ↓
+You get working code in the workspace/ folder
+```
+
+There is only **one AI model** running. Each "agent" is just the same model called with a different system prompt and a different set of tools. For a deeper explanation, see [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md).
+
+---
+
+## Learn How to Build This
+
+This project comes with **14 step-by-step lessons** that teach you how to build the entire system from scratch. Each lesson adds one concept, and you test it before moving on.
+
+| #   | Lesson                                                  | What you build                                            |
+| --- | ------------------------------------------------------- | --------------------------------------------------------- |
+| 01  | [Talking to an AI Model](docs/01_talking_to_ai.md)      | Send a message to LM Studio and get a reply               |
+| 02  | [Giving the AI a Role](docs/02_giving_the_ai_a_role.md) | System prompts, multi-turn conversation                   |
+| 03  | [Tool Calling](docs/03_tool_calling.md)                 | AI calls real Python functions (read files, run commands) |
+| 04  | [Your First Agent Class](docs/04_your_first_agent.md)   | Package role + tools + loop into a reusable Agent         |
+| 05  | [Multiple Agents](docs/05_multiple_agents.md)           | 2 agents → 3 agents, passing context between them         |
+| 06  | [The Orchestrator](docs/06_the_orchestrator.md)         | AI decides which agents to run and in what order          |
+| 07  | [The Full System](docs/07_the_full_system.md)           | Add remaining tools + WebSearcher + Researcher            |
+| 08  | [Debugging Failures](docs/08_debugging_failures.md)     | Real failure cases and how to fix them                    |
+| 09  | [Speed & Context](docs/09_speed_and_context.md)         | 6 optimizations: caching, streaming, parallel execution   |
+| 10  | [Surgical Editing](docs/10_surgical_editing.md)         | Line-by-line editing tools (edit_lines, insert_code)      |
+| 11  | [Small-Model Safety](docs/11_small_model_safety.md)     | Safety nets for 3-4B models that fail often               |
+| 12  | [CLI & Packaging](docs/12_cli_and_packaging.md)         | Turn it into an installable `nnn` command                 |
+| 13  | [Project Intelligence](docs/13_project_intelligence.md) | Detect language/runtime, auto-install deps, syntax check  |
+| 14  | [Loop Hardening](docs/14_loop_hardening.md)             | Catch stealth errors, duplicate calls, smarter bailout    |
+
+Start at Lesson 01. Each lesson builds on the previous one. By Lesson 14 you have the complete system.
+
+**New to programming?** Start with [docs/BEGINNER_GUIDE.md](docs/BEGINNER_GUIDE.md) instead — it's a gentler introduction.
+
+---
+
+## Project Structure
+
+```
+nnn/
+├── main.py              ← entry point (REPL + one-shot mode)
+├── orchestrator.py      ← plans tasks and delegates to agents
+├── agent.py             ← base Agent class
+├── llm.py               ← LLM bridge (tool-calling loop, streaming, caching)
+├── tools.py             ← all tool implementations (read/write files, run commands, web search)
+├── config.py            ← settings (server URL, token limits, temperatures)
+├── agents/
+│   ├── architect.py     ← system designer
+│   ├── developer.py     ← code writer (with rescue safety nets)
+│   ├── bug_fixer.py     ← run → diagnose → fix → verify
+│   ├── researcher.py    ← code analyzer
+│   └── web_searcher.py  ← internet search
+├── workspace/           ← where agents write code (shared workspace)
+├── docs/                ← 12 step-by-step lessons
+├── pyproject.toml       ← package config
+└── requirements.txt     ← dependencies
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- [LM Studio](https://lmstudio.ai) with any loaded model
+- Recommended: Qwen 2.5 Coder 7B+ or Qwen 3 8B+ for best results
+- Works with 3-4B models too (with safety nets — see Lesson 11)
+
+---
+
+## Configuration
+
+All settings are in `config.py`:
+
+```python
+LM_BASE_URL = "http://localhost:1234/v1"   # LM Studio server
+MAX_TOKENS = 8192                           # max response length
+TEMPERATURE_CODE = 0.3                      # lower = more reliable tool use
+PARALLEL_AGENTS = True                      # run independent agents concurrently
+```
+
+Override with environment variables:
+
+```bash
+LM_BASE_URL=http://192.168.1.5:1234/v1 nnn "build a todo app"
+```
+
+---
+
+## License
+
+MIT

nnn_agent-0.1.0/agent.py

@@ -0,0 +1,82 @@
+"""
+Base Agent class.
+Each agent has a name, a role (system prompt), and a set of tools it can use.
+
+SPEED OPTIMIZATION — KV Cache Prefix Sharing:
+  All agents share a common system-prompt prefix (from config.SHARED_SYSTEM_PREFIX).
+  This means when LM Studio processes Agent B after Agent A, it can reuse the
+  KV cache for the shared prefix tokens instead of recomputing them from scratch.
+  On a 7B model, this saves ~200-500ms per agent switch.
+"""
+
+from rich.console import Console
+import llm
+import config
+import tools as tool_module
+
+console = Console()
+
+
+class Agent:
+    """A single AI agent with a specific role and tool set."""
+
+    def __init__(self, name: str, role: str, tool_names: list[str]):
+        """
+        Args:
+            name: Display name (e.g. "Architect")
+            role: System prompt describing the agent's persona and job
+            tool_names: List of tool names this agent can use (from tools.py)
+        """
+        self.name = name
+        # KV Cache optimization: prepend shared prefix so all agents
+        # share the same token prefix → LM Studio reuses KV cache
+        self.role = f"{config.SHARED_SYSTEM_PREFIX}\n\n{role}"
+        self.tool_names = tool_names
+
+        # Build the tool schemas and function map for this agent
+        self.tool_schemas = [
+            tool_module.TOOL_SCHEMAS[t] for t in tool_names
+            if t in tool_module.TOOL_SCHEMAS
+        ]
+        self.tool_functions = {
+            t: tool_module.TOOL_FUNCTIONS[t] for t in tool_names
+            if t in tool_module.TOOL_FUNCTIONS
+        }
+
+    def run(self, task: str, context: str = "") -> str:
+        """
+        Run this agent on a task.
+
+        Args:
+            task: What the agent should do
+            context: Additional context from previous agents or the workspace
+
+        Returns:
+            The agent's final text response
+        """
+        console.print(f"  [bold]{self.name}[/bold]")
+
+        system_msg = self.role
+        if context:
+            system_msg += f"\n\n--- CONTEXT FROM PREVIOUS WORK ---\n{context}"
+
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": task},
+        ]
+
+        # Speed: agents with tools use a smaller token limit than the default 8K
+        # Code agents use lower temperature for more reliable tool calling
+        response = llm.chat(
+            messages=messages,
+            tools=self.tool_schemas if self.tool_schemas else None,
+            tool_functions=self.tool_functions,
+            agent_name=self.name,
+            max_tokens=config.MAX_TOKENS_TOOL_AGENT,
+            temperature=config.TEMPERATURE_CODE if self.tool_schemas else None,
+        )
+
+        console.print()
+
+
+        return response

nnn_agent-0.1.0/agents/__init__.py

@@ -0,0 +1 @@
+"""Specialized agents package."""

nnn_agent-0.1.0/agents/architect.py

@@ -0,0 +1,28 @@
+"""
+Architect Agent — designs systems, creates plans, defines structure.
+"""
+
+from agent import Agent
+
+SYSTEM_PROMPT = """You are the Architect — a senior software architect.
+
+YOUR JOB:
+- Design system architecture and file structure
+- Create technical plans and specifications  
+- Define APIs, data models, and component boundaries
+- Write your plans to the shared workspace so other agents can follow them
+
+RULES:
+- Think before you act. Lay out the full design before any code is written.
+- Use `write_plan` to save your architecture docs to the workspace.
+- Use `list_files` and `read_workspace` to understand what already exists.
+- Be specific: name files, define interfaces, describe data flow.
+- Output clean, well-structured markdown plans.
+"""
+
+def create() -> Agent:
+    return Agent(
+        name="Architect",
+        role=SYSTEM_PROMPT,
+        tool_names=["write_plan", "read_workspace", "list_files", "read_file"],
+    )

nnn_agent-0.1.0/agents/bug_fixer.py

@@ -0,0 +1,40 @@
+"""
+Bug Fixer Agent — reviews code, spots bugs, applies fixes.
+"""
+
+from agent import Agent
+
+SYSTEM_PROMPT = """You are the Bug Fixer. You run code, find errors, and fix them.
+
+WORKFLOW — follow this exact order:
+1. RUN the code first. Pick the correct runtime based on file extension:
+   - .py  → run_command({"command": "python3 filename.py"})
+   - .js  → run_command({"command": "node filename.js"})
+   - .ts  → run_command({"command": "npx tsx filename.ts"})
+   - .go  → run_command({"command": "go run filename.go"})
+   IMPORTANT: NEVER use python3 to run .js files! Use node for JavaScript.
+   run_command already runs from workspace/, so just use the filename. Do NOT add 'cd workspace'.
+2. READ the error output. It tells you the exact line and problem.
+3. Use `read_file` to see the code.
+4. Fix it:
+   - Simple error (1-2 lines wrong) → use `edit_lines` on those lines.
+   - Many errors or structural mess → rewrite with `write_file`.
+5. RUN again to verify the fix worked.
+6. If same error appears twice, STOP editing and REWRITE with write_file.
+7. If you have tried 3 times and cannot fix it, STOP and report what you found.
+
+SERVERS / LONG-RUNNING PROCESSES (Express, Flask, http.server, fastapi, etc.):
+- Do NOT run them with run_command — they never exit and will timeout.
+- Instead: read the code, check for syntax errors and missing imports, fix issues, done.
+- For JS servers: node -e "require('./file.js')" (quick syntax check)
+- For Python: python3 -c "import ast; ast.parse(open('file.py').read())"
+
+NEVER guess at bugs. ALWAYS run first (unless it's a server).
+"""
+
+def create() -> Agent:
+    return Agent(
+        name="BugFixer",
+        role=SYSTEM_PROMPT,
+        tool_names=["read_file", "write_file", "edit_lines", "run_command", "read_workspace", "list_files"],
+    )