Ada-SI

Repository: github.com/nazirlouis/Ada-SI

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.

The 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.

⚠️ Disclaimer — Read Before Installing

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.

Do not download, clone, or install Ada-SI unless you understand what it does and accept the risks.

When you run Ada-SI, you grant an AI substantial control over your computer:

Scout can call installed skills and propose new ones that run arbitrary Python on your machine.
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).
Forged skills run in an isolated Python venv, not a hardened container. They can still read/write files, spawn subprocesses, and make network requests within your OS user permissions.
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.
API keys are stored in .env and chat/staging/secrets.json and may be readable by forged tools via environment variables.

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.

See also Security & Trust for a fuller threat model.

Security & Trust

Ada-SI is designed for one person on one trusted machine. It is not multi-tenant software, and it is still experimental. The default local launchers now favor localhost-only access and reduced secret exposure, but they do not make forged code safe. Treat every forged skill like an untrusted script that you chose to run.

Current local safety defaults

Area	Default / mitigation	Remaining risk
Network exposure	Native launch binds chat, LiteLLM, and tool runtime to `127.0.0.1`. Docker Compose publishes the chat UI as `127.0.0.1:8080:8080`; LiteLLM and tool runtime are not published to the host.	Any local process or browser profile on the machine can still reach the app. If you deliberately rebind to `0.0.0.0`, you are exposing a privileged unauthenticated app.
No authentication	Localhost-only binding is the primary protection for local runs.	There is still no login. Anyone who can reach port `8080` can use chat, forge, secrets, and persona APIs. On native installs, local processes can also reach tool runtime on `127.0.0.1:8090`.
Forged tool file access	Tool runtime validates tool names before run, verify, install, and delete operations so requests cannot use path separators or dotted names to target files outside `chat/custom_tools/`.	Tool code itself is still arbitrary Python once you approve and install it.
Pip installs	Tool runtime accepts only simple PyPI requirement strings with optional version specifiers; it rejects local paths, VCS/URL installs, pip flags, and environment markers before invoking `pip`.	Normal PyPI packages can still execute install-time code and may be malicious or compromised. Review package approvals carefully.
Secrets exposure	Docker and native launchers do not pass provider API keys into the tool-runtime process by default; keys are intended for chat/LiteLLM.	The chat server still needs keys to call providers, keys may be stored in `.env` and `chat/staging/secrets.json`, and unsafe forged tools may try to read files or environment available to their process.
Debug logging	Default log level is `INFO`; use `DEBUG` only when troubleshooting.	`ADA_LOG_LEVEL=DEBUG` may log chat content, tool arguments, and generated code to `logs/chat.log`.
VPS / remote use	The checked-in Docker Compose file is local-only.	Remote use requires intentionally changing port binding or adding a reverse proxy/VPN/IP allowlist. Do not expose Ada-SI directly to the public internet.

Risks that are not “fixed” by design

AI computer control: Scout can call installed skills and propose new ones that run arbitrary Python.
Forge writes code: the Forge pipeline can install packages and write executable files after approval gates. Those gates reduce accidents; they are not a security sandbox.
Weak isolation: forged skills run in a separate Python venv, not a hardened OS/container sandbox. They can still read/write files, spawn subprocesses, and make network requests with the permissions of the process running them.
Local API trust: because there is no built-in authentication, localhost access is treated as trusted. Do not run this on a shared, hostile, or kiosk machine.

If you are unsure whether those risks are acceptable, do not run this project.

Features

Gamified chat UI — XP, levels (1–50), rank titles, level-up effects, and a 3D avatar visualizer
Runtime skill forging — Scout can create, test, and install Python tools on the fly with your approval
Interactive skill apps — Forged skills can ship custom HTML/CSS/JS UIs (calendar, list, table, or custom layouts)
Multi-provider LLM routing — OpenAI, Anthropic, Gemini, and Groq via LiteLLM
Persona and memory — OpenClaw-style markdown files (SOUL, IDENTITY, MEMORY, and more) shape Scout's behavior
Voice input and TTS — Browser speech recognition for input; optional ElevenLabs read-aloud for responses
Batch forging — Create 2–10 independent tools in parallel
No database required — File-based persistence plus browser localStorage for progression

Architecture

Ada-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).

flowchart LR
  Browser["Browser UI :8080 or :5173"]
  Chat["Chat API + React static"]
  LiteLLM["LiteLLM proxy :4000"]
  ToolRT["Tool runtime :8090"]
  Providers["OpenAI / Anthropic / Gemini / Groq"]
  Files["staging/ + custom_tools/"]

  Browser --> Chat
  Chat --> LiteLLM
  Chat --> ToolRT
  LiteLLM --> Providers
  Chat --> Files
  ToolRT --> Files

Service	Port	Role	Key file
Chat server	8080	FastAPI backend, SSE chat, forge APIs, persona, TTS; serves built React UI	`chat/app.py`
LiteLLM proxy	4000	Routes model requests to LLM providers	`litellm/config.yaml`
Tool runtime	8090	Executes installed Python skills in an isolated venv (not OS-level sandboxing)	`tool_runtime/server.py`
Vite dev server (optional)	5173	Hot-reload frontend; proxies `/api` to chat server	`chat/frontend/vite.config.ts`

Frontend — React 19 + TypeScript + Vite, source in chat/frontend/, production build output in chat/static/.

Persistence — No traditional database. Runtime config lives in chat/staging/; forged skills in chat/custom_tools/; player XP in browser localStorage.

Prerequisites

Native install (Windows)

Requirement	Version	Used for
Python	3.12	Chat server, tool runtime, LiteLLM venv
Node.js	22+	Frontend build and dev mode
PowerShell	5.1+	Native launchers (`start.ps1`, `install-native.ps1`)

On Windows, the launcher looks for Python via py -3.12, python3.12, or python.

Docker install (VPS / cross-platform)

Requirement	Version	Used for
Docker Engine	—	Container runtime
Docker Compose	v2 plugin	Orchestrates three services via `docker-compose.yml`

No host Python or Node.js is required for Docker — the frontend is built inside the chat/Dockerfile image.

Installation and Setup

Choose your install path

Goal	Install path	Scripts
Local Windows development	Native	`install-native.bat` → `start.bat`
VPS, Linux, Mac, or Windows with Docker Desktop	Docker	`install-docker.sh` / `install-docker.bat` → `start-docker.sh` / `start-docker.bat`

Both paths use the same .env configuration and persist data under chat/staging/ and chat/custom_tools/.

Native install (Windows)

Clone the repository

git clone https://github.com/nazirlouis/Ada-SI.git
cd Ada-SI

Run the native installer (first time only)
```
.\install-native.bat
```
This creates .env from .env.example, prepares runtime directories, and installs Python/Node dependencies.
Edit .env — set at minimum:
```
LITELLM_MASTER_KEY=sk-ada-dev-key
LITE_MODEL=openai/gpt-4o-mini
TOOL_CREATOR_MODEL=openai/gpt-4o-mini
OPENAI_API_KEY=sk-...
```
Use any secure string for LITELLM_MASTER_KEY. Model IDs follow the provider/model format (e.g. anthropic/claude-sonnet-4-20250514, gemini/gemini-2.0-flash, groq/llama-3.3-70b-versatile). Add keys only for providers you plan to use.
Start Ada-SI
```
.\start.bat
```
Or run the PowerShell script directly:
```
.\start.ps1
```
Open the app — your browser should open automatically at:
```
http://127.0.0.1:8080
```

What `start.ps1` Does

The launcher handles the full native setup:

Creates Python virtual environments: .venv (app) and .venv-litellm (LiteLLM proxy)
Installs Python dependencies from chat/requirements.txt and tool_runtime/requirements.txt
Runs npm ci and npm run build in chat/frontend (unless -SkipBuild is passed)
Starts LiteLLM on port 4000, tool runtime on 8090, and the chat server on 8080
Writes service logs to logs/ (chat.log, litellm.log, tool-runtime.log)
Tracks process IDs in .ada-si.pids

`start.ps1` Flags

Flag	Effect
`-Dev`	Run Vite dev server at `http://127.0.0.1:5173` (proxies `/api` → `:8080`)
`-SkipBuild`	Skip `npm run build` when static assets already exist
`-NoBrowser`	Do not auto-open a browser tab
`-InstallOnly`	Install dependencies and exit without starting services

Examples:

.\start.ps1 -Dev          # Frontend hot-reload during development
.\start.ps1 -InstallOnly  # Set up venvs and deps only
.\start.ps1 -NoBrowser    # Start services without opening a tab

Stopping native services

.\stop.ps1

Or press Ctrl+C in the terminal where start.ps1 is running.

Docker install (VPS / cross-platform)

Use 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.

Linux / macOS

Clone and install

git clone https://github.com/nazirlouis/Ada-SI.git
cd Ada-SI
chmod +x install-docker.sh start-docker.sh stop-docker.sh
./install-docker.sh

Edit .env — add your API keys (same variables as native install).
Start Ada-SI
```
./start-docker.sh
```
Open the app at http://localhost:8080. The default Docker Compose file binds to 127.0.0.1 only; remote/VPS access requires an explicit reverse proxy, VPN, SSH tunnel, or a deliberate port-binding change.

Windows (Docker Desktop)

git clone https://github.com/nazirlouis/Ada-SI.git
cd Ada-SI
.\install-docker.bat
# edit .env
.\start-docker.bat

Docker commands

Action	Linux / macOS	Windows
Install	`./install-docker.sh`	`.\install-docker.bat`
Start	`./start-docker.sh`	`.\start-docker.bat`
Stop	`./stop-docker.sh`	`.\stop-docker.bat`
View logs	`docker compose logs -f`	`docker compose logs -f`
Update / rebuild	Re-run `start-docker`	Re-run `start-docker`

What Docker runs

Three containers: LiteLLM, tool runtime, and chat server
Only port 8080 is exposed to the host, and it is bound to 127.0.0.1 by default; LiteLLM and tool runtime are internal
Data persists via volume mounts: chat/staging/, chat/custom_tools/
See docker-compose.yml for service wiring

VPS deployment

Ada-SI is safest as a local-only app. The checked-in Docker Compose file binds the UI to 127.0.0.1, so a browser on another machine cannot reach it directly. If you run Ada-SI on a VPS, prefer one of these access patterns instead of opening the app to the internet:

SSH tunnel (recommended for personal use) — keep Compose local-only and tunnel from your laptop:
```
ssh -L 8080:127.0.0.1:8080 user@your-server
```
Then open http://127.0.0.1:8080 on your laptop.
VPN / private network — expose access only over a private interface you control.
Reverse proxy with authentication and IP allowlisting — if you must use HTTPS, put Caddy/nginx/Traefik in front and require authentication before traffic reaches Ada-SI.

Do not run sudo ufw allow 8080/tcp for public access unless you have intentionally changed the deployment model and understand that Ada-SI has no built-in authentication.

Auto-start on reboot (optional systemd unit):

# /etc/systemd/system/ada-si.service
[Unit]
Description=Ada-SI
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/Ada-SI
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

Then: sudo systemctl enable --now ada-si

Back up chat/staging/, chat/custom_tools/, and .env — these hold persona, secrets, and forged skills.

Configuration

Environment Variables

Copy .env.example to .env and configure:

Variable	Required	Description
`LITELLM_MASTER_KEY`	Yes	Auth key for the LiteLLM proxy (any secure string)
`LITE_MODEL`	Yes*	Scout chat model (`provider/model`, e.g. `openai/gpt-4o-mini`)
`TOOL_CREATOR_MODEL`	Yes*	Forge/codegen model
`LITE_MODEL_REASONING_EFFORT`	No	Scout reasoning: `low`, `medium`, or `high` (empty to disable)
`CHAT_MODEL`	No	Legacy fallback if `LITE_MODEL` is unset
`SECOND_MODEL`	No	Legacy fallback if `TOOL_CREATOR_MODEL` is unset
`OPENAI_API_KEY`	No**	OpenAI API key
`ANTHROPIC_API_KEY`	No**	Anthropic API key
`GEMINI_API_KEY`	No**	Google Gemini API key
`GROQ_API_KEY`	No**	Groq API key
`ELEVENLABS_API_KEY`	No	ElevenLabs TTS for read-aloud voice output
`ADA_LOG_LEVEL`	No	Debug logging level (e.g. `DEBUG` — see `logs/chat.log`)
`ADA_LOG_MAX_BODY`	No	Max logged response body size (default `32000`)

* At least one of LITE_MODEL / CHAT_MODEL and TOOL_CREATOR_MODEL / SECOND_MODEL should be set.

** At least one provider key is required for models to appear in the picker.

Set automatically by start.ps1 (override in .env if needed):

Variable	Default
`LITELLM_URL`	`http://127.0.0.1:4000`
`TOOL_RUNTIME_URL`	`http://127.0.0.1:8090`
`TOOLS_DIR`	`chat/custom_tools`
`VENV_PATH`	`chat/.tool_runtime_venv`

Settings UI

Click 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).

Section	What you configure
Agents	Scout model, Forge model, reasoning effort, Gemini Google Search toggle
API keys	Provider keys (saved to `chat/staging/secrets.json`)
Voice	ElevenLabs TTS on/off and voice selection
Persona	Markdown persona files, bootstrap ritual, heartbeat interval
Model prompts	Scout routing and Forge phase prompt templates
Progress	View XP stats; reset level, skills, and pip packages

API keys can be set in three places (in order of precedence at runtime): Settings UI → chat/staging/secrets.json → .env.

Runtime Data Locations

These directories are gitignored and created at runtime:

Path	Contents
`chat/staging/secrets.json`	API keys managed via Settings
`chat/staging/persona/`	Live persona markdown files
`chat/staging/prompts_config.json`	Custom prompt overrides
`chat/staging/persona_config.json`	Heartbeat on/off and interval
`chat/custom_tools/`	Forged Python skills and their data
`logs/`	Service log files

Persona templates (committed defaults) live in chat/persona_defaults/.

Using Ada-SI

Ada-SI is a single-screen application — there is no page routing. The main layout is defined in chat/frontend/src/components/layout/AppShell.tsx.

UI Layout

┌─────────────────────────────────────────────────────────────────┐
│  Header: Level / XP / Rank / Model picker / Settings / New quest │
├──────────────┬──────────────────────────────┬───────────────────┤
│  Quest Log   │         Chat area            │  Skill Loadout    │
│  (left)      │  Messages + Composer         │  (right sidebar)  │
│              │                              │  Skills | Supplies│
│  Live steps  │  Tool plans, forge viewers   │                   │
│  Abort btn   │  Mic input, read-aloud       │  Installed skills │
├──────────────┴──────────────────────────────┴───────────────────┤
│  3D avatar visualizer (activity feedback)                        │
└─────────────────────────────────────────────────────────────────┘

Area	Component	How to use
Quest Log (left)	`ProcessPanel`	Shows live agent steps during chat and forging. Click Abort to cancel an in-flight run.
Chat (center)	`Messages` + `Composer`	Type messages or use the microphone. Tool plan cards appear inline for approval.
Header stats	`PlayerStatsBar`	Displays level, XP bar, rank title, and installed skill count.
Skill Loadout (right)	`SidePanel`	Skills tab lists installed tools; Supplies tab lists pip packages in the tool-runtime venv.
3D avatar	`AiVisualizerAvatar`	Animated visualizer that reacts to agent activity.
Settings	`SettingsModal`	Configure agents, keys, voice, persona, prompts, and progress.
Skill apps	`SkillAppShell`	Full-screen overlay when opening an interactive skill.
Forge batch	`ForgeBatchModal`	Multi-tool forge workflow when Scout proposes a batch.

Modals and Overlays

Settings — Six configuration sections (see Configuration)
Skill apps — Interactive UIs for forged skills (calendar, list, table, or custom iframe templates)
Forge batch — Parallel plan review and build for 2–10 tools
Celebrations — Level-up confetti, skill-unlock modals, and sound effects

Core Workflows

A. First-Time Setup

Run .\install-native.bat (first time) or .\start.bat / .\start.ps1
Open Settings → API keys and add at least one LLM provider key (or set keys in .env before starting)
Open Settings → Agents and select models for Scout and Forge master
Optional: Settings → Persona → Start bootstrap ritual to run the "Give Scout a soul" identity setup guided by Scout

There is no login or authentication. Ada-SI is designed to run locally on your machine.

B. Chatting with Scout

Type a message in the composer or click the microphone for voice input (browser Web Speech API)
Scout streams its reply. Reasoning/thinking blocks appear for supported models
Scout may call installed skills automatically, or propose forging a new one
The Quest Log on the left shows step-by-step progress; use Abort to cancel
Optional: enable read-aloud in Settings → Voice (requires ElevenLabs API key)
Gemini models with Google Search enabled can surface web search sources in replies

New quest (header button) clears the chat and starts a fresh conversation.

C. Forging a Single Skill

When Scout needs a capability it does not have, it proposes a tool plan:

Ask Scout for something it cannot do yet (e.g. "Track my daily water intake")
A tool plan card appears in chat — review the proposed skill name, description, and approach
Choose Approve, Revise (provide feedback), or Reject

On approval, the Forge build pipeline runs. Watch progress in the Quest Log:

Step	Label
`generate_code`	Blueprint skill code
`validate_code`	Inspect module structure
`sandbox_test`	Trial in test venv
`validate_ui`	Validate app UI
`contract_test`	Test skill API contract
`preview_review`	Automated app review
`ui_preview`	Preview interactive app
`pip_review`	Review supply packages
`runtime_verify`	Verify skill runtime
`install_tool`	Unlock skill

Human-in-the-loop gates may pause the build:
- Pip approval — when the skill needs new Python packages (reviewed in Supplies)
- UI preview approval — when the skill has an interactive app (approve or request revisions)
On success, the skill appears in Skill Loadout and you earn XP (+180 for skill unlock)

D. Batch Forging

Scout can propose 2–10 independent tools at once via propose_tool_batch:

Scout presents a batch of tool plans
The Forge Batch Modal opens for parallel review
Approve, revise, or reject individual plans (or approve all)
Start the batch build — tools are forged in parallel where possible
Scout resumes automatically when the batch completes

E. Using Installed Skills

Headless skills — Scout calls them during chat without any action from you. Examples: calculators, API wrappers, file processors.

Interactive skills — Skills with custom UIs open in the Skill App overlay:

Open from the Skills tab in the right sidebar, or ask Scout to open one
UI templates: calendar, list, table, or custom (iframe)
Skill actions run via POST /api/skills/{name}/action
Persistent data is stored at chat/custom_tools/skill_data/{skill_name}.json
Custom UI assets live under chat/custom_tools/ui/{skill_name}/

Removing skills — Delete from the Skills tab, or use Settings → Progress → reset.

F. Persona and Memory

Scout's personality and long-term memory are stored as markdown files, inspired by the OpenClaw persona system.

File	Purpose
`AGENTS.md`	Operating rules and forge routing reminders
`SOUL.md`	Core personality and values
`IDENTITY.md`	Name, role, and presentation
`USER.md`	Information about you
`MEMORY.md`	Durable facts Scout should remember
`HEARTBEAT.md`	Rules for background memory maintenance
`TOOLS.md`	Notes about installed skills
`BOOTSTRAP.md`	Guided first-time identity ritual

Defaults (committed): chat/persona_defaults/
Runtime copies (gitignored): chat/staging/persona/
Edit files in Settings → Persona, or let Scout update them via memory tools during chat
Bootstrap ritual — first-time guided setup via Settings → Persona → Start bootstrap ritual
Heartbeat — background service (~30 min interval, configurable) consolidates daily logs into MEMORY. Toggle in Persona settings.

G. Gamification

Mechanic	Detail
XP sources	+30 for chat completion, +180 for skill unlock
Levels	1–50 (max total XP capped at level 50)
Rank titles	Initiate (1) → Operator (11) → Architect (21) → Synthesist (31) → Apex (41)
Storage	Browser `localStorage` key `ada-player-progress`
Reset	Settings → Progress → reset all progress, skills, and supplies

Level-up triggers confetti and sound effects via the effects layer.

Agents

Ada-SI uses two LLM-backed agents with separate model assignments:

Agent	Role	Model variable	Prompt config
Scout (Ada)	Main chat, tool routing, skill execution, memory updates	`LITE_MODEL`	Scout routing prompts
Forge master	Tool planning, code generation, validation, UI design	`TOOL_CREATOR_MODEL`	Forge phase prompts

Default prompts live in chat/prompts_config.py. Customize them in Settings → Model prompts (saved to chat/staging/prompts_config.json).

Forge guidance — additional context injected during forging. Edit in Settings or via GET/PUT /api/forger-guidance (chat/forger_guidance.py).

Project Structure

Ada-SI/
├── install-native.bat        # Native Windows first-time install
├── install-native.ps1
├── install-docker.sh         # Docker first-time install (Unix)
├── install-docker.bat        # Docker first-time install (Windows)
├── install-docker.ps1
├── start.bat                 # Native Windows launcher (calls start.ps1)
├── start.ps1                 # Native setup + service orchestration
├── start-docker.sh           # Start Docker stack (Unix)
├── start-docker.bat          # Start Docker stack (Windows)
├── start-docker.ps1
├── stop.ps1                  # Stop native services
├── stop-docker.sh            # Stop Docker stack (Unix)
├── stop-docker.bat           # Stop Docker stack (Windows)
├── stop-docker.ps1
├── .env.example              # Environment variable template
├── docker-compose.yml        # Docker deployment (3 services)
├── LICENSE                   # MIT license
│
├── litellm/
│   └── config.yaml           # LiteLLM model routing config
│
├── tool_runtime/             # Isolated Python skill execution service
│   ├── server.py             # FastAPI: /health, /tools, /run, pip install
│   ├── runner.py             # Tool install and execution logic
│   ├── Dockerfile
│   └── requirements.txt
│
├── chat/                     # Main application (port 8080)
│   ├── app.py                # FastAPI monolith: chat, forge, persona, TTS APIs
│   ├── tools_engine.py       # Skill loading, execution, manifests
│   ├── tool_creator.py       # Forge LLM code generation
│   ├── build_pipeline.py     # Build phases and approval gates
│   ├── forge_batch.py        # Multi-tool batch orchestration
│   ├── scout_persona.py      # Persona file management
│   ├── heartbeat_service.py  # Background memory maintenance
│   ├── litellm_client.py     # LLM streaming client
│   ├── runtime_client.py     # Tool runtime HTTP client
│   ├── prompts_config.py     # Scout/Forge prompt defaults
│   ├── secrets_config.py     # API key storage
│   ├── elevenlabs_tts.py     # Text-to-speech integration
│   ├── forger_guidance.py    # Forge runtime context
│   ├── test_*.py             # Python unit tests
│   │
│   ├── persona_defaults/     # Committed persona templates
│   ├── staging/              # Runtime config (gitignored)
│   ├── custom_tools/         # Forged skills at runtime (gitignored)
│   ├── static/               # Built frontend (served at / and /static)
│   └── frontend/             # React + TypeScript + Vite source
│       ├── package.json
│       ├── vite.config.ts
│       └── src/
│           ├── api/          # REST + SSE clients
│           ├── components/   # chat, tools, settings, visualizer, effects
│           ├── hooks/        # useChatStream, useToolBuildStream, TTS, etc.
│           └── state/        # Zustand store + progression
│
└── logs/                     # Runtime service logs (gitignored)

Developer Reference

Source: https://github.com/nazirlouis/Ada-SI

Frontend Development

# Option 1: Launcher with hot-reload
.\start.ps1 -Dev

# Option 2: Manual Vite dev server (chat API must be running on :8080)
cd chat/frontend
npm run dev

Vite dev server runs at http://127.0.0.1:5173 and proxies /api requests to the chat server.

Production build:

cd chat/frontend
npm ci
npm run build    # Output → chat/static/

Other npm scripts: npm run lint (ESLint), npm run preview (preview production build).

Key Backend Modules

Module	Responsibility
`chat/app.py`	FastAPI routes, SSE chat loop, forge approval endpoints
`chat/tools_engine.py`	Skill discovery, execution, UI serving, data persistence
`chat/build_pipeline.py`	Multi-phase forge build with approval gates
`chat/tool_creator.py`	LLM-driven code generation for new skills
`chat/forge_batch.py`	Parallel multi-tool forge orchestration
`chat/scout_persona.py`	Persona file read/write, bootstrap, reset
`chat/heartbeat_service.py`	Periodic memory consolidation
`chat/litellm_client.py`	Streaming LLM calls via LiteLLM proxy
`chat/runtime_client.py`	HTTP client for tool runtime service

API Endpoints

All routes are defined in chat/app.py. Grouped by area:

Chat and runs

Endpoint	Method	Purpose
`/api/config`	GET	App config, tools list, runtime health
`/api/models`	GET	Available LLM models
`/api/chat`	POST	Main chat stream (SSE)
`/api/resume_scout`	POST	Resume Scout after skill install
`/api/cancel_run`	POST	Cancel in-flight run

Forge (single tool)

Endpoint	Method	Purpose
`/api/approve_tool`	POST	Approve plan → start build (SSE)
`/api/revise_tool`	POST	Revise rejected plan (SSE)
`/api/reject_tool`	POST	Reject plan
`/api/approve_pip`	POST	Approve pip install (SSE)
`/api/reject_pip`	POST	Reject pip install
`/api/approve_preview`	POST	Approve UI preview (SSE)
`/api/revise_preview`	POST	Request UI changes (SSE)
`/api/reject_preview`	POST	Reject UI preview

Forge (batch)

Endpoint	Method	Purpose
`/api/forge_batch/confirm`	POST	Confirm batch → parallel planning (SSE)
`/api/forge_batch/cancel`	POST	Cancel batch
`/api/forge_batch/approve_plan`	POST	Approve one plan
`/api/forge_batch/approve_all_plans`	POST	Approve all plans
`/api/forge_batch/reject_plan`	POST	Reject a plan
`/api/forge_batch/revise_plan`	POST	Revise a plan (SSE)
`/api/forge_batch/start_build`	POST	Build approved tools (SSE)
`/api/forge_batch/resume_agent`	POST	Resume Scout after batch

Skills and supplies

Endpoint	Method	Purpose
`/api/tools`	GET	List installed skills
`/api/tools/{name}`	DELETE	Remove a skill
`/api/skills/{name}/ui`	GET	Skill UI entry HTML
`/api/skills/{name}/ui/{path}`	GET	Skill UI static assets
`/api/skills/{name}/action`	POST	Run skill action from UI
`/api/skills/{name}/data`	GET	Read skill persistent JSON data (writes go through `POST .../action`)
`/api/pip/packages`	GET	Installed pip packages
`/api/pip/packages/{name}`	DELETE	Uninstall package

Persona, secrets, prompts, TTS

Endpoint	Method	Purpose
`/api/persona`	GET/PUT	Read/write persona files
`/api/persona/status`	GET	Bootstrap status
`/api/persona/reset`	POST	Reset to defaults
`/api/persona/bootstrap`	POST	Start bootstrap ritual
`/api/persona/config`	PUT	Heartbeat settings
`/api/prompts`	GET/PUT	Model prompt templates
`/api/prompts/reset`	POST	Reset prompts to defaults
`/api/secrets`	GET/PUT	API key status and storage
`/api/secrets/{key}`	DELETE	Clear one key
`/api/forger-guidance`	GET/PUT	Forge context text
`/api/forger-guidance/reset`	POST	Reset forger guidance
`/api/tts`	POST	Text-to-speech
`/api/tts/stream`	POST	Streaming TTS
`/api/tts/voices`	GET	List TTS voices

Tool runtime (internal, port 8090; unauthenticated on native installs) — see tool_runtime/server.py: /health, /tools, /tools/{name}/run, /tools/{name}/install, /tools/{name}/verify, DELETE /tools/{name}, /pip/install, /pip/packages, /manifest.

Frontend API client: chat/frontend/src/api/client.ts.

Tests

Python tests in chat/test_*.py:

# From repo root with .venv activated
python -m pytest chat/

Or run individual test files:

python chat/test_litellm_client.py
python chat/test_tool_verify.py
python chat/test_elevenlabs_tts.py

Logs

File	Service
`logs/chat.log`	Chat server
`logs/litellm.log`	LiteLLM proxy
`logs/tool-runtime.log`	Tool runtime

Set ADA_LOG_LEVEL=DEBUG in .env for verbose stream logging.

Optional Environment Overrides

Variable	Purpose
`ADA_PERSONA_DIR`	Alternate persona directory (`scout_persona.py`)

Troubleshooting

Problem	Solution
No models in the picker	Add a provider API key in Settings → API keys or `.env`. Only providers with valid keys return models.
Services won't start (native)	Verify Python 3.12 and Node.js 22+ are installed. Check `logs/` for errors. Try `.\install-native.bat` or `.\start.ps1 -InstallOnly` then `.\start.ps1`.
Docker build fails at `npm ci`	Usually an out-of-sync `chat/frontend/package-lock.json`. On a dev machine run `npm install` in `chat/frontend`, commit the updated lockfile, pull on the VPS, and re-run `./start-docker.sh`.
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`.
Blank or broken UI	Run `npm run build` in `chat/frontend`, or start with `.\start.ps1 -Dev`. Ensure `chat/static/index.html` exists.
LiteLLM connection errors	Confirm LiteLLM is running on port 4000. Check `logs/litellm.log`. Verify `LITELLM_MASTER_KEY` matches in `.env` and LiteLLM config.
Forge fails at pip step	Review the proposed packages in the Supplies tab. Approve or reject; some packages may conflict.
Forge fails at UI preview	Request revisions with specific feedback, or reject and ask Scout to simplify the skill.
TTS not working	Set `ELEVENLABS_API_KEY` in Settings or `.env`. Enable TTS in Settings → Voice.
Scout seems forgetful	Check `MEMORY.md` in Settings → Persona. Run bootstrap if persona files are empty. Ensure heartbeat is enabled.
Reset everything	Settings → Progress → reset. Or delete `chat/staging/` and `chat/custom_tools/` (back up first). Clear browser `localStorage` for XP reset.
Port already in use (native)	Stop other instances with `.\stop.ps1`. Check `.ada-si.pids` for stale processes.
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.

Tech Stack

Layer	Technologies
Backend	Python 3.12, FastAPI, Uvicorn, httpx
LLM routing	LiteLLM proxy
Tool execution	Separate FastAPI service + isolated Python venv (not OS sandbox)
Frontend	React 19, TypeScript, Vite 8
UI / graphics	Framer Motion, Three.js, @react-three/fiber, Zustand
Markdown	react-markdown, highlight.js, rehype-sanitize
Audio	Howler.js, ElevenLabs TTS, Web Speech API
Containers	Docker Compose

LLM providers (via LiteLLM): OpenAI, Anthropic, Google Gemini, Groq.

License

Ada-SI is released under the MIT License.

Third-Party / Open-Source Dependencies

Ada-SI builds on many open-source libraries. Major dependencies and their licenses:

Backend (Python)

Package	License
FastAPI	MIT
Uvicorn	BSD-3-Clause
httpx	BSD-3-Clause
LiteLLM	MIT

Frontend (JavaScript / TypeScript)

Package	License
React	MIT
Vite	MIT
Three.js	MIT
Zustand	MIT
Framer Motion	MIT
Howler.js	MIT
react-markdown	MIT
@react-three/fiber	MIT
highlight.js	BSD-3-Clause

Infrastructure

Component	License
LiteLLM Docker image (BerriAI)	MIT

See chat/frontend/package.json, chat/requirements.txt, and tool_runtime/requirements.txt for complete dependency lists.

Name		Name	Last commit message	Last commit date
chat		chat
litellm		litellm
tool_runtime		tool_runtime
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
install-docker.bat		install-docker.bat
install-docker.ps1		install-docker.ps1
install-docker.sh		install-docker.sh
install-native.bat		install-native.bat
install-native.ps1		install-native.ps1
start-docker.bat		start-docker.bat
start-docker.ps1		start-docker.ps1
start-docker.sh		start-docker.sh
start.bat		start.bat
start.ps1		start.ps1
stop-docker.bat		stop-docker.bat
stop-docker.ps1		stop-docker.ps1
stop-docker.sh		stop-docker.sh
stop.ps1		stop.ps1
test_calc_snippet.py		test_calc_snippet.py

Latest commit

History

Folders and files

Repository files navigation