Behavioral Signal Engine

A minimal, framework-agnostic behavioral pattern detection core (TypeScript).

This repository demonstrates the shape of a deterministic signal engine:

• Rolling window behavioral analysis (24h / 7d / 30d)
• Threshold-based signal triggering
• Cooldown + dedup enforcement
• Detector abstraction
• Runnable demo with an in-memory stats adapter

This is an open-core structural blueprint.
Production DB queries, Nest wiring, proprietary tuning, and product DTOs are intentionally omitted.

---

Architecture (high level)

Events / Aggregates
      |
      v
  Stats Adapter (interface)
      |
      v
Detectors (pure logic)
      |
      v
Cooldown + Dedup Layer
      |
      v
Signal Results (events for downstream insight layer)

Key rule: deterministic core first. Optional AI interpretation lives above this engine.

---

Included detectors

• FrequencySpike24h (example)

---

Run the demo

npm i
npm run demo

---

Run tests

npm test

---

Scaling notes (practical)

• Keep detectors stateless and idempotent.
• Make stats adapters responsible for efficient queries (indexes, window buckets).
• Cooldown/dedup should be backed by a fast store (Redis) in production.
• Prefer scheduled execution (cron) over real-time for cost control.

---

Repo structure

src/
  types.ts
  bucket-keys.ts
  stats/
    activity-stats.interface.ts
    in-memory-activity-stats.ts
  detectors/
    freq-spike-24h.detector.ts
  engine/
    cooldown-store.ts
    signal-engine.ts
  demo/
    sample-events.ts
    run.ts
tests/
  freq-spike-24h.test.ts
  cooldown-dedup.test.ts