Execution Modes & Contracts

Kafal distinguishes between script execution targets (what the interpreter extracts) and order execution engine rules (how trade fills, margins, and prices are processed).

Script Run Modes

When executing a script via interpreter.run(code, df, mode=...), you can select one of three operational modes depending on your workload:

chart: Captures visual primitives alongside standard strategy performance curves.
strategy: Skips visual outputs to focus purely on trade logs, equity curves, and metrics.
research: Optimizes for factor generation, capturing outputs via the feature() API.

# 1. Chart Mode (Default): Visual primitives + basic strategy state
chart_payload = interpreter.run(script, df, mode="chart")

# 2. Strategy Mode: Focuses on trade logs, equity curves, and performance stats
strategy_payload = interpreter.run(script, df, mode="strategy")

# 3. Research Mode: Feature extraction for quantitative research
research_payload = interpreter.run(script, df, mode="research")
features = research_payload["features"]  # Dict[str, pd.Series]

Feature Extraction in Research Mode

In research mode, use the feature() function to export factor series directly to the host without rendering overhead.

// Research Mode Feature Extraction
alpha = zscore(close, 60)
vol = ta.atr(high, low, close, 14) / close

// Export features directly to the Python host payload
feature("alpha_z60", alpha)
feature("rel_atr_14", vol)

Order Matching Engine: Backtest vs. Realistic

Kafal allows you to configure trade matching rules when instantiating the interpreter using the execution_mode parameter.

backtest Mode

Optimistic matching mode. Evaluates limit orders first, followed by stop orders. Assumes frictionless execution paths.

realistic Mode

Production-grade simulation. Evaluates stop orders first, fills gapped stops/limits at the candle open price, and validates margin requirements.

from kafal.core.interpreter import KafalInterpreter

# Configure realistic order execution rules and symbol specifications
interpreter = KafalInterpreter(
    initial_equity=100_000.0,
    commission_perc=0.0005,  # 0.05% commission per order
    slippage=0.01,           # $0.01 fixed slippage
    pyramiding=2,            # Max 2 concurrent positions
    execution_mode="realistic", # "backtest" | "realistic"
    intrabar_model="random_walk", # "none" | "random_walk"
    intrabar_steps=4,
    symbol_configs={
        "chart": {
            "spread_points": 0.02,   # Fixed bid/ask spread
            "min_lot": 0.1,          # Minimum position lot size
            "lot_step": 0.1,         # Lot increment step
            "max_leverage": 10.0,    # Maximum allowed leverage
            "contract_size": 100.0   # Contract multiplier
        }
    }
)

Intrabar Path Modeling

When intrabar_model="random_walk" is enabled in realistic mode, Kafal decomposes historical bars into simulated price steps to prevent unrealistic intra-candle dual-fills.

Symbol Specifications & Margin Rules

Host applications configure symbol-specific rules via symbol_configs.

spread_points: Fixed spread subtracted on short fills and added on long fills.
min_lot / lot_step: Quantizes position sizes to valid lot increments.
max_leverage: Validates margin before order execution. Position-reducing orders are exempt from margin checks.
contract_size: Multiplier used for notional calculation.