Projects & factors

Projects & factors

Project model#

Every strategy is a project. A simple strategy may keep all code in its entrypoint; larger strategies can add Python modules and nested paths in the same file tree. The entrypoint owns the Strategy subclass and __data__ declaration, while supporting modules hold signals, portfolio rules or utilities.

Python completion combines exact opbt SDK suggestions with static semantic analysis of the current scope, Python builtins and standard library, plus imports and inferred types across files in the same draft. Analysis reads source and type stubs without importing or executing project modules; requests are revision-bound so results never mix two draft versions.

Factor library#

Factors live in a separate library and follow the same draft-and-version model. Contract v2 records the callable, call style, output shape, value type and null policy. Strategy projects pin an exact Factor version under an alias and import it from opr_factors.<alias>.

The starter library covers per-instrument momentum, time-series mean reversion, cross-sectional reversal and a layered range-efficiency project. Each starter states its output meaning and recommended evaluation mode; these are observable contracts, not platform scores.

def compute(factor_ctx, instrument, **factor_params):
    fast = int(factor_params.get("fast_window", 24))
    slow = int(factor_params.get("slow_window", 96))
    if not 2 <= fast < slow <= 2000:
        raise ValueError("windows must satisfy 2 <= fast < slow <= 2000")
    prices = factor_ctx.history(instrument, fields="close", window=slow + 1)
    if len(prices) < slow + 1:
        return None
    latest = float(prices["close"].iloc[-1])
    fast_base = float(prices["close"].iloc[-fast - 1])
    slow_base = float(prices["close"].iloc[-slow - 1])
    return float(latest / fast_base - latest / slow_base)

from opbt import Strategy
from opr_factors.momentum import compute as momentum_score

class FactorMomentumStrategy(Strategy):
    def handle_bar(self, ctx, bars):
        instrument = ctx.universe[0]
        score = momentum_score(
            ctx, instrument,
            fast_window=int(ctx.params.get("fast_window", 24)),
            slow_window=int(ctx.params.get("slow_window", 96)),
        )

Factor contract v2#

Parameter rules and evaluation values#

Versioned parameter contract for the Factor callable. Declare type: object, properties, required names, additionalProperties: false, and optional default/minimum/maximum/multipleOf/enum or x-constraints. Evaluation values are validated against it.

{
  "type": "object",
  "properties": {
    "fast_window": {"type": "integer", "default": 24, "minimum": 2, "maximum": 1999},
    "slow_window": {"type": "integer", "default": 96, "minimum": 3, "maximum": 2000}
  },
  "required": [],
  "additionalProperties": false,
  "x-constraints": [
    {"left": "fast_window", "op": "<", "right": {"param": "slow_window"}}
  ]
}

JSON keyword arguments passed to the selected Factor callable. Names, types, required fields, defaults, ranges, enums, and cross-field constraints come from that frozen version's parameter contract; unknown keys are rejected and the encoded object is capped at 64 KiB.

{
  "fast_window": 24,
  "slow_window": 96
}

Library lists and completed evidence#

A compact snapshot of evidence available to you. For a shared project, the normal library includes the latest successful standalone run from the Artifact owner or owning organization, while runs by other direct collaborators remain private. The row identifies the exact frozen version used; a saved row stays scoped to the version you saved. Completion is evidence for that version, not a platform quality verdict.

Sorting is applied by the server to the complete visible collection before pagination. Missing metrics stay last. Metric order uses the stored numeric value and is not a platform score; compare rows only after checking their version, window, universe, costs and label definition.

Factor evaluation#

An evaluation tests one frozen Factor version over a fixed data window and forward-return definition. The report covers data availability, IC, HAC, horizons, rolling results, equal-weight quantiles, a rank-weighted factor-mimicking return and target-weight turnover. Completed reports never change; if the methodology is updated, the platform creates a separate report for the same frozen version. These are research diagnostics, not a platform score.

Evaluation configuration#

Labels are matched exactly at t + horizon × frequency. If that target timestamp is missing, the label stays missing; the evaluator does not substitute a nearby value or carry one forward. Adjusted-price series that use information unavailable at the decision time cannot be selected as labels.

Versions, restore & access#

You may add release notes when freezing a version. Restore copies that version into a new editable draft; the original version and every historical run that used it remain unchanged.

Saving a version creates only a private reference for the current user. It does not duplicate the version or its source, and it never grants access; current Artifact permissions are checked again whenever the saved list is read.