Spaces:
Running
Running
| # SoniCoder v2.1 — Project Memory | |
| > This file is the project's persistent memory. The agent reads it on every session. | |
| > Edit it freely — it overrides defaults. | |
| ## What is SoniCoder? | |
| SoniCoder v2.1 is a **local-first AI coding agent** that can: | |
| ### Core Capabilities | |
| - Generate complete fullstack applications in any language/framework | |
| - Read, write, and edit files in a sandboxed workspace | |
| - Run shell commands (git, npm, pip, tests) with enhanced safety | |
| - Apply specialized skills (frontend-design, feature-dev, code-review, debugging, fullstack-scaffold, commit-workflow) | |
| - Respond to slash commands (/commit, /review, /feature, /design, /explain, /test, /refactor, /skill, /help) | |
| - Deploy to HuggingFace Spaces with one click | |
| - Manage and export conversation sessions | |
| - Use code templates for rapid development | |
| ### v2.1 Enhancements | |
| - **Session Management**: Persistent conversations with JSON/Markdown/HTML export | |
| - **Code Templates**: Pre-built templates for Flask, React, Gradio, Express | |
| - **Performance**: Response caching, model optimization, progress tracking | |
| - **Security**: Enhanced command blocking, input validation, audit logging | |
| - **Metrics**: Inference statistics, token counting, performance monitoring | |
| - **New Models**: DeepSeek-Coder-1.3B support for advanced reasoning | |
| ## Architecture | |
| ``` | |
| app.py ← Entry point: launches Gradio Server | |
| code/ | |
| ├── config/constants.py ← App config, system prompt, templates (ENHANCED) | |
| ├── model/ | |
| │ ├── loader.py ← Model loading with progress & memory optimization | |
| │ └── inference.py ← Streaming inference with caching & metrics | |
| ├── agent/__init__.py ← Agent loop (model ↔ tools, supports custom agents) | |
| ├── tools/ | |
| │ ├── fs.py ← read_file, write_file, edit_file, glob, grep, list_dir | |
| │ ├── bash.py ← Sandboxed shell execution (ENHANCED - audit trail) | |
| │ ├── todos.py ← Todo list management | |
| │ └── github.py ← GitHub repo import (shallow clone + strip heavy dirs) | |
| ├── skills/ | |
| │ ├── __init__.py ← Skill discovery + loading | |
| │ └── builtins/ ← Built-in skills (markdown) | |
| ├── agents/ ← Custom Agent system (AI-generated personas) | |
| │ ├── __init__.py ← Agent CRUD + system-prompt builder | |
| │ └── builtins/ ← Built-in agents (code-reviewer, test-writer) | |
| ├── commands/ | |
| │ ├── __init__.py ← Slash command parser + expander | |
| │ └── builtins/ ← Built-in commands (markdown) | |
| ├── hooks/ | |
| │ ├── __init__.py ← Hook rule engine | |
| │ └── builtins/ ← Built-in hook rules (markdown) | |
| ├── execution/ | |
| │ ├── code_extractor.py ← Code extraction from model output | |
| │ ├── python_runner.py ← Sandboxed Python execution | |
| │ └── gradio_runner.py ← Gradio app subprocess runner | |
| ├── huggingface/ | |
| │ ├── dockerfile_gen.py ← Auto Dockerfile/package.json for JS | |
| │ └── push.py ← HF Hub push + ZIP packaging | |
| ├── websearch/google_scraper.py ← DuckDuckGo + Google scraping (no API) | |
| ├── server/ | |
| ├── routes.py ← All HTTP + API endpoints | |
| ├── chat_helpers.py ← Chat history + prompt building (ENHANCED) | |
| ├── session_manager.py ← Session persistence & export (NEW) | |
| └── __init__.py ← Server utilities & helpers | |
| index.html ← Frontend (single-file SPA) | |
| workspace/ ← Sandboxed agent workspace (auto-created) | |
| downloads/ ← Exported files directory (auto-created) | |
| ``` | |
| ## Conventions | |
| - **Python**: 3.11+, type hints everywhere, `from __future__ import annotations` | |
| - **Style**: Black formatting, 4-space indent, 100 char line limit | |
| - **Docstrings**: Google style for modules, functions, classes | |
| - **Error handling**: catch specific exceptions, never bare `except:` | |
| - **Logging**: use `logging.getLogger(__name__)`, never `print()` | |
| - **Tests**: pytest, in `tests/` directory, `test_*.py` naming | |
| - **Frontend**: single-file HTML with inline CSS/JS, no build step | |
| ## Server Rules | |
| - All servers bind to `0.0.0.0` (never `localhost`) | |
| - Default port: `7860` (HF Spaces convention) | |
| - Sub-servers use `7861`, `7862`, etc. | |
| - Graceful shutdown on SIGTERM/SIGINT | |
| ## Model Configuration | |
| | Model | Type | Size | Best For | | |
| |-------|------|------|----------| | |
| | Qwen2.5-Coder-1.5B | Text | 3.0 GB | Tool-calling, code generation | | |
| | MiniCPM5-1B | Text | 2.17 GB | Fast inference | | |
| | MiniCPM-V-4.6 | VLM | 2.8 GB | Image understanding | | |
| | DeepSeek-Coder-1.3B | Text | 2.6 GB | Advanced reasoning | | |
| - Default: `Qwen/Qwen2.5-Coder-1.5B-Instruct` | |
| - Loaded in background thread on startup | |
| - Streaming inference via `TextIteratorStreamer` | |
| - One model loaded at a time (memory conservation) | |
| ## Tool Call Format | |
| The model calls tools by emitting fenced code blocks with `tool` as the language: | |
| ```tool | |
| read_file | |
| path: src/app.py | |
| ``` | |
| Multi-line values use YAML block scalars: | |
| ```tool | |
| write_file | |
| path: src/new.py | |
| content: | | |
| import os | |
| def main(): | |
| pass | |
| ``` | |
| ## Slash Commands | |
| | Command | Description | | |
| |---------|-------------| | |
| | `/commit` | Create a git commit with a generated message | | |
| | `/review` | Review current changes for bugs and quality | | |
| | `/feature <desc>` | Guided feature development workflow | | |
| | `/design <brief>` | Generate a distinctive frontend design | | |
| | `/explain <target>` | Explain how code works | | |
| | `/test <target>` | Generate tests | | |
| | `/refactor <target>` | Refactor code for clarity | | |
| | `/skill <name>` | Load and apply a skill | | |
| | `/agent create <desc>` | AI generates a custom agent from natural-language description | | |
| | `/agent use <name>` | Activate a saved agent | | |
| | `/agent list` | List all saved agents | | |
| | `/github <url> [subdir] [--branch <name>] [--into <path>]` | Import a GitHub repo into the workspace | | |
| | `/help` | Show available commands and skills | | |
| ## Code Templates | |
| Templates provide quick-start code for common patterns: | |
| | Template ID | Name | Language | Framework | | |
| |-------------|------|----------|-----------| | |
| | `python-flask-api` | Flask REST API | Python | Flask | | |
| | `react-todo-app` | React Todo App | JavaScript | React | | |
| | `gradio-image-app` | Gradio Image Processor | Python | Gradio | | |
| | `express-js-server` | Express.js Server | JavaScript | Express.js | | |
| Access via API: `GET /api/templates` or `GET /api/templates/{id}` | |
| ## Session Management | |
| Sessions are automatically created and persisted: | |
| - **Storage**: `CONFIG_DIR/sessions/*.json` | |
| - **Auto-save**: On each message | |
| - **Export formats**: JSON, Markdown, HTML | |
| - **Cleanup**: Sessions older than 30 days are auto-removed | |
| ### Session API Endpoints | |
| | Endpoint | Description | | |
| |----------|-------------| | |
| | `POST /api/sessions/create` | Create new session | | |
| | `GET /api/sessions/{id}` | Get session details | | |
| | `PUT /api/sessions/{id}` | Update session metadata | | |
| | `DELETE /api/sessions/{id}` | Delete session | | |
| | `GET /api/sessions` | List sessions (with search) | | |
| | `POST /api/sessions/{id}/export` | Export session | | |
| ## Performance Features | |
| ### Response Caching | |
| - Similar prompts are cached for faster responses | |
| - Configurable TTL (default: 5 minutes) | |
| - Automatic cache invalidation | |
| - Cache stats available via `/api/cache/stats` | |
| ### Model Optimization | |
| - Automatic precision selection (bfloat16 > float16 > float32) | |
| - Better Transformer structure when available | |
| - Torch compile support (PyTorch 2.0+) | |
| - Memory-efficient loading with offload support | |
| ### Metrics Tracking | |
| Each inference call tracks: | |
| - Time to first token (TTFT) | |
| - Tokens per second | |
| - Total generation time | |
| - Cache hit/miss status | |
| - Error information | |
| ## Security Enhancements | |
| ### Command Safety (Enhanced) | |
| Additional blocked patterns: | |
| - Regex-based pattern matching | |
| - Fork bomb detection (`:(){:|:&};:`) | |
| - Pipe-to-shell prevention (`curl ... | bash`) | |
| - Root filesystem protection | |
| - Character validation (null bytes, etc.) | |
| ### Input Validation | |
| - Maximum prompt length: 10,000 characters | |
| - Maximum file size: 10 MB | |
| - Rate limiting: 30 requests/minute | |
| - Environment variable scrubbing (secrets removal) | |
| ### Audit Trail | |
| All bash commands are logged with: | |
| - Timestamp | |
| - Full command (truncated to 500 chars) | |
| - Success/failure status | |
| - Return code | |
| - Timeout flag | |
| - Execution duration | |
| Access via: `GET /api/audit/log` or `code.tools.bash.get_command_history()` | |
| ## Hooks | |
| Hooks are markdown rules that fire on events (`bash`, `file`, `prompt`, `stop`). | |
| They can `warn` (show a message) or `block` (prevent the action). | |
| Built-in hooks: | |
| - `block-dangerous-rm` — blocks `rm -rf /`, `~`, `$HOME`, `..` | |
| - `warn-debug-code` — warns on `console.log`, `debugger`, `print`, `alert` | |
| - `warn-secrets-in-code` — warns on hardcoded API_KEY/SECRET/TOKEN/PASSWORD | |
| - `warn-eval-exec` — warns on `eval()` and `exec()` | |
| Users can add custom hooks in `workspace/.sonicoder/hooks/*.local.md`. | |
| ## Workspace | |
| The agent's sandboxed filesystem lives at `./workspace/` (configurable via | |
| `SONICODER_WORKSPACE` env var). All file tools refuse paths that escape this root. | |
| ## Deploy | |
| Generated projects can be pushed to HuggingFace Spaces via the Deploy tab. | |
| Supported SDKs: | |
| - `static` — HTML/CSS/JS | |
| - `gradio` — Python Gradio apps | |
| - `streamlit` — Python Streamlit apps | |
| - `docker` — JS/TS frameworks (auto-generates Dockerfile + package.json) | |
| ## Testing | |
| Run the test suite: | |
| ```bash | |
| # Install test dependencies | |
| pip install pytest pytest-cov | |
| # Run tests | |
| pytest tests/ -v --cov=code --cov-report=html | |
| # Run specific test file | |
| pytest tests/test_bash_safety.py -v | |
| ``` | |
| ## Troubleshooting | |
| ### Common Issues | |
| **Model fails to load (OOM)** | |
| - Try a smaller model (MiniCPM5-1B) | |
| - Close other applications using GPU memory | |
| - Check available RAM (need ~4GB for text models) | |
| **Slow response times** | |
| - Enable caching (default: on) | |
| - Use smaller max_tokens for testing | |
| - Consider CPU-only mode if GPU transfer is slow | |
| **Commands being blocked** | |
| - Review blocked patterns in `code/tools/bash.py` | |
| - Check hook rules in `code/hooks/` | |
| - Use `/help` for allowed operations | |
| ## Version History | |
| ### v2.1.0 (Current) | |
| - Added DeepSeek-Coder-1.3B model support | |
| - Implemented session management with persistence | |
| - Added code template system | |
| - Enhanced security with regex-based command blocking | |
| - Added response caching and performance metrics | |
| - Improved error handling and recovery | |
| - Added export functionality (JSON/Markdown/HTML) | |
| ### v2.0.0 | |
| - Initial release with Gradio 6.x architecture | |
| - Multi-model support (Qwen2.5-Coder, MiniCPM5, MiniCPM-V) | |
| - Agent loop with tool calling | |
| - Skills and commands system | |
| - GitHub integration | |
| - HuggingFace deployment | |