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 -> Portfolio

TradePose Client is Alpha software. Expect the authoring and research interfaces to evolve between releases, and review release notes before upgrading an active workspace.

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.

The Client selects a compatible tradepose-models dependency. Do not install or pin Models separately.

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.

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.

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. State schema migrations are explicit and create a backup; they are never performed silently 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

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

Interactive notebook API

BatchTester remains a compact interactive DataFrame interface. This example reuses the Working Source generated in the local workflow:

from tradepose_client import BatchTester
from tradepose_client.batch import Period
from playbook.strategies.rsi_reversion import (
    RsiReversionParams,
    rsi_reversion,
)

configs = rsi_reversion.build(RsiReversionParams())
tester = BatchTester(api_key="...")
batch = tester.submit_backtest(
    strategies=configs,
    periods=[Period.from_year(2024)],
)
trades = batch.wait(timeout=1_800).trades

BatchTester.submit_backtest() immediately creates remote work. It does not provide the complete Experiment and Run evidence lifecycle described above.

Support, status, and license

• Homepage: tradepose.com
• Support: admin@tradepose.com
• Status: Alpha
• License: MIT