Core Concepts

Understanding these building blocks will help you navigate every other part of the documentation.

The core loop

Causeloop is organized around a single closed loop that turns raw failures into verified fixes. Under the hood, “predicts” and “verified” are not figures of speech — they’re a fitted point-process model and a statistical monitor, respectively, and every number either endpoint returns says exactly which run produced it.

Issue

A discrete failure event — an incident, a defect, a failed check. Issues arrive automatically from connected sources or are created directly via the API or UI, and are recorded first as an event in the append-only log.

Pattern

An engine run groups related issues by shared root-cause fingerprint (Leiden partition + deterministic cross-check). A pattern surfaces the recurring failure behind a set of issues rather than treating each one as isolated. Analysts can pin constraints the clustering must honor on every future run.

Prediction

From each pattern’s fitted hazard model, Causeloop forecasts where and when the failure is likely to recur — giving you a window to act before it does. If there isn’t yet enough history to fit, the API says so explicitly rather than guessing.

Recommendation

Causeloop proposes a concrete remediation with a computed business case, then runs verification — a statistical monitor, not a status flag — to prove the pattern’s intensity actually dropped before marking it implemented.

The loop closes when verification confirms the fix held. If new issues matching the pattern appear after a fix, the loop reopens automatically.

Event log & projections

Every mutation in Causeloop starts as an event, not a row update. Ingesting an issue writes an issue.ingested event; editing a field appends field_updated / attr_corrected; pinning, activating a config version, and a fix verifying all append their own event types. The issues, patterns, and other rows you read back over the REST API are projections — rebuilt deterministically from this append-only log, never the source of truth themselves.

Field	Notes
`content_hash`	Hash of the event payload — the basis for proving a replay is byte-identical.
`occurred_at`	When the underlying failure actually happened (drives the hazard model’s point process) — distinct from when it was logged.
`actor`	Who or what produced the event (user, service account, or the engine itself).

Two read surfaces expose the log directly: GET /workspaces/current/events (workspace-wide, cursor-paginated, filterable by type) and GET /issues/{id}/events (one issue’s ordered history). GET /activity remains the human-friendly narrative view of the same underlying events.

Provenance

Every computed number — a hazard forecast, a prediction’s p_recurrence, a recommendation’s ROI, a report’s figures — carries a provenance object:

{
  "run_id": "run_01j...",
  "manifest_hash": "sha256:9c2e...",
  "config_versions": { "hazard": "hz#a91f...", "cluster": "cl#7b02..." }
}

This is not optional metadata; it’s how you trace any number back to exactly which engine run, which snapshot of the event log, and which config version hashes produced it. Two numbers with different provenance are never assumed comparable.

Abstention & the review queue

Classification is allowed to answer “I don’t know.” Extraction and root-cause return a prediction set — a conformal set of candidate values with a guaranteed coverage_level, not a single point guess. A singleton set writes the value straight through (origin: "extracted"); a multi-value or empty set writes null and creates a /review-queue item instead of a low-confidence guess. A human resolution (POST /review-queue/{id}/resolve) appends an event, always wins over the model (origin: "human"), and joins the calibration set that keeps future coverage honest — GET /ai/calibration/{task} tracks empirical coverage against target, and coverage that drifts more than 3 points below target automatically flips the task into abstain-more mode.

Hazard model

Recurrence risk — predictions, time-to-repeat (T̂_R), crest alerts — is not an LLM guess. It’s a fitted point-process model per pattern (powerlaw_nhpp_hawkes_v1): baseline intensity, a power-law aging term, Hawkes self-excitation, covariate priors (verification pending / churn intensity / severity history), and shrinkage for low-count patterns. GET /patterns/{id}/hazard is the canonical resource — forecast per horizon, the time-to-repeat interval, and a crest_alert when accelerating intensity crosses a threshold for consecutive runs. When there isn’t enough history to fit, the endpoint returns 404 not_fitted with a reason (insufficient_events or no_timestamps) instead of a placeholder curve.

Pins

Analysts sometimes know something the graph doesn’t yet — two patterns are really one, or an issue was mis-clustered. Pins (POST /patterns/{id}/pins, actions merge_into / exclude_issue / include_issue / split) are events, and the clustering anchorer honors them as hard constraints on every subsequent run — a pin beats the majority vote. This is the single, auditable replacement for the old link/unlink/merge affordances, which silently fought the engine on the next recompute.

Verification loop

A recommendation isn’t “done” when someone marks it implemented — it’s done when the theme’s failure intensity measurably drops. POST /recommendations/{id}/attest starts monitoring; GET /recommendations/{id}/verification returns a CUSUM (cumulative-sum) statistic tracked against a decision boundary derived from the fix’s own counterfactual target, plus an expected decision window. When the statistic crosses the boundary, a fix.verified (or fix.failed) event fires, updates the theme’s severity input for the next hazard fit, and stamps the recommendation — this endpoint is the product’s proof-of-value artifact, not a checkbox.

Config registry

Everything that used to be a hardcoded constant or a single mutable document is now a versioned, hash-identified config under /configs/{kind} — rubric (criticality scoring), cluster (edge weights, Leiden parameters), hazard (covariate priors, crest thresholds), rate-card (financial modeling inputs), and taxonomy (theme/bone vocabulary). Versions are immutable and content-hashed at creation; activation is a separate, privileged, audited step (POST /configs/{kind}/versions/{v}/activate). Run manifests pin config hashes, not labels, so a run’s inputs are exactly reproducible — and activating a new cluster or hazard version invalidates downstream partitions by design, so the next run must be mode: full.

Tenancy model

Organization

The top-level account — one per client. Carries the plan, seat count, and billing identity. Status: active, suspended, or cancelled.

Workspace

The data boundary owned by an organization. All issues, patterns, connectors, and settings live inside a workspace. One organization typically has one workspace, but the model supports more.

Membership

The link between a user and a workspace. Carries the role that governs what the user can do inside that workspace.

Organization

An organization is the client entity. It owns one or more workspaces and controls plan-level constraints:

Field	Notes
`slug`	URL-safe unique identifier (e.g. `acme`)
`plan`	`free` / `starter` / `growth` / `enterprise`
`seats_total`	Maximum active memberships
`status`	`active` / `suspended` / `cancelled`

Workspace

A workspace is the operational data boundary. Every API call resolves to a single workspace; Row-Level Security (RLS) enforces that no query can read another tenant’s data.

Field	Notes
`slug`	Unique within the organization
`timezone`	Default display timezone for all reports
`sso_enforced`	When true, password login is blocked for the workspace

Each workspace has a companion workspace_settings record controlling AI confidence thresholds, retention policies, and alert sensitivity, and an onboarding_state record that drives the setup wizard.

User

A user is a global identity (unique by email). The external_id field stores the upstream identity provider’s subject ID (WorkOS, or another configured OIDC provider) when the user authenticates through POST /auth/exchange.

Membership

A membership joins a user to a workspace with a role. Roles are cumulative — each role includes all permissions of the roles below it:

Role	Can do
`viewer`	Read issues, patterns, predictions, recommendations, and reports
`analyst`	Everything above, plus create/update issues, link patterns, trigger analysis, create connectors
`admin`	Everything above, plus invite members, manage settings, create alert rules, export data
`owner`	Everything above, plus manage organization settings, billing, and SSO

A user can belong to multiple workspaces with different roles in each.

Product entities

Issue

An issue is a single failure event ingested from a connected source or created manually.

Field	Values
`severity`	`p1` (critical) · `p2` · `p3` · `p4`
`status`	`open` · `in_loop` · `mitigating` · `resolved` · `closed`
`source`	The connector type that originated the issue (e.g. `pagerduty`, `jira`, `github`)
`risk_score`	0–100 composite risk signal

An issue moves through statuses as it is investigated and linked to a pattern. Issues with status in_loop are actively being analyzed as part of a pattern.

Pattern

A pattern groups issues that share the same underlying root cause. Causeloop detects patterns automatically by clustering issues on their fingerprint (signal dimensions such as service, error type, time-of-day, and affected team).

Field	Values
`status`	`emerging` · `active` · `mitigating` · `resolved` — the engine-owned lifecycle state machine
`phase`	`emerging` · `active` · `held` · `broken` — a UI-facing projection of `status` plus one piece of real cross-entity state (an open fix-verification window); never a second source of truth
`risk_score`	0–100 aggregate signal
`confidence`	0.0–1.0 model confidence that the grouping is accurate
`fingerprint`	Key–value map of the shared signal dimensions
`sparkline`	Real per-bucket occurrence-count series over the trailing 30 days; `[]` when the pattern has no dated member issues
`recurrence`	Recurrence probability at a fixed 45-day horizon, derived from the pattern’s stored hazard fit; omitted entirely (not zero) when the pattern isn’t fitted yet

A pattern transitions to resolved when a closure note is recorded and its open member issues stop recurring within the configured proof window.

Cluster

A cluster is a higher-order grouping of patterns that share structural relationships (common services, overlapping time windows, or shared contributing factors). Clusters appear in the pattern graph view and help you see which patterns belong to the same systemic problem. Clusters are a byproduct of the engine’s Leiden partition stage — recomputed on every POST /engine/runs, never via a standalone recompute call. To change membership directly, use a pin rather than editing a cluster.

Prediction

A prediction is a forward-looking risk signal derived from a pattern’s recurrence history.

Field	Notes
`probability`	0.0–1.0 likelihood the pattern recurs within `window_days`
`window_days`	Forecast horizon in days
`impact`	`critical` / `high` / `medium` / `low`
`likely_trigger`	AI-generated description of what will likely cause the next recurrence

The prediction model is evaluated continuously. You can record feedback (hit / miss / prevented) on each prediction to improve accuracy over time.

Recommendation

A recommendation is a ranked, actionable remediation tied to one or more patterns.

Field	Values
`status`	`pending` · `in_progress` · `implemented` · `dismissed`
`effort`	`low` / `medium` / `high`
`impact`	`high` / `medium` / `quick_win`
`rank`	Priority order within the workspace (1 = highest)
`expected_loops_prevented`	Model estimate of recurrences eliminated if this fix holds

Recommendations can be queued for push to your issue tracker (Jira, Linear, GitHub, ServiceNow) via POST /recommendations/{id}/push. This requires a connected connector of that tracker type (409 tracker_not_connected otherwise); Causeloop does not fabricate a ticket ID or URL — a successful push returns external_ref: null until a real tracker integration creates one.

Integration entities

Connector

A connector is a configured integration with an external tool. Connectors pull issue data into Causeloop on a schedule or respond to inbound webhooks. Causeloop supports 70+ connector types organized by category:

Category	Examples
Cloud & Monitoring	Datadog, Dynatrace, New Relic, AWS CloudWatch
Productivity & Incident	PagerDuty, Jira, GitHub, Linear, Opsgenie
CRM & Support	Salesforce, Zendesk, HubSpot
Data	PostgreSQL, Snowflake, BigQuery
Security	Okta, CrowdStrike, Splunk

Each connector has a status (active / paused / error), a configurable poll_interval_seconds, and a sync run history.

Plan and seat concepts

Plan

A plan is the subscription tier of an organization: free, starter, growth, or enterprise. The plan controls feature flags, rate limits, and which connectors are available.

Seat

A seat is one active membership slot. The organization’s seats_total cap limits how many concurrent active memberships a workspace can hold. Suspending a membership frees the seat without deleting the user’s data.

Quick reference

Term	One-line definition
Organization	Top-level client account
Workspace	Data boundary; all product data lives here
User	Global identity (unique email)
Membership	User ↔ Workspace link with a role
Issue	A single failure event
Pattern	A cluster of related issues sharing a root cause
Cluster	A grouping of related patterns
Prediction	A forward-looking recurrence risk signal, derived from a fitted hazard model
Recommendation	A ranked, trackable fix for a pattern with a computed business case
Connector	A configured integration that feeds issues in
Plan	Subscription tier controlling features and limits
Seat	One active membership slot against the org’s cap
Event	An append-only, content-hashed record — the source of truth issues/patterns are projected from
Provenance	`{run_id, manifest_hash, config_versions}` attached to every computed number
Review item	An abstained classification result routed to a human instead of a guess
Hazard model	The fitted point process (`powerlaw_nhpp_hawkes_v1`) behind a pattern’s predictions
Pin	A hard constraint on clustering that survives every future engine run
Verification	CUSUM-based monitoring that proves a fix’s effect before closing the loop
Config version	An immutable, hash-identified control-plane document (`rubric`, `cluster`, `hazard`, `rate-card`, `taxonomy`)

Quickstart

Get from sign-in to your first insights in 10 minutes.

Architecture

Understand how the platform layers fit together.

Overview

Tutorials

The core loop

Event log & projections

Provenance

Abstention & the review queue

Hazard model

Pins

Verification loop

Config registry

Tenancy model

Organization

Workspace

Membership

Organization

Workspace

User

Membership

Product entities

Issue

Pattern

Cluster

Prediction

Recommendation

Integration entities

Connector

Plan and seat concepts

Plan

Seat

Quick reference

Quickstart

Architecture

​The core loop

​Event log & projections

​Provenance

​Abstention & the review queue

​Hazard model

​Pins

​Verification loop

​Config registry

​Tenancy model

Organization

Workspace

Membership

​Organization

​Workspace

​User

​Membership

​Product entities

​Issue

​Pattern

​Cluster

​Prediction

​Recommendation

​Integration entities

​Connector

​Plan and seat concepts

​Plan

​Seat

​Quick reference

Quickstart

Architecture

The core loop

Event log & projections

Provenance

Abstention & the review queue

Hazard model

Pins

Verification loop

Config registry

Tenancy model

Organization

Workspace

User

Membership

Product entities

Issue

Pattern

Cluster

Prediction

Recommendation

Integration entities

Connector

Plan and seat concepts

Plan

Seat

Quick reference