# SDK-001 — Package Scaffold & CLI Entry Point

**Status:** Complete
**Date:** 2026-03-03
**Branch:** `sdk-001/package-scaffold` (off `main`)
**Location:** `hyperscaled-sdk/`

---

## Summary

Set up the full Python package, build tooling, CI pipeline, and a working CLI with stub subcommands for all planned features. This is the foundation every subsequent SDK ticket builds on.

---

## What Was Built

### Directory Structure

```
hyperscaled-sdk/
├── hyperscaled/
│   ├── __init__.py              # Exports HyperscaledClient, __version__
│   ├── py.typed                 # PEP 561 marker
│   ├── exceptions.py            # Base HyperscaledError class
│   ├── models/
│   │   └── __init__.py          # Stub (wired in SDK-004)
│   ├── cli/
│   │   ├── __init__.py
│   │   ├── main.py              # Typer app with 10 subcommand groups
│   │   ├── data.py              # Stub — Phase 2
│   │   ├── backtest.py          # Stub — Phase 2
│   │   ├── account.py           # Stub — Sprint 05
│   │   ├── miners.py            # Stub — wired in SDK-005
│   │   ├── register.py          # Stub — Sprint 05
│   │   ├── trade.py             # Stub — Sprint 06
│   │   ├── positions.py         # Stub — Sprint 06
│   │   ├── info.py              # Stub — Sprint 06
│   │   ├── kyc.py               # Stub — Sprint 06
│   │   └── rules.py             # Stub — Sprint 06
│   └── sdk/
│       ├── __init__.py
│       ├── client.py            # Minimal HyperscaledClient (wired in SDK-003)
│       ├── data.py              # Stub — Phase 2
│       ├── backtest.py          # Stub — Phase 2
│       ├── account.py           # Stub — Sprint 05
│       ├── trading.py           # Stub — Sprint 06
│       ├── portfolio.py         # Stub — Sprint 06
│       ├── payouts.py           # Stub — Sprint 06
│       └── rules.py             # Stub — Sprint 06
├── tests/
│   ├── __init__.py
│   └── test_imports.py          # 4 tests
├── .github/workflows/ci.yml    # Lint, type-check, test (Python 3.10–3.13)
├── pyproject.toml
├── README.md
└── .gitignore
```

### pyproject.toml

- **Build backend:** hatchling
- **Entry point:** `hyperscaled = hyperscaled.cli.main:app`
- **Dependencies:** `typer[all]`, `httpx`, `pydantic>=2`, `tomli`/`tomli-w`, `rich`
- **Dev dependencies:** `ruff`, `mypy`, `pytest`, `pytest-asyncio`
- **Optional `[hl]` extra:** `hyperliquid-python-sdk`

### CLI

`hyperscaled --help` shows all 10 subcommand groups:

| Group | Description | Target |
|-------|-------------|--------|
| `data` | Market data providers and streaming | Phase 2 |
| `backtest` | Backtesting with QuantConnect Lean | Phase 2 |
| `account` | Hyperliquid account setup and funding | Sprint 05 |
| `miners` | Browse entity miners and pricing | Sprint 04 (SDK-005) |
| `register` | Purchase and connect a funded account | Sprint 05 |
| `trade` | Submit and manage trades | Sprint 06 |
| `positions` | Open and historical positions | Sprint 06 |
| `info` | Account info and payout history | Sprint 06 |
| `kyc` | Identity verification (Privado ID) | Sprint 06 |
| `rules` | Vanta Network rules and trade validation | Sprint 06 |

Each stub subcommand prints "Not yet implemented" with its target sprint.

### CI/CD

GitHub Actions workflow (`ci.yml`) runs on push/PR to `main`:
- **Lint:** `ruff check` + `ruff format --check`
- **Type-check:** `mypy hyperscaled`
- **Test:** `pytest -v` across Python 3.10, 3.11, 3.12, 3.13

---

## Acceptance Criteria — All Met

| Criterion | Status |
|-----------|--------|
| `pip install -e .` works from the repo root | Pass |
| `hyperscaled --help` shows all subcommand groups | Pass |
| `hyperscaled --version` prints `hyperscaled 0.1.0` | Pass |
| CI passes with lint, type-check, and test suite | Pass |
| All stub modules import cleanly | Pass (4/4 tests) |

### Verification Results

```
ruff check .          → All checks passed!
mypy hyperscaled      → Success: no issues found in 24 source files
pytest -v             → 4 passed in 0.02s
```

---

## What's Next

This unblocks two parallel tracks:

- **SDK-002** (Config system) — can start immediately
- **SDK-004** (Pydantic models & exception hierarchy) — can start immediately

Then **SDK-003** (HyperscaledClient core class) depends on SDK-002, and **SDK-005** (entity miner discovery) depends on both SDK-003 and SDK-004.

```
SDK-001 ──┬── SDK-002 ── SDK-003 ──┐
          │                        ├── SDK-005
          └── SDK-004 ─────────────┘
```
