Metadata-Version: 2.4
Name: fiuai-sdk-agent
Version: 1.0.0
Summary: FiuAI SDK Agent - A framework for building AI agents with LLM support, context management, and event handling
Author-email: liming <lmlala@aliyun.com>
License: Proprietary
Keywords: ai,agent,llm,langchain,fiuai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fiuai-sdk-python>=0.8.2
Requires-Dist: langchain>=1.2.0
Requires-Dist: langchain-core>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: redis>=7.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: snowflake-id>=1.0.2
Requires-Dist: jinja2==3.1.6
Requires-Dist: markupsafe==3.0.3
Provides-Extra: embedding
Requires-Dist: openai>=1.0.0; extra == "embedding"
Provides-Extra: vector
Requires-Dist: qdrant-client>=1.7.0; extra == "vector"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: qdrant-client>=1.7.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# FiuAI SDK Agent 1.0

这是一个 provider-free 的 Agent 基础 SDK。业务 chat 调用必须通过
`LLMGatewayClient` 发送到 fiuai-ai Gateway；SDK 不创建 `ChatOpenAI`、模型实例、
provider client、callback 或 usage log writer。

## 安装

```bash
pip install fiuai-sdk-agent==1.0.0
pip install fiuai-sdk-agent[embedding]
pip install fiuai-sdk-agent[vector]
```

`0.5.x` 是 legacy 版本，只供尚未迁移的 fiuai-agent 使用。World 业务使用 1.x，
升级时由应用显式更新依赖和 lock 文件。

## Gateway 调用

```python
from fiuai_sdk_agent import AgentRuntime, LLMGatewayClient, SkillRegistry

client = LLMGatewayClient(base_url="http://fiuai-ai:8000")
runtime = AgentRuntime(
    context=business_context,
    skill_registry=SkillRegistry(),
    gateway_client=client,
)

model = runtime.get_chat_model(role="semantic.document_summary", model="auto")
response = await model.ainvoke([
    {"role": "user", "content": "请摘要这份文档"},
])
print(response.content)
```

Gateway 负责 provider/model 路由、重试、fallback、deadline、认证上下文校验和
`llm.llm_usage_log`。调用方负责 evidence、结构化结果校验和业务防火墙。

## SDK 边界

SDK 提供：

- `LLMGatewayClient`、`LLMGatewayResponse`、`LLMGatewayError`
- `GatewayAgent`、`AgentRuntime`、Skill、Plan、Event 和 Graph 抽象
- 独立 embedding 与 vector 能力
- 纯协议类型、token 限制、价格计算和响应解析 helper

SDK 不提供：

- provider key、base URL 或本地模型 catalog
- `LLMManager`、`ChatOpenAI` 和旧 callback
- 本地 chat retry/fallback 或 usage database writer
- World、Chat、Agent 的业务对象和 prompt

## Embedding

Embedding 是独立能力，可以按需启用 `embedding` extra。Embedding 配置不依赖
chat runtime，也不写 Gateway chat usage log。

## 未来流式协议

1.0 首期只实现非流式 Gateway chat。SSE、thinking/text/tool-call 事件和
`astream()` 将在 fiuai-agent 后续迁移中单独发布，不影响当前 1.0 contract。
