Update README.md

README.md

@@ -4,4 +4,168 @@ language:
 - en
 base_model:
 - Qwen/Qwen3-Coder-30B-A3B-Instruct
----
+---
+
+# Coding agent
+
+A simple coding agent built with Qwen_Distilled_Coder (via OpenRouter) that can view/edit files and execute bash commands—all in ~200 lines.
+
+
+```mermaid
+flowchart TD
+   Start([Start]) --> UserInput[Get User Input]
+   UserInput --> Qwen_Distilled_Coder[Send to Qwen_Distilled_Coder]
+   Qwen_Distilled_Coder --> NeedsTools{Needs Tools?}
+
+   NeedsTools -->|No| ShowResponse[Show Response]
+   NeedsTools -->|Yes| ExecuteTools[Execute Tools]
+
+   ExecuteTools --> SendResults[Send Results to Qwen_Distilled_Coder]
+   SendResults --> Qwen_Distilled_Coder
+
+   ShowResponse --> UserInput
+
+   ExecuteTools -.-> Tools
+```
+
+## Quick start
+
+1. **Create virtual environment and install dependencies**:
+
+   ```bash
+   # Option 1: uv installed
+   uv venv
+   source .venv/bin/activate # On Windows: .venv\Scripts\activate
+   uv sync
+
+   # Option 2: Without uv
+   python3 -m venv .venv
+   source .venv/bin/activate # On Windows: .venv\Scripts\activate
+   pip3 install uv
+   uv sync
+   ```
+
+2. **Setup environment & add API key**:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Be sure to add your OpenRouter API key! You can get one from [OpenRouter](https://openrouter.ai/keys).
+
+3. **Run the CLI agent**:
+
+   ```bash
+   uv run simple_agent.py
+   ```
+
+
+Note: `uv` and an appropriate virtualenv are prerequisites—our agent will use uv to execute Python scripts
+
+## Using OpenRouter with Qwen Distilled Coder
+
+This agent uses the [OpenRouter](https://openrouter.ai/) API to access the Qwen_Distilled_Coder model. OpenRouter provides a unified API for accessing various AI models, including those from Anthropic, OpenAI, and others.
+
+To use this agent:
+
+1. Sign up for an account at [OpenRouter](https://openrouter.ai/)
+2. Create an API key at [OpenRouter Keys](https://openrouter.ai/keys)
+3. Add your API key to the `.env` file
+4. Run the agent with `uv run simple_agent.py`
+
+The agent uses the OpenAI client library but points it to the OpenRouter API endpoint, allowing it to access the Qwen_Distilled_Coder model.
+
+## What it does
+
+- **Fix broken files**: `"can you help me fix broken_file.py?"`
+- **Research and implement**: `"research new Python 3.13 features and write a file that demonstrates a simple example"`
+- **Create new code**: `"write a simple tip splitting calculator Python file"`
+
+## Architecture
+
+The agent follows a straightforward pattern with three core components:
+
+### Prompt structure
+
+```xml
+<role>
+You are an expert software engineering assistant...
+</role>
+
+<thinking_process>
+Before taking any action, think through the problem step by step...
+</thinking_process>
+
+<instructions>
+When working with code:
+1. Understanding First: Always examine existing files...
+2. Targeted Changes: Use precise `str_replace` operations...
+</instructions>
+```
+
+**Best practices:**
+
+- Split system prompt (role) from user instructions for better caching
+- Use XML tags for structured prompts and interpretability  
+- Include chain-of-thought reasoning with `<thinking_process>` blocks
+- Cache tools, system prompt, and first user message for cost optimization
+
+### Tool execution router
+
+```python
+def execute_tool(tool_name: str, tool_input: dict) -> dict:
+    """Execute a tool and return structured result with error handling."""
+    try:
+        if tool_name == "view":
+            # Handle file/directory viewing
+        elif tool_name == "str_replace":
+            # Handle targeted file edits
+        elif tool_name == "bash":
+            # Handle command execution with timeout
+        # ...
+    except Exception as e:
+        return {"content": f"Error: {str(e)}", "is_error": True}
+```
+
+**Best practices:**
+
+- Return structured responses with `is_error` flag for Qwen_Distilled_Coder
+- Use proper timeout protection (30s default for bash)
+- Include detailed error logging and handling
+- Support both file operations and bash commands
+
+### Agent loop
+
+```python
+while True:
+    response = client.messages.create(
+        model=ANTHROPIC_MODEL,
+        system=[{"type": "text", "text": system_prompt}],
+        messages=messages,
+        tools=ANTHROPIC_TOOLS,
+    )
+    
+    if response.stop_reason == "tool_use":
+        # Execute tools in parallel when possible
+        # Return results to Qwen_Distilled_Coder for continued processing
+    else:
+        # Handle final response
+        break
+```
+
+**Best practices:**
+
+- Handle all stop reasons robustly (tool_use, end_turn, etc.)
+- Execute multiple tools in parallel when possible
+- Maintain conversation state through message history
+- Use low temperature (0.2) for consistent, focused responses
+
+## Files
+
+- `simple_agent.py` - CLI version
+- `prompt.md` - System prompt and instructions
+
+## Requirements
+
+- Python 3.13+
+- OpenRouter API key