TradePose Models

Models 2.25.0 is paired with Client 3.22.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.25.0 is an Alpha minor-breaking release that separates strategy identity from engine identity. StrategyDefinition, Workload and TaskSourceBinding no longer carry execution_semantics_revision, so every behavioral ref (DefinitionRef, WorkloadRef, TradePolicyRef, MarketDataRef, OpportunityRef, TaskSourceBindingRef) changes once and then stays the same across engine revisions. ResearchTaskRequest requires execution_semantics_revision (engine-v1). TaskMetadata and TaskMetadataResponse add execution_semantics_revision and build_source_sha, null until a Worker claims the Task, and the closed failure code execution_engine_mismatch reports a request for other execution semantics than the Worker's or shards that ran on different execution semantics revisions. Every model still rejects unknown fields, so this release and the Gateway/Worker cohort it pairs with must change together. Client 3.22.0 requires this release; pair them with Gateway/Worker built from the same source, which applies database migrations through 000058.

Models 2.25.0 also removes tradepose_models.enums.ExportType and TaskMetadata.export_type; TaskFailure.context accepts only strategy_count and policy_ref. Every Task is a Research Task, and its request's result_kind decides what it produces.

Models 2.23.2 adds two closed Task failure projections, both at stage result_persistence. result_storage_full (retryable) means shared result storage was temporarily occupied by results that could not be evicted, so the Run can be submitted again later. result_too_large (not retryable) means the result can never fit, so the Run must be split. Earlier Models versions reject Task metadata that carries either code.

Models 2.23.1 gives a strategy one clock. compile_data_graph fills every direct source without its own evaluation_tz with the backtest source's timezone, and resolve_source_descriptors(sources, *, backtest_evaluation_tz) takes that timezone as a keyword. A feature direct source therefore carries the primary timezone in its SourceDescriptor, its computation ids and MarketDataSource.evaluation_timezone, and sources resampled from it build bars on that clock: a 1D feature bar rolls over at the primary's local midnight. Computation ids of Definitions with a feature direct source change; strategies with only a primary source are unchanged. AccountSource.broker_clock() returns the new BrokerClock, and MT5 sources (FTMO, Pepperstone, IC Markets, Exness) convert broker-local times with America/New_York+07:00; AccountSource.timezone() and tz_offset() are removed.

The preceding Models 2.23.0 is an Alpha minor-breaking release. Instrument keys are two-part SOURCE:SYMBOL: parse_instrument_key, Instrument.key, CatalogInstrument and the Research planner reject three-part keys, and market type is an instrument attribute only. BrokerAccount drops available_markets and default_market, and AccountRiskBinding drops pinned_market_types. PortfolioSelectionPublication.history_warmup_days is required and part of portfolio_content_hash, so existing PortfolioVersion content hashes change; tradepose_models.research.history_warmup defines the operational round window and the publication check. Readiness adds source_frequency and drops account_markets, datafeed.OHLCVUpdatedEvent announces bar arrival, and SyncEngagementsCommand expires after SYNC_ENGAGEMENTS_COMMAND_TTL (30 minutes). Client 3.20.0 requires that release; pair them with Gateway/Worker built from the same source, which applies database migrations through 000055.

The preceding Models 2.22.0 is an Alpha minor-breaking release for the Research planner. A trades physical shard executes only the computations its selected Definitions map to, while ohlcv_indicators and ohlcv_signals shards keep the complete group graph. Shard estimates charge only retained computations, so one Definition's smallest shard no longer grows with the group and parameter sweeps that 2.21.0 rejected can fit. Python and Rust projection validation require the shard graph to equal the graph recomputed from its selections. PhysicalExecutionShard.resolve_workload, validate_physical_workload_projection and validate_physical_policy_coverage take the result kind. ExecutionCostCoefficients and PlanningBudget are keyword-only and take their capacity values from the deployment instead of package defaults. Workload, binding, request and snapshot wire shapes are unchanged. Client 3.19.1 requires that release; pair them with Gateway/Worker built from the same source, because an older Gateway or Worker rejects the new shard graphs.

The preceding Client 3.19.0 / Models 2.21.0 release added the Research admission planner and estimator that Gateway admission and Client 3.19.0 preview share; its other 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 compares each physical task's estimated peak, computed from the ExecutionCostCoefficients (RESEARCH_PLANNER_* keys), with RESEARCH_PLANNER_MAX_PEAK_MEMORY_BYTES. This is sample-based empirical calibration, not a promise about RSS. Definitions split by budget with no promised average count; an oversized minimum unit rejects the whole request. The admission budget, Worker container memory and child virtual address space of every environment are defined only in deploy/environments/capacity.json; python3 deploy/scripts/capacity.py --profile <env> prints the effective values. RSS, container RAM and virtual address space are distinct.

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

python -m pip install --upgrade 'tradepose-client==3.22.0' 'tradepose-models==2.25.0'
tradepose --version
tradepose skills check

Installation

Ordinary users should install the paired Client and Models versions:

uv add 'tradepose-client==3.22.0' 'tradepose-models==2.25.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 canonicalization revision; unknown, missing, legacy schema-version, and extra fields fail closed. ResearchTaskRequest carries the engine-v1 execution semantics revision (EXECUTION_SEMANTICS_REVISION), which names the engine semantics the request expects and is not part of any behavioral ref. 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, saved_result_publication_failed, result_storage_full, result_too_large and execution_engine_mismatch. 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.