@barfinex/signal-engine

Доменный decision-layer для сигналов Barfinex.

Indicators (math) -> Signal Engine (decision) -> Detector (execution)

Библиотека остаётся чистой:

• без NestJS;
• без IndicatorsService;
• без зависимости от detector implementation.

v2: что доступно

• Core
  • SignalFeatureSet, IntervalSignalScore, AggregateSignalScore
  • SignalRuntimeContext, SignalScorer<TFeatures>
  • SignalPipeline, SignalStage
  • SignalDiagnostics
• Regime
  • MarketRegime
  • RegimeProfile
  • RegimeClassifier
• Volatility
  • VolatilityMetrics
  • VolatilityProfile
  • readVolatility(...)
  • VolatilityStage
• Trend
  • TrendSignalEngine
  • TrendSignalProfile
  • TrendFeatures (типизированный SignalFeatureSet)
• ML
  • MLAdapter, MLInputBuilder, MLOutputParser
  • MLSignalRequest, MLSignalResponse, MLDirection
  • buildSystemInstructions(), strict JSON schema contract
  • HybridPolicy, combineDecisions(...)
• Advisor facade
  • DefaultAdvisorSignalFacade
  • AdvisorSignalFacade contracts for build/parse/combine

Структура

libs/signal-engine/
  src/
    core/
      signal.types.ts
      signal.runtime.ts
      signal.scorer.ts
      signal.pipeline.ts
      signal.diagnostics.ts
    regime/
      regime.types.ts
      regime.profile.ts
      regime.classifier.ts
    volatility/
      volatility.types.ts
      volatility.profile.ts
      volatility.metrics.ts
    trend/
      trend.types.ts
      trend.profile.ts
      trend.engine.ts
      trend.engine.spec.ts
    index.ts

Быстрый пример v2

import {
  DEFAULT_TREND_PROFILE,
  SignalDirection,
  TrendSignalEngine,
} from '@barfinex/signal-engine';
import { TimeFrame } from '@barfinex/types';

const engine = new TrendSignalEngine({
  ...DEFAULT_TREND_PROFILE,
  regime: {
    enabled: true,
  },
  volatility: {
    enabled: true,
    blockHighVol: true,
  },
});

const intervalScore = engine.evaluateInterval(
  {
    interval: TimeFrame.min5,
    price: 102,
    values: {
      smaFast: 100,
      smaMid: 99,
      smaSlow: 97,
      rsi: 58,
      adx: 24,
      macdHistogram: 0.4,
      atrPct: 0.012,
      rangePct: 0.008,
    },
  },
  { barsCount: 180 },
);

const aggregate = engine.aggregate([intervalScore]);

if (aggregate.direction === SignalDirection.Up) {
  // execution в detector слое
}

Pipeline (stages)

import {
  SignalPipeline,
  SignalFeatureSet,
  VolatilityStage,
} from '@barfinex/signal-engine';

const pipeline = new SignalPipeline<SignalFeatureSet>([
  new VolatilityStage(),
]);

const enriched = pipeline.run(featureSet, runtime);
const score = engine.evaluateInterval(enriched, runtime);

Диагностика

На interval и aggregate уровне доступны:

• diagnostics.regime
• diagnostics.volatility (atr, atrPct, rangePct, flags)
• diagnostics.confidence
• diagnostics.notes (explainability reasons)

FollowTrend integration (v2)

FollowTrendService в detector:

• собирает SignalFeatureSet из indicator values;
• прокидывает rangePct и/или atrPct в values;
• вызывает engine.evaluateInterval(...);
• агрегирует через engine.aggregate(...).

Тесты

npm run test -- libs/signal-engine/src/trend/trend.engine.spec.ts

ML/Advisor facade tests:

npx jest "libs/signal-engine/src/ml/ml.adapter.spec.ts" "libs/signal-engine/src/advisor/advisor.facade.spec.ts"

Advisor hybrid integration

signal-engine предоставляет pure layer для apps/advisor:

• build ML request (deterministic payload),
• parse ML response (strict JSON contract),
• merge rule + ml decision (policy-driven).

Важно:

• никаких сетевых вызовов внутри signal-engine;
• никаких секретов/токенов в библиотеке;
• реальные LLM вызовы остаются на стороне apps/advisor/libs/advisor.

Детальный гайд:

• docs/advisor-signal-engine-hybrid-integration.md