Metadata-Version: 2.4
Name: tradepose-models
Version: 2.19.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.43.2
Requires-Dist: pydantic>=2.12.1
Description-Content-Type: text/markdown

# TradePose Models

Models 2.19.0 is paired with Client 3.17.0 and a matching Gateway/Worker source
cohort. 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.

## Current contract upgrade

Client 3.17.0 and Models 2.19.0 are an Alpha minor-breaking pair. Profile Workload and
result declarations use contextual `datetime_ms` rather than fixed-UTC
`datetime_ms_utc`. A source-owned Profile may publish in its source timezone; the
evaluation frame converts its three Profile time columns to the evaluation timezone
while preserving physical epochs. Trades and persisted timestamps remain UTC.
The old declaration has no fallback. Use Client, Models, Gateway and Worker from a
compatible source cohort before remote execution.

The preceding Client 3.15.0 / Models 2.18.0 pair introduced Workloads that
carry complete Definitions and Definition-qualified Policy selections; WorkloadMember
and the old member-selection authoring interface are removed. Volatility references
are unified and classifications preserve their declared integer/String type.
Execution-plan shards require `cost_breakdown`; fixed Policy shard-size fields and
TaskSnapshot `shard_size` are removed. The strict current readers reject old shapes.
Client consumes these shared Models contracts; it does not shard requests locally.

Preserve the old environment, lock and evidence for reading old data. Recompile from
strategy source into a separate paired workspace. SQLite schema 12 alone does not
establish old plan, snapshot or evidence readability. No compatibility reader,
automatic rewrite or migration is provided. Polars remains 1.43.2 in this pair.
Remote execution requires Gateway/Worker built together with these current contracts;
service version 0.2.0 alone is not a sufficient compatibility identifier. Record exact
source and immutable image digests before activation. No deployment is claimed here.

Admission uses `max(128 MiB, ceil(raw_peak_memory_bytes / 2))`: raw 3 GiB becomes
1.5 GiB and raw 4 GiB becomes 2 GiB. This is sample-based empirical calibration,
not a promise that RSS halves. Definitions split by budget with no promised average
count; an oversized minimum unit rejects the whole request. Production/development/e2e
target 2 GiB admission, 3 GiB Worker container and 4 GiB child virtual address space.
CI retains 1,792 MiB / 2 GiB / 3 GiB. RSS, container RAM and virtual address space
are distinct. Prior RSS recalculations are not new large-task measurements.

Upgrade a separate Python 3.13+ environment with the published pair:

```bash
python -m pip install --upgrade 'tradepose-client==3.17.0' 'tradepose-models==2.19.0'
tradepose --version
tradepose skills check
```

## Installation

Ordinary users should install the paired Client and Models versions:

```bash
uv add 'tradepose-client==3.17.0' 'tradepose-models==2.19.0'
```

The preceding Client 3.14 / Models 2.17 Alpha minor-breaking upgrade established
the native expression contract described below. It is retained in this pair.
Python Polars is pinned to `polars==1.43.2`,
the paired version for Rust Polars 0.55.2 (Rust toolchain 1.98.1), not a claim about
the latest Polars release. Native expression bytes and derived Definition/content
identities change. The sizing evaluator is
`tradepose-sizing:polars-1.43.2:points-floor`; snapshots using the old evaluator
do not satisfy the new contract. Do not mix this SDK with an old Worker.
Preserve the old environment, lock and evidence, then recompile and validate from
strategy source in a separate paired environment. Old native expressions and saved
evidence are not guaranteed to replay. No automatic data rewrite or old AST reader
is provided. Client SQLite schema remains 12; this release is not a schema migration.
Matching Gateway/Worker contracts must be available before remote execution;
installing packages does not deploy services.
 The 2.16 line introduced breaking Definition bytes/refs, Workload member
selection and compact admission receipts relative to earlier minor versions. Users own migration of their data, strategies,
Portfolio/Scheduler bindings and workspaces; no historical readers or migration tools
are provided. Package installation does not deploy matching services.

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

Canonical serializers and ref helpers derive content identity; they do not perform
expression admission. Use `parse_workload_bytes()` or
`parse_research_task_request_bytes()` for external canonical bytes. Explicit
`validate_workload_expressions()` checks authored Definition expressions, including
unselected Policies and unused registered user columns. Shared validation results
remain local to the current operation; they are never a serialized trust flag.

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

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,
`Workload.definitions`, `AuthoringOccurrenceBinding`, Workload/Definition-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-Definition,
one-Period restrictions. Offline Preview does not predict the accepted shard count.
