Inferred FSM Discovery

PyStator can infer candidate state-machine transitions from observed entity state sequences.

This feature is designed to remain stateless-core first:

• discovery data is ingested and persisted separately,
• inferred candidates compile to normal FSM configs,
• runtime transition decisions still use the active machine,
• inferred machines are compared in shadow mode only (no enforcement).

To automatically classify raw data records into states before feeding them to discovery, see the Classification guide.

Architecture

flowchart LR
  obs[ObservedStateEvents] --> ingest[DiscoveryIngestion]
  ingest --> obsStore[ObservationStore]
  obsStore --> infer[InferenceEngine]
  infer --> edgeStore[InferenceStore]
  infer --> candStore[CandidateStore]
  candStore --> shadow[ShadowComparison]
  shadow --> api[ProcessEntityAPIs]

Config

Use environment variables or pystator.cfg [discovery]:

• PYSTATOR_DISCOVERY_BACKEND
• PYSTATOR_DISCOVERY_DATABASE_URL
• PYSTATOR_DISCOVERY_SHADOW_ENABLED
• PYSTATOR_DISCOVERY_MIN_EDGE_COUNT
• PYSTATOR_DISCOVERY_MIN_CONFIDENCE

Env values override pystator.cfg.

API endpoints

• POST /api/v1/discovery/observations — append an observed state event
• POST /api/v1/discovery/candidates/build — infer and persist candidate machine
• GET /api/v1/discovery/candidates/{machine_name}/latest — latest candidate
• GET /api/v1/discovery/shadow/{machine_name} — recent shadow diffs

Settings endpoints:

• GET /api/v1/settings/discovery-config
• POST /api/v1/settings/test-discovery-database

Operational workflow

1. Ingest observed states for entity streams (manually or via classification).
2. Build candidate machine versions from inferred edges.
3. Keep active machine authoritative.
4. Compare active vs candidate outcomes via shadow diffs.
5. Promote candidates manually in future enforcement phases.

See also

• Classification — Classify raw data records into states using declarative when rules, then feed into discovery automatically.
• Worker — Process events through a concurrent, durable queue.
• State Stores — Where entity and discovery data is persisted.