Metadata-Version: 2.4
Name: tradepose-client
Version: 3.4.3
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.9.0
Requires-Dist: typer>=0.16.0
Provides-Extra: dev
Requires-Dist: click>=8.1.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
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 -> 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](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.

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:

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

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

## 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. 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:

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

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:

```python
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](https://tradepose.com)
- Support: [admin@tradepose.com](mailto:admin@tradepose.com)
- Status: Alpha
- License: MIT
