Metadata-Version: 2.4
Name: ai-hello
Version: 0.1.1
Summary: Agent development framework with OpenAI-compatible LLM adapters, tools, memory, and RAG.
Author: AiHello Team
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/zhangman995746185/ai_hello
Project-URL: Repository, https://gitee.com/zhangman995746185/ai_hello
Keywords: agent,llm,rag,openai,langchain,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohappyeyeballs==2.6.1
Requires-Dist: aiohttp==3.13.5
Requires-Dist: aiosignal==1.4.0
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.13.0
Requires-Dist: attrs==26.1.0
Requires-Dist: certifi==2026.4.22
Requires-Dist: cffi==2.0.0
Requires-Dist: charset-normalizer==3.4.7
Requires-Dist: colorama==0.4.6
Requires-Dist: cryptography==47.0.0
Requires-Dist: dashscope==1.25.17
Requires-Dist: dataclasses-json==0.6.7
Requires-Dist: distro==1.9.0
Requires-Dist: frozenlist==1.8.0
Requires-Dist: greenlet==3.4.0
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: httpx-sse==0.4.3
Requires-Dist: idna==3.13
Requires-Dist: jiter==0.14.0
Requires-Dist: jsonpatch==1.33
Requires-Dist: jsonpointer==3.1.1
Requires-Dist: langchain==1.2.15
Requires-Dist: langchain-classic==1.0.4
Requires-Dist: langchain-community==0.4.1
Requires-Dist: langchain-core==1.3.2
Requires-Dist: langchain-protocol==0.0.12
Requires-Dist: langchain-text-splitters==1.1.2
Requires-Dist: langgraph==1.1.9
Requires-Dist: langgraph-checkpoint==4.0.2
Requires-Dist: langgraph-prebuilt==1.0.11
Requires-Dist: langgraph-sdk==0.3.13
Requires-Dist: langsmith==0.7.36
Requires-Dist: marshmallow==3.26.2
Requires-Dist: multidict==6.7.1
Requires-Dist: mypy_extensions==1.1.0
Requires-Dist: numpy==2.4.4
Requires-Dist: openai==2.32.0
Requires-Dist: orjson==3.11.8
Requires-Dist: ormsgpack==1.12.2
Requires-Dist: packaging==26.2
Requires-Dist: propcache==0.4.1
Requires-Dist: pycparser==3.0
Requires-Dist: pydantic==2.13.3
Requires-Dist: pydantic-settings==2.14.0
Requires-Dist: pydantic_core==2.46.3
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: PyYAML==6.0.3
Requires-Dist: regex==2026.4.4
Requires-Dist: requests==2.33.1
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: sniffio==1.3.1
Requires-Dist: SQLAlchemy==2.0.49
Requires-Dist: tavily-python==0.7.23
Requires-Dist: tenacity==9.1.4
Requires-Dist: tiktoken==0.12.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: typing-inspect==0.9.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: typing_extensions==4.15.0
Requires-Dist: urllib3==2.6.3
Requires-Dist: uuid_utils==0.14.1
Requires-Dist: websocket-client==1.9.0
Requires-Dist: xxhash==3.7.0
Requires-Dist: yarl==1.23.0
Requires-Dist: zstandard==0.25.0
Requires-Dist: hello-agents
Requires-Dist: qdrant-client
Requires-Dist: markitdown
Requires-Dist: paramiko
Dynamic: license-file

# AiHello - 智能 Agent 开发框架

## 📖 项目简介

AiHello 是一个基于 OpenAI 兼容接口的通用 Agent 开发框架，面向 Python 应用集成场景，提供模型适配、Agent 基类、记忆系统、RAG 检索、工具注册与协议层能力。

当前项目已经整理为标准 `pip` 包发布形态，默认以库的方式使用，不提供 CLI。

适用场景：

- 智能问答与对话系统
- 知识库检索与 RAG 应用
- 带记忆能力的 Agent
- 需要工具调用的自动化助手

### ✨ 核心特性

- **多模型支持**：兼容 `openai`、`zhipu`、`qwen`、`deepseek`、`ollama`、`vllm` 等 OpenAI 兼容提供方
- **多层次记忆系统**：工作记忆、情景记忆、语义记忆、感知记忆四类记忆管理
- **高级 RAG 引擎**：支持文档导入、分块、向量检索、MQE、HyDE、重排序
- **灵活的工具系统**：原生工具注册机制，支持动态注册与执行
- **协议层能力**：提供 `MCP`、`A2A`、`ANP` 相关实现
- **标准包发布**：支持直接 `pip install ai-hello`

---

## 🏗️ 软件架构

```text
ai_hello/
├── ai_hello/              # 包元数据与运行时路径
├── agent/                 # Agent 核心层
│   ├── agent_base.py      # Agent 基类
│   └── base_type/         # 基础 Agent 类型
│       ├── simple_agent.py
│       ├── react_agent.py
│       ├── reflection_agent.py
│       └── plan_solve_agent.py
├── model/                 # 模型适配层
│   ├── openai_sdk_llm.py  # OpenAI SDK 原生接口
│   └── lanchain_llm.py    # LangChain 适配器
├── memory/                # 记忆与 RAG
│   ├── manager.py         # 记忆统一入口
│   ├── memory_base.py     # 记忆基类与配置
│   ├── types/             # 四类记忆实现
│   ├── rag/               # RAG 管线
│   ├── storage/           # 向量/文档/图存储
│   └── context/           # 上下文加载
├── tools/                 # 工具系统
│   ├── registry.py        # 工具注册表
│   ├── tools_base.py      # 工具基类
│   ├── chain.py           # 工具链
│   └── builtin/           # 内置工具
│       ├── calculator.py
│       ├── context_tool.py
│       ├── memory_tool.py
│       ├── note_tool.py
│       ├── rag_tool.py
│       ├── search.py
│       └── terminal_tool.py
├── protocols/             # 协议层
│   ├── mcp/
│   ├── a2a/
│   └── anp/
├── config/                # 配置管理
└── utils/                 # 消息、日志、辅助函数
```

---

## 🔧 安装教程

### 1. 环境要求

- Python 3.10+
- pip

### 2. 从 PyPI 安装

```bash
pip install ai-hello
```

### 3. 从源码安装

```bash
git clone <repository-url>
cd ai_hello
pip install .
```

开发时建议使用虚拟环境：

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
```

### 4. 可选外部服务

如果你要使用 RAG、向量检索或图存储能力，通常还需要准备：

- Qdrant
- Neo4j

项目根目录保留了 `docker-compose.yml`，可用于本地启动依赖服务。

---

## 📦 pip 包使用方式

AiHello 当前以“整包库发布”的方式提供能力，不带命令行入口。安装后常用导入方式如下：

```python
from model.openai_sdk_llm import AiHelloLLM
from agent.base_type.simple_agent import SimpleAgent
from memory.manager import MemoryManager
from tools.registry import ToolRegistry
from ai_hello import get_data_dir
```

建议最少配置一组 OpenAI 兼容接口环境变量：

```bash
# Windows PowerShell
$env:LLM_API_KEY="your-api-key"
$env:LLM_BASE_URL="https://api.openai.com/v1"
$env:LLM_MODEL_ID="gpt-4o-mini"
```

---

## 🚀 使用说明

### 1. 快速开始 - 使用 AiHelloLLM

```python
from model.openai_sdk_llm import AiHelloLLM

llm = AiHelloLLM(provider="openai")

messages = [
    {"role": "user", "content": "你好，请介绍一下 AiHello。"}
]

response = llm.invoke(messages)
print(response)
```

### 2. 使用 SimpleAgent

```python
from agent.base_type.simple_agent import SimpleAgent
from model.openai_sdk_llm import AiHelloLLM

llm = AiHelloLLM(provider="openai")

agent = SimpleAgent(
    name="assistant",
    llm=llm,
    system_prompt="你是一个简洁、可靠的开发助手。"
)

result = agent.run("解释一下什么是向量检索。")
print(result)
```

### 3. 使用记忆系统

```python
from memory.manager import MemoryManager

memory_manager = MemoryManager(
    user_id="user_001",
    enable_working=True,
    enable_episodic=True,
    enable_semantic=True,
    enable_perceptual=False
)

memory_id = memory_manager.add_memory(
    content="用户偏好简洁的技术说明",
    memory_type="semantic",
    importance=0.8,
    auto_classify=False
)

memories = memory_manager.retrieve_memories(
    query="用户偏好",
    limit=5,
    min_importance=0.5
)

for memory in memories:
    print(f"[{memory.memory_type}] {memory.content}")
```

### 4. 使用 RAG 引擎

```python
from memory.rag.pipeline import load_and_chunk_texts, index_chunks, search_vectors

chunks = load_and_chunk_texts(
    paths=["data/raw_data/document.pdf"],
    chunk_size=800,
    chunk_overlap=100,
    namespace="my_knowledge"
)

index_chunks(chunks=chunks, rag_namespace="my_knowledge")

results = search_vectors(
    query="什么是人工智能？",
    top_k=5,
    rag_namespace="my_knowledge"
)

for result in results:
    print(result["score"])
    print(result["metadata"]["content"][:200])
```

### 5. 使用工具注册表

```python
from tools.registry import ToolRegistry

registry = ToolRegistry()
registry.register_function(
    name="echo",
    description="返回原始输入",
    func=lambda text: f"echo: {text}"
)

print(registry.execute_tool("echo", "hello ai_hello"))
```

---

## 📂 运行时数据目录

安装后的默认数据目录规则如下：

- 设置了 `AI_HELLO_DATA_DIR` 时，直接使用该目录
- 设置了 `AI_HELLO_HOME` 时，使用 `AI_HELLO_HOME/data`
- 在源码仓库内运行时，默认使用仓库下的 `data/`
- 作为已安装包运行时：
  - Windows: `%LOCALAPPDATA%\AiHello\data`
  - Linux/macOS: `$XDG_DATA_HOME/ai_hello/data` 或 `~/.local/share/ai_hello/data`

建议显式设置：

```bash
# Windows PowerShell
$env:AI_HELLO_HOME="$HOME\\.ai_hello"
```

Python 中可以查看：

```python
from ai_hello import get_data_dir

print(get_data_dir())
```

---

## 📦 核心组件详解

### 1. Model 层

`AiHelloLLM` 是当前最核心的统一模型入口，特点包括：

- 参数优先，环境变量兜底
- 自动识别 Provider
- 支持流式与非流式调用
- 面向 OpenAI 兼容接口统一封装

### 2. Agent 层

当前内置的基础 Agent 类型包括：

- `SimpleAgent`
- `ReActAgent`
- `ReflectionAgent`
- `PlanSolveAgent`

它们都基于 `AgentBase` 扩展，可继续派生自定义 Agent。

### 3. Memory 层

四类记忆：

- `working`
- `episodic`
- `semantic`
- `perceptual`

`MemoryManager` 负责统一协调、检索、更新、遗忘和整合。

### 4. RAG 层

RAG 管线支持：

- 文本 / Markdown
- PDF
- Office 文档
- 图片
- 音频

并提供：

- 文档切分
- 向量化
- 检索
- 查询扩展
- 重排序

### 5. Tools 层

当前内置工具包括：

- `calculator`
- `context`
- `memory`
- `note`
- `rag`
- `search`
- `terminal`

---

## 🔍 常见问题

### 1. API 调用失败（401）

通常是 API Key 无效或未配置。

检查：

```bash
# Windows PowerShell
echo $env:LLM_API_KEY
```

### 2. Provider 检测不符合预期

如果你同时设置了多组环境变量，建议显式指定：

```python
llm = AiHelloLLM(provider="zhipu")
```

### 3. Qdrant 连接失败

检查项：

- 本机服务是否已经启动
- `QDRANT_URL` 是否正确
- 云端场景下 `QDRANT_API_KEY` 是否正确

### 4. 向量维度不匹配

检查当前 embedding 实际维度：

```python
from memory.embedding import EmbeddingModelManger

dimension = EmbeddingModelManger().get_dimension(1024)
print(dimension)
```

---

## 🛠️ 开发说明

- 当前包结构保留历史上的平铺模块布局，优先沿用现有导入路径
- 当前发布形态是库，不是 CLI
- RAG、Qdrant、Neo4j 等能力依赖外部服务，安装成功不等于这些服务已经可用

---

## 🤝 参与贡献

1. Fork 本仓库
2. 创建特性分支
3. 提交更改
4. 推送分支
5. 发起 Pull Request

---

## 📝 许可证

MIT
