Metadata-Version: 2.4
Name: tradepose-client
Version: 3.5.1
Summary: Python client SDK for TradePose trading platform
Project-URL: Homepage, https://tradepose.com
Author-email: TradePose Team <admin@tradepose.com>
License: MIT
Keywords: client,quantitative,sdk,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: filelock>=3.16.0
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: polars==1.33.1
Requires-Dist: pyarrow
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.12.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.0.0
Requires-Dist: tradepose-models<3.0.0,>=2.10.0
Requires-Dist: typer>=0.16.0
Provides-Extra: optional
Requires-Dist: orjson>=3.10.0; extra == 'optional'
Requires-Dist: tenacity>=9.0.0; extra == 'optional'
Description-Content-Type: text/markdown

# TradePose Client

TradePose Client is the public Python SDK and command-line workspace for reproducible
quantitative trading research. It keeps strategy source, experiment definitions, and
research evidence connected from the first local check through portfolio selection.

The primary workflow is:

```text
Strategy Family -> Experiment -> Preview -> Run -> Evidence -> PortfolioVersion -> Risk
```

TradePose Client is Alpha software. Expect the authoring and research interfaces to
evolve between releases. Client 3.5.0 is an approved minor breaking release with direct
removals and no compatibility facade; preserve active workspace evidence and follow the
packaged `docs/MIGRATION_3_5.md` guide before upgrading.

## Requirements and installation

- Python 3.13 or newer
- macOS or Linux
- A TradePose account and API key only when you choose remote execution

For a new project, install with [uv](https://docs.astral.sh/uv/):

```bash
uv init --python 3.13
uv add tradepose-client
```

If you already have an activated Python 3.13+ environment, `pip install
tradepose-client` is also supported.

Client 3.5.0 selects `tradepose-models>=2.10.0,<3.0.0`. Do not install or pin Models
separately. `tradepose-analyzer` is not a Client runtime dependency or installable Client
extra.

## Five-minute local workflow

Start in the clean project directory created above:

```bash
uv run tradepose init .
uv run tradepose doctor

uv run tradepose strategy new rsi_reversion --template rsi-reversion
uv run tradepose strategy show rsi_reversion
uv run tradepose strategy check rsi_reversion

uv run tradepose experiment new rsi_2024 \
  --source working:rsi_reversion \
  --year 2024

uv run tradepose experiment check rsi_2024
uv run tradepose experiment preview rsi_2024 --verbose
```

Everything through Preview is local-only. These commands do not construct a Gateway
client, create a Run, or consume remote execution usage. Preview resolves the exact
source revision, parameter selection, execution configuration, request identity, and
remote-work count before anything is submitted.

The generated Working Source is
`playbook/strategies/rsi_reversion.py`. Edit its typed parameters and recipe, then rerun
the Strategy and Experiment checks to catch authoring errors locally.

## Remote execution is explicit

Set an API key only when the preview is ready to run:

```bash
export TRADEPOSE_API_KEY="..."
uv run tradepose experiment run rsi_2024
```

`experiment run` is the explicit remote-execution boundary. Before submission it shows
the exact remote-work count and asks for confirmation. Remote execution is subject to
the usage limits applicable to your account.

For intentional automation, `--yes` skips the confirmation prompt. Use it only when the
automation has already reviewed the preview and remote-work count.

Each accepted execution creates one durable Run. An unprotected terminal Run becomes
eligible for local cleanup after seven days by default. Preserve important evidence as
an explicit research decision:

```bash
uv run tradepose run keep <run-id> --reason "selected for forward evaluation"
```

`run unkeep` removes that protection. `state clean` previews eligible cleanup unless you
explicitly apply it, and local removal never cancels remote work.

## Research lifecycle and evidence

A Strategy Family owns the stable research idea. Its Working Source is the editable
Python implementation. Exact source revisions let Experiments and Runs retain the code
that produced their results even after the Working Source changes.

An Experiment records periods, Strategy Family members, parameter selection, and build
mode. It is revisioned rather than overwritten, so changes remain reviewable. Useful
local commands include:

```bash
uv run tradepose experiment show rsi_2024
uv run tradepose experiment history rsi_2024
uv run tradepose experiment diff rsi_2024
uv run tradepose experiment clone rsi_2024 --as rsi_2025
```

A Run is the evidence root for one remote execution. It connects the submitted request,
source snapshots, results, and selected configurations. Inspect evidence locally with:

```bash
uv run tradepose run list
uv run tradepose run show <run-id> --verbose
uv run tradepose inspect run:<run-id>
```

Portfolio promotion records exact selected evidence instead of copying an untraceable
configuration. A Portfolio version can later create a new-period evaluation Experiment
without automatically executing it.

Published catalogs enter the same lifecycle through explicit resolution. Use
`client.definitions.materialize_experiment(...)` for exact Definition/Policy selections
or `client.portfolios.materialize_evaluation_experiment(...)` for an immutable published
PortfolioVersion. Both seal verified Gateway bytes and refs into an ordinary local
Experiment revision; later preview, prepare, run, resume, and result access are local
workspace operations and never recompile Working Source or implicitly refresh Gateway.

Catalog publication is also explicit. Publish one complete compiled Definition/Policy
set with `client.definitions.register(compilation)`. After a Run is complete and locally
verified, use `client.portfolios.publish_verified_run_version(...)`; the Gateway
independently revalidates the completed remote work, admitted source binding, and canonical
artifact bundle before publishing one immutable `PortfolioVersion`. Neither operation is
part of Preview or ordinary Run recovery.

The public async client exposes `client.risk_policies` for the post-publication sizing
handoff: register an immutable policy/account binding, inspect replaceable projections,
request formal batch evaluation, and resolve a sizing Engagement's canonical context.
These calls return typed `tradepose-models` contracts; the removed local
Portfolio-to-order-event handoff has no sizing fallback. Returned quantities are
authoritative Gateway pre-execution sizing
evidence, not live margin, open-heat, liquidity, or broker-execution authorization.

## Strategy authoring model

TradePose strategies are typed Python modules. A source declares market data and
indicators, a Base opportunity describes the market event, and optional post-Base
policies describe entry and exit decisions. Parameters remain separate from assembly so
one definition can produce reproducible baseline, sweep, or policy cases.

The generated RSI template is executable documentation. Its central shape is:

```python
from tradepose_client import authoring as tp


@tp.strategy(RsiReversionParams)
def rsi_reversion(
    builder: tp.DefinitionBuilder,
    params: RsiReversionParams,
) -> None:
    primary = params.primary
    opportunity = params.opportunity
    rsi = builder.col(primary.rsi)
    long_entry = rsi < opportunity.lower_level
    long_exit = rsi >= 50.0
    short_entry = rsi > (100.0 - opportunity.lower_level)
    short_exit = rsi <= 50.0
    entry, exit = (
        (long_entry, long_exit)
        if opportunity.direction == tp.TradeDirection.LONG
        else (short_entry, short_exit)
    )
    builder.data.set_volatility_scale(primary.volatility_atr)
    builder.base(
        direction=opportunity.direction,
        trend=opportunity.trend,
        entry=entry,
        exit=exit,
    )
```

Use `strategy show` to inspect the public parameter interface and `strategy check` to
validate source identity, completed-bar causality, indicator dependencies, and build
contracts. Experiment Preview then expands parameter selections and reports exact work
without crossing the remote boundary.

Policy and Experiment authoring describe executable entry and exit behavior only. Position
sizing belongs to the Gateway-owned `RiskPolicy` resource after verified selection and
explicit Portfolio Version publication; it is not a Policy sweep or compatibility input.

## Local state and retention

Workspace metadata lives in `.tradepose/state.sqlite3`. Canonical request bytes and
source snapshots stay with Run records; larger downloaded artifacts live below
`results/runs/<run-id>/`.

```bash
uv run tradepose state info
uv run tradepose state clean
```

Keep `.tradepose/state.sqlite3` and retained result artifacts together when backing up a
workspace. SQLite v10 is authoritative. Migrate v9 only with the explicit, backed-up
`tradepose state migrate` command; migration is never implicit during ordinary commands.

## Instruments and optional agent skills

The workspace instrument catalog supplies canonical identifiers and market metadata.
After configuring remote access, synchronize it deliberately:

```bash
uv run tradepose instruments sync
uv run tradepose instruments status
```

The Client also ships optional Claude and Codex skills for strategy authoring and
research workflow guidance. Install and verify them in a workspace with:

```bash
uv run tradepose skills install --agents claude,codex
uv run tradepose skills check
```

After upgrading the SDK, synchronize the selected agents and check the result so the
workspace uses the bundled guidance from the installed version:

```bash
uv run tradepose skills sync --agents claude,codex
uv run tradepose skills check
```

These generated guidance files are local tooling. They do not submit research or grant
an agent remote-execution authority.

## Interactive notebook API

`ResearchWorkspace` is the public durable notebook interface. Opening a workspace and
looking up an Experiment are local-only. Creating remote work requires the explicit
`authorize_remote=True` boundary, and every handle shares the workspace's single
SubmissionEngine runtime owner:

```python
from tradepose_client import (
    ResearchWorkspace,
    RunSubmissionInterruptedError,
    RunWaitTimeoutError,
)

with ResearchWorkspace.open(".") as research:
    experiment = research.experiments.get("rsi_2024")
    preview = experiment.preview()  # local-only; no Run and no network runtime
    try:
        run = experiment.run(authorize_remote=True, preview=preview)
        run_id = run.run_id
    except RunSubmissionInterruptedError as interrupted:
        # The Run already exists. Resume this identity; never create a replacement.
        run_id = interrupted.run_id
        run = research.runs.open(run_id).resume()
    try:
        run.wait(timeout=1_800)
    except RunWaitTimeoutError:
        # The local deadline stopped observation only. Reopen the same durable Run later.
        pass

with ResearchWorkspace.open(".") as research:
    run = research.runs.open(run_id)
    run.wait(timeout=1_800)
    evidence = run.evidence()
    result = run.result()  # kind-directed, complete verified local artifacts only
    frame = result.frame()  # concatenated trades, or one physical OHLCV DataFrame
```

Use `experiment.prepare(preview=preview)` when the durable evidence boundary must be
separate from remote submission. Preparation commits exact source bytes, Experiment
revision, resolved Params, canonical Definition and Workload bytes/refs, BuildEvidence,
catalog snapshot bytes/digest, and environment provenance. A changed source or catalog
fails closed before submission. `run.result()` works after restart without network I/O
and never exposes internal remote-work identities or artifact paths. It verifies complete
exact Run evidence before exposing results and loads artifact content lazily with a fresh
digest check at use time; incomplete, incompatible, corrupt, or digest-invalid evidence
or artifacts raise typed `RunResultUnavailableError` outcomes.

`RunHandle.close()`, a local timeout, and Ctrl-C never claim to cancel accepted remote
work. `diagnostics()` exposes detailed lifecycle and internal remote-work identities on
request; those identities and artifact paths are not the primary notebook interface. If
Ctrl-C interrupts the initial submission after durable Run creation,
`RunSubmissionInterruptedError.run_id` identifies the only Run that may be reopened and
resumed.

Use `run.rerun(authorize_remote=True)` only for an intentional new execution. It creates
a new Run linked by `rerun_of`, copies the saved exact canonical requests without
recompiling the current Working Source, and obtains fresh idempotency keys, Tasks, and
admission evidence.

Run network recovery is operation-aware and bounded. An ambiguous submission replays
only the exact persisted request bytes with its durable idempotency key, so it resolves
to the same logical remote work; a key/content conflict is terminal. Polling and
downloads retry only network failures, temporary rate limits, and selected server
failures with capped jittered backoff. Temporary rate limits honor a bounded
`Retry-After`; quota, authentication, validation, and other deterministic failures do
not retry. If the attempt cap or local wait deadline is reached, reopen the same Run to
continue from SQLite state. Completed artifact bundles are still checksum-, schema-,
identity-, and compatibility-verified before they become locally available.

## Support, status, and license

- Homepage: [tradepose.com](https://tradepose.com)
- Support: [admin@tradepose.com](mailto:admin@tradepose.com)
- Status: Alpha
- License: MIT
