Metadata-Version: 2.5
Name: daphnis
Version: 0.1.0
Summary: A Python async agent library
Project-URL: Repository, https://github.com/GilbertXD/Daphnis
Project-URL: Issues, https://github.com/GilbertXD/Daphnis/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: httpx-sse>=0.4.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25; sys_platform == 'darwin'
Description-Content-Type: text/markdown

# Daphnis

Daphnis 是一个基于 Python asyncio 的 Agent 库，提供异步模型调用、流式事件、会话历史和上下文管理等能力。

面向需要在 Python 应用中集成 AI Agent 能力的开发者，可用于命令行工具、桌面应用或其他异步服务。Daphnis 提供会话与模型接入接口，界面和业务逻辑由宿主应用实现。

## 安装

需要 **Python 3.13 或更高版本**。在项目的虚拟环境中，从 PyPI 安装：

```sh
python -m pip install daphnis
```


## 开始一次对话

以 DeepSeek 为例
安装 Daphnis 后，在运行环境中设置 `DEEPSEEK_API_KEY`，再将下面代码保存为 Python 文件并运行。示例使用库内目录登记的模型，实际可用性取决于远端服务与账户权限。

```python
import asyncio
import os

from daphnis.providers import create_agent


async def main() -> None:
    async with await create_agent(
        provider="deepseek",
        model="deepseek-flash",
        api_key=os.environ["DEEPSEEK_API_KEY"],
    ) as agent:
        result = await agent.run("你好，请简单介绍一下你自己。")
        print(result.text)
        print("结束原因：", result.stop_reason)


if __name__ == "__main__":
    asyncio.run(main())
```

`create_agent()` 按传入配置创建会话，本身不读取环境变量、配置文件或钥匙串；上例由调用方读取环境变量并传入凭据。创建过程执行本地校验，首次 `run()` 才请求模型。会话应通过 `async with` 或 `await agent.aclose()` 关闭。

同一会话中顺序调用 `await agent.run(...)` 可以继续对话，后续调用会使用已提交的历史。已有 asyncio 事件循环的应用可直接 `await main()`；`asyncio.run(main())` 用于独立脚本入口。

需要逐片段展示回答时，可向 `create_agent()` 传入 `EventBus`，监听 `MessageUpdate` 中的 `TextDelta`。完整示例见[流式事件](https://github.com/GilbertXD/Daphnis/blob/main/docs/usage.md#3-流式事件)。

## 模型接入

内置适配器的厂商说明、已登记模型、连接配置及参数限制见[已支持的模型服务](https://github.com/GilbertXD/Daphnis/blob/main/docs/supported_providers.md)。

模型目录是本库维护的离线声明，不会访问远端，也不是完整的远端模型清单。可通过以下接口查询：

```python
from daphnis.providers import available_providers, list_models, model_info

print(available_providers())
for item in list_models("deepseek"):
    print(item.model, item.capabilities.thinking_mode)

info = model_info("deepseek", "deepseek-flash")
print(info.known, info.capabilities.reasoning_levels)
```

## 文档

- [使用指南](https://github.com/GilbertXD/Daphnis/blob/main/docs/usage.md)：模型配置、连续对话、流式事件、历史保存、上下文与预算，以及本地配置恢复。
- [已支持的模型服务](https://github.com/GilbertXD/Daphnis/blob/main/docs/supported_providers.md)：按厂商介绍适配器、模型目录、参数限制和环境变量入口。
- [架构与运行约定](https://github.com/GilbertXD/Daphnis/blob/main/docs/architecture.md)：模块职责、消息结构、状态提交、模型切换与资源所有权。
- [问题反馈](https://github.com/GilbertXD/Daphnis/issues)：报告缺陷或提出功能建议。

## 当前范围

- 基础会话核心不管理文件、凭据或界面，模型绑定由外层注入。
- 提供工具接口和调用机制，具体工具由宿主应用实现并注册。
- 不提供默认模型服务商、自动重试、自动摘要或自动历史保存。
- 默认凭据后端正式支持 macOS，通过显式的 keyring macOS 后端访问钥匙串。

## 开发检查

从源码开发时，在仓库根目录安装项目及开发依赖后运行检查：

```sh
python -m pip install --upgrade pip
python -m pip install . --group dev
python -m ruff check .
python -m pytest -q
```

GitHub Actions 会在推送到 `main`、向 `main` 提交 PR 或手动触发时执行 CI：检查代码，在 Linux、macOS、Windows 上测试 Python 3.13–3.15，并验证源码包、wheel 和安装后的公开接口。

## 许可证

本项目采用 [MIT 许可证](https://github.com/GilbertXD/Daphnis/blob/main/LICENSE)。
