README.md

---
title: SoniCoder v2.1
emoji: 🚀
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
pinned: false
license: apache-2.0
---

# SoniCoder v2.1 — Enhanced AI Code Agent

> **Optimized AI code writer agent with architecture inspired by Gemini CLI and Claude Code.**

**No external APIs needed** — runs entirely on local inference with smart 1B models.

## ✨ What's New in v2.1

### 🎯 Major Enhancements

- **🤖 New Model Support**: Added DeepSeek-Coder-1.3B for advanced code reasoning
- **💾 Session Management**: Persistent conversations with export to JSON/Markdown/HTML
- **📝 Code Templates**: Quick-start templates for common project types (Flask, React, Express, Gradio)
- **⚡ Performance Optimizations**: Response caching, model optimization, better memory management
- **🔒 Security Hardening**: Enhanced input validation, command blocking patterns, environment scrubbing
- **📊 Metrics & Monitoring**: Inference metrics tracking, token counting, performance statistics
- **🎨 Improved UI**: Better error messages, loading states, progress indicators

### 🔧 Technical Improvements

- **Model Loading Progress**: Real-time progress callbacks during model initialization
- **Response Caching**: Cache similar prompts for faster responses (configurable TTL)
- **Better Error Recovery**: Graceful fallbacks when streaming fails
- **Command Audit Trail**: Track executed commands with timestamps and results
- **Conversation Summarization**: Auto-summarize long contexts to stay within token limits
- **Token Usage Estimation**: Estimate token counts for cost/performance planning

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://huggingface.co/spaces/sonic-coder/sonicoder
cd sonicoder

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

### Docker (Alternative)

```dockerfile
FROM python:3.11-slim

WORKSPACE /app
COPY . .

RUN pip install -r requirements.txt

EXPOSE 7860

CMD ["python", "app.py"]
```

## 🖥️ Features

### Core Capabilities

| Feature | Description |
|---------|-------------|
| **Code Generation** | Generate complete applications in any language/framework |
| **File Operations** | Read, write, edit files in a sandboxed workspace |
| **Shell Execution** | Run commands (git, npm, pip, tests) with safety controls |
| **Multi-model Support** | Switch between Qwen2.5-Coder, MiniCPM5, MiniCPM-V, DeepSeek-Coder |
| **Vision Support** | Upload images for VLM-powered code generation |
| **Slash Commands** | `/commit`, `/review`, `/feature`, `/design`, etc. |
| **Custom Agents** | Create AI-generated personas with specialized behaviors |

### Built-in Skills

| Skill | Description |
|-------|-------------|
| `frontend-design` | Distinctive visual design guidance |
| `feature-dev` | Guided feature implementation workflow |
| `code-review` | High-signal code review |
| `debugging` | Systematic debugging workflow |
| `fullstack-scaffold` | Project structure scaffolding rules |
| `commit-workflow` | Git commit best practices |

### Code Templates

Quick-start templates available:

| Template | Language | Framework |
|----------|----------|-----------|
| `python-flask-api` | Python | Flask |
| `react-todo-app` | JavaScript | React |
| `gradio-image-app` | Python | Gradio |
| `express-js-server` | JavaScript | Express.js |

## 📁 Project Structure

```
sonicoder/
├── app.py                          # Entry point: launches Gradio Server
├── requirements.txt                # Python dependencies
├── README.md                       # This file
├── CLAUDE.md                       # Project memory & conventions
├── index.html                      # Frontend (single-file SPA)
│
└── code/
    ├── config/
    │   └── constants.py            # App config, system prompt, templates
    ├── model/
    │   ├── loader.py               # Model loading with progress tracking
    │   └── inference.py            # Streaming inference with caching
    ├── agent/
    │   └── __init__.py             # Agent loop (model ↔ tools)
    ├── tools/
    │   ├── fs.py                   # File operations
    │   ├── bash.py                 # Sandboxed shell execution (enhanced)
    │   ├── todos.py                # Todo list management
    │   └── github.py               # GitHub integration
    ├── skills/                     # Built-in skills (markdown)
    ├── agents/                     # Custom agent system
    ├── commands/                   # Slash command definitions
    ├── hooks/                      # Safety hook rules
    ├── execution/                  # Code execution sandbox
    ├── server/
    │   ├── routes.py               # All HTTP + API endpoints
    │   ├── chat_helpers.py         # Prompt building (enhanced)
    │   ├── session_manager.py      # Session persistence & export (NEW)
    │   └── __init__.py             # Server utilities
    ├── huggingface/                # HF Spaces deployment
    ├── websearch/                  # Web search scraping
    └── config.py                   # Workspace & config paths
```

## 🎮 Usage Examples

### Basic Code Generation

```
User: Create a Python Flask API with CRUD operations for a todo list
SoniCoder: [Generates complete Flask application with proper structure]
```

### Using Templates

```
User: Use the react-todo-app template as a starting point
SoniCoder: [Loads template and customizes based on requirements]
```

### Iterative Development

```
User: Build me a REST API
SoniCoder: [Creates initial API]

User: Add authentication to it
SoniCoder: [Reads existing file, adds auth middleware]

User: Write tests for the auth endpoint
SoniCoder: [Creates test file with pytest]
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SONICODER_WORKSPACE` | Workspace root directory | `./workspace` |
| `MODEL_CACHE_DIR` | Model cache location | Default HF cache |

### Model Selection

Models can be switched via the UI or API:

```python
from code.model.loader import switch_model

# Switch to DeepSeek Coder
result = switch_model("deepseek-coder-1.3b")
print(result)  # {"success": True, "message": "Switching to DeepSeek-Coder-1.3B..."}
```

### Performance Tuning

In `code/config/constants.py`:

```python
# Enable response caching
CACHE_ENABLED = True
CACHE_TTL_SECONDS = 300  # 5 minutes

# Concurrency limits
MAX_CONCURRENT_REQUESTS = 5
```

## 🔒 Security

### Command Safety

Blocked patterns include:
- Destructive commands (`rm -rf /`, `mkfs`, `dd`)
- System control (`shutdown`, `reboot`)
- Fork bombs (`:(){:|:&};:`)
- Pipe-to-shell attacks (`curl ... | bash`)
- Root filesystem modifications

### Input Validation

- Maximum prompt length: 10,000 characters
- Maximum file size: 10 MB
- Rate limiting: 30 requests/minute
- Regex-based pattern blocking

## 📊 Export & Sessions

### Export Formats

Sessions can be exported in multiple formats:

```python
from code.server.session_manager import export_session, get_session_manager

manager = get_session_manager()
session = manager.get_session("session_id")

# Export as JSON
export_session(session, format="json", output_dir="./exports")

# Export as Markdown
export_session(session, format="markdown", output_dir="./exports")

# Export as styled HTML
export_session(session, format="html", output_dir="./exports")
```

### Session Persistence

Sessions are automatically saved to `CONFIG_DIR/sessions/` and restored on restart.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

## 🙏 Acknowledgments

- Inspired by [Gemini CLI](https://github.com/google-gemini/gemini-cli) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- Powered by Hugging Face Transformers
- Models: Qwen2.5-Coder, MiniCPM5, MiniCPM-V, DeepSeek-Coder

---

**Built with ❤️ by the SoniCoder team**