The Detector Rule Engine: Typed Strategy Configurations for the AI-Native Pipeline

What the Rule Engine Is

The Barfinex Detector service uses a declarative rule engine that replaces imperative strategy functions with a typed, composable configuration system. Strategies are easier to write, easier to test, and dramatically easier to reason about six months later.

More importantly: the scored signals produced by the rule engine are the primary input to Advisor's 8-stage AI reasoning pipeline. The precision and attribution of the rule engine's output directly determines the quality of the AI decisions that follow.

This is not a breaking change — existing Detector instances continue to work. But for new strategies, the rule engine is the recommended approach.

The Problem with Imperative Strategy Code

The old way of writing a Detector strategy looked something like this: a TypeScript class with lifecycle hooks, direct access to indicator values, and custom scoring logic scattered across methods. This worked, but it had real problems:

• Hard to reason about: Strategy logic was tangled with infrastructure concerns
• Hard to debug: No standard way to trace which condition fired and why
• Hard to compare: Two strategies written by two developers looked completely different
• No shared scoring model: Each strategy invented its own conviction scale

The rule engine solves all four problems.

How the Rule Engine Works

A rule engine configuration is a structured TypeScript object with three sections:

1. Inputs

Declare what data your strategy uses:

inputs: {
  candles: { symbol: 'BTCUSDT', timeframe: '5m' },
  orderflow: { symbol: 'BTCUSDT', depth: 10 },
}

Inputs are fetched from Provider automatically. No manual data fetching in your strategy code.

2. Rules

Define the conditions that must be true for a signal. Each rule has a condition, a weight, and an optional description:

rules: [
  {
    id: 'ema_trend_aligned',
    description: 'Price is above the 20 EMA on the 5m chart',
    condition: ({ candles }) => candles.close > candles.ema(20),
    weight: 2.0,
    direction: 'long',
  },
  {
    id: 'orderflow_imbalance',
    description: 'Buy-side order flow exceeds sell-side by > 30%',
    condition: ({ orderflow }) => orderflow.buyRatio > 0.65,
    weight: 1.5,
    direction: 'long',
  },
  {
    id: 'volume_spike',
    description: 'Current candle volume exceeds 20-period average by 2x',
    condition: ({ candles }) => candles.volume > candles.avgVolume(20) * 2,
    weight: 1.0,
    direction: 'long',
  },
]

Rules are evaluated independently. Each one that fires contributes its weight to the total signal score.

3. Thresholds

Define when the accumulated score becomes a tradeable signal:

thresholds: {
  long: { min: 3.5 },    // fire a long signal when score ≥ 3.5
  short: { min: 3.5 },
}

With the example above: if ema_trend_aligned and orderflow_imbalance both fire, the score is 3.5 — exactly at threshold. All three firing gives 4.5.

What You Get for Free

The rule engine gives you several things you'd otherwise have to build yourself:

Per-rule firing history — every rule evaluation is logged with its result and contribution. In Studio, you can see exactly which rules fired for each candle and why the signal score was what it was.

Standardized conviction scale — all strategies produce scores on the same normalized scale, making it possible to compare strategies meaningfully and combine signals from multiple instances.

Instance isolation — each Detector instance runs its own rule evaluation loop. An error in one rule of one instance doesn't affect other instances or other rules in the same instance.

Zero-overhead configuration — the config object is plain TypeScript. It's statically typed, autocompleted in your IDE, and versioned in git like any other code.

Multiple Instances, Multiple Strategies

You can run as many Detector instances as you want simultaneously. This is useful for:

• Regime detection: one instance looks for trend-following setups, another for mean-reversion
• Multi-symbol coverage: different instances watch different assets
• A/B testing: compare rule sets with different weights on the same symbol

Each instance produces independent signals that Advisor can synthesize together or Inspector can gate separately.

Observability Built In

Every signal generated by the rule engine includes a full audit record:

• Which rules were evaluated
• Which rules fired and which didn't
• The weight contribution of each fired rule
• The final score and whether it crossed threshold
• The timestamp of each evaluation

Studio surfaces this data in a signal timeline view, making it immediately clear why a signal was generated at a specific candle and what would have needed to change for it to fire earlier or not at all.

How Rule Engine Output Feeds the AI Pipeline

The signal events emitted by the rule engine include a full attribution record: which rules fired, which didn't, and the weight contribution of each. This attribution is passed forward to Advisor as part of the signal context.

Advisor uses this attribution in Stage 3 of its pipeline (independent signal evaluation) and in Stage 6 (LLM synthesis). The LLM receives the rule attribution alongside market context and conviction scores — giving it a clear, structured basis for its reasoning rather than raw indicator values.

The result: the quality of your rule definitions directly influences the quality of the AI's reasoning. A well-attributed signal produces a more grounded AI decision.

Getting Started with the Rule Engine

The Detector API reference has the complete configuration schema. The Detector installation guide walks through setting up your first instance.

For a production-ready example configuration, see the advisor-llm-hybrid instance in the repository — it demonstrates combining order flow rules, trend rules, and LLM-augmented scoring in a single Detector config, with full signal attribution flowing through to Advisor.