Metadata-Version: 2.4
Name: ockham
Version: 0.1.0
Summary: Ockham — single-user analyst terminal (backend + executor + frontend, one wheel)
License-Expression: LicenseRef-Proprietary
Requires-Python: <3.13,>=3.11
Requires-Dist: altair<7,>=6.0.0
Requires-Dist: chromadb<2,>=1.4.0
Requires-Dist: dateparser<2,>=1.3.0
Requires-Dist: duckdb<2,>=1.4.3
Requires-Dist: edgartools>=5.20.2
Requires-Dist: fastapi[standard]>=0.116.1
Requires-Dist: financial-reports-generated-client>=1.4.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: json-schema-to-pydantic<1,>=0.4.3
Requires-Dist: litellm<2,>=1.83.3
Requires-Dist: numpy<3,>=1.24.0
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: opentelemetry-api>=1.28.2
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.28.2
Requires-Dist: opentelemetry-sdk>=1.28.2
Requires-Dist: pandas<3,>=2.3.3
Requires-Dist: parsimony-coingecko<0.6,>=0.5
Requires-Dist: parsimony-core[litellm,standard]<0.6,>=0.5
Requires-Dist: parsimony-eia<0.6,>=0.5
Requires-Dist: parsimony-eodhd<0.6,>=0.5
Requires-Dist: parsimony-financial-reports<0.6,>=0.5
Requires-Dist: parsimony-finnhub<0.6,>=0.5
Requires-Dist: parsimony-fmp<0.6,>=0.5
Requires-Dist: parsimony-fred<0.6,>=0.5
Requires-Dist: parsimony-sdmx<0.6,>=0.5
Requires-Dist: parsimony-sec-edgar<0.6,>=0.5
Requires-Dist: parsimony-tiingo<0.6,>=0.5
Requires-Dist: parsimony-treasury<0.6,>=0.5
Requires-Dist: platformdirs<5,>=4.0
Requires-Dist: pydantic-settings<3,>=2.6.1
Requires-Dist: pydantic<3,>=2.11.1
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pypdf<6,>=5.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-pptx<2,>=1.0.0
Requires-Dist: rich>=14.0.0
Requires-Dist: scipy<2,>=1.15.2
Requires-Dist: statsmodels<1,>=0.14.5
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tantivy>=0.25.0
Requires-Dist: uvicorn[standard]>=0.35.0
Requires-Dist: vega-datasets>=0.9.0
Requires-Dist: vl-convert-python<2,>=1.7
Requires-Dist: watchfiles>=0.24.0
Description-Content-Type: text/markdown

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

```bash
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

```python
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](https://docs.astral.sh/uv/getting-started/installation/)

### Setup (5 minutes)

```bash
# 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](./docs/SETUP.md)** — Installation and configuration
- **[Architecture](./docs/ARCHITECTURE.md)** — System design and the file-based-IDE invariants (REST endpoints live next to their implementation under `server/api/*/router.py`)

### For Developers
- **[Architecture](./docs/CODEMAPS.md)** — Codebase structure and component maps
- **[Development Guide](./docs/DEVELOPMENT.md)** — Development workflow and code standards
- **[Architecture Decisions](./docs/ARCHITECTURE.md)** — Design rationale

## Common Commands

### Development

```bash
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

```bash
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

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

See [Makefile](./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

```bash
# 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)

```bash
# 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)

```bash
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/](./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](./server/product.py) for model definitions and tiers.

### System Prompt

Domain-specific prompt for financial analysis: [server/prompts/financial_analysis.xml](./server/prompts/financial_analysis.xml)

## Development Philosophy

From [AGENTS.md](./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](./docs/DEVELOPMENT.md).

## Documentation

Complete reference guides and architecture documentation in [docs/](./docs/) directory.

## Getting Started Next

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

---

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