agent_alpha/
├── .env.example             # Environment variable template
├── .gitignore
├── Makefile                 # Common dev commands
├── pyproject.toml           # Python deps & metadata
├── backend/
│   ├── app.py               # FastAPI application factory
│   ├── main.py              # Uvicorn entry point
│   ├── core/
│   │   ├── agent.py         # Agent lifecycle & inference
│   │   └── config.py        # pydantic-settings config
│   └── 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. Configuration

cp .env.example .env   # then edit .env with your LLM endpoint & model

2. Backend (FastAPI)

make install            # uv sync — create .venv & install deps
make run                # → http://localhost:8000
                        # → API docs at http://localhost:8000/docs

3. Frontend (React + Vite)

make frontend-install   # bun install
make frontend-dev       # → http://localhost:5173

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

Makefile Commands

Command	Description
`make install`	Install Python deps via `uv sync`
`make run` / `make dev`	Start the FastAPI backend (reload)
`make frontend-install`	Install frontend deps via `bun`
`make frontend-dev`	Start the Vite dev server
`make frontend-build`	Build frontend for production
`make clean`	Remove caches and build artifacts

Configuration

Environment variables are loaded from .env via pydantic-settings (see backend/core/config.py).

Variable	Default	Description
`LLM_BASE_URL`	`http://localhost:11434/v1`	OpenAI-compatible API
`LLM_MODEL`	`llama`	Model name to use

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
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/