Metadata-Version: 2.3
Name: jude-agent
Version: 0.3.1
Summary: 智能 Agent，支持多渠道对话和 RAG 能力
Keywords: ai,agent,rag,llm,chatbot,langchain,claude,minimax
Author: Jude
License: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Dist: langchain>=1.0.0
Requires-Dist: langchain-community>=0.2.0
Requires-Dist: langchain-chroma>=0.2.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: langchain-ollama>=0.2.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-classic>=0.1.0
Requires-Dist: langchain-experimental>=0.3.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: flask>=3.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: lark-oapi>=1.5.0
Requires-Dist: spacy>=3.8.0
Requires-Dist: nltk>=3.9.3
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: wcwidth>=0.2.13
Requires-Dist: langchain-mcp-adapters>=0.1.0
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0 ; extra == 'dev'
Maintainer: Jude
Maintainer-email: Jude <humanleft.jude@gmail.com>
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/humanleft/jude_agent
Project-URL: Repository, https://github.com/humanleft/jude_agent
Project-URL: Issues, https://github.com/humanleft/jude_agent/issues
Project-URL: Changelog, https://github.com/humanleft/jude_agent/blob/main/CHANGELOG.md
Provides-Extra: dev
Provides-Extra: zh
Description-Content-Type: text/markdown

# Jude Agent

[![Python Version](https://img.shields.io/pypi/pyversions/jude-agent)](https://pypi.org/project/jude-agent/)
[![License](https://img.shields.io/pypi/l/jude-agent)](LICENSE) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
[![CI](https://github.com/humanleft/jude_agent/actions/workflows/ci.yml/badge.svg)](https://github.com/humanleft/jude_agent/actions)
[![Coverage](https://codecov.io/gh/humanleft/jude_agent/branch/main/graph/badge.svg)](https://codecov.io/gh/humanleft/jude_agent)

一个智能 Agent 项目，支持多渠道（CLI、HTTP Gateway、飞书）对话，具备 RAG（检索增强生成）能力。

## 技术栈

- **LLM**: MiniMax Anthropic API (MiniMax-M2.5)
- **Embedding**: Ollama (nomic-embed-text, 本地运行)
- **向量数据库**: Chroma
- **框架**: LangChain v1 (含 Agent 框架 + Middleware 动态工具加载)
- **项目管理/打包**: uv (uv_build 后端)
- **HTTP 框架**: Flask
- **事件系统**: 自研同步事件总线

## 快速开始

### 1. 安装依赖

```bash
# 安装 uv (如果没有)
brew install uv

# 安装项目依赖
uv sync
```

### 2. 配置环境变量

```bash
# 复制配置模板
cp .env.example .env
```

从 [MiniMax 开放平台](https://platform.minimaxi.com/) 获取 API Key 并填入 `.env`。

### 3. 启动 Ollama (Embedding)

```bash
# 启动 Ollama
ollama serve

# 下载 Embedding 模型
ollama pull nomic-embed-text
```

### 4. 初始化并运行

```bash
# 初始化知识库
uv run agent init

# 启动服务
uv run agent gateway

# 或使用 CLI
uv run agent cli
```

## 快速命令

```bash
# 安装项目（推荐）- 自动安装依赖并创建可执行命令
uv pip install -e .

# 或使用 uv run（无需安装）
uv sync

# 启动服务
agent gateway              # 默认端口 8080
agent gateway --port 9000 # 指定端口

# CLI 客户端
agent cli                 # 交互式对话
agent cli ask "问题"      # 单次问答
agent cli --no-rag ask "问题"  # 禁用 RAG

# 飞书通道
agent feishu
```

## 完整命令（无需安装）

```bash
# HTTP 服务
uv run agent gateway              # 默认端口 8080
uv run agent gateway --port 9000 # 指定端口

# CLI 客户端
uv run agent cli                 # 交互式对话
uv run agent cli ask "问题"      # 单次问答
uv run agent cli --no-rag ask "问题"  # 禁用 RAG

# 飞书通道
uv run agent feishu
```

## 文档

- [架构文档](docs/architecture.md) - 系统架构和流程图
- [API 参考](docs/api.md) - 所有 API 端点说明
- [核心概念](docs/concepts.md) - 技术原理和概念解释

## 配置

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ANTHROPIC_API_KEY` | MiniMax API Key | (必填) |
| `ANTHROPIC_BASE_URL` | API 端点 | `https://api.minimaxi.com/anthropic` |
| `LLM_MODEL` | LLM 模型 | `MiniMax-M2.5` |
| `EMBEDDING_MODEL` | Embedding 模型 | `nomic-embed-text` |
| `CHUNK_SIZE` | 文本分块大小 | `500` |
| `TOP_K` | 检索返回数 | `3` |
| `AGENT_MODEL` | Agent 模型 | `MiniMax-M2.5` |
| `AGENT_SERVER_PORT` | 服务端口 | `8080` |

### 记忆配置

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AGENT_MEMORY_MAX_MESSAGES` | 最多保留消息数 | 20 |
| `AGENT_MEMORY_SUMMARY_THRESHOLD` | 触发摘要的消息数 | 10 |

## 测试

```bash
# 运行测试
uv run pytest tests/ -v

# 代码检查
ruff check .
uv run mypy src/
```

## 文件说明

| 目录/文件 | 说明 |
|-----------|------|
| `src/config/` | 统一配置模块 |
| `src/core/` | 核心组件（LLM、Agent、Memory、Middleware） |
| `src/events/` | 事件系统 |
| `src/gateway/` | Flask HTTP 网关 |
| `src/rag/` | RAG 核心模块 |
| `src/agent/` | Agent 模块 |
| `src/agent/tools/` | 工具系统（插件式架构） |
| `data/` | 测试文档目录 |
| `chroma_db/` | 向量数据库 |
| `~/.local/share/jude_agent/plugins/` | 本地插件目录 |
| `docs/` | 详细文档 |

## 动态工具创建

Agent 支持在运行时动态创建新工具：

```bash
# 在 CLI 中告诉 Agent 创建新工具
uv run agent cli
# 然后输入: "请创建一个问候工具，输入名字返回 Hello xxx!"
```

### 工作流程

1. Agent 判断需要新工具
2. 调用 `create_tool` 工具
3. 自动生成 Python 代码并保存到插件目录
4. 代码验证（语法 + 结构）
5. 热加载到当前 Agent 实例
6. 新工具立即可用

### LangChain v1 Middleware 架构

项目使用 LangChain v1 原生支持的 Middleware 架构实现动态工具加载：

```
LLM 调用 ──► DynamicToolMiddleware.wrap_model_call()
                │
                ▼
        获取最新工具列表 ──► 动态更新请求
                │
                ▼
        执行 LLM 调用
                │
                ▼
        wrap_tool_call()（处理动态工具执行）
```

### 内置工具

| 工具 | 功能 |
|------|------|
| `calculator` | 数学计算 |
| `search_documents` | 搜索知识库文档 |
| `create_tool` | 动态创建新工具 |
| `list_plugins` | 列出已安装的插件 |

### 工具配置

编辑 `tools.yaml` 启用/禁用工具：

```yaml
tools:
  calculator: true
  search_documents: true
  create_tool: true
  list_plugins: true
  delete_plugin: false
```
