Documentation
Segment Evaluator & Pattern Miner
Segment Evaluator
The Segment Evaluator is a sidecar service that sits in front of the graph engine's ingest path. It evaluates configurable segment rules in real time on every transaction — automatically assigning entities to segments like "High Velocity", "New Merchant Risk", or "Fraud Ring Adjacent" based on graph signals.
The Segment Evaluator runs as a separate container (
segment-evaluator) in the stack. It connects to the graph engine over gRPC and exposes its own HTTP API on port 8081.How It Works
- You define signals (individual graph metrics — velocity, novelty, fraud proximity) and segments (named groups with threshold rules over signals)
- On every
POST /ingest/evaluatecall, the evaluator ingests the transaction into the graph engine and re-evaluates which segments the entity belongs to - Segment membership is stored as
MEMBER_OFstatic edges to aSegmentnode — queryable via standard Cypher - Segments persist in a sled key-value store at
/data/seg-configand survive restarts - Configuration can be managed via the API or by editing TOML files (seeded on first boot)
Key API Endpoints (port 8081)
| Method | Path | Description |
|---|---|---|
POST | /ingest/evaluate | Ingest a transaction and re-evaluate segments for the entities involved |
GET | /segments | List all defined segments |
GET | /segments/:name/members | List all current members of a segment |
POST | /segments/simulate | Dry-run: evaluate signals for an entity without writing segment membership |
POST | /segments/sweep | Re-evaluate all entities against all segments (useful after rule changes) |
GET | /segments/signals | List all configured signals |
POST | /segments/node/lookup | Look up which segments a specific entity belongs to |
GET/POST/DELETE | /config/signals | Manage signal definitions |
GET/POST/DELETE | /config/segments | Manage segment definitions |
POST | /segments/config/reload | Hot-reload config from TOML files without restarting |
GET | /health | Health check |
Querying Segments via Cypher
Once segments are assigned, you can query them like any other graph relationship:
cypher
// Find all cards in the "High Velocity" segment
MATCH (c:CARD)-[:MEMBER_OF]->(s:Segment)
WHERE s.external_id = "High Velocity"
RETURN c.external_id AS card
LIMIT 100
Pattern Miner
The Pattern Miner is a sidecar service that watches the graph engine's edge stream in real time and builds behavioral transition patterns — sequences of entities a node visited over time. These patterns power next-location prediction, impossible-travel detection, and anomaly scoring.
The Pattern Miner runs as a separate container (
pattern-miner) and exposes its API on port 8082. It subscribes to the graph engine's WatchEdgeUpserts CDC stream over gRPC.How It Works
- You define rules that watch a specific edge type (e.g.,
USES_IP) - For each new edge event, the miner calls
graph.lastNeighborto find the previous entity of that type, then writes a transition edge (e.g.,NEXT_IP) capturing the sequence - Transition contexts accumulate in an in-memory
PatternStoreand are persisted in a sled store at/data/pm-config - The
/patterns/predict/:node_idendpoint returns the most probable next entity based on historical transitions
Key API Endpoints (port 8082)
| Method | Path | Description |
|---|---|---|
GET | /patterns/transitions | List all tracked transition pairs across all rules |
GET | /patterns/predict/:node_id | Predict the most likely next entity for a given node based on historical transitions |
GET | /patterns/path/:node_id | Return the full transition path (sequence of entities) for a node |
GET | /patterns/context/:m1/:m2 | Return the transition context between two specific entities |
GET/POST | /config/rules | List or create pattern rules (which edge type to watch) |
DELETE | /config/rules/:watch_edge | Remove a rule |
GET/POST | /config/settings | Manage global miner settings |
POST | /patterns/config/reload | Hot-reload rules from TOML without restarting |
GET | /health | Health check |
Impossible-Travel Detection Example
bash
# Get the transition path for a card (sequence of IPs it has used)
curl http://localhost:8082/patterns/path/CARD:card-001
# Predict the next likely IP for this card
curl http://localhost:8082/patterns/predict/CARD:card-001