Nilesh1735/LumanGuide---Onboarding-Illuminated
GitHub: Nilesh1735/LumanGuide---Onboarding-Illuminated
一个企业级 Agentic RAG 系统，通过智能路由、多模态文档摄取和 LLMOps 可观测性，帮助工程团队实现入职引导和内部知识的高效检索与管理。
Stars: 0 | Forks: 0
# LumanGuide - 入职引导，照亮前程
## 概述
LumanGuide 是一个有状态的 Agentic AI 平台，它使用 LangGraph 状态机智能地将查询路由到最合适的数据源——已索引的内部文档（FAISS）、通用的 LLM 知识或实时网络搜索（Tavily）。
与标准的 RAG 实现不同，LumanGuide 具备弹性回退架构（NVIDIA NIM 和 SQLite）、用于 SME 路由的上下文团队导航器、LLMOps 可观测性（LangSmith），以及一个强大的 AppSec 套件，以防止提示词注入和机密泄露。
## 技术栈
| 层级 |
技术 |
| AI & GenAI |
LangChain, LangGraph, Google Gemini, OpenAI API, Tavily, FAISS |
| 后端 |
FastAPI, Pydantic, MongoDB (Motor), SQLite |
| 前端 |
Streamlit, Custom CSS, streamlit-agraph |
| 安全与 LLMOps |
JWT (RBAC), LangSmith, pip-audit, Regex Secret Scanner |
## 企业级架构升级
本仓库包含生产级的企业级架构实现：
1. **LLMOps 可观测性 (`src/core/telemetry.py`)：** LangSmith 集成，带有 `@trace_node` 装饰器，可记录 LangGraph 工作流中每一步的输入、输出和 token 使用情况。
2. **Agentic Slack 工具 (`src/tools/slack_tool.py`)：** 一个 LangChain `BaseTool`，允许 AI agent 实际向 Slack 频道发送消息以通知 SME。
3. **多模态视觉摄取 (`src/rag/multimodal_ingestor.py`)：** 将 PDF 图表转换为图像，并使用 GPT-4o 将其转录为 Markdown。
4. **自动化 RAG 评估 (`tests/eval_pipeline.py`)：** 一个 CI/CD 就绪的脚本，使用 RAGAS 计算 `faithfulness`、`answer_relevancy` 和 `context_precision`。
5. **AppSec 安全套件：**
- **安全标头中间件：** 强制执行 CSP、HSTS、X-Frame-Options。
- **机密扫描器：** 在进行 embedding 之前扫描上传的文档中是否包含 AWS 密钥、JWT 和 Slack token，并将其脱敏为 `[REDACTED_SECRET]`。
- **提示词注入防护栏：** 一个 LangGraph 节点，可阻止越狱尝试，并对 NoSQL/模板注入向量进行清理。
- **RBAC (`src/security/rbac.py`)：** 基于 JWT 的基于角色的访问控制（admin > contributor > viewer）。
## 系统架构
```
┌─────────────────────────────────────────────────────────────────┐
│ User Interface │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ Streamlit Web Application (Custom Theme) │ │
│ • Auth (Login/Signup) • Chat • Document Upload • Team Graph │ │
└───────────────────────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ FastAPI Backend (Async) │
│ ┌────────────────────┐ ┌────────────────────┐ ┌──────────────┐ │
│ │ Security Headers │ │ RBAC (JWT verify) │ │ Rate Limiter │ │
│ └────────────────────┘ └────────────────────┘ └──────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ REST API Endpoints │ │
│ │ POST /api/rag/query • POST /api/rag/documents/upload │ │
│ └─────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ LangGraph Orchestration │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │
│ │Guardrail│ -> │ Classify │ -> │ Router │ -> │ Pipeline │ │
│ └─────────┘ └──────────┘ └─────────┘ └──────────┘ │
└───────────────────────────────────┬─────────────────────────────┘
↓ ↓ ↓
┌─────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Retriever │ │ General LLM │ │ Web Search │
│ (FAISS + Vision│ │ (Gemini/ │ │ (Tavily) │
│ Multimodal) │ │ OpenAI) │ │ │
└─────────────────┘ └──────────────┘ └──────────────────┘
```
## 项目结构
```
LumanGuide/
├── .github/workflows/
│ └── dependency-audit.yml # pip-audit CI/CD integration
├── data/
│ └── team_config.yaml # Contextual Team Navigator SME list
├── src/
│ ├── main.py # FastAPI app entry & middleware setup
│ ├── api/
│ │ ├── routes.py # RAG query, document, and team endpoints
│ │ └── auth.py # Login, Signup, JWT generation
│ ├── core/
│ │ ├── config.py # Settings loader
│ │ ├── logger.py # Logging setup
│ │ └── telemetry.py # LangSmith LLMOps tracing
│ ├── llms/
│ │ ├── openai.py # Primary LLM (Gemini/OpenAI)
│ │ └── router.py # NVIDIA NIM fallback router
│ ├── memory/
│ │ ├── chat_history_mongo.py# MongoDB persistent history
│ │ ├── chat_history_sqlite.py# SQLite persistent fallback
│ │ └── chathistory_in_memory.py
│ ├── ml_pipeline/
│ │ └── intent_classifier.py # BERT + TF + Random Forest router
│ ├── rag/
│ │ ├── graph_builder.py # LangGraph state machine construction
│ │ ├── nodes.py # Graph node implementations
│ │ ├── guardrail_node.py # Prompt injection defense
│ │ ├── multimodal_ingestor.py # GPT-4o Vision PDF processing
│ │ ├── retriever_setup.py # FAISS vector store setup
│ │ ├── document_upload.py # Document processing & secret scanning
│ │ └── reAct_agent.py # ReAct agent setup
│ ├── security/
│ │ ├── headers_middleware.py# CSP, HSTS, X-Frame-Options
│ │ ├── rbac.py # JWT RBAC (admin/contributor/viewer)
│ │ └── secret_scanner.py # Regex secret detection & redaction
│ └── tools/
│ ├── common_tools.py # Shared utilities
│ ├── graph_tools.py # Graph routing logic
│ └── slack_tool.py # Agentic Slack notification tool
├── streamlit_app/
│ ├── Home.py # Authentication and login page
│ ├── pages/
│ │ ├── Chat.py # Chat interface and document upload
│ │ └── Admin_Telemetry.py # LangSmith dashboard embed
│ └── components/
│ └── team_graph.py # 3D interactive team graph (streamlit-agraph)
├── tests/
│ └── eval_pipeline.py # RAGAS automated evaluation script
├── .env.example # Environment variable template
├── requirements.txt # Python dependencies
└── README.md # This file
```
## 快速开始
### 前置条件
- **Python 3.12+**（由于存在 `traceback.py` 的 bug，请勿使用 Python 3.14）
- **Poppler**（用于多模态摄取中的 PDF 图像栅格化）
- API Key：Google Gemini (AI Studio)、OpenAI（用于 Vision）、Tavily（用于搜索）
### 安装
1. **克隆仓库：**
git clone https://github.com/Nilesh1735/LumanGuide.git
cd LumanGuide
2. **创建并激活虚拟环境：**
python -m venv venv
.\venv\Scripts\Activate.ps1
3. **安装依赖项：**
pip install -r requirements.txt
## 环境配置
在项目根目录下创建一个 `.env` 文件。**切勿提交此文件。**
```
# --- 核心 AI 配置 ---
GOOGLE_API_KEY=AIzaSyYOUR_GEMINI_KEY
OPENAI_API_KEY=sk-YOUR_OPENAI_KEY
TAVILY_API_KEY=tvly-YOUR_TAVILY_KEY
# --- LLM Fallback (NVIDIA NIM) ---
NVIDIA_NIM_BASE_URL=http://localhost:8000/v1
NVIDIA_NIM_MODEL=meta-llama/Llama-3-8B-Instruct
# --- 数据库 (MongoDB - 可选) ---
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB_NAME=lumanguide
# --- 安全与 RBAC ---
JWT_SECRET=YOUR_SUPER_SECRET_JWT_KEY_HERE
JWT_ALGORITHM=HS256
LUMANGUIDE_ADMIN_USER=admin
LUMANGUIDE_ADMIN_PASSWORD=ChangeThisPassword123!
# --- LLMOps (LangSmith) ---
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_YOUR_LANGSMITH_KEY
LANGCHAIN_PROJECT=lumanguide
```
## 运行应用
您需要两个终端窗口（均已激活虚拟环境）。
**终端 1：启动 FastAPI 后端**
```
python -m uvicorn src.main:app --reload --port 8000
```
*请等待，直到看到 `INFO: Application startup complete.`*
**终端 2：启动 Streamlit 前端**
```
python -m streamlit run streamlit_app/Home.py
```
*（使用 `python -m streamlit` 可以绕过 Windows 应用程序控制策略对 `.exe` 文件的阻止）。*
在 `http://localhost:8501` 访问该应用程序。
## API Endpoints
### 查询 RAG 系统
```
POST /api/rag/query
Authorization: Bearer
Content-Type: application/json
{
"query": "What is the main topic of the document?",
"session_id": "user_session_123"
}
```
### 上传文档（需要 `contributor` 或 `admin` 角色）
```
POST /api/rag/documents/upload
Authorization: Bearer
X-Description: Engineering Runbook 2024
Form Data:
- file:
```
## 安全与 RBAC
LumanGuide 实施了严格的安全态势：
1. **传输安全：** FastAPI 中间件会注入 `Content-Security-Policy`、`X-Frame-Options: DENY` 和 `Strict-Transport-Security`。
2. **机密扫描：** 在将任何文档分块并嵌入（embedding）到 FAISS 之前，`src/security/secret_scanner.py` 会通过正则表达式扫描文本中的 AWS 密钥、Slack token、JWT 和 PEM 私钥，并将其替换为 `[REDACTED_SECRET]`。
3. **提示词注入防御：** LangGraph 的 `guardrail_node` 会拦截试图覆盖系统提示词的查询（例如，“ignore previous instructions”），并返回 `403 Forbidden`。
4. **基于角色的访问控制：** 基于 JWT 的身份验证。用户会被分配 `admin`、`contributor` 或 `viewer` 角色。文档摄取需要 `contributor` 权限。
## 测试与评估
### 自动化 RAG 评估 (RAGAS)
运行 RAGAS 评估流水线，以在合成的黄金数据集上测试 AI 的准确性、忠实度和上下文精确度。
```
python -m tests.eval_pipeline
```
### 依赖审计
一个 GitHub Actions 工作流（`.github/workflows/dependency-audit.yml`）会在每次推送时运行 `pip-audit`，以确保供应链中不存在已知的高严重性 CVE。
## 与我联系
```
标签：AI安全防护, AV绕过, FastAPI, Kubernetes, LangGraph, LLMOps, RAG系统, 人工智能, 用户模式Hook绕过, 知识管理, 请求拦截, 逆向工具
