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

Models 2.15.0 is paired with Client 3.11.0 and a matching Gateway 0.2.0 / Rust 0.2.0
backend. Analyzer remains an internal source package 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 the paired Client and Models versions:

```bash
uv add 'tradepose-client==3.11.0' 'tradepose-models==2.15.0'
```

This is an Alpha minor-breaking release. Existing Client 3.10.0 users should retain
Models 2.14.0 until upgrading both packages. Package installation does not deploy
matching backend services or migrate stored artifacts.

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`, the complete Core schema and execution identity columns are mandatory
in producer order, including empty and all-null scenarios. Member, Definition, Policy
and execution-window identities preserve aggregate membership. Missing, extra,
reordered, physical `Null`, or castable-but-wrong columns are rejected.

`MarketDataSpec` contains direct/resampled source lineage and a closed computation DAG
with separate Indicator and DataColumn nodes. `market_data_spec_from_compiled_graph()`
projects the validated authoring graph and verifies content-addressed computation
identities. DataColumn selects OHLCV or TS and applies a non-negative owning-source
row shift after resampling, before evaluation alignment. Its scalar dtype, timezone
and nulls are preserved. The manifest contains separate `indicators` and `data_columns`
membership; older shapes are not accepted. `RawOhlcvIndicator` is removed.

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

## Research execution identity

The current `research` exports include complete `ResearchTaskRequest` collections,
`WorkloadMember.original_definition`, `AuthoringOccurrenceBinding`, member-qualified
`WorkloadExecutionManifest`, and the data-only `ResearchExecutionPlan` contract.
Canonical bytes and strict validators are shared with Rust Common. Backtest submissions
carry complete Workload and execution-window collections; the Gateway accepted plan
records execution groups and shards. OHLCV diagnostics retain their one-member,
one-Period restrictions. Offline Preview does not predict the accepted shard count.
