Weather Agent

天气人工智能代理服务

      ](./CHANGELOG.md)

                      

用于天气预报智能的生产级AI代理： 基于LangChain 1.0、LangGraph 1.0、FastAPI和OpenAI构建。具有15个代理多代理编排、自动路由（基于意图的查询分类）、7层内存架构、高级推理（树/思维图）、情绪智能、， 两层语义缓存 （成本降低40-60%）、多层缓存（L1+L2+L3+语义）、普罗米修斯指标和可观察性、通过双MCP服务器的实时天气数据、RAG增强的知识库、思维链推理、循环中的人（HITL）审批工作流程、具有宪法护栏的自进化人工智能、全面的黄金数据集评估（185个测试用例，零安全违规）和两层语义缓存-LLM resposne和工具缓存。

从零到生产： 渐进式实施展示了企业AI模式，包括多代理编排（3→8→15个代理）、自动路由架构、7层存储系统（99.7%的存储减少）、上下文窗口优化（对于\环境变量（.env）>代码默认值

3.安装所有依赖项

这创造了 .venv/ 并安装了121个软件包（包括开发工具）：

make install-dev

或者：

make sync

4.运行验证

运行9个自动检查：

make verify

预期产量： ALL 9 CHECKS PASSED!

5.（可选）手动激活虚拟环境

注： uv run 和 make 命令无需激活即可工作。

source .venv/bin/activate

6.检查已安装的版本

make version

选项2：手动设置（无Makefile）

1.克隆存储库

git clone https://github.com/kumaran-is/weather-agent.git
cd weather-agent

2.配置环境

cp .env.template .env

编辑 .env 并添加您的API密钥和MCP服务器路径（有关详细信息，请参见选项1）。

3.安装所有依赖项

创建 .venv/ 自动：

uv sync

4.运行验证

跑 8 自动检查：

uv run python verify_setup.py

预期产量： ALL 9 CHECKS PASSED!

5.（可选）手动激活venv

source .venv/bin/activate

6.检查版本

uv pip list | grep -E "langchain|langgraph|fastapi"

备注:

• uv 自动创建和管理 .venv/ 虚拟环境
• 命令如下 uv run 和 make 无需手动激活venv即可工作
• 手动激活(source .venv/bin/activate)仅适用于直接的Python命令

常见Makefile命令

开发与测试 （渐进式构建方法）

渐进式建设理念: make test-dev 自动测试当前级别的所有已实现功能，而无需在级别中进行Makefile更新。

Docker命令（4个服务：天气mcp:8080，飓风mcp:8081，qdrant:6333，天气ai api:8000）

生产模式 （建议用于测试生产版本）：

开发模式 （建议使用热重新加载进行编码）：

生产与发展：

典型工作流程：

开发工作流程（推荐-渐进式构建）：

# 1. Start in dev mode with hot reload
make docker-up-dev

# 2. Load RAG knowledge base (one-time setup)
make rag-load

# 3. Run unified test suite (tests ALL current features: Level 1+2+3)
make test-dev

# 4. Edit code in ./backend (changes reflect immediately)

# 5. View logs
make docker-logs-dev

# 6. Stop when done
make docker-down-dev

生产工作流程：

# Start all services
make docker-up

# Check status
make docker-ps
make docker-health

# Debug issues
make docker-logs

# Stop all services
make docker-down

RAG命令（第2级：Qdrant矢量数据库）

数据集指南：参见 RAG数据集指南 有关模拟数据源、Kaggle数据集（290多万条记录）、下载说明和数据集统计的完整详细信息。

典型的RAG工作流程：

# 1. Validate datasets
make rag-validate

# 2. Load knowledge base (one-time setup)
make rag-load

# 3. Test retrieval (verify 603 documents loaded)
make rag-test

⚠️ 重要提示：Qdrant数据持久性

您的嵌入式文档（603个块）存储在 Docker命名卷 并在容器重新启动时保持不变：

在以下情况下，数据会被保存：

• ✅ make docker-restart / make docker-restart-dev -重启安全
• ✅ make docker-down / make docker-down-dev -可以安全地停止集装箱
• ✅ make docker-up / make docker-up-dev -数据自动重新加载

在以下情况下，数据将被删除：

• ❌ make docker-clean / make docker-clean-dev -删除卷（5秒警告）
• ❌ docker-compose down -v -The -v 标志删除卷

验证重新启动后数据是否仍然存在：

# Check document count
make rag-test

# Restart Qdrant
make docker-restart

# Check again - same 603 documents!
make rag-test

何时跑步 make rag-load 再一次：

1. 之后 make docker-clean （已删除卷）
2. 向添加新文档时 backend/data/raw/
3. 在生产和开发（不同卷）之间切换时

注： 生产和开发使用单独的卷(weather-ai-qdrant-data 对比 weather-ai-qdrant-data-dev)，因此您可能需要为每个环境分别加载数据。

Docker故障排除

常见的Docker构建错误：

# Error: "parent snapshot does not exist: not found"
# Cause: Docker BuildKit cache corruption (common after Docker restarts/updates)
# Fix:
docker builder prune -f
make docker-rebuild-dev

# If still failing, full cleanup:
docker system prune -a --volumes -f
make docker-rebuild-dev

内存命令（级别3a+：Redis+Neo4j）

典型内存工作流程：

# 1. Start development containers
make docker-up-dev

# 2. Check all services are running
make docker-ps-dev

# 3. Verify health
make docker-health

# 4. Test memory connectivity
make memory-test

# 5. Explore Redis data (interactive CLI)
make memory-redis-cli

# 6. Open Neo4j Browser (graph visualization)
make memory-neo4j-browser

# 7. Stop when done
make docker-down-dev

可观测性命令（8级：普罗米修斯+格拉法纳+洛基+天波）

典型的可观察性工作流程：

# 1. Start dev containers (includes observability stack + Tempo)
make docker-up-dev

# 2. Check observability status (includes Tempo)
make observability-status

# 3. Verify signal correlation (Level 8)
make verify-signal-correlation

# 4. Open Grafana dashboards (Signal Correlation dashboard)
make grafana-open
# Login: admin / weatherai2025

# 5. View Prometheus metrics (with exemplars)
make prometheus-open

# 6. Query logs via Loki (in Grafana) - click trace_id to jump to Tempo
make loki-logs

评估命令（5b级+6级：黄金数据集测试和质量门）

所有8个评估命令均已验证并正常工作：

质量门 （5个门，所有门都必须通过才能部署）：

典型评估工作流程：

# Quick smoke test (recommended first)
make eval-quick

# Test specific category
make eval-category CATEGORY=hurricane

# Full evaluation pipeline (all 185 cases)
make eval-full

# View results in LangSmith
# https://smith.langchain.com/datasets

质量门指南：参见 文档/知识库/质量标准指南.md 了解质量门是什么、它们是如何工作的，以及当它们失败时该怎么办的全面细节。

项目结构

weather-agent/
├── backend/                     # Backend application (Level 8 Complete)
│   ├── config/                  # Configuration (SINGLE LOCATION)
│   │   ├── settings.py          # Centralized app settings (50+ env vars)
│   │   ├── llm_config.py        # LLM use case configuration
│   │   ├── memory_config.py     # Memory system configuration
│   │   ├── cache_config.py      # Cache system configuration
│   │   └── tool_registry_config.py  # Tool Registry configuration (Level 7)
│   ├── data/raw/                # RAG knowledge base (603 documents)
│   ├── migrations/              # Database migration scripts
│   ├── src/                     # Source code
│   │   ├── agents/              # 15 specialized agents (weather, triage, hurricane, etc.)
│   │   ├── api/main.py          # FastAPI app (13 endpoints + Prometheus metrics)
│   │   ├── cache/               # Multi-layer + Semantic Caching (Level 9)
│   │   │   ├── l1_memory_cache.py        # L1 in-process LRU (<1ms, life-safety bypass)
│   │   │   ├── l2_redis_cache.py         # L2 Redis distributed (<10ms, life-safety bypass)
│   │   │   ├── l3_anthropic_cache.py     # L3 Anthropic prompt cache (transparent)
│   │   │   ├── query_normalizer.py       # Query normalization (aliases, case, whitespace)
│   │   │   ├── semantic_matcher.py       # Semantic similarity matching (Qdrant)
│   │   │   ├── two_tier_cache.py         # Two-tier architecture (exact + semantic)
│   │   │   ├── tool_cache.py             # Tool result caching with bypass
│   │   │   └── llm_cache.py              # LLM response caching
│   │   ├── context/             # Context Window Optimization (Level 8)
│   │   │   ├── context_optimizer.py      # 5-phase optimization pipeline (50-60% reduction)
│   │   │   ├── query_type_detector.py    # Auto-classification (EMERGENCY/COMPLEX/SIMPLE)
│   │   │   ├── semantic_chunker.py       # Semantic text chunking
│   │   │   ├── relevance_filter.py       # Relevance-based filtering
│   │   │   ├── dynamic_assembler.py      # Dynamic context assembly
│   │   │   └── hierarchical_loader.py    # Hierarchical context loading
│   │   ├── evaluation/          # Evaluation framework
│   │   ├── guardrails/          # 12-layer safety guardrails
│   │   ├── hitl/                # Human-in-the-Loop approval nodes
│   │   ├── mcp/                 # MCP client integration
│   │   ├── memory/              # 7-layer memory system
│   │   ├── models/              # Pydantic models (weather, hurricane, health, tool_registry)
│   │   ├── observability/       # Full Observability Stack (Level 8 + Level 9)
│   │   │   ├── callbacks.py             # LangSmith tracing callbacks
│   │   │   ├── logging.py               # Structured JSON logging with trace context
│   │   │   ├── metrics.py               # Prometheus metrics (context optimization + LLM)
│   │   │   ├── cache_metrics.py         # Cache metrics (Level 9: hit/miss/latency/similarity/cost)
│   │   │   └── tracing.py               # OpenTelemetry tracing integration
│   │   ├── orchestration/       # Multi-agent workflow orchestration
│   │   ├── rag/                 # RAG pipeline (embeddings, hybrid search)
│   │   ├── reasoning/           # ToT/GoT advanced reasoning
│   │   ├── registry/            # Tool Registry & Semantic Discovery (Level 7)
│   │   │   ├── tool_registry.py         # Thread-safe singleton registry
│   │   │   └── semantic_discovery.py    # AI-powered tool discovery
│   │   ├── routing/             # Auto-routing system
│   │   ├── services/            # Shared business logic services
│   │   ├── tools/               # LangChain tools (MCP + RAG + Hurricane)
│   │   │   ├── weather_tools.py         # Weather MCP tool wrappers
│   │   │   ├── rag_tools.py             # RAG retrieval tools
│   │   │   └── hurricane_tools.py       # Hurricane MCP tool wrappers (Level 7)
│   │   ├── utils/               # Utility functions and helpers
│   │   └── workflows/           # LangGraph workflows
│   └── tests/                   # Backend-specific tests
├── docs/                        # Documentation
│   ├── setup/                   # Setup and configuration guides
│   ├── test-guide/              # Test guides by level (9 guides)
├── observability/               # Observability stack configuration (Level 8)
│   ├── grafana/                 # Grafana dashboards and datasources (signal correlation)
│   ├── loki/                    # Loki log aggregation config
│   ├── prometheus/              # Prometheus metrics config (exemplar storage)
│   └── tempo/                   # Tempo distributed tracing config (Level 8)
├── scripts/                     # Evaluation and automation scripts
├── tests/                       # Test suite (27 test files)
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── .env.template                # Environment variables template
├── CHANGELOG.md                 # Version history and release notes
├── Dockerfile                   # Multi-stage production container
├── docker-compose.yml           # Production orchestration (9 services)
├── docker-compose.dev.yml       # Development orchestration (hot reload)
├── langgraph.json               # LangGraph Studio (4 graphs)
├── LICENSE                      # MIT License
├── Makefile                     # Development and deployment commands
├── pyproject.toml               # Project config (v1.7.0)
└── README.md                    # This file

关键目录:

• 后端/src/代理/15名气象情报专业人员（主管、分诊、飓风、紧急情况、预报员、气候、历史、研究、个性化、元提示、批评、辩论、反思、自我修复、警报管理）
• 后端/src/cache/：L1（进程内）、L2（Redis）、L3（Anthropic）缓存
• backend/src/context/：上下文窗口优化（8级）-5阶段管道实现50-60%的令牌减少
• 后端/src/内存/：7层记忆（对话、会话、情景、语义、程序、情感、反思）
• 后端/src/可观察性/：完整可观察性堆栈（级别8）-跟踪、结构化JSON日志记录、度量、警报
• 后端/src/注册表/：工具注册表和语义发现（第7级）-线程安全的单例、人工智能驱动的搜索
• 后端/src/编排/：多代理工作流（监督、并行执行、自动路由）
• backend/src/评估/：4支柱评估框架（有效性、效率、稳健性、安全性）
• backend/src/tools/：LangChain工具包装（天气MCP、飓风MCP、RAG检索）
• 文档/测试指南/：9个测试指南（L0-L8，8级18个场景）
• 可观测性/：普罗米修斯、格拉法纳、洛基、Tempo配置（8级信号相关性）
• 脚本/：评估自动化（质量门、批量评估、数据集上传）
• 测试/：27个测试文件（单元+集成，包括2个新的8级测试文件）

渐进式学习路径

• 级别0 （v0.1.0）：设置✅ 完成
• 级别1 （v0.2.0-v0.2.1）：重演+HITL+LangSmith工作室✅ 完成
• 2级 （v0.3.0）：重组+CoT+RAG+混合搜索（语义+关键字）✅ 完成
• 3a级 （v0.4.0）：2层内存（对话+会话）✅ 完成
• 3b级 （v0.5.0）：高级推理（思想树+思想图）✅ 完成
• 3c级 （v0.6.0）：全7层记忆+情商+个性化✅ 完成
• 级别4 （v0.7.0）：多代理编排+自动路由✅ 完成

- Auto Routing v0.6.0：基于意图的查询分类（\<1ms）✅ 完成 - 4a级：3-Agent基础（分诊+专家+警报）✅ 完成 - 4b级：8-代理编排（+主管+并行）✅ 完成 - 4c级：15个代理制作（+元提示+辩论+自愈+断路器）✅ 完成

• 5a级 （v0.8.0）：多层缓存（L1+L2+L3）✅ 完成
• 5b级 （v0.9.0）：评估框架+12层护栏✅ 完成
• 5c级 （v0.10.0）：满负荷生产+可观测堆栈✅ 完成
• 第6级 （v1.3.0）：自我进化的人工智能平台✅ 完成

- 6a级：上下文优化+Ragas/DeepEval评估✅ 完成 - 6b级：TruLens+AgentBench+自动提示工程✅ 完成 - 6c级：宪法AI+生产测试基础设施✅ 完成

• 级别7 （v1.5.0）：LangGraph大工具注册表和语义发现✅ 完成
• 级别8 （v1.6.0）：上下文窗口优化和全观察性堆栈✅ 完成

- 8a级：查询类型检测+5阶段优化流水线✅ 完成 - 级别8b：开放遥测跟踪+结构化JSON日志记录✅ 完成 - 8c级：普罗米修斯指标+Grafana仪表板+警报规则✅ 完成 - 测试覆盖率：114/114个测试通过（18个场景）✅ 完成

• 第9级 （v1.7.0）：两层语义缓存架构✅ 完成

- 级别9a：二层缓存基类+查询规范化器+语义匹配器✅ 完成 - 9b级：具有生命安全旁路的工具结果缓存✅ 完成 - 9c级：LLM响应缓存+普罗米修斯指标✅ 完成

• 等级10：自进化代理架构：基于现实世界性能不断学习、适应和改进的自进化代理系统。 🔜 下一个
• 级别11：高级HITL🔜 未来

当前状态：级别9（v1.7.0）-两层语义缓存架构（100%符合LangChain v1.x/LangGraph v1.x）|使用 make test-dev

API端点参考

所有REST端点（共13个）：

接入点:

• Swagger 用户界面: http://localhost:8000/docs（37个示例场景的交互式测试）
• ReDoc: http://localhost:8000/redoc（API综合文档）
• 普罗米修斯指标: http://localhost:8000/metrics（纯文本格式）

示例用法:

# Simple weather query
curl -X POST "http://localhost:8000/weather/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the weather in Miami?", "user_id": "test_001"}'

# Hurricane query (triggers multi-agent routing)
curl -X POST "http://localhost:8000/weather/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the status of Hurricane Milton?", "user_id": "test_002"}'

# Emergency evacuation query (triggers l4b orchestration)
curl -X POST "http://localhost:8000/weather/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "Should I evacuate from Tampa Beach?", "user_id": "test_003"}'

# Create Category 4 hurricane alert (requires HITL approval)
curl -X POST "http://localhost:8000/weather/hurricane/alert" \
  -H "Content-Type: application/json" \
  -d '{"category": 4, "message": "Cat 4 Hurricane approaching Tampa", "thread_id": "alert-001"}'

# Approve pending alert
curl -X POST "http://localhost:8000/weather/hurricane/approve/alert-001" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "reviewer_notes": "Verified with NHC"}'

# Health check
curl http://localhost:8000/health

# Context optimization health metrics (Level 8)
curl http://localhost:8000/health/context

# Tool Registry health check (Level 7)
curl http://localhost:8000/health/tools

# MCP server health check
curl http://localhost:8000/mcp/health

# Cache statistics
curl http://localhost:8000/cache/stats

# List all registered tools (Level 7)
curl http://localhost:8000/tools/list

# Prometheus metrics (includes Level 8 context optimization metrics)
curl http://localhost:8000/metrics

LangGraph Studio图形 （4个图形用于可视化调试）：

• weather_agent：采用RAG+CoT的统一代理
• weather_hitl_workflow：飓风警报HITL审批工作流程
• multi_agent_workflow：4a级3代理编排
• level4b_workflow：4b级8代理并行执行

______________________________________________________________________

测试（渐进式构建方法）

当前测试覆盖率：49个测试文件+185个黄金数据集测试用例+9级语义缓存集成测试，涵盖所有级别（L1-L9）

统一测试指挥部 （推荐）：

# Test ALL implemented features (Level 1-9: 49 unit tests + 185 golden dataset cases + semantic caching tests)
make test-dev

这个命令：

1. ✅ 重启开发环境（10个Docker服务，干净状态）
2. ✅ 运行完整的单元测试套件（各级49个测试）

- 级别1 （7次测试）：ReAct Agent、HITL、MCP集成 - 2级 （4个测试）：RAG、CoT、混合搜索 - 级别3 （15个测试）：7层内存、ToT/GoT推理、3层缓存（L1+L2+L3） - 级别4 （20个测试）：15个代理多代理编排、监督、并行执行 - 五级 （3项测试）：生产API、护栏、评估框架 - 第9级 （5个测试）：语义缓存（查询规范化、语义匹配、生命安全旁路、指标导出）

1. ✅ 验证LangChain v1.x合规性（100%必需，零弃用导入）

黄金数据集评估 （第6级）：

# Run comprehensive evaluation with 185 test cases
make eval-full  # ~30-35 minutes

# Or test specific categories
make eval-category CATEGORY=simple      # 70 simple queries
make eval-category CATEGORY=hurricane   # 35 safety-critical queries
make eval-category CATEGORY=complex     # 50 multi-location queries
make eval-category CATEGORY=edge        # 30 edge cases

渐进式：随着您构建更多关卡， make test-dev 自动包含新测试，无需更改Makefile！

特定级别测试指南:

• 2级测试指南 -RAG+CoT+混合搜索（6次Swagger测试+6次Studio配置）
• 3级测试指南 -内存+ToT/GoT+多层缓存
• 4级测试指南 -多代理编排（15个专业代理）
• 5级测试指南 -生产部署+可观察性
• 6级测试指南 -高级评估+185个黄金数据集案例
• 7级测试指南 -LangGraph bigtool工具注册表和语义发现
• 8级测试指南 -上下文窗口优化和全观察性堆栈（跟踪、结构化日志记录、度量和警报）
• 9级测试指南 -两层语义缓存（查询/工具/LLM响应缓存、生命安全旁路、普罗米修斯指标）

先决条件： Docker服务正在运行（10个服务处于开发模式）

# Start all services (weather-ai-api, MCP servers, databases, observability)
make docker-up-dev

# Load RAG knowledge base (603 documents)
make rag-load

# Run complete unit test suite (49 tests)
make test-dev

# Run comprehensive golden dataset evaluation (185 cases)
make eval-full

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 提交更改： git commit -m 'Add amazing feature'
4. 推送到分支： git push origin feature/amazing-feature
5. 打开拉取请求

许可证

该项目根据 MIT许可证 -看看 许可证 文件以获取详细信息。

支持

• 问题:
• 讨论:
• 文档：参见 docs/ 目录

专为探索代理人工智能系统的团队而设计

版本: 1.7.0 | 最后更新: 2025-12-17