Composer, Strategy IR, and SDK

One contract, two authoring paths

Composer and the Python Strategy SDK both produce typed Strategy IR. The runtime consumes validated, compiled StrategyProgram artifacts—not Composer UI state and not arbitrary plugin Python.

Composer document ─┐
                   ├─> Strategy IR (`sir1:`) -> validation -> compiler
trusted SDK plugin ┘                            -> StrategyProgram -> runtime

Use Composer when its visible controls express the rule. Use the SDK for generated expression trees, specialized multi-input declarations, reusable builder code, or public IR features that are not yet practical in Composer. Keep exploratory calculations in Notebooks and reusable calculations in Signals.

Composer workspace map

Cards/Dense mode and panel layout are presentation state. They do not change Strategy identity.

Strategy IR layers

The canonical IR rejects extra/invalid fields and validates cross-field semantics. A syntactically valid JSON object is not necessarily a valid Strategy.

Functional versus presentation fields

Functional changes normally create a new sir1: fingerprint:

• inputs, source references, dtypes or alignment;
• parameter declarations/domains;
• variables and expression trees;
• entry/exit rules and their order;
• evaluation timing;
• order instructions and replacement policy;
• position/risk semantics; and
• execution requirements.

Name, description, comments, editor layout and other declared presentation fields do not necessarily change functional identity. Do not bump or preserve a semantic version based on intent alone; compare canonical IR and retained hash fixtures.

Input source registry

Every input has a stable ID and dtype. A DataFrame column name or display label does not establish source identity. Shifts are nonnegative prior-observation access; shift(1) increases derived lookback and cannot access a future row.

Multi-input latest-visible alignment declares reference clock, finite staleness tolerance, and session-boundary policy. A secondary value newer than the decision time is ineligible.

Parameter registry

Supported parameter dtypes are float, integer, Boolean, and enum under their declared contracts.

Strategy parameters change decision behavior. Signal parameters belong to the Signal and its Output identity; binding a Signal does not copy its parameter declaration into Strategy IR as an unrelated Strategy parameter.

Operand and expression types

Conditions are typed expression trees, not strings. Operands include:

• input/Signal/Feature handles;
• parameter handles;
• typed literals;
• formula variables;
• supported arithmetic/transform nodes; and
• Boolean combinations.

Comparisons require compatible types. Supported control vocabulary includes ordinary comparisons, crossings and Boolean AND/OR/NOT where the authoring surface exposes them. Do not cast float to Boolean or compare unrelated enum domains silently.

Canonical normalization makes semantically identical trees stable where the IR contract says so; UI condition order remains significant when sequence or rule priority is authored.

Entry Setups and Followed by

An Entry Setup groups conditions for one Long or Short entry rule. Multiple setups act as alternative entry paths under the saved rule semantics.

Followed by is a temporal confirmation contract:

setup condition becomes eligible
  -> confirmation must occur afterward
  -> within the declared bound
  -> without future data or an undeclared session crossing

It is not ordinary AND on the same row. Reordering or changing the bound is a functional change.

Long and Short rules are independent. The Position policy decides whether each side is allowed and what happens when both signal simultaneously (for example, enter neither under the current example policy).

Exit purposes

Live Signal evaluates the Strategy exit condition as the runtime progresses. Entry Bracket attaches supported protective/target intent at entry and requires matching risk-distance/target semantics plus a compatible execution model. The label alone does not make a bracket supported at every fidelity.

Orders, position, risk, and sizing

Strategy IR can declare Market, Limit, Stop, Stop-Limit, Trailing and supported replacement semantics with typed offsets and time in force. Exact availability depends on compiler/runtime/provider matrices.

Tick offsets use the governed Instrument price increment. A positive number is not meaningful without side, reference price and instruction semantics.

The Strategy owns signal-to-intent semantics. It does not own final quantity. Study Design, Portfolio policy, or Live deployment combines the saved risk distance with capital, risk budget, Instrument value and admission rules.

builder.risk() or Composer risk controls define maximum stop distances and bracket targets; they are not an account-level risk profile.

Evaluation clocks

Evaluation trigger does not select fill model. Decision time, submission time, eligibility time and fill time remain separate.

Configuration and version identities

Saving a Strategy version does not queue a Study. Saving a Configuration pins values to an exact Strategy version. Rebase is explicit; no current/latest Strategy substitution rewrites historical Configurations, Portfolios, Studies, Results, or deployments.

Public Python SDK surface

Representative public imports include:

from arizmic.strategy_sdk import (
    ExecutionRequirements,
    ParameterDeclaration,
    StrategyBuilder,
    StrategyIR,
    ValueDType,
    compile_fast,
    compile_vector,
    discover_strategy_plugin,
    validate_strategy_ir,
)

StrategyBuilder provides the public construction surface for:

• input() and param() typed handles;
• formula/comparison/crossing/Boolean expression trees;
• long_entry(), short_entry() and exit_when();
• completed-Bar, Trade, Quote and supported Timer evaluation;
• latest-visible input alignment;
• order instructions and supported replacement fields;
• position_rule();
• risk distances, bracket targets and exit-mode parameters; and
• build() with name, description and ExecutionRequirements.

The exact installed SDK signature is authoritative. Do not import internal compiler/service modules when a public builder feature is absent.

Plugin protocol

A trusted plugin module is discovered from plugin.py and exposes one strategy_plugin object or zero-argument factory with:

• plugin_id;
• plugin_version;
• a tuple of ParameterDeclaration values; and
• build_ir(overrides=None) -> StrategyIR.

Discovery imports and executes the module. Treat it as trusted local code: review filesystem, network, environment, subprocess and dependency behavior before installation. Plugin Python is authoring code only. Runtime engines do not call it per row/trial or use it as a fallback.

Plugin-level declarations and builder parameters must match exactly in ID, dtype, default, bounds/choices and meaning.

Validation vocabulary

An empty validation finding list means that owner passed. It is not a universal green light.

Minimum owner test suite

Retain tests for:

1. stable plugin and Strategy identity;
2. declared-versus-built parameters and edge/invalid overrides;
3. exact input source/ref/dtype/alignment/requirements;
4. hand-calculated entry/exit and current-position behavior;
5. Long/Short conflicts;
6. warm-up, null/non-finite, duplicate-time, gap/session behavior;
7. future-row mutation/no-lookahead proof;
8. stable sir1: and migration fixtures;
9. Vector/Direct Array compile and eligible reference parity;
10. order/risk/bracket/execution blockers; and
11. Signal dependency failure and recovery.

Shared repository tests do not replace the plugin owner's semantic tests.

Sync and source ownership

Full Sync Plugins scans the configured root and reports discovered, synced, missing and issue outcomes. Targeted Sync reconciles one installed plugin selector without rescanning unrelated roots.

Plugin Strategies remain Python-owned. Edit source and sync; Composer restore is unavailable for plugin snapshots. Composer-authored Strategies remain Composer- owned. Converting/forking source ownership requires a new explicit identity and does not create bidirectional synchronization.

Sync stores the IR plus plugin provenance and updates the system Default Configuration where the owner specifies. It does not bind a Dataset, build Signals, certify a target, or rewrite exact historical references.

Compiler and runtime boundary

typed IR inputs + parameter slots + canonical expressions
  + evaluation + entries/exits + position/risk/order metadata
  -> target compiler
  -> StrategyProgram ABI + program hash + derived lookback
  -> Study/Portfolio/Live evaluator under its own capability matrix

No Strategy-specific engine branch or Python fallback may bypass the ABI. Unsupported IR remains blocked at the target compiler/readiness gate.

Next

Use Composer Workspace and Inputs for every visual control, Python SDK Quickstart for a complete trusted plugin, and Strategy IR, Plugin Testing, and Sync for the verification pipeline.