Metadata-Version: 2.4
Name: keel-trade
Version: 0.2.1
Summary: Keel — CLI and MCP server for AI-driven crypto strategy development
Project-URL: Homepage, https://usekeel.io
Project-URL: Documentation, https://docs.usekeel.io
Author-email: Keel <team@usekeel.io>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: fastmcp>=3.1.1
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# Keel Agent SDK

Keel is a quantitative crypto trading platform. This SDK provides CLI and MCP tools for AI agents to create, validate, backtest, and deploy trading strategies.

## Quick Start

```bash
pipx install keel-trade    # or: pip install keel-trade
keel auth login                                     # Store API key
keel components search "momentum"                   # Search 160+ components (local)
keel strategy checkout str_abc123                   # Pull strategy for editing
keel strategy validate                              # Local 9-pass validation
keel strategy push -m "tuned parameters"            # Push changes to platform
keel backtest run str_abc123 --start-date 2024-01-01 --end-date 2025-01-01
```

## Strategy Workspace

Agents use a checkout/push/pull model to iterate on strategies:

```bash
# Start from existing strategy
keel strategy checkout str_abc123    # Pull to ~/.keel/workspace/

# Or create new (auto-checks out)
keel strategy create strategy.py     # Creates on platform + local checkout

# Edit locally — commands auto-detect the workspace
keel strategy validate               # No file arg needed
keel strategy explain                # Structure walkthrough
keel universe set --mode top_volume --top-n 30   # Edits file in place

# Push to platform (creates version, enables backtesting)
keel strategy push -m "added universe"

# Check sync state
keel strategy status                 # current / ahead / behind / conflict

# If someone edited in the web editor
keel strategy pull                   # Pull their changes
```

## Available Tools

### Local (no API key)

| Command | Description |
|---------|-------------|
| `keel components search <query>` | Search components by keyword |
| `keel components detail <name>` | Full component spec |
| `keel components after <name>` | Type-compatible successors |
| `keel components before <name>` | Type-compatible predecessors |
| `keel components list` | List all 160+ components |
| `keel components reference [topic]` | DSL reference docs |
| `keel strategy new <name>` | Create from template |
| `keel strategy validate [file]` | Validate strategy (auto-detects workspace) |
| `keel strategy explain [file]` | Explain structure |
| `keel strategy diff <a> <b>` | Structural diff |
| `keel strategy stage [file]` | Pipeline completeness check |
| `keel strategy examples` | Browse examples |
| `keel strategy patterns <query>` | Composition patterns |
| `keel strategy lock-status [file]` | Component version drift |
| `keel strategy lock-upgrade [file]` | Upgrade component versions |
| `keel universe get [file]` | Read universe config |
| `keel universe set [file] --mode ...` | Set universe (writes back to workspace) |
| `keel universe add-group [file] <name>` | Add asset group |
| `keel universe modify-group [file] <name>` | Modify asset group |
| `keel universe remove-group [file] <name>` | Remove asset group |

### Workspace (requires API key)

| Command | Description |
|---------|-------------|
| `keel strategy checkout <id>` | Pull strategy to local workspace |
| `keel strategy push [-m "msg"]` | Push local changes to platform |
| `keel strategy pull [--force]` | Pull remote changes |
| `keel strategy status` | Compare local vs remote |
| `keel strategy workspaces` | List checked-out strategies |
| `keel strategy discard` | Remove local workspace |

### Remote (requires API key)

| Command | Description |
|---------|-------------|
| `keel auth login` | Store API key |
| `keel auth whoami` | Current identity |
| `keel strategy create <file>` | Create on platform + auto-checkout |
| `keel strategy compile [file]` | Compile (needs live components) |
| `keel strategy list` | List platform strategies |
| `keel strategy show <id>` | Strategy details |
| `keel strategy update <id> <file>` | Update strategy |
| `keel backtest run <id> --start-date --end-date` | Start backtest |
| `keel backtest status <id>` | Check progress |
| `keel backtest results <id>` | Get results |
| `keel backtest list` | List backtests |
| `keel live deploy <id>` | Deploy strategy |
| `keel live list` | List deployments |
| `keel live positions <id>` | View positions |
| `keel live stop <id>` | Stop deployment |
| `keel sharing create-link <id>` | Share a strategy |
| `keel sharing fork <share_id>` | Fork shared strategy |
| `keel audit list` | View action history |

## Authentication

```bash
export KEEL_API_KEY=sk_org_xxx    # Env var (preferred for agents)
keel auth login                    # Interactive (stores in ~/.keel/config.yaml)
```

## Output Formats

All commands support `--format` (json | table | tsv | human). Default: `json` in agent mode, `human` in terminal.

Agent mode is auto-detected via `CLAUDE_CODE`, `CURSOR_AGENT`, `AIDER`, `GITHUB_COPILOT`, or `KEEL_AGENT_MODE` env vars.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General failure |
| 2 | Usage error |
| 3 | Not found |
| 4 | Auth failed |
| 5 | Conflict (push rejected — pull first) |
| 6 | Insufficient entitlements |
| 7 | Validation failed |

## MCP Server

```json
{"keel": {"command": "keel", "args": ["mcp", "serve"], "env": {"KEEL_API_KEY": "sk_org_xxx"}}}
```

The MCP server exposes each CLI command directly as a named tool (~70 total) — there is no meta-tool layer. Tools are grouped by domain (`strategy_components_*`, `strategy_*`, `universe_*`, `backtest_*`, `live_*`, `accounts_*`, `sharing_*`, `audit_*`, `market_data_*`) plus the SDK helpers `keel_status` and `strategy_find_local`. Live-trading mutation tools (`live_deploy`, `live_pause`, `live_resume`, `live_stop`) are gated by API-key `runner.*` scope and removed from `tools/list` when the key cannot create deployments. Resources: `keel://components/catalog` and `keel://dsl/reference/{topic}`.

## Strategy Workflow

1. **Discover**: `keel components search "momentum"` → find components
2. **Compose**: `keel strategy new my_strat` → create from template
3. **Validate**: `keel strategy validate` → check for errors
4. **Stage**: `keel strategy stage` → verify backtest-ready
5. **Create**: `keel strategy create my_strat.py` → upload to platform
6. **Backtest**: `keel backtest run str_xxx --start-date ... --end-date ...`
7. **Iterate**: edit → `keel strategy push` → backtest → repeat
8. **Deploy**: `keel live deploy str_xxx` → go live
