create-rule

Create Rule

You create bar-by-bar risk, hold, weight override, or exit logic.

Scope

Default built-in paths:

• source: src/oxq/rules/{snake_name}.py
• tests: tests/rules/test_{snake_name}.py
• package export: src/oxq/rules/__init__.py
• built-in registry: src/oxq/core/registry.py

Phase 1: Read Existing Patterns

Read before editing:

• src/oxq/core/types.py
• src/oxq/core/engine.py rule handling in step()
• src/oxq/rules/constraint.py
• src/oxq/rules/order.py
• one existing test in tests/rules/
• src/oxq/rules/__init__.py
• the rule registration block in src/oxq/core/registry.py

Important current engine behavior:

• pre-trade consumes RuleResult.weights
• pre-trade consumes RuleResult.hold
• post-trade consumes RuleResult.target_positions
• RuleResult.constraints exists in the type but is not currently applied by Engine.step()

Phase 2: Define Behavior

State before coding:

• pre-trade or post-trade
• trigger condition
• fields returned in RuleResult
• constructor parameters
• internal state, if any
• reset behavior, if any
• exact no-trigger result

Ask the user if risk thresholds or trigger semantics are ambiguous.

Phase 3: Test First

Write tests with hand-built portfolio and bar rows:

• protocol compliance with Rule
• trigger scenario
• no-trigger scenario returns empty RuleResult()
• correct reason when activated
• no mutation of Portfolio
• stateful behavior if relevant
• name value

Run the new test and confirm the missing implementation fails before coding.

uv run pytest tests/rules/test_{snake_name}.py -v

Phase 4: Implement

Skeleton:

"""Short description rule."""

from __future__ import annotations

from decimal import Decimal

import pandas as pd

from oxq.core.types import Portfolio, RuleResult


class ClassName:
    """Short behavior description."""

    name = "ClassName"

    def __init__(self, threshold: float) -> None:
        self.threshold = threshold

    def evaluate(
        self,
        symbol: str,
        row: pd.Series,
        portfolio: Portfolio,
        prices: dict[str, Decimal] | None = None,
    ) -> RuleResult:
        """Return a RuleResult when the rule activates."""
        ...