Nilesh1735/LumanGuide-Onboarding-Illuminated

# LumanGuide - 入职引导，启明之光 ## 概述 LumanGuide 是一个有状态的 Agentic AI 平台，它使用 LangGraph 状态机将查询智能路由到最合适的数据源——内部索引文档 (FAISS)、通用 LLM 知识或实时网络搜索 (Tavily)。 与标准的 RAG 实现不同，LumanGuide 具备弹性回退架构（NVIDIA NIM 和 SQLite）、用于路由 SME 的情境感知团队导航器、LLMOps 可观测性 (LangSmith)，以及用于防止提示词注入和机密泄露的强大 AppSec 套件。 ## 技术栈 ## 企业架构升级 本仓库包含生产级的企业级架构实现： 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 安全套件：** - **安全标头 Middleware：** 强制执行 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 密钥：Google Gemini (AI Studio)、OpenAI（用于视觉）、Tavily（用于搜索） ### 安装 1. **克隆仓库：** git clone https://github.com/Nilesh1735/LumanGuide---Onboarding-Illuminated.git cd LumanGuide---Onboarding-Illuminated 2. **创建并激活虚拟环境：** python -m venv venv .\venv\Scripts\Activate.ps1 3. **安装依赖项：** pip install -r requirements.txt ## 环境配置 在项目根目录下创建一个 `.env` 文件。**切勿提交此文件。** ``` # --- Core 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 端点 ### 查询 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 middleware 会注入 `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` 会拦截试图覆盖系统提示词的查询（例如：“忽略之前的指令”），并返回 `403 Forbidden`。 4. **基于角色的访问控制：** 基于 JWT 的身份验证。用户会被分配为 `admin`、`contributor` 或 `viewer` 角色。文档摄取需要 `contributor` 权限。 ## 测试与评估 ### 自动化 RAG 评估 (RAGAS) 运行 RAGAS 评估 pipeline，以针对合成的黄金数据集测试 AI 的准确性、忠实度和上下文精度。 ``` python -m tests.eval_pipeline ``` ### 依赖项审计 GitHub Actions 工作流 (`.github/workflows/dependency-audit.yml`) 会在每次推送时运行 `pip-audit`，以确保供应链中不存在已知的高严重性 CVE。 ## 与我联系

```

标签：AI智能体, AV绕过, FastAPI, Kubernetes, LangGraph, LLMOps, Petitpotam, Python, RAG, Ruby, 企业应用安全, 无后门, 知识库, 请求拦截, 逆向工具