kkjiangk / agent-py

# Agent Py
A personal engineering project for investigating alerts with tool-backed evidence, retrieving runbooks, and reviewing remediation proposals. Built with **Python, FastAPI, Vue 3, LangGraph, Kafka, Redis, SQLite, and Milvus**.
The backend coordinates persistent work, enforces user ownership, and streams progress to the browser. It uses actual configured MCP tools and model providers for diagnosis. The current UI is Chinese; repository documentation is English.
## Features
- **Authentication and ownership:** Argon2 password hashes, hashed bearer tokens, logout revocation, and user-scoped repositories and vector queries.
- **Streaming chat:** persistent conversations, LangChain agents, knowledge/MCP tools, configurable prompts, progressively loaded skills, and session memory.
- **Hybrid retrieval:** Markdown/PDF ingestion, durable indexing, Milvus vector recall, BM25L lexical recall, reciprocal rank fusion, and reranking with traceable citations.
- **Incident diagnosis:** a LangGraph Plan-Execute-Replan workflow, active Prometheus/Alertmanager alerts, evidence-linked reports, and persisted SSE events that survive browser disconnection.
- **Reliable event delivery:** manually committed Kafka offsets, retries before advancing to another record, Redis lease ownership checks, and sanitized dead letters.
- **Remediation approval:** an approval and dispatch job committed in one SQLite transaction, atomic dispatch leases, restart recovery, and a stable `commandId` for downstream deduplication.
- **Release and verification:** API/worker ECS revision checks and rollback tooling, real Kafka/Redis integration tests, Playwright browser tests, and public-only frontend configuration.
## Architecture
 [code] 
See Architecture and Engineering decisions for failure semantics, caching, and storage boundaries.
## Local development
Requirements: **Python 3.10+**, **uv**, **Node.js 22+**, **Docker Compose**, access to the configured Qwen-compatible model service, and Tencent CLS credentials when using the CLS integration.
From the repository root:
 [code] 
Edit the two local JSON files before starting. Set the model API key, chat/embedding model names, model capability profile, and required CLS fields. `config/user.project.json` overrides the base configuration. Both files are Git-ignored; checked-in templates contain empty credential values.
 [code] 
Windows Command Prompt:
 [code] 
The launcher starts the CLS MCP Server, FastAPI, event worker, and frontend. Docker Compose provides Kafka, Redis, etcd, MinIO, Milvus, Attu, and Alertmanager. It also applies Alembic migrations. Use Getting started for manual startup and Configuration for field requirements.
| Service | Local address |
| --- | --- |
| Frontend | `http://127.0.0.1:5173` |
| API / OpenAPI | `http://127.0.0.1:8000` / `http://127.0.0.1:8000/docs` |
| CLS MCP SSE | `http://127.0.0.1:3000/sse` |
| Kafka / Redis | `127.0.0.1:9092` / `127.0.0.1:6379` |
| Milvus / Attu | `127.0.0.1:19530` / `http://127.0.