Metadata-Version: 2.5
Name: longtrader-sdk
Version: 0.1.0
Summary: Thin Python wrapper over the longtrader Connect contract
Project-URL: Homepage, https://github.com/longcipher/longtrader
Project-URL: Repository, https://github.com/longcipher/longtrader
Project-URL: Documentation, https://github.com/longcipher/longtrader#readme
Project-URL: Issues, https://github.com/longcipher/longtrader/issues
Author: LongCipher
License: Apache-2.0
Keywords: connectrpc,finance,grpc,protobuf,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: protobuf>=5
Description-Content-Type: text/markdown

# longtrader-sdk (Python)

Tier-2 thin wrapper over the generated longtrader Connect stubs. Hand-written
code stays minimal — session handling plus overflow policies — while all
trading semantics live in the contract (`proto/`, buf-managed).

## Installation

```bash
pip install longtrader-sdk
```

The published wheel bundles the generated protobuf stubs, so no code-generation
step is required for end users. Generate stubs locally only when building from
source (repo `just sdk-generate`).

**Requirements:** Python >= 3.10.

## Canonical layout (design doc §6.8)

| Canonical dir | This SDK |
|---|---|
| `contract/` | `longtrader_sdk/proto/` — generated by `just sdk-generate`, never hand-edited |
| `session/` | `longtrader_sdk/session.py` — attach / keep-alive / reconcile / kill-switch |
| `ports/` | `longtrader_sdk/ports.py` — `TradingPort`, `MarketPort`, `OverflowPolicy` |
| `adapters/` | thin by design: Connect-over-httpx inside `session.py`; mock adapter planned |
| `strategies/` | `examples/grid_strategy.py` — the same grid ships in every language |
| `examples/` | `examples/` |

Concept names match the TypeScript/Rust wrappers 1:1 (`Session`,
`TradingPort`, `MarketPort`, `sync_state()`, `OverflowPolicy`).

## Proto namespaces

| Service | Proto package | Stubs | Notes |
|---|---|---|---|
| market | `longtrader.market.v1` | `longtrader_sdk/proto/longtrader/market/v1/` | candles, ticker, order book |
| trading | `longtrader.trading.v1` | `longtrader_sdk/proto/longtrader/trading/v1/` | orders, positions, account |
| worker | `longtrader.worker.v1` | `longtrader_sdk/proto/longtrader/worker/v1/` | session lifecycle |
| data | `longtrader.data.v1` | `longtrader_sdk/proto/longtrader/data/v1/` | dataset download/list/validate/delete, streaming `DownloadProgress` with `dataset_id` |
| backtest | `longtrader.backtest.v1` | `longtrader_sdk/proto/longtrader/backtest/v1/` | `Start`/`Cancel`/`ListRuns`/`GetReport`/`StartReplaySession`, `FinalReport.equity_curve_json` + `report_path` persisted |

Generated stubs are produced by `just sdk-generate` into `longtrader_sdk/proto/` (never hand-edit).

## Quickstart

```bash
just sdk-generate          # generates stubs into longtrader_sdk/proto/
pip install -e sdks/python
python sdks/python/examples/grid_strategy.py --help
```

Minimal use:

```python
from longtrader_sdk import Session

s = Session.attach("http://127.0.0.1:8080", token="YOUR_TERMINAL_TOKEN")
s.start_heartbeat()
snapshot = s.reconcile_state()   # gate to ACTIVE; pre-ACTIVE orders are rejected
print(s.session_id, s.state, snapshot.snapshot_sequence)
s.close()
```

## Wire notes

- Unary calls: `POST {base}/longtrader.worker.v1.WorkerSessionService/{Method}`,
  `Content-Type: application/proto`; errors arrive as non-200 JSON bodies
  surfaced as `ConnectError` (`.code`, `.details`).
- Server-streaming uses `application/connect+proto` with 5-byte envelopes
  (1 flag byte + u32 big-endian length; flag `0x02` = end-of-stream JSON).
  See `docs/bare-protocol-guide.md` sections 4–5.
- Auth is the existing terminal API token passed to `AttachSession`.
- `OverflowPolicy` governs event-queue behavior under slow consumers
  (`DROP_OLDEST` preserves newest, `COALESCE` last-writer-wins, `BLOCK`
  applies backpressure); sequence gaps require snapshot resync/reconcile.

## License

Apache-2.0 — see the repository `LICENSE`.
