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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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:

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:

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:

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
• Support: admin@tradepose.com
• Status: Alpha
• License: MIT