CauseFlow is a realtime causal intelligence platform for operational telemetry. It turns high-volume logs, metrics, traces, and action history into compact causal context, then uses that context to drive deterministic analysis, guarded remediation, and operator-visible workflows.
CauseFlow is organized as a three-layer system:
causeflow-flink/for stream-side log refinement and context compression.causeflow-agent/for causal SQL compilation, guardrails, and remediation orchestration.causeflow-portal/for the browser portal, OpenAI-compatible API, and live demo experience.
The design is intentionally production-shaped:
- telemetry is compressed before it reaches any model
- structured context is used instead of raw log sprawl
- candidate actions are evaluated through deterministic query paths
- remediation is gated by hard safety rules
- the portal exposes the full flow through a usable web surface
CauseFlow follows a staged data-to-decision pipeline:
- Raw events enter Kafka.
- Flink filters low-value noise, normalizes repeated text, and summarizes anomalies.
- A compact causal context is emitted for query-time evaluation.
- The agent compiles that context into causal SQL.
- StarRocks evaluates candidate actions and produces deterministic findings.
- Guardrails approve or reject remediation before execution.
- The portal renders the full timeline and exposes an OpenAI-compatible API.
causeflow-flink/ is the first compression stage. It is responsible for:
- structured parsing and filtering
- template normalization for repeated errors
- rolling anomaly summarization
- compact causal event emission
causeflow-agent/ is the action-side control plane. It provides:
- causal SQL compilation
- StarRocks query execution abstraction
- hard-rule guardrails for destructive actions
- remediation execution hooks
causeflow-portal/ is the operator-facing surface. It provides:
- a browser UI for the live causal demo
- an OpenAI-compatible chat API
- WebSocket-based event streaming for the demo timeline
- request/response samples for integration testing
GET /v1/modelsPOST /v1/chat/completions
Supported behavior:
- non-stream chat completions
- streaming chat completions
- proxying to an upstream OpenAI-compatible provider
- deterministic local fallback when no upstream is configured
The homepage presents a synthetic incident walkthrough that:
- generates a telemetry burst
- builds compact causal context
- compiles a causal SQL statement
- requests a remediation summary from the LLM layer
- applies guardrail evaluation
- streams the result into the browser as a live timeline
causeflow-flink/ Java/Flink refinement layer
causeflow-agent/ Python orchestration and guardrails
causeflow-portal/ FastAPI portal, API, and live demo
doc/design.md architecture note and system rationale
Run the portal locally:
cd causeflow-portal
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn causeflow_portal.app:app --host 127.0.0.1 --port 8000Open:
http://127.0.0.1:8000/http://127.0.0.1:8000/v1/models
Portal configuration:
PORT- HTTP port, default8000HOST- bind host, default127.0.0.1OPENAI_BASE_URL- upstream OpenAI-compatible endpoint, optionalOPENAI_API_KEY- upstream API key, optionalOPENAI_MODEL- model name used by the portal, defaultcauseflow-demo
If OPENAI_BASE_URL is unset, the portal uses a deterministic local responder so the demo remains fully runnable.
The live demo follows the same control path as the architecture:
- ingest a synthetic incident
- compress it into structured context
- generate the causal SQL view
- request an LLM recommendation
- apply hard guardrails
- surface the final remediation decision
Each step is streamed to the UI in real time.
- The portal is self-contained and does not require Kafka, Fluss, or StarRocks to start.
- The agent and Flink modules are scaffolded integration points for the production path.
- The LLM gateway is OpenAI-compatible so the portal can target local models, hosted endpoints, or gateway services without code changes.
- Wire
causeflow-portalto the agent service over an internal API instead of the local demo engine. - Replace the local reasoning fallback with a production GPT-backed path.
- Connect the demo to persisted action history and live telemetry.
- Add role-based access control and audit logging for operator actions.