Metadata-Version: 2.4
Name: tradepose-models
Version: 2.13.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

Client 3.8.0 is paired with Models 2.13.0. Installation and migration details are
provided in the Client package’s `docs/MIGRATION_3_8.md`. Analyzer is installed locally
from the same release source and is not published to PyPI.

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.8.0' 'tradepose-models==2.13.0'
```

Models 2.13.0 is an Alpha minor-breaking release paired with Client 3.8.0.
Client 3.7.0 permits this version in its dependency range but expects earlier public
interfaces: preserve its lock or explicitly pin Models 2.12.0 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 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
