使用说明
Governed Data Analyst Agent
Ask data questions in Slack. Get governed, explainable answers.
A reference implementation built with LangGraph, an MCP tool server, OPA, PostgreSQL, and Ollama.
Quick start · Architecture · Tech stack · Documentation
Overview
Business users ask questions with /askdata in Slack. A LangGraph workflow retrieves context, plans a query with a local LLM, and calls governed tools for SQL, document search, metric definitions, and charts. The tool server checks OPA policy before execution and records audit data for review.
Example question:
/askdata What was our customer acquisition cost last month?
Highlights
| Capability | How it works |
|---|---|
| Natural language analysis | Ollama helps classify questions, plan SQL, and compose answers. |
| Governed tools | The tool server implements SQL, document search, metric lookup, and chart tools; the agent currently calls its REST endpoints. |
| Policy checks | OPA evaluates role, table, column, and approval rules before tool execution. |
| Data boundaries | PostgreSQL contains reporting, raw, and internal schemas, with row-level security policies defined for regional data. |
| Evidence and replay | Tool decisions are logged, and the admin UI exposes audit and replay views. |
| Visual answers | Chart requests can produce rendered images for Slack responses. |
Architecture
The deployment contains seven Docker Compose services: Slack app, agent, MCP tool server, OPA, Ollama, PostgreSQL, and admin UI.
- Slack entry:
/askdatareaches the Slack Bolt app, which adds a user role and region before calling the agent’sPOST /askendpoint. - Agent workflow: LangGraph classifies intent, retrieves context, plans SQL, invokes tools, validates results, and composes an answer. Ollama supplies local inference.
- Governed execution: The agent calls the tool server’s REST
/api/*endpoints. MCP handlers are defined, but the/mcpHTTP router is currently commented out. The server consults OPA before running a tool. - Data and operations: The tool server queries PostgreSQL, uses pgvector for document search, and writes audit records. The admin UI reads audit, replay, and approval data.
The image’s Auth & IAM symbol represents identity and role context in the flow; Docker Compose does not define a separate IAM service. See the detailed architecture for the broader design.
[!NOTE] OPA can return
REQUIRE_APPROVAL, but the Slack admin-channel post is currently commented out. The callback updates an existing approval record and does not resume the query.
Quick start
Prerequisites
- Docker with Compose
- Git
- A Slack app with Socket Mode and
/askdataconfigured; see the setup guide
Start the stack
git clone https://github.com/4ymaneBH/Governed-Data-Analyst-Agent-for-slack.git
cd Governed-Data-Analyst-Agent-for-slack
cp .env.example .env
Set SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, and SLACK_APP_TOKEN in .env, then start the services:
docker compose -f infra/docker-compose.yml up -d --build
docker exec analyst-ollama ollama pull llama3.2
docker exec analyst-ollama ollama pull nomic-embed-text
The Compose file requests an NVIDIA GPU for Ollama. If your machine has no NVIDIA GPU, remove the deploy.resources.reservations.devices block from the Ollama service before starting the stack.
| Service | Local address |
|---|---|
| Admin dashboard | localhost:8080 |
| Agent API docs | localhost:8002/docs |
| MCP tool server | localhost:8001/tools |
| OPA health | localhost:8181/health |
Once the Slack app is configured, try /askdata Show me the top 5 customers by revenue. For a Windows setup without Docker, see Run Locally.
Tech stack
Interface: Slack Bolt · Tool integration: REST endpoints and defined MCP handlers · Policy engine: OPA/Rego · Vector search: pgvector · Charts: Altair
Security and governance
| Control | Implementation |
|---|---|
| Role and tool access | RBAC rules in OPA |
| Schema and table access | Table rules in OPA |
| Sensitive columns | Column rules and result masking |
| Regional data | Row policies in PostgreSQL |
| Approval decisions | Approval rules; request delivery and resumption remain incomplete |
| Audit and replay | Records in internal.audit_logs, surfaced by the admin UI |
Role mapping in the Slack service is currently defined in code. Review the threat model before adapting this reference implementation for real data.
Evaluation
The repository includes 50 evaluation questions and unit tests. With the agent running, execute:
python -m pip install httpx
python eval/runner.py
The runner writes eval/report.md. To run the local checks:
ruff check services/ tests/
python -m pytest -q tests/unit
opa test policies/rego/ -v
CI runs these checks, builds the service images, then exercises the REST SQL endpoint against PostgreSQL and OPA. The integration tests in tests/integration/ run when RUN_INTEGRATION=1 and both services are available.
Project layout
| Path | Purpose |
|---|---|
services/slack_app/ |
Slack command and interactive handlers |
services/agent/ |
FastAPI and LangGraph workflow |
services/mcp_server/ |
Governed tools, OPA client, and auditing |
apps/admin-ui/ |
Audit, replay, policy, and approval views |
policies/rego/ |
OPA policy definitions and tests |
infra/ |
Docker Compose and PostgreSQL setup |
eval/ |
Evaluation questions and runner |
Documentation
- Setup and deployment guide
- Run locally on Windows
- Architecture details
- Threat model
- Data dictionary · Metric definitions · Business glossary
Contributing
Issues and pull requests are welcome. Include a focused test when changing policy behavior or tool execution, and describe any impact on access control.
License
No license file is currently included in this repository.
