Metadata-Version: 2.4
Name: tradepose-models
Version: 2.12.0
Summary: Shared Pydantic models for TradePose platform
Project-URL: Homepage, https://tradepose.com
Author-email: TradePose Team <admin@tradepose.com>
License: MIT
Keywords: models,pydantic,trading
Classifier: Development Status :: 3 - Alpha
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

TradePose Models contains independently versioned Pydantic and Polars contracts shared
by the public TradePose Client and private TradePose systems. It keeps serialized
strategy, execution, result, and market-data shapes consistent across those boundaries.

## Installation

Ordinary users should install only `tradepose-client`:

```bash
uv add 'tradepose-client==3.7.0' 'tradepose-models==2.12.0'
```

Models 2.12.0 is an Alpha minor-breaking release paired with Client 3.7.0.
Client 3.6.1 permits this version in its dependency range but expects older billing
shapes: preserve its lock or explicitly pin Models 2.11.1 until upgrading the pair.

If a package resolver reports a Models conflict, upgrade `tradepose-client` instead of
guessing a Models version:

```bash
uv lock --upgrade-package tradepose-client
uv sync
```

Direct installation is intended only for maintainers of systems that implement the
shared TradePose contracts.

## Canonical research Workloads

Maintainers can import the closed research execution contract from
`tradepose_models.research`. `Workload` and `TaskSourceBinding` use only the exact
current typed schema and carry no schema-version field. They require the
`canonical-json-v1` and `research-execution-v1` capability revisions; unknown,
missing, legacy schema-version, and extra fields fail closed. Use
`canonical_workload_bytes()` and `canonical_task_source_binding_bytes()` for transport, the typed ref helpers for
content identity, and `binding_requirements()` to derive source roles solely from the
Workload's `MarketDataSpec`.

Use `validate_research_result_frame()` at Python artifact boundaries to verify a typed
`ResearchTaskRequest`, its kind-required Workload/Indicator manifests, exact physical
Polars schema and nullability, indicator Struct fields, and canonical Policy row order.
The validator intentionally does not cast: accepting a convertible dtype would hide a
Worker wire-schema violation. Perform any desired data conversion only after canonical
artifact admission, outside this contract check.

For `trades`, all 45 Core columns are mandatory in their producer order and retain
their exact dtype through Parquet, including empty and all-null scenarios. The Worker
adds only a non-null trailing `policy_ref`. Missing, extra, reordered, physical `Null`,
or castable-but-wrong columns are rejected without compatibility fallback.

`MarketDataSpec` contains the complete direct/resampled source lineage and normalized
indicator computation DAG. `market_data_spec_from_compiled_graph()` is the sole narrow
projection from the validated authoring graph; it verifies every physical computation
identity and preserves typed dependencies, selected multi-output fields, shift, and
publication alignment. It is not a second runtime contract.

This package does not compile authoring sources, resolve catalogs, admit Tasks, or
execute Workloads. Those remain separate service boundaries.

## Task and expression compatibility

Models 2.12.0 includes immutable Task snapshots and closed failure projections for
`business_commit_unconfirmed` and `saved_result_publication_failed`. Deploy matching
Gateway/Worker task notification and snapshot contracts together. Expanded native Polars
expression support also requires a matching Worker; package installation does not update
server services or translate older schemas.

## Billing and resource contracts

Plans require `research_ingest_per_minute` and `task_slots`. `monthly_quota`,
`max_concurrent_tasks`, subscription `usage_limit`, and usage limit/remaining/percentage
fields are removed. Usage telemetry remains. Models validates format, semantics and
forbidden capabilities; server policy owns bounded resource refusals. Gzip changes
transport/storage representation without changing computation identity.

## Runtime requirements

- Python 3.13 or newer
- Pydantic 2.12.1 or newer
- Polars 1.33.1

Models is Alpha software. Its version is independent from the Client version, and
contract-breaking changes may require a coordinated Client upgrade.

## Support and license

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