TradePose Models

Models 2.21.0 is paired with Client 3.19.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

Models 2.21.0 adds the Research admission planner and estimator that Gateway admission and Client 3.19.0 preview share; existing public interfaces and every wire shape are unchanged. PlanningBudget holds only physical limits, rows are calendar bounds of each window up to the observation time, and planning reads no stored market data. A budget rejection lists every exceeded limit as a BudgetViolation.

The preceding Client 3.18.0 and Models 2.20.0 Alpha minor-breaking pair gave Market Profile Daily, Weekly and Rolling modes a required trading_weekdays Workload field (default Monday to Friday) and plan windows between trading-day anchor times, so Profile parameter payloads, identities and values change. TrendType and the Opportunity trend field are removed with no compatibility reader; Params containing trend fail validation, and params_hash, occurrence refs and definition_id change. tradepose_models.strategy provides the Regime, Edge and BaselineDescription hypothesis labels, which never enter Params, Definition, Workload or Policy identities. Every concrete StrategyParams provides a validated, isolated default sweep(). They retain the contextual Profile timestamp contract introduced by the 3.17 / 2.19 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. The SQLite schema version 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:

python -m pip install --upgrade 'tradepose-client==3.19.0' 'tradepose-models==2.21.0'
tradepose --version
tradepose skills check

Installation

Ordinary users should install the paired Client and Models versions:

uv add 'tradepose-client==3.19.0' 'tradepose-models==2.21.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:

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
• Support: 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.