adithyavedavyas1999/Sentinel

# Sentinel 🛡 [](https://github.com/adithyavedavyas1999/Sentinel/actions/workflows/ci.yml)   一个本地数据 pipeline，在发生故障时会尝试自我诊断。 Sentinel 会摄取 NYC TLC trip data 和 Open-Meteo 天气数据，通过 DuckDB 中的 bronze/silver/gold 数据仓库进行存储落地，并在上层运行 dbt 模型。当 asset 发生故障或数据质量检查触发警报时，LLM agent 会读取失败 asset 的日志、dbt manifest 以及最近的运行历史记录，然后要么执行小范围的自动修复（auto-remediation），要么提交一份带有建议修复方案的结构化事件（incident）。该 agent 不能在小型白名单（allowlist）之外更改数据仓库的状态。 这个项目的重点不在于数据本身。重点在于故障处理循环（failure-handling loop）：输入结构化日志，输入数据血缘（lineage）和元数据，输出决策，并保留审计追踪（audit trail）。 ## 状态 路线图中的十二周计划已全部落地。端到端流程：混沌注入（chaos injection）→ asset 故障 → 事件记录至 sqlite → agent 通过 LLM 进行诊断 → 针对白名单进行可选的自动修复 → 事件 JSON 写入 MinIO → FastAPI + Streamlit 面板供人类审查和批准。 查看 [docs/roadmap.md](docs/roadmap.md) 了解每周交付的内容，查看 [docs/known-issues.md](docs/known-issues.md) 了解在真实代码库中我会修复的问题，查看 [docs/architecture.md](docs/architecture.md) 了解 ADR。 截图：仍待完成。等录制完演示视频后会更容易处理。 ## 包含内容 - Dagster（assets + sensors）用于编排 - 基于 DuckDB 的 dbt-core 用于数据转换（transforms） - MinIO 用于原始数据落地（landing），Postgres 用于 Dagster 元数据 - Prometheus + Grafana + Loki 用于监控指标和日志 - LiteLLM（默认为 Groq）用于诊断提示（prompt）；可通过环境变量更换 provider - fastembed + Qdrant 用于相似事件检索 - LangGraph 用于 agent 状态机 — 仅用于编排，不包含 LangChain 的 provider 抽象（见 ADR-005） - FastAPI + Streamlit 用于事件面板 ## 快速开始 ``` make setup # uv venv + install cp .env.example .env make up # docker compose up make seed-data # pulls a TLC sample make demo # materializes the pipeline end-to-end ``` Dagster UI: Grafana: MinIO 控制台: Incident API: (Swagger) 事件面板 (Incident dashboard): 如果你不需要完整的 compose 技术栈，可以使用仅限本地的入口： ``` make api # uvicorn on :8000 make dashboard # streamlit on :8501 ``` ## 演示路径 1. `make demo` — 三个月的 bronze 层数据 + dbt build。 2. `sentinel chaos inject tlc_5xx` — 触发一个标志，使得下一次 TLC 物化（materialization）将抛出异常。 3. 在 Dagster 中重新运行该 partition。故障捕获传感器（failure capture sensor）会将事件存储在 sqlite 中。 4. 从 Dagster UI 启用 `diagnostic_agent_sensor`。在大约 30 秒内，agent 会完成诊断，提出 `retry-with-backoff` 建议，清除 chaos 标志，随后事件报告将出现在 `sentinel-incidents/incidents/.json` 中。 5. 打开 Streamlit 面板，点击“Apply”应用 retry-with-backoff（幂等操作 — 与 agent 执行的操作相同）。Pipeline 随即恢复运行。 详细版本请参见 [docs/demo-script.md](docs/demo-script.md)。 ## 文档 - [架构与 ADR](docs/architecture.md) - [路线图](docs/roadmap.md) - [数据模型](docs/data-model.md) - [混沌场景](docs/chaos-scenarios.md) - [演示脚本](docs/demo-script.md) - [已知问题](docs/known-issues.md) ## 仓库布局 - `sentinel/ingest/`: 纯 Python 编写的 TLC + Open-Meteo 抓取器，支持重试 - `sentinel/assets/`: Dagster bronze + interim silver assets - `sentinel/observability/`: Prometheus, Grafana, Loki（指标、日志） - `sentinel/agent/llm.py`: LiteLLM（默认为 Groq）封装诊断提示 - `sentinel/agent/context.py`: dbt manifest + 运行历史记录 + 最近的日志 + 来自 Qdrant 的相似事件，均为可选项 - `sentinel/agent/embeddings.py`: fastembed + Qdrant 用于相似事件检索 - `sentinel/agent/graph.py`: LangGraph 状态机 (classify → gather_context → diagnose → propose_action → format_incident) - `sentinel/agent/remediation/`: 三个白名单操作 (retry-with-backoff, partition-window-slip, coerce-to-string)，每个都包含守卫（guard）/执行（execute）/回滚（rollback） - `sentinel/api/`: 基于事件存储 + 白名单的 FastAPI 服务 - `sentinel/ui/dashboard.py`: Streamlit 事件页面 - `sentinel/chaos/`: 九种故障场景，全部实现端到端打通 - `sentinel/quality/`: sqlite 中的事件存储，供 agent 消费 - `dbt/`: 基于 DuckDB 的 dbt-core ## 为什么会有这个项目 我想要一个项目，其核心在于处理故障路径（failure path），而不是正常路径（happy path）。大多数 pipeline 在一切正常（绿灯）时看起来都一样。它们在出现故障（红灯）时才会体现出差异。 ## 许可证 MIT。

标签：Dagster, dbt, DuckDB, Kubernetes, 数据管道, 数据质量, 版权保护, 自动化运维, 自定义请求头, 软件工程, 逆向工具