Metadata-Version: 2.4
Name: iris-next
Version: 0.0.2
Summary: iris-next
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/xxWeiDG/iris-next
Project-URL: Repository, https://github.com/xxWeiDG/iris-next
Project-URL: Issues, https://github.com/xxWeiDG/iris-next/issues
Keywords: agent,llm,ai,openai,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# IrisAgent

最小化的智能体框架，基于 openai-agents-python 和 loom-agent 的核心设计理念。

## 核心特性

### ✅ 已实现

1. **Pydantic 增强的工具系统**
   - 支持复杂嵌套参数（List[str], BaseModel）
   - 自动类型校验和反序列化
   - 自动生成 JSON Schema
   - **工具安全属性**（read_only, destructive）
   - **工具速率限制**（rate_limit）

2. **多智能体交接 (Handoff)**
   - 原生支持 Agent 之间的动态切换
   - 保留上下文无缝交接
   - 类似 OpenAI Agents SDK 的 Handoff 机制

3. **沙盒隔离 (Sandbox)**
   - 抽象 Sandbox 接口
   - LocalSandbox 实现
   - 为危险工具提供隔离执行环境

4. **分层流式输出**
   - **原始事件流**（RawLLMEvent）
   - LLM Token 流
   - 工具调用入参流
   - 工具执行状态流
   - 工具结果流
   - Handoff 事件流

5. **工具治理**
   - 权限检查
   - 自动重试
   - 超时控制
   - **速率限制**（防止滥用）

6. **智能上下文压缩**
   - 基于阈值的自动压缩
   - 保留重要消息

7. **Skill 动态加载**
   - 从文件/目录加载
   - 自动注册工具

8. **Usage 统计**
   - Token 消耗跟踪
   - 按 Agent 分组统计
   - 成本估算支持

9. **Hook 系统**
   - before_run / after_run
   - before_tool_call / after_tool_call
   - on_error / on_handoff

10. **完善的异常体系**
    - 语义化异常类型
    - 区分可恢复/不可恢复错误

## 架构设计

```
src/iris_agent/
├── agent.py           # Agent 配置
├── run.py             # Runner 执行引擎
├── tool.py            # 工具系统（Pydantic + 安全属性）
├── tool_executor.py   # 工具执行器（权限 + 速率限制）
├── handoff.py         # Handoff 机制
├── exceptions.py      # 异常体系
├── usage.py           # Token 使用统计
├── hooks.py           # 生命周期钩子
├── context/           # 上下文管理
├── sandbox/           # 沙盒抽象
├── streaming/         # 分层流式事件
├── skill/             # 技能加载
└── types/             # 类型定义
```

## 快速开始

### 安装

```bash
pip install -r requirements.txt
```

### 环境变量配置

```bash
export OPENAI_API_KEY=your-api-key
export OPENAI_BASE_URL=http://localhost:11434/v1
```

### 基础使用

```python
from iris_agent import Agent, Runner, tool, ToolRegistry

@tool(name="calculator", description="Calculate")
def calculator(expression: str) -> str:
    return str(eval(expression))

registry = ToolRegistry()
registry.register(calculator._tool_config)

agent = Agent(
    name="math_agent",
    instructions="You are a math assistant.",
    tool_registry=registry
)

runner = Runner(agent)

async for event in runner.run("What is 123 * 456?"):
    if event.type.value == "llm_token":
        print(event.token, end="")
```

### Pydantic 复杂参数

```python
from pydantic import BaseModel
from iris_agent import tool

class SearchParams(BaseModel):
    query: str
    filters: list[str]
    limit: int = 10

@tool(name="search", description="Search with filters")
def search(params: SearchParams) -> str:
    return f"Searching: {params.query}, filters: {params.filters}"
```

### 多智能体 Handoff

```python
from iris_agent import Agent, Handoff, Runner

specialist = Agent(name="specialist", instructions="...")
generalist = Agent(
    name="generalist",
    instructions="...",
    handoffs=[
        Handoff(
            target_agent=specialist,
            description="Transfer to specialist for complex queries"
        )
    ]
)

runner = Runner(generalist)
# Agent 会自动切换
```

## 新特性使用示例

### 工具安全属性

```python
from iris_agent import tool

@tool(
    name="delete_file",
    description="Delete a file",
    destructive=True,          # 标记为破坏性操作
    requires_permission=True
)
def delete_file(path: str) -> str:
    return f"Deleted {path}"

@tool(
    name="read_file",
    description="Read a file",
    read_only=True,            # 只读工具
    requires_permission=False
)
def read_file(path: str) -> str:
    return f"Content of {path}"

@tool(
    name="api_call",
    description="Call external API",
    rate_limit=10              # 限制每分钟10次调用
)
def api_call(endpoint: str) -> str:
    return f"Called {endpoint}"
```

### Usage 统计

```python
from iris_agent import Agent, Runner, UsageTracker

tracker = UsageTracker()
agent = Agent(name="assistant", instructions="...")
runner = Runner(agent)

# 运行后获取统计
async for event in runner.run("Hello"):
    pass

# 记录使用（需在 Runner 中集成）
# tracker.record("assistant", Usage(prompt_tokens=100, completion_tokens=50))
print(tracker.get_summary())
```

### Hook 系统

```python
from iris_agent import Agent, Runner, Hooks

async def log_before_tool(tool_name: str, args: dict):
    print(f"Calling tool: {tool_name} with {args}")

async def log_after_tool(tool_name: str, result):
    print(f"Tool {tool_name} returned: {result}")

hooks = Hooks()
hooks.before_tool_call.append(log_before_tool)
hooks.after_tool_call.append(log_after_tool)

# 在 Runner 中使用（需集成到 Runner）
```

## 依赖

- openai >= 1.0.0
- pydantic >= 2.0.0
