ockham 0.1.0

Ockham — single-user analyst terminal (backend + executor + frontend, one wheel)

Ockham Terminal

AI-powered financial data analysis platform. Ships as one wheel (ockham) and one container — same binary for the local single-user install and the Tier A in-VPC deployment.

Tier B Quickstart (60 seconds)

For design partners and small funds — runs entirely on your laptop, opens in a browser tab. JupyterLab-style.

uvx ockham --workspace ~/research

That's the install. uvx downloads the wheel, sets up an isolated runtime, and launches the server. The browser opens to a working analyst environment with the agent runtime, code executor, and all parsimony-* connectors pre-wired. Workspace files land under ~/research/.

Flags:

Flag	Default	Purpose
--workspace <dir>	~/ockham	All persistent data lives here. Anything under it is yours.
--port <n>	8000	Falls back to ephemeral if taken.
--host <h>	127.0.0.1	Loopback by default; set 0.0.0.0 for LAN access.
--no-browser	off	Don't open the browser automatically.

Configure via env vars (.env in CWD is auto-loaded):

Env var	What it is
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY	At least one LLM key.
OCKHAM_LLM_PROXY_URL	Optional. Route LLM traffic through a metered proxy.
FRED_API_KEY, FMP_API_KEY, EODHD_API_KEY	Per-connector creds; free tiers work.
OCKHAM_DATA_DIR	Override --workspace.
OCKHAM_CACHE_DIR	Regeneratable cache; default platformdirs.

Stop: Ctrl-C in the terminal where you launched it.

5-Minute Experience

from parsimony_agents import Agent
from parsimony import discover

agent = Agent(
    model="claude-sonnet-4-6",
    connectors=discover.load_all().bind_env(),
)

result = await agent.ask("Show me US GDP trends over the last 20 years")
print(result.text)        # Natural language analysis
print(result.datasets)    # {"us_gdp": <DataFrame>}

Project Structure

terminal/
├── server/                  # FastAPI backend (proprietary)
├── web/                     # React frontend (proprietary)
├── sandbox/                 # Code executor service (isolated Python)
├── infra/                   # Deployment configs (Fly.io, Docker, Cloudflare)
├── scripts/                 # Utility & admin scripts
├── docs/                    # Comprehensive documentation
├── pyproject.toml           # Python dependencies
├── Makefile                 # Development commands
└── README.md                # This file

Architecture

Internal Components
├── server/                    # FastAPI backend, OckhamAgent, auth, sessions, storage
│   └── Connectors for: FRED, SDMX, FMP, SEC Edgar, Polymarket, EODHD, IBKR
├── web/                       # React + TypeScript frontend
├── sandbox/                   # Code execution sandbox
└── Supporting infrastructure  # Curated catalog, embeddings, system prompts

Quick Start

Prerequisites

• Python: 3.11 or 3.12
• Node.js: 20+ (for frontend)
• uv: Latest (Python package manager) — Install

Setup (5 minutes)

# 1. Clone and install
git clone https://github.com/ockham-sh/terminal.git
cd terminal
uv sync

# 2. Create environment file
cp .env.example .env
# Add ANTHROPIC_API_KEY (required) and FRED_API_KEY (optional, free)

# 3. Run services (in separate terminals)
make backend    # Backend API (port 8000)
make executor   # Code executor (port 8001, required)
make frontend   # Frontend dev server (optional, auto-redirects from 8080)

# 4. Open http://localhost:8000

All services running? You're done! Start asking questions.

Documentation

Comprehensive guides for different roles:

For Users

• Getting Started — Installation and configuration
• Architecture — System design and the file-based-IDE invariants (REST endpoints live next to their implementation under server/api/*/router.py)

For Developers

• Architecture — Codebase structure and component maps
• Development Guide — Development workflow and code standards
• Architecture Decisions — Design rationale

Common Commands

Development

make setup          # Complete environment setup (one-time)
make backend        # Run FastAPI server (port 8000)
make executor       # Run code executor (port 8001, required)
make frontend       # Run React dev server (port 8080)

Testing & Quality

make test           # Run all tests
make test-data      # Test OSS packages only
make test-agents    # Test OSS packages only
make lint           # Lint Python code (ruff)
make format         # Auto-format code (ruff)
make typecheck      # Type checking (mypy)
make check          # Run all: lint + typecheck + test

Deployment

make deploy-fly     # Deploy to Fly.io
make deploy-local   # Deploy to local Docker

See Makefile for all available commands.

Environment Configuration

Minimum required:

• One LLM API key: ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY

Optional (for richer data):

• FRED_API_KEY — US Federal Reserve economic data (free, instant)
• FMP_API_KEY — Financial Modeling Prep (stocks, crypto)
• EODHD_API_KEY — Historical pricing data

Hosted (Fly):

• SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_JWT_SECRET — Auth (JWT verification only; no database)
• OCKHAM_DATA_DIR=/data/ockham — durable user content (workspaces) on the data Fly volume
• OCKHAM_CACHE_DIR=/cache/ockham — regeneratable state (sessions, artifacts) on the cache Fly volume
• PARSIMONY_CACHE_DIR=/cache/parsimony — HF catalog snapshots and embedder models

The hosted deployment is currently single-machine. Workspace files are file-backed on the data volume; there is no S3, no remote object store, and no Postgres/Redis dependency.

Running Tests

# All tests
uv run pytest

# Specific suite
uv run pytest server/tests/ -v
uv run pytest parsimony/tests/ -v
uv run pytest parsimony-agents/tests/ -v

# Coverage report
uv run pytest --cov=server --cov-report=term-missing

Minimum coverage: 80%

Deployment

Fly.io (Full-Stack)

# Setup Fly CLI
curl -L https://fly.io/install.sh | sh
fly auth login

# Deploy
fly launch
fly secrets set ANTHROPIC_API_KEY=sk-ant-...
fly deploy

Docker (Local)

docker build -t ockham-terminal:latest .
docker run -p 8000:8000 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e AUTH_ENABLED=false \
  ockham-terminal:latest

See infra/ for detailed deployment guides.

Architecture Overview

System Flow

User Request
    ↓
React Frontend (web/)
    ↓ HTTP/WebSocket
    ↓
FastAPI Backend (server/api/main.py)
    ├─ Authentication (Supabase Auth JWT when `AUTH_ENABLED`)
    ├─ In-memory cache + file-backed workspace state
    └─ OckhamAgent
        ├─ LLM (Claude, GPT, Gemini via litellm)
        ├─ Connectors (each parsimony plugin contributes its own tools and per-namespace search)
        │   ├─ parsimony-fred, parsimony-sdmx, parsimony-fmp, parsimony-eodhd, …
        │   └─ parsimony-sec-edgar, parsimony-treasury, parsimony-eia, …
        └─ Code Executor (sandbox/executor.py)
            ├─ Python notebooks
            ├─ DataFrame operations
            └─ Vega visualizations
    ↓
Storage Layer (file-backed; no DB, no S3, no Redis)
    ├─ OCKHAM_DATA_DIR  → workspaces (durable user content)
    ├─ OCKHAM_CACHE_DIR → sessions, artifacts (regeneratable)
    └─ PARSIMONY_CACHE_DIR → HF catalog snapshots, embedder models

Key Components

Component	Language	Purpose
server/api/	Python	REST API, session management
server/execution.py	Python	Code executor integration
server/product.py	Python	LLM models, system prompts
sandbox/executor.py	Python	Isolated code execution
web/src/	TypeScript/React	Frontend UI
infra/	Docker/YAML	Deployment configs

Model Configuration

Terminal ships with multiple LLM tiers:

Available Models

• Mini: Gemini 3.0 Flash (fast, free-tier friendly)
• Pro: Claude Sonnet 4.6 (high-quality, reasoning)

See server/product.py for model definitions and tiers.

System Prompt

Domain-specific prompt for financial analysis: server/prompts/financial_analysis.xml

Development Philosophy

From AGENTS.md:

Minimize entropy. Prefer consolidation and strong contracts. Reject hacky, defensive workarounds that mask design problems.

Key principles:

• No generic dict parameters — Use typed contracts (Pydantic, dataclass)
• Fail fast — Raise validation/type errors, don't coerce
• Validation at boundaries — Validate at API/RPC only
• Immutable patterns — New objects, never mutation
• Earned abstractions — Justify new modules/classes
• Single responsibility — High cohesion, low coupling

Development Standards

All contributions must follow these standards:

• Python 3.11+ with type annotations
• 80%+ test coverage minimum
• PEP 8 formatting (black/ruff)
• mypy type checking pass

For detailed development guidelines, see Development Guide.

Documentation

Complete reference guides and architecture documentation in docs/ directory.

Getting Started Next

1. Try it out: make backend && make executor && make frontend
2. Explore the code: Read CODEMAPS.md
3. Learn the architecture: ARCHITECTURE.md
4. Make changes: DEVELOPMENT.md
5. Deploy: infra/ guides

---

Happy coding! Questions? Check the docs or open an issue.