8000 GitHub - yzhou86/CauseFlow: CauseFlow is a realtime causal intelligence platform for telemetry-driven remediation. · GitHub
[go: up one dir, main page]

Skip to content
yzhou86Public

About

CauseFlow is a realtime causal intelligence platform for telemetry-driven remediation.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

CauseFlow

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.

Overview

CauseFlow is organized as a three-layer system:

  1. causeflow-flink/ for stream-side log refinement and context compression.
  2. causeflow-agent/ for causal SQL compilation, guardrails, and remediation orchestration.
  3. 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

System Architecture

CauseFlow follows a staged data-to-decision pipeline:

  1. Raw events enter Kafka.
  2. Flink filters low-value noise, normalizes repeated text, and summarizes anomalies.
  3. A compact causal context is emitted for query-time evaluation.
  4. The agent compiles that context into causal SQL.
  5. StarRocks evaluates candidate actions and produces deterministic findings.
  6. Guardrails approve or reject remediation before execution.
  7. The portal renders the full timeline and exposes an OpenAI-compatible API.

Component Roles

Stream refinement layer

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

Reasoning and guardrail layer

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

Portal layer

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

Portal Capabilities

OpenAI-compatible API

  • GET /v1/models
  • POST /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

Live demo experience

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

Repository Layout

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

Quick Start

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 8000

Open:

  • http://127.0.0.1:8000/
  • http://127.0.0.1:8000/v1/models

Environment Variables

Portal configuration:

  • PORT - HTTP port, default 8000
  • HOST - bind host, default 127.0.0.1
  • OPENAI_BASE_URL - upstream OpenAI-compatible endpoint, optional
  • OPENAI_API_KEY - upstream API key, optional
  • OPENAI_MODEL - model name used by the portal, default causeflow-demo

If OPENAI_BASE_URL is unset, the portal uses a deterministic local responder so the demo remains fully runnable.

Demo Flow

The live demo follows the same control path as the architecture:

  1. ingest a synthetic incident
  2. compress it into structured context
  3. generate the causal SQL view
  4. request an LLM recommendation
  5. apply hard guardrails
  6. surface the final remediation decision

Each step is streamed to the UI in real time.

Current Status

  • 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.

Roadmap

  1. Wire causeflow-portal to the agent service over an internal API instead of the local demo engine.
  2. Replace the local reasoning fallback with a production GPT-backed path.
  3. Connect the demo to persisted action history and live telemetry.
  4. Add role-based access control and audit logging for operator actions.

About

CauseFlow is a realtime causal intelligence platform for telemetry-driven remediation.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0