Metadata-Version: 2.4
Name: tradepose-models
Version: 2.9.0
Summary: Shared Pydantic models for TradePose platform
Author-email: TradePose Team <codeotter0201@gmail.com>
License: MIT
Keywords: models,pydantic,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: polars==1.33.1
Requires-Dist: pydantic>=2.12.1
Description-Content-Type: text/markdown

# TradePose Models

Shared Pydantic contracts, enums, indicator calculations, and Polars schemas for
TradePose packages.

## Installation

```bash
pip install tradepose-models
```

Python 3.13 or newer is required.

## Indicator specification

Concrete indicator models are the calculation configs. `IndicatorSpec` adds canonical
source provenance and resolved wire identity.

```python
from tradepose_models.enums import Freq
from tradepose_models.indicators import ATRIndicator
from tradepose_models.strategy import IndicatorSpec, SourceDescriptor

source = SourceDescriptor(instrument="NAS100", freq=Freq.DAY_1)
atr_spec = IndicatorSpec(
    source=source,
    indicator=ATRIndicator(period=14, shift=1),
)

assert atr_spec.instrument == "NAS100"
assert atr_spec.indicator_id.startswith("sha256:")
assert atr_spec.column_id.startswith("ind_v1_")
assert atr_spec.public_name.startswith("NAS100@1D:ATR(period=14)")
assert atr_spec.output_ref().indicator_id == atr_spec.indicator_id
```

`public_name` is presentation metadata for logs and friendly artifact views.
`column_id` is the only physical DataFrame column name; `col()` selects that struct
column and callers then select a declared field such as `.struct.field("value")`.
`short_name` and `display_name()` are not part of the indicator API.

## Typed authoring dependencies

Client authoring dependencies use `tp.input(...)`; resolved `IndicatorOutputRef` values
belong only to compiled `IndicatorSpec` wire data. Do not substitute readable labels
or physical `ind_v1_*` column identities for typed references.

```python
from tradepose_client import authoring as tp

atr = ATRIndicator(period=14, shift=1)
atr_quantile = ATRQuantileIndicator(
    atr_column=tp.input("atr"),
    window=252,
    quantile=0.5,
    shift=0,
)
supertrend = SuperTrendIndicator(
    multiplier=3.0,
    volatility_column=tp.input("atr"),
    shift=1,
)
```

For open-driven decisions, indicators reading `high`, `low`, `close`, or `volume`
require `shift >= 1`. A literal current-bar `column="open"` may use `shift=0`.

## Core modules

- `tradepose_models.strategy`: strategy, graph, authoring, manifest, and portfolio
  data contracts.
- `tradepose_models.indicators`: concrete calculation models and their output contracts.
- `tradepose_models.enums`: shared frequencies and trading enums.
- `tradepose_models.schemas`: trades and timezone-aware OHLCV schemas.
- `tradepose_models.export`: typed export request and response contracts.

Experiment catalogs, workspace lifecycle, execution, and portfolio promotion are
owned by `tradepose-client`; Models does not provide a Python strategy registry.

## Development

From the repository `python/` directory:

```bash
uv run --project packages/models pytest packages/models/tests
uv run ruff check packages/models
```
