agent_alpha/
├── agent_a.py              # Standalone agent runner (CLI)
├── pyproject.toml           # Python deps & metadata
├── backend/
│   ├── app.py               # FastAPI application factory
│   ├── main.py              # Uvicorn entry point
│   ├── core/
│   │   └── agent.py         # Agent lifecycle & inference
│   └── routes/
│       ├── chat.py          # POST /api/chat
│       └── health.py        # GET  /api/health
├── frontend/
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   └── src/
│       ├── main.tsx         # React entry
│       ├── App.tsx          # Chat UI
│       ├── api.ts           # API client
│       └── index.css        # Tailwind base
└── skills/                  # Agent skill definitions

Quick Start

1. Python environment

uv sync                     # Create .venv & install deps

2. Backend (FastAPI)

uv run python -m backend.main
# → http://localhost:8000
# → API docs at http://localhost:8000/docs

3. Frontend (React + Vite)

cd frontend
npm install
npm run dev
# → http://localhost:5173

The Vite dev server proxies /api/* requests to the FastAPI backend.

API Endpoints

Method	Path	Description
GET	`/api/health`	Health check
POST	`/api/chat`	Send a message to the agent

POST /api/chat

{ "message": "What are your skills?", "session_id": null }

{ "reply": "I can help you with...", "session_id": null }

Key Capabilities

Code execution via sandboxed CodeMode
Web search (DuckDuckGo / provider-adaptive)
MCP tool integration (Hacker News, etc.)
Context management (sliding window + LLM compaction)
Memory persistence (./MEMORY.md)
Sub-agents (e.g., researcher)
Task tracking with subtask support
Safety shields: cost caps, input guards, tool approval, secret redaction, stuck-loop detection

Skills

Skills are loaded from the ./skills/ directory. See each skill's SKILL.md for details.

analyzing-financial-statements/
applying-brand-guidelines/
creating-financial-models/