[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92658":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":12,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":13,"stars30d":12,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":14,"rankGlobal":8,"rankLanguage":8,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":16,"hasPages":16,"topics":18,"createdAt":8,"pushedAt":8,"updatedAt":19,"readmeContent":20,"aiSummary":21,"trendingCount":13,"starSnapshotCount":13,"syncStatus":22,"lastSyncTime":23,"discoverSource":24},92658,"Ada-SI","nazirlouis\u002FAda-SI","nazirlouis",null,"Python",59,21,1,0,41.13,"MIT License",false,"main",[],"2026-07-22 04:02:06","# Ada-SI\n\n**Repository:** [github.com\u002Fnazirlouis\u002FAda-SI](https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI)\n\n**Ada-SI** is a local-first, self-improving AI assistant platform. Chat with **Scout** (Ada) through a gamified interface, watch it forge new Python skills at runtime, and run interactive skill apps — all on your machine.\n\nThe UI title is **ADA Chat**. Scout is the main agent; a separate **Forge master** agent plans, writes, tests, and installs new tools when Scout needs capabilities it does not yet have.\n\n## ⚠️ Disclaimer — Read Before Installing\n\n**This project is an experiment.** It was built to explore local AI assistants that can extend their own capabilities at runtime. It is **not** production software, has **not** been audited for security, and may contain bugs or unsafe behavior.\n\n**Do not download, clone, or install Ada-SI unless you understand what it does and accept the risks.**\n\nWhen you run Ada-SI, you grant an AI substantial control over your computer:\n\n- **Scout** can call installed skills and propose new ones that run **arbitrary Python** on your machine.\n- The **Forge** pipeline can **install pip packages** and write executable code to disk (with your approval at several steps — but approval gates reduce accidents; they are **not** a security sandbox).\n- Forged skills run in an **isolated Python venv**, not a hardened container. They can still read\u002Fwrite files, spawn subprocesses, and make network requests within your OS user permissions.\n- There is **no login or authentication**. Anyone who can reach the chat server (port 8080) or, on native installs, the tool runtime (port 8090) can use your API keys, forge tools, and run code.\n- API keys are stored in `.env` and `chat\u002Fstaging\u002Fsecrets.json` and may be readable by forged tools via environment variables.\n\n**Use Ada-SI only on a trusted machine, for a single user, on localhost.** Do not expose it to the public internet without a reverse proxy, VPN, or IP allowlist — and even then, treat it as high-risk software. If you are unsure, **do not run this project.**\n\nSee also [Security & Trust](#security--trust) for a fuller threat model.\n\n## Table of Contents\n\n- [Disclaimer](#-disclaimer--read-before-installing)\n- [Security & Trust](#security--trust)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Installation and Setup](#installation-and-setup)\n  - [Choose your install path](#choose-your-install-path)\n  - [Native install (Windows)](#native-install-windows)\n  - [Docker install (VPS \u002F cross-platform)](#docker-install-vps--cross-platform)\n  - [VPS deployment](#vps-deployment)\n- [Configuration](#configuration)\n- [Using Ada-SI](#using-ada-si)\n- [Core Workflows](#core-workflows)\n- [Agents](#agents)\n- [Project Structure](#project-structure)\n- [Developer Reference](#developer-reference)\n- [Troubleshooting](#troubleshooting)\n- [Tech Stack](#tech-stack)\n- [License](#license)\n\n---\n\n## Security & Trust\n\nAda-SI is designed for **one person on one trusted machine**. It is not multi-tenant software.\n\n| Risk | Detail |\n|------|--------|\n| **No authentication** | Chat, forge, secrets, and persona APIs are open to anyone who can reach the service. Native installs also expose the tool runtime on `127.0.0.1:8090` with no auth — any local process can install packages or run tools. |\n| **AI computer control** | Scout and forged skills can execute Python, modify files under `chat\u002Fcustom_tools\u002F` and `chat\u002Fstaging\u002F`, install pip packages, and update persona\u002Fmemory files. Background **heartbeat** can trigger LLM calls on a timer. |\n| **Weak isolation** | Tool execution uses a separate Python venv, not OS-level sandboxing. Do not treat forged skills as safe — treat them like running **untrusted scripts** you wrote yourself. |\n| **Supply chain** | Pip packages installed during forge (including pre-approval sandbox tests) can run install-time code on your host. Review package approvals in the Supplies tab. |\n| **Secrets exposure** | Provider API keys live in `.env`, `chat\u002Fstaging\u002Fsecrets.json`, and process environment. Forged tools may read `os.environ`. |\n| **Debug logging** | `ADA_LOG_LEVEL=DEBUG` may log chat content, tool arguments, and generated code to `logs\u002Fchat.log`. |\n| **VPS \u002F remote use** | If you deploy with Docker, bind behind HTTPS, restrict network access, and assume port 8080 is fully privileged. Consider disabling forge on any internet-facing host. |\n\nHuman-in-the-loop gates (plan approval, pip approval, UI preview) help prevent mistakes. They do **not** prevent a determined or prompt-injected model from proposing harmful tools — you are the last line of defense.\n\n---\n\n## Features\n\n- **Gamified chat UI** — XP, levels (1–50), rank titles, level-up effects, and a 3D avatar visualizer\n- **Runtime skill forging** — Scout can create, test, and install Python tools on the fly with your approval\n- **Interactive skill apps** — Forged skills can ship custom HTML\u002FCSS\u002FJS UIs (calendar, list, table, or custom layouts)\n- **Multi-provider LLM routing** — OpenAI, Anthropic, Gemini, and Groq via [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm)\n- **Persona and memory** — OpenClaw-style markdown files (SOUL, IDENTITY, MEMORY, and more) shape Scout's behavior\n- **Voice input and TTS** — Browser speech recognition for input; optional ElevenLabs read-aloud for responses\n- **Batch forging** — Create 2–10 independent tools in parallel\n- **No database required** — File-based persistence plus browser `localStorage` for progression\n\n---\n\n## Architecture\n\nAda-SI runs as three cooperating services. The chat server serves the React UI and orchestrates everything; LiteLLM routes LLM calls; the tool runtime executes forged Python skills in an isolated Python venv (not OS-level sandboxing).\n\n```mermaid\nflowchart LR\n  Browser[\"Browser UI :8080 or :5173\"]\n  Chat[\"Chat API + React static\"]\n  LiteLLM[\"LiteLLM proxy :4000\"]\n  ToolRT[\"Tool runtime :8090\"]\n  Providers[\"OpenAI \u002F Anthropic \u002F Gemini \u002F Groq\"]\n  Files[\"staging\u002F + custom_tools\u002F\"]\n\n  Browser --> Chat\n  Chat --> LiteLLM\n  Chat --> ToolRT\n  LiteLLM --> Providers\n  Chat --> Files\n  ToolRT --> Files\n```\n\n| Service | Port | Role | Key file |\n|---------|------|------|----------|\n| **Chat server** | 8080 | FastAPI backend, SSE chat, forge APIs, persona, TTS; serves built React UI | [`chat\u002Fapp.py`](chat\u002Fapp.py) |\n| **LiteLLM proxy** | 4000 | Routes model requests to LLM providers | [`litellm\u002Fconfig.yaml`](litellm\u002Fconfig.yaml) |\n| **Tool runtime** | 8090 | Executes installed Python skills in an isolated venv (not OS-level sandboxing) | [`tool_runtime\u002Fserver.py`](tool_runtime\u002Fserver.py) |\n| **Vite dev server** (optional) | 5173 | Hot-reload frontend; proxies `\u002Fapi` to chat server | [`chat\u002Ffrontend\u002Fvite.config.ts`](chat\u002Ffrontend\u002Fvite.config.ts) |\n\n**Frontend** — React 19 + TypeScript + Vite, source in [`chat\u002Ffrontend\u002F`](chat\u002Ffrontend), production build output in [`chat\u002Fstatic\u002F`](chat\u002Fstatic).\n\n**Persistence** — No traditional database. Runtime config lives in `chat\u002Fstaging\u002F`; forged skills in `chat\u002Fcustom_tools\u002F`; player XP in browser `localStorage`.\n\n---\n\n## Prerequisites\n\n**Native install (Windows)**\n\n| Requirement | Version | Used for |\n|-------------|---------|----------|\n| **Python** | 3.12 | Chat server, tool runtime, LiteLLM venv |\n| **Node.js** | 22+ | Frontend build and dev mode |\n| **PowerShell** | 5.1+ | Native launchers ([`start.ps1`](start.ps1), [`install-native.ps1`](install-native.ps1)) |\n\nOn Windows, the launcher looks for Python via `py -3.12`, `python3.12`, or `python`.\n\n**Docker install (VPS \u002F cross-platform)**\n\n| Requirement | Version | Used for |\n|-------------|---------|----------|\n| **Docker Engine** | — | Container runtime |\n| **Docker Compose** | v2 plugin | Orchestrates three services via [`docker-compose.yml`](docker-compose.yml) |\n\nNo host Python or Node.js is required for Docker — the frontend is built inside the [`chat\u002FDockerfile`](chat\u002FDockerfile) image.\n\n---\n\n## Installation and Setup\n\n### Choose your install path\n\n| Goal | Install path | Scripts |\n|------|--------------|---------|\n| **Local Windows development** | Native | [`install-native.bat`](install-native.bat) → [`start.bat`](start.bat) |\n| **VPS, Linux, Mac, or Windows with Docker Desktop** | Docker | [`install-docker.sh`](install-docker.sh) \u002F [`install-docker.bat`](install-docker.bat) → [`start-docker.sh`](start-docker.sh) \u002F [`start-docker.bat`](start-docker.bat) |\n\nBoth paths use the same [`.env`](.env.example) configuration and persist data under `chat\u002Fstaging\u002F` and `chat\u002Fcustom_tools\u002F`.\n\n---\n\n### Native install (Windows)\n\n1. **Clone the repository**\n\n   ```powershell\n   git clone https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI.git\n   cd Ada-SI\n   ```\n\n2. **Run the native installer** (first time only)\n\n   ```powershell\n   .\\install-native.bat\n   ```\n\n   This creates `.env` from [`.env.example`](.env.example), prepares runtime directories, and installs Python\u002FNode dependencies.\n\n3. **Edit `.env`** — set at minimum:\n\n   ```env\n   LITELLM_MASTER_KEY=sk-ada-dev-key\n   LITE_MODEL=openai\u002Fgpt-4o-mini\n   TOOL_CREATOR_MODEL=openai\u002Fgpt-4o-mini\n   OPENAI_API_KEY=sk-...\n   ```\n\n   Use any secure string for `LITELLM_MASTER_KEY`. Model IDs follow the `provider\u002Fmodel` format (e.g. `anthropic\u002Fclaude-sonnet-4-20250514`, `gemini\u002Fgemini-2.0-flash`, `groq\u002Fllama-3.3-70b-versatile`). Add keys only for providers you plan to use.\n\n4. **Start Ada-SI**\n\n   ```powershell\n   .\\start.bat\n   ```\n\n   Or run the PowerShell script directly:\n\n   ```powershell\n   .\\start.ps1\n   ```\n\n5. **Open the app** — your browser should open automatically at:\n\n   ```\n   http:\u002F\u002F127.0.0.1:8080\n   ```\n\n### What `start.ps1` Does\n\nThe launcher handles the full native setup:\n\n- Creates Python virtual environments: `.venv` (app) and `.venv-litellm` (LiteLLM proxy)\n- Installs Python dependencies from [`chat\u002Frequirements.txt`](chat\u002Frequirements.txt) and [`tool_runtime\u002Frequirements.txt`](tool_runtime\u002Frequirements.txt)\n- Runs `npm ci` and `npm run build` in `chat\u002Ffrontend` (unless `-SkipBuild` is passed)\n- Starts LiteLLM on port **4000**, tool runtime on **8090**, and the chat server on **8080**\n- Writes service logs to [`logs\u002F`](logs\u002F) (`chat.log`, `litellm.log`, `tool-runtime.log`)\n- Tracks process IDs in `.ada-si.pids`\n\n### `start.ps1` Flags\n\n| Flag | Effect |\n|------|--------|\n| `-Dev` | Run Vite dev server at `http:\u002F\u002F127.0.0.1:5173` (proxies `\u002Fapi` → `:8080`) |\n| `-SkipBuild` | Skip `npm run build` when static assets already exist |\n| `-NoBrowser` | Do not auto-open a browser tab |\n| `-InstallOnly` | Install dependencies and exit without starting services |\n\n**Examples:**\n\n```powershell\n.\\start.ps1 -Dev          # Frontend hot-reload during development\n.\\start.ps1 -InstallOnly  # Set up venvs and deps only\n.\\start.ps1 -NoBrowser    # Start services without opening a tab\n```\n\n### Stopping native services\n\n```powershell\n.\\stop.ps1\n```\n\nOr press **Ctrl+C** in the terminal where `start.ps1` is running.\n\n---\n\n### Docker install (VPS \u002F cross-platform)\n\nUse Docker when deploying to a VPS or when you do not want to install Python and Node on the host. The frontend is built automatically inside the Docker image — no manual `npm run build` required.\n\n**Linux \u002F macOS**\n\n1. **Clone and install**\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI.git\n   cd Ada-SI\n   chmod +x install-docker.sh start-docker.sh stop-docker.sh\n   .\u002Finstall-docker.sh\n   ```\n\n2. **Edit `.env`** — add your API keys (same variables as native install).\n\n3. **Start Ada-SI**\n\n   ```bash\n   .\u002Fstart-docker.sh\n   ```\n\n4. **Open the app** at `http:\u002F\u002Flocalhost:8080` (or `http:\u002F\u002F\u003Cyour-server-ip>:8080` on a VPS).\n\n**Windows (Docker Desktop)**\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI.git\ncd Ada-SI\n.\\install-docker.bat\n# edit .env\n.\\start-docker.bat\n```\n\n**Docker commands**\n\n| Action | Linux \u002F macOS | Windows |\n|--------|---------------|---------|\n| Install | `.\u002Finstall-docker.sh` | `.\\install-docker.bat` |\n| Start | `.\u002Fstart-docker.sh` | `.\\start-docker.bat` |\n| Stop | `.\u002Fstop-docker.sh` | `.\\stop-docker.bat` |\n| View logs | `docker compose logs -f` | `docker compose logs -f` |\n| Update \u002F rebuild | Re-run `start-docker` | Re-run `start-docker` |\n\n**What Docker runs**\n\n- Three containers: LiteLLM, tool runtime, and chat server\n- Only **port 8080** is exposed to the host; LiteLLM and tool runtime are internal\n- Data persists via volume mounts: `chat\u002Fstaging\u002F`, `chat\u002Fcustom_tools\u002F`\n- See [`docker-compose.yml`](docker-compose.yml) for service wiring\n\n---\n\n### VPS deployment\n\nWhen running Ada-SI on a remote server, use the **Docker install** path above.\n\n1. **Firewall** — open port 8080, or place a reverse proxy (Caddy, nginx) in front for HTTPS on port 443.\n\n   ```bash\n   sudo ufw allow 8080\u002Ftcp\n   ```\n\n2. **Security** — Ada-SI has **no built-in authentication**. Do not expose port 8080 to the public internet without a reverse proxy, VPN, or IP allowlist.\n\n3. **Auto-start on reboot** (optional systemd unit):\n\n   ```ini\n   # \u002Fetc\u002Fsystemd\u002Fsystem\u002Fada-si.service\n   [Unit]\n   Description=Ada-SI\n   After=docker.service\n   Requires=docker.service\n\n   [Service]\n   Type=oneshot\n   RemainAfterExit=yes\n   WorkingDirectory=\u002Fopt\u002FAda-SI\n   ExecStart=\u002Fusr\u002Fbin\u002Fdocker compose up -d\n   ExecStop=\u002Fusr\u002Fbin\u002Fdocker compose down\n\n   [Install]\n   WantedBy=multi-user.target\n   ```\n\n   Then: `sudo systemctl enable --now ada-si`\n\n4. **Back up** `chat\u002Fstaging\u002F`, `chat\u002Fcustom_tools\u002F`, and `.env` — these hold persona, secrets, and forged skills.\n\n---\n\n## Configuration\n\n### Environment Variables\n\nCopy [`.env.example`](.env.example) to `.env` and configure:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `LITELLM_MASTER_KEY` | Yes | Auth key for the LiteLLM proxy (any secure string) |\n| `LITE_MODEL` | Yes* | Scout chat model (`provider\u002Fmodel`, e.g. `openai\u002Fgpt-4o-mini`) |\n| `TOOL_CREATOR_MODEL` | Yes* | Forge\u002Fcodegen model |\n| `LITE_MODEL_REASONING_EFFORT` | No | Scout reasoning: `low`, `medium`, or `high` (empty to disable) |\n| `CHAT_MODEL` | No | Legacy fallback if `LITE_MODEL` is unset |\n| `SECOND_MODEL` | No | Legacy fallback if `TOOL_CREATOR_MODEL` is unset |\n| `OPENAI_API_KEY` | No** | OpenAI API key |\n| `ANTHROPIC_API_KEY` | No** | Anthropic API key |\n| `GEMINI_API_KEY` | No** | Google Gemini API key |\n| `GROQ_API_KEY` | No** | Groq API key |\n| `ELEVENLABS_API_KEY` | No | ElevenLabs TTS for read-aloud voice output |\n| `ADA_LOG_LEVEL` | No | Debug logging level (e.g. `DEBUG` — see `logs\u002Fchat.log`) |\n| `ADA_LOG_MAX_BODY` | No | Max logged response body size (default `32000`) |\n\n\\* At least one of `LITE_MODEL` \u002F `CHAT_MODEL` and `TOOL_CREATOR_MODEL` \u002F `SECOND_MODEL` should be set.\n\n\\** At least one provider key is required for models to appear in the picker.\n\n**Set automatically by `start.ps1`** (override in `.env` if needed):\n\n| Variable | Default |\n|----------|---------|\n| `LITELLM_URL` | `http:\u002F\u002F127.0.0.1:4000` |\n| `TOOL_RUNTIME_URL` | `http:\u002F\u002F127.0.0.1:8090` |\n| `TOOLS_DIR` | `chat\u002Fcustom_tools` |\n| `VENV_PATH` | `chat\u002F.tool_runtime_venv` |\n\n### Settings UI\n\nClick the **gear icon** in the header to open Settings. All sections are available without restarting the app (model changes take effect on the next chat).\n\n| Section | What you configure |\n|---------|-------------------|\n| **Agents** | Scout model, Forge model, reasoning effort, Gemini Google Search toggle |\n| **API keys** | Provider keys (saved to `chat\u002Fstaging\u002Fsecrets.json`) |\n| **Voice** | ElevenLabs TTS on\u002Foff and voice selection |\n| **Persona** | Markdown persona files, bootstrap ritual, heartbeat interval |\n| **Model prompts** | Scout routing and Forge phase prompt templates |\n| **Progress** | View XP stats; reset level, skills, and pip packages |\n\nAPI keys can be set in **three places** (in order of precedence at runtime): Settings UI → `chat\u002Fstaging\u002Fsecrets.json` → `.env`.\n\n### Runtime Data Locations\n\nThese directories are gitignored and created at runtime:\n\n| Path | Contents |\n|------|----------|\n| `chat\u002Fstaging\u002Fsecrets.json` | API keys managed via Settings |\n| `chat\u002Fstaging\u002Fpersona\u002F` | Live persona markdown files |\n| `chat\u002Fstaging\u002Fprompts_config.json` | Custom prompt overrides |\n| `chat\u002Fstaging\u002Fpersona_config.json` | Heartbeat on\u002Foff and interval |\n| `chat\u002Fcustom_tools\u002F` | Forged Python skills and their data |\n| `logs\u002F` | Service log files |\n\nPersona templates (committed defaults) live in [`chat\u002Fpersona_defaults\u002F`](chat\u002Fpersona_defaults\u002F).\n\n---\n\n## Using Ada-SI\n\nAda-SI is a **single-screen application** — there is no page routing. The main layout is defined in [`chat\u002Ffrontend\u002Fsrc\u002Fcomponents\u002Flayout\u002FAppShell.tsx`](chat\u002Ffrontend\u002Fsrc\u002Fcomponents\u002Flayout\u002FAppShell.tsx).\n\n### UI Layout\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  Header: Level \u002F XP \u002F Rank \u002F Model picker \u002F Settings \u002F New quest │\n├──────────────┬──────────────────────────────┬───────────────────┤\n│  Quest Log   │         Chat area            │  Skill Loadout    │\n│  (left)      │  Messages + Composer         │  (right sidebar)  │\n│              │                              │  Skills | Supplies│\n│  Live steps  │  Tool plans, forge viewers   │                   │\n│  Abort btn   │  Mic input, read-aloud       │  Installed skills │\n├──────────────┴──────────────────────────────┴───────────────────┤\n│  3D avatar visualizer (activity feedback)                        │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n| Area | Component | How to use |\n|------|-----------|------------|\n| **Quest Log** (left) | `ProcessPanel` | Shows live agent steps during chat and forging. Click **Abort** to cancel an in-flight run. |\n| **Chat** (center) | `Messages` + `Composer` | Type messages or use the microphone. Tool plan cards appear inline for approval. |\n| **Header stats** | `PlayerStatsBar` | Displays level, XP bar, rank title, and installed skill count. |\n| **Skill Loadout** (right) | `SidePanel` | **Skills** tab lists installed tools; **Supplies** tab lists pip packages in the tool-runtime venv. |\n| **3D avatar** | `AiVisualizerAvatar` | Animated visualizer that reacts to agent activity. |\n| **Settings** | `SettingsModal` | Configure agents, keys, voice, persona, prompts, and progress. |\n| **Skill apps** | `SkillAppShell` | Full-screen overlay when opening an interactive skill. |\n| **Forge batch** | `ForgeBatchModal` | Multi-tool forge workflow when Scout proposes a batch. |\n\n### Modals and Overlays\n\n- **Settings** — Six configuration sections (see [Configuration](#configuration))\n- **Skill apps** — Interactive UIs for forged skills (calendar, list, table, or custom iframe templates)\n- **Forge batch** — Parallel plan review and build for 2–10 tools\n- **Celebrations** — Level-up confetti, skill-unlock modals, and sound effects\n\n---\n\n## Core Workflows\n\n### A. First-Time Setup\n\n1. Run `.\\install-native.bat` (first time) or `.\\start.bat` \u002F `.\\start.ps1`\n2. Open **Settings → API keys** and add at least one LLM provider key (or set keys in `.env` before starting)\n3. Open **Settings → Agents** and select models for **Scout** and **Forge master**\n4. Optional: **Settings → Persona → Start bootstrap ritual** to run the \"Give Scout a soul\" identity setup guided by Scout\n\nThere is **no login or authentication**. Ada-SI is designed to run locally on your machine.\n\n### B. Chatting with Scout\n\n1. Type a message in the composer or click the **microphone** for voice input (browser Web Speech API)\n2. Scout streams its reply. Reasoning\u002Fthinking blocks appear for supported models\n3. Scout may call installed skills automatically, or propose forging a new one\n4. The **Quest Log** on the left shows step-by-step progress; use **Abort** to cancel\n5. Optional: enable **read-aloud** in Settings → Voice (requires ElevenLabs API key)\n6. Gemini models with Google Search enabled can surface web search sources in replies\n\n**New quest** (header button) clears the chat and starts a fresh conversation.\n\n### C. Forging a Single Skill\n\nWhen Scout needs a capability it does not have, it proposes a tool plan:\n\n1. **Ask** Scout for something it cannot do yet (e.g. \"Track my daily water intake\")\n2. A **tool plan card** appears in chat — review the proposed skill name, description, and approach\n3. Choose **Approve**, **Revise** (provide feedback), or **Reject**\n4. On approval, the **Forge build pipeline** runs. Watch progress in the Quest Log:\n\n   | Step | Label |\n   |------|-------|\n   | `generate_code` | Blueprint skill code |\n   | `validate_code` | Inspect module structure |\n   | `sandbox_test` | Trial in test venv |\n   | `validate_ui` | Validate app UI |\n   | `contract_test` | Test skill API contract |\n   | `preview_review` | Automated app review |\n   | `ui_preview` | Preview interactive app |\n   | `pip_review` | Review supply packages |\n   | `runtime_verify` | Verify skill runtime |\n   | `install_tool` | Unlock skill |\n\n5. **Human-in-the-loop gates** may pause the build:\n   - **Pip approval** — when the skill needs new Python packages (reviewed in Supplies)\n   - **UI preview approval** — when the skill has an interactive app (approve or request revisions)\n6. On success, the skill appears in **Skill Loadout** and you earn XP (+180 for skill unlock)\n\n### D. Batch Forging\n\nScout can propose **2–10 independent tools** at once via `propose_tool_batch`:\n\n1. Scout presents a batch of tool plans\n2. The **Forge Batch Modal** opens for parallel review\n3. Approve, revise, or reject individual plans (or approve all)\n4. Start the batch build — tools are forged in parallel where possible\n5. Scout resumes automatically when the batch completes\n\n### E. Using Installed Skills\n\n**Headless skills** — Scout calls them during chat without any action from you. Examples: calculators, API wrappers, file processors.\n\n**Interactive skills** — Skills with custom UIs open in the **Skill App** overlay:\n\n- Open from the **Skills** tab in the right sidebar, or ask Scout to open one\n- UI templates: `calendar`, `list`, `table`, or `custom` (iframe)\n- Skill actions run via `POST \u002Fapi\u002Fskills\u002F{name}\u002Faction`\n- Persistent data is stored at `chat\u002Fcustom_tools\u002Fskill_data\u002F{skill_name}.json`\n- Custom UI assets live under `chat\u002Fcustom_tools\u002Fui\u002F{skill_name}\u002F`\n\n**Removing skills** — Delete from the Skills tab, or use Settings → Progress → reset.\n\n### F. Persona and Memory\n\nScout's personality and long-term memory are stored as markdown files, inspired by the OpenClaw persona system.\n\n| File | Purpose |\n|------|---------|\n| `AGENTS.md` | Operating rules and forge routing reminders |\n| `SOUL.md` | Core personality and values |\n| `IDENTITY.md` | Name, role, and presentation |\n| `USER.md` | Information about you |\n| `MEMORY.md` | Durable facts Scout should remember |\n| `HEARTBEAT.md` | Rules for background memory maintenance |\n| `TOOLS.md` | Notes about installed skills |\n| `BOOTSTRAP.md` | Guided first-time identity ritual |\n\n- **Defaults** (committed): [`chat\u002Fpersona_defaults\u002F`](chat\u002Fpersona_defaults\u002F)\n- **Runtime copies** (gitignored): `chat\u002Fstaging\u002Fpersona\u002F`\n- Edit files in **Settings → Persona**, or let Scout update them via memory tools during chat\n- **Bootstrap ritual** — first-time guided setup via Settings → Persona → Start bootstrap ritual\n- **Heartbeat** — background service (~30 min interval, configurable) consolidates daily logs into MEMORY. Toggle in Persona settings.\n\n### G. Gamification\n\n| Mechanic | Detail |\n|----------|--------|\n| **XP sources** | +30 for chat completion, +180 for skill unlock |\n| **Levels** | 1–50 (max total XP capped at level 50) |\n| **Rank titles** | Initiate (1) → Operator (11) → Architect (21) → Synthesist (31) → Apex (41) |\n| **Storage** | Browser `localStorage` key `ada-player-progress` |\n| **Reset** | Settings → Progress → reset all progress, skills, and supplies |\n\nLevel-up triggers confetti and sound effects via the effects layer.\n\n---\n\n## Agents\n\nAda-SI uses two LLM-backed agents with separate model assignments:\n\n| Agent | Role | Model variable | Prompt config |\n|-------|------|----------------|---------------|\n| **Scout** (Ada) | Main chat, tool routing, skill execution, memory updates | `LITE_MODEL` | Scout routing prompts |\n| **Forge master** | Tool planning, code generation, validation, UI design | `TOOL_CREATOR_MODEL` | Forge phase prompts |\n\nDefault prompts live in [`chat\u002Fprompts_config.py`](chat\u002Fprompts_config.py). Customize them in **Settings → Model prompts** (saved to `chat\u002Fstaging\u002Fprompts_config.json`).\n\n**Forge guidance** — additional context injected during forging. Edit in Settings or via `GET\u002FPUT \u002Fapi\u002Fforger-guidance` ([`chat\u002Fforger_guidance.py`](chat\u002Fforger_guidance.py)).\n\n---\n\n## Project Structure\n\n```\nAda-SI\u002F\n├── install-native.bat        # Native Windows first-time install\n├── install-native.ps1\n├── install-docker.sh         # Docker first-time install (Unix)\n├── install-docker.bat        # Docker first-time install (Windows)\n├── install-docker.ps1\n├── start.bat                 # Native Windows launcher (calls start.ps1)\n├── start.ps1                 # Native setup + service orchestration\n├── start-docker.sh           # Start Docker stack (Unix)\n├── start-docker.bat          # Start Docker stack (Windows)\n├── start-docker.ps1\n├── stop.ps1                  # Stop native services\n├── stop-docker.sh            # Stop Docker stack (Unix)\n├── stop-docker.bat           # Stop Docker stack (Windows)\n├── stop-docker.ps1\n├── .env.example              # Environment variable template\n├── docker-compose.yml        # Docker deployment (3 services)\n├── LICENSE                   # MIT license\n│\n├── litellm\u002F\n│   └── config.yaml           # LiteLLM model routing config\n│\n├── tool_runtime\u002F             # Isolated Python skill execution service\n│   ├── server.py             # FastAPI: \u002Fhealth, \u002Ftools, \u002Frun, pip install\n│   ├── runner.py             # Tool install and execution logic\n│   ├── Dockerfile\n│   └── requirements.txt\n│\n├── chat\u002F                     # Main application (port 8080)\n│   ├── app.py                # FastAPI monolith: chat, forge, persona, TTS APIs\n│   ├── tools_engine.py       # Skill loading, execution, manifests\n│   ├── tool_creator.py       # Forge LLM code generation\n│   ├── build_pipeline.py     # Build phases and approval gates\n│   ├── forge_batch.py        # Multi-tool batch orchestration\n│   ├── scout_persona.py      # Persona file management\n│   ├── heartbeat_service.py  # Background memory maintenance\n│   ├── litellm_client.py     # LLM streaming client\n│   ├── runtime_client.py     # Tool runtime HTTP client\n│   ├── prompts_config.py     # Scout\u002FForge prompt defaults\n│   ├── secrets_config.py     # API key storage\n│   ├── elevenlabs_tts.py     # Text-to-speech integration\n│   ├── forger_guidance.py    # Forge runtime context\n│   ├── test_*.py             # Python unit tests\n│   │\n│   ├── persona_defaults\u002F     # Committed persona templates\n│   ├── staging\u002F              # Runtime config (gitignored)\n│   ├── custom_tools\u002F         # Forged skills at runtime (gitignored)\n│   ├── static\u002F               # Built frontend (served at \u002F and \u002Fstatic)\n│   └── frontend\u002F             # React + TypeScript + Vite source\n│       ├── package.json\n│       ├── vite.config.ts\n│       └── src\u002F\n│           ├── api\u002F          # REST + SSE clients\n│           ├── components\u002F   # chat, tools, settings, visualizer, effects\n│           ├── hooks\u002F        # useChatStream, useToolBuildStream, TTS, etc.\n│           └── state\u002F        # Zustand store + progression\n│\n└── logs\u002F                     # Runtime service logs (gitignored)\n```\n\n---\n\n## Developer Reference\n\nSource: [https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI](https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI)\n\n### Frontend Development\n\n```powershell\n# Option 1: Launcher with hot-reload\n.\\start.ps1 -Dev\n\n# Option 2: Manual Vite dev server (chat API must be running on :8080)\ncd chat\u002Ffrontend\nnpm run dev\n```\n\nVite dev server runs at `http:\u002F\u002F127.0.0.1:5173` and proxies `\u002Fapi` requests to the chat server.\n\n**Production build:**\n\n```bash\ncd chat\u002Ffrontend\nnpm ci\nnpm run build    # Output → chat\u002Fstatic\u002F\n```\n\nOther npm scripts: `npm run lint` (ESLint), `npm run preview` (preview production build).\n\n### Key Backend Modules\n\n| Module | Responsibility |\n|--------|----------------|\n| [`chat\u002Fapp.py`](chat\u002Fapp.py) | FastAPI routes, SSE chat loop, forge approval endpoints |\n| [`chat\u002Ftools_engine.py`](chat\u002Ftools_engine.py) | Skill discovery, execution, UI serving, data persistence |\n| [`chat\u002Fbuild_pipeline.py`](chat\u002Fbuild_pipeline.py) | Multi-phase forge build with approval gates |\n| [`chat\u002Ftool_creator.py`](chat\u002Ftool_creator.py) | LLM-driven code generation for new skills |\n| [`chat\u002Fforge_batch.py`](chat\u002Fforge_batch.py) | Parallel multi-tool forge orchestration |\n| [`chat\u002Fscout_persona.py`](chat\u002Fscout_persona.py) | Persona file read\u002Fwrite, bootstrap, reset |\n| [`chat\u002Fheartbeat_service.py`](chat\u002Fheartbeat_service.py) | Periodic memory consolidation |\n| [`chat\u002Flitellm_client.py`](chat\u002Flitellm_client.py) | Streaming LLM calls via LiteLLM proxy |\n| [`chat\u002Fruntime_client.py`](chat\u002Fruntime_client.py) | HTTP client for tool runtime service |\n\n### API Endpoints\n\nAll routes are defined in [`chat\u002Fapp.py`](chat\u002Fapp.py). Grouped by area:\n\n**Chat and runs**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `\u002Fapi\u002Fconfig` | GET | App config, tools list, runtime health |\n| `\u002Fapi\u002Fmodels` | GET | Available LLM models |\n| `\u002Fapi\u002Fchat` | POST | Main chat stream (SSE) |\n| `\u002Fapi\u002Fresume_scout` | POST | Resume Scout after skill install |\n| `\u002Fapi\u002Fcancel_run` | POST | Cancel in-flight run |\n\n**Forge (single tool)**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `\u002Fapi\u002Fapprove_tool` | POST | Approve plan → start build (SSE) |\n| `\u002Fapi\u002Frevise_tool` | POST | Revise rejected plan (SSE) |\n| `\u002Fapi\u002Freject_tool` | POST | Reject plan |\n| `\u002Fapi\u002Fapprove_pip` | POST | Approve pip install (SSE) |\n| `\u002Fapi\u002Freject_pip` | POST | Reject pip install |\n| `\u002Fapi\u002Fapprove_preview` | POST | Approve UI preview (SSE) |\n| `\u002Fapi\u002Frevise_preview` | POST | Request UI changes (SSE) |\n| `\u002Fapi\u002Freject_preview` | POST | Reject UI preview |\n\n**Forge (batch)**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `\u002Fapi\u002Fforge_batch\u002Fconfirm` | POST | Confirm batch → parallel planning (SSE) |\n| `\u002Fapi\u002Fforge_batch\u002Fcancel` | POST | Cancel batch |\n| `\u002Fapi\u002Fforge_batch\u002Fapprove_plan` | POST | Approve one plan |\n| `\u002Fapi\u002Fforge_batch\u002Fapprove_all_plans` | POST | Approve all plans |\n| `\u002Fapi\u002Fforge_batch\u002Freject_plan` | POST | Reject a plan |\n| `\u002Fapi\u002Fforge_batch\u002Frevise_plan` | POST | Revise a plan (SSE) |\n| `\u002Fapi\u002Fforge_batch\u002Fstart_build` | POST | Build approved tools (SSE) |\n| `\u002Fapi\u002Fforge_batch\u002Fresume_agent` | POST | Resume Scout after batch |\n\n**Skills and supplies**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `\u002Fapi\u002Ftools` | GET | List installed skills |\n| `\u002Fapi\u002Ftools\u002F{name}` | DELETE | Remove a skill |\n| `\u002Fapi\u002Fskills\u002F{name}\u002Fui` | GET | Skill UI entry HTML |\n| `\u002Fapi\u002Fskills\u002F{name}\u002Fui\u002F{path}` | GET | Skill UI static assets |\n| `\u002Fapi\u002Fskills\u002F{name}\u002Faction` | POST | Run skill action from UI |\n| `\u002Fapi\u002Fskills\u002F{name}\u002Fdata` | GET | Read skill persistent JSON data (writes go through `POST ...\u002Faction`) |\n| `\u002Fapi\u002Fpip\u002Fpackages` | GET | Installed pip packages |\n| `\u002Fapi\u002Fpip\u002Fpackages\u002F{name}` | DELETE | Uninstall package |\n\n**Persona, secrets, prompts, TTS**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `\u002Fapi\u002Fpersona` | GET\u002FPUT | Read\u002Fwrite persona files |\n| `\u002Fapi\u002Fpersona\u002Fstatus` | GET | Bootstrap status |\n| `\u002Fapi\u002Fpersona\u002Freset` | POST | Reset to defaults |\n| `\u002Fapi\u002Fpersona\u002Fbootstrap` | POST | Start bootstrap ritual |\n| `\u002Fapi\u002Fpersona\u002Fconfig` | PUT | Heartbeat settings |\n| `\u002Fapi\u002Fprompts` | GET\u002FPUT | Model prompt templates |\n| `\u002Fapi\u002Fprompts\u002Freset` | POST | Reset prompts to defaults |\n| `\u002Fapi\u002Fsecrets` | GET\u002FPUT | API key status and storage |\n| `\u002Fapi\u002Fsecrets\u002F{key}` | DELETE | Clear one key |\n| `\u002Fapi\u002Fforger-guidance` | GET\u002FPUT | Forge context text |\n| `\u002Fapi\u002Fforger-guidance\u002Freset` | POST | Reset forger guidance |\n| `\u002Fapi\u002Ftts` | POST | Text-to-speech |\n| `\u002Fapi\u002Ftts\u002Fstream` | POST | Streaming TTS |\n| `\u002Fapi\u002Ftts\u002Fvoices` | GET | List TTS voices |\n\n**Tool runtime** (internal, port 8090; **unauthenticated** on native installs) — see [`tool_runtime\u002Fserver.py`](tool_runtime\u002Fserver.py): `\u002Fhealth`, `\u002Ftools`, `\u002Ftools\u002F{name}\u002Frun`, `\u002Ftools\u002F{name}\u002Finstall`, `\u002Ftools\u002F{name}\u002Fverify`, `DELETE \u002Ftools\u002F{name}`, `\u002Fpip\u002Finstall`, `\u002Fpip\u002Fpackages`, `\u002Fmanifest`.\n\nFrontend API client: [`chat\u002Ffrontend\u002Fsrc\u002Fapi\u002Fclient.ts`](chat\u002Ffrontend\u002Fsrc\u002Fapi\u002Fclient.ts).\n\n### Tests\n\nPython tests in `chat\u002Ftest_*.py`:\n\n```bash\n# From repo root with .venv activated\npython -m pytest chat\u002F\n```\n\nOr run individual test files:\n\n```bash\npython chat\u002Ftest_litellm_client.py\npython chat\u002Ftest_tool_verify.py\npython chat\u002Ftest_elevenlabs_tts.py\n```\n\n### Logs\n\n| File | Service |\n|------|---------|\n| `logs\u002Fchat.log` | Chat server |\n| `logs\u002Flitellm.log` | LiteLLM proxy |\n| `logs\u002Ftool-runtime.log` | Tool runtime |\n\nSet `ADA_LOG_LEVEL=DEBUG` in `.env` for verbose stream logging.\n\n### Optional Environment Overrides\n\n| Variable | Purpose |\n|----------|---------|\n| `ADA_PERSONA_DIR` | Alternate persona directory ([`scout_persona.py`](chat\u002Fscout_persona.py)) |\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| **No models in the picker** | Add a provider API key in Settings → API keys or `.env`. Only providers with valid keys return models. |\n| **Services won't start (native)** | Verify Python 3.12 and Node.js 22+ are installed. Check `logs\u002F` for errors. Try `.\\install-native.bat` or `.\\start.ps1 -InstallOnly` then `.\\start.ps1`. |\n| **Docker build fails at `npm ci`** | Usually an out-of-sync `chat\u002Ffrontend\u002Fpackage-lock.json`. On a dev machine run `npm install` in `chat\u002Ffrontend`, commit the updated lockfile, pull on the VPS, and re-run `.\u002Fstart-docker.sh`. |\n| **Services won't start (Docker)** | Ensure Docker is running. Check `docker compose logs` for errors. Verify `.env` exists and API keys are set. Try `.\\stop-docker.ps1` then re-run `start-docker`. |\n| **Blank or broken UI** | Run `npm run build` in `chat\u002Ffrontend`, or start with `.\\start.ps1 -Dev`. Ensure `chat\u002Fstatic\u002Findex.html` exists. |\n| **LiteLLM connection errors** | Confirm LiteLLM is running on port 4000. Check `logs\u002Flitellm.log`. Verify `LITELLM_MASTER_KEY` matches in `.env` and LiteLLM config. |\n| **Forge fails at pip step** | Review the proposed packages in the Supplies tab. Approve or reject; some packages may conflict. |\n| **Forge fails at UI preview** | Request revisions with specific feedback, or reject and ask Scout to simplify the skill. |\n| **TTS not working** | Set `ELEVENLABS_API_KEY` in Settings or `.env`. Enable TTS in Settings → Voice. |\n| **Scout seems forgetful** | Check `MEMORY.md` in Settings → Persona. Run bootstrap if persona files are empty. Ensure heartbeat is enabled. |\n| **Reset everything** | Settings → Progress → reset. Or delete `chat\u002Fstaging\u002F` and `chat\u002Fcustom_tools\u002F` (back up first). Clear browser `localStorage` for XP reset. |\n| **Port already in use (native)** | Stop other instances with `.\\stop.ps1`. Check `.ada-si.pids` for stale processes. |\n| **Port already in use (Docker)** | Run `.\\stop-docker.ps1` or `docker compose down`. Ensure no native `start.ps1` instance is also bound to port 8080. |\n\n---\n\n## Tech Stack\n\n| Layer | Technologies |\n|-------|--------------|\n| **Backend** | Python 3.12, FastAPI, Uvicorn, httpx |\n| **LLM routing** | LiteLLM proxy |\n| **Tool execution** | Separate FastAPI service + isolated Python venv (not OS sandbox) |\n| **Frontend** | React 19, TypeScript, Vite 8 |\n| **UI \u002F graphics** | Framer Motion, Three.js, @react-three\u002Ffiber, Zustand |\n| **Markdown** | react-markdown, highlight.js, rehype-sanitize |\n| **Audio** | Howler.js, ElevenLabs TTS, Web Speech API |\n| **Containers** | Docker Compose |\n\n**LLM providers** (via LiteLLM): OpenAI, Anthropic, Google Gemini, Groq.\n\n---\n\n## License\n\nAda-SI is released under the [MIT License](LICENSE).\n\nCopyright (c) 2026 Ada-SI contributors. Source: [github.com\u002Fnazirlouis\u002FAda-SI](https:\u002F\u002Fgithub.com\u002Fnazirlouis\u002FAda-SI).\n\n### Third-Party \u002F Open-Source Dependencies\n\nAda-SI builds on many open-source libraries. Major dependencies and their licenses:\n\n**Backend (Python)**\n\n| Package | License |\n|---------|---------|\n| [FastAPI](https:\u002F\u002Fgithub.com\u002Ftiangolo\u002Ffastapi) | MIT |\n| [Uvicorn](https:\u002F\u002Fgithub.com\u002Fencode\u002Fuvicorn) | BSD-3-Clause |\n| [httpx](https:\u002F\u002Fgithub.com\u002Fencode\u002Fhttpx) | BSD-3-Clause |\n| [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) | MIT |\n\n**Frontend (JavaScript \u002F TypeScript)**\n\n| Package | License |\n|---------|---------|\n| [React](https:\u002F\u002Fgithub.com\u002Ffacebook\u002Freact) | MIT |\n| [Vite](https:\u002F\u002Fgithub.com\u002Fvitejs\u002Fvite) | MIT |\n| [Three.js](https:\u002F\u002Fgithub.com\u002Fmrdoob\u002Fthree.js) | MIT |\n| [Zustand](https:\u002F\u002Fgithub.com\u002Fpmndrs\u002Fzustand) | MIT |\n| [Framer Motion](https:\u002F\u002Fgithub.com\u002Fmotiondivision\u002Fmotion) | MIT |\n| [Howler.js](https:\u002F\u002Fgithub.com\u002Fgoldfire\u002Fhowler.js) | MIT |\n| [react-markdown](https:\u002F\u002Fgithub.com\u002Fremarkjs\u002Freact-markdown) | MIT |\n| [@react-three\u002Ffiber](https:\u002F\u002Fgithub.com\u002Fpmndrs\u002Freact-three-fiber) | MIT |\n| [highlight.js](https:\u002F\u002Fgithub.com\u002Fhighlightjs\u002Fhighlight.js) | BSD-3-Clause |\n\n**Infrastructure**\n\n| Component | License |\n|-----------|---------|\n| [LiteLLM Docker image](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) (BerriAI) | MIT |\n\nSee [`chat\u002Ffrontend\u002Fpackage.json`](chat\u002Ffrontend\u002Fpackage.json), [`chat\u002Frequirements.txt`](chat\u002Frequirements.txt), and [`tool_runtime\u002Frequirements.txt`](tool_runtime\u002Frequirements.txt) for complete dependency lists.\n","Ada-SI 是一个本地优先、具备自进化能力的AI助手平台，支持在用户设备上运行可动态生成与执行Python技能的智能代理。其核心包含Scout（交互式对话代理）和Forge Master（自主规划、编码、测试并安装新技能的元代理），所有计算与代码执行均在本地隔离虚拟环境中完成，无需云端依赖。项目强调可扩展性与运行时自适应能力，适用于个人研究、AI代理行为探索及本地化智能工具原型开发，但明确声明不适用于生产环境或多人共享系统。",2,"2026-07-10 02:30:06","CREATED_QUERY"]