Metadata-Version: 2.4
Name: wagent-framework
Version: 2.1.0
Summary: Spring-inspired Python framework for building composable agent harnesses
Home-page: https://github.com/LuckyStar2456/W-Agent-FrameWork
Author: LuckyStar2456
Author-email: lucky_star_2456@example.com
License: MIT
Project-URL: Bug Reports, https://github.com/LuckyStar2456/W-Agent-FrameWork/issues
Project-URL: Source, https://github.com/LuckyStar2456/W-Agent-FrameWork
Keywords: agent framework AOP IOC sandbox
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic
Requires-Dist: structlog
Requires-Dist: cryptography
Requires-Dist: msgpack
Requires-Dist: zstandard
Requires-Dist: pyjwt
Requires-Dist: asgiref
Requires-Dist: redis
Requires-Dist: packaging>=23
Requires-Dist: pyyaml>=6
Requires-Dist: typer<1,>=0.12
Requires-Dist: rich<15,>=13
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == "fastapi"
Requires-Dist: uvicorn; extra == "fastapi"
Provides-Extra: langchain
Requires-Dist: langchain; extra == "langchain"
Provides-Extra: models
Requires-Dist: httpx<1,>=0.27; extra == "models"
Provides-Extra: mcp
Requires-Dist: httpx<1,>=0.27; extra == "mcp"
Provides-Extra: tui
Requires-Dist: textual<9,>=0.70; extra == "tui"
Provides-Extra: media-preview
Requires-Dist: Pillow<13,>=12; extra == "media-preview"
Provides-Extra: knowledge-documents
Requires-Dist: pypdf<7,>=6; extra == "knowledge-documents"
Requires-Dist: python-docx<2,>=1.2; extra == "knowledge-documents"
Requires-Dist: openpyxl<4,>=3.1; extra == "knowledge-documents"
Requires-Dist: python-pptx<2,>=1; extra == "knowledge-documents"
Provides-Extra: wasm
Requires-Dist: wasmer-sdk<0.2,>=0.1.2; platform_system != "Windows" and extra == "wasm"
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-api; extra == "opentelemetry"
Requires-Dist: opentelemetry-sdk; extra == "opentelemetry"
Requires-Dist: opentelemetry-exporter-otlp; extra == "opentelemetry"
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-asyncio; extra == "testing"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# W-Agent

**借鉴 Spring 的 IoC、AOP 与生命周期思想，开发你自己的 Harness。**

[English](./README_EN.md) · [文档](./docs/README.md) · [快速入门](#快速入门) · [扩展开发](./docs/developer.md) · [路线图](./docs/roadmap.md)

[![PyPI](https://img.shields.io/pypi/v/wagent-framework)](https://pypi.org/project/wagent-framework/)
[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](./setup.py)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)

W-Agent 是面向 Python 开发者的本地开源 Harness 开发框架。目标是通过统一容器、依赖注入、切面和生命周期，让你用注解、配置或显式代码自由装配执行体系。ReAct、Workflow、客服/编码模板与 CLI/TUI 是可选实现，而不是框架本身的边界。

**版本范围：**2.1.0 纳入已完成 M0–M5 验收的 Harness 开发核心。验收基线包含 259 项相关测试、离线制品、隔离安装与三示例仓库外 Python/CLI/无显示 TUI。见[发布说明](./docs/releases/2.1.0.md)和[证据与限制](./docs/harness-acceptance.md)。上传状态以 [PyPI](https://pypi.org/project/wagent-framework/2.1.0/) 为准。

它提供组合能力的协议和实现，不要求你采用固定 Harness，也不需要托管平台账户。

## 为什么使用 W-Agent

- **模块可替换**：从 Provider 到 Agent Loop 都有公开扩展接口；Python、装饰器、YAML 引用和 entry point 汇入统一插件注册表。
- **链路可组合**：单 Agent ReAct/tool loop 与 DAG、状态图、Python Workflow 可以通过适配器组合。
- **模型不绑定厂商**：提供通用 HTTP 请求映射，以及 OpenAI、Anthropic、Gemini、Ollama、DeepSeek、GLM、Qwen、Turbo 模板；厂商专有参数可通过扩展接口处理。
- **执行边界明确**：工具权限、逐调用审批、Docker 沙箱和显式授权的本地执行相互独立；隔离不可用时不静默降级。
- **运行过程可观察**：Run/Session、输入输出 Token、可配置预算、事件回放和本地评测，为调试与迭代提供基础。

## 安装

需要 **Python 3.11+**。建议在项目自己的虚拟环境中安装。以下命令固定到正式版 2.1.0：

```bash
python -m pip install "wagent-framework==2.1.0"
```

按需添加依赖，不必安装所有模块：

```bash
# HTTP 模型接入与终端界面
python -m pip install "wagent-framework[models,tui]==2.1.0"

# PDF / DOCX / XLSX / PPTX 解析
python -m pip install "wagent-framework[knowledge-documents]==2.1.0"
```

其他 extras 包括 `mcp`、`media-preview`、`testing`、`fastapi`、`langchain`、`opentelemetry` 和平台受限的 `wasm`。参见[安装指南](./docs/guide.md)。

## 快速入门

以下示例使用 2.1.0 框架核心。先按上方命令安装 `wagent-framework==2.1.0`，也可从匹配源码安装 `python -m pip install -e .`；TUI 是可选依赖。仍使用 2.0.0 时请看[此前基础组件教程](./docs/basic-development.md)。

保存为 `hello_harness.py`，然后执行 `python hello_harness.py`。它不使用模型、ReAct 或工具注册表，也不需要 API Key：

```python
import asyncio

from w_agent import (
    AgentComponent, ApplicationOperation, ApplicationProject,
    PostConstruct, PreDestroy, ServiceComponent, compile_decorated,
)


@ServiceComponent("formatter")
class Formatter:
    def format(self, text: str) -> str:
        return text.strip().upper()


@AgentComponent("hello", scope="run")
class HelloHarness:
    def __init__(self, formatter: Formatter):
        self.formatter = formatter
        self.ready = False

    @PostConstruct
    def initialize(self):
        self.ready = True

    async def run(self, text: str) -> str:
        if not self.ready:
            raise RuntimeError("Harness not initialized")
        return self.formatter.format(text)

    @PreDestroy
    def close(self):
        self.ready = False


async def main():
    plan = compile_decorated([Formatter, HelloHarness])
    project = ApplicationProject(plan, {"run": ApplicationOperation("hello")})
    async with project.open() as host:
        print(await host.invoke("run", "hello framework"))


asyncio.run(main())
```

预期输出为 `HELLO FRAMEWORK`。注解只声明组件；`compile_decorated` 编译依赖和作用域，`ApplicationContext` 管理实例与生命周期，`ApplicationHost` 执行公开操作。这里的 Run 组件每次调用初始化，并在返回时清理，不是固定 Agent 基类。

三条完整开发链路见[开发自己的 Harness](./docs/harness-development.md)：

| 示例 | 主要方式 | 演示边界 |
|---|---|---|
| [自定义 Harness](./examples/custom_harness.py) | 显式 Python 装配 | 自定义模型参数、工具和存储，无默认 Loop |
| [客服](./examples/support_harness.py) | 注解扫描、依赖注入、AOP | 本地 FAQ、未知问题转人工、生命周期记录 |
| [编码](./examples/coding_harness.py) | 配置目录、Bean 工厂、AOP | 预览与摘要批准，只修改内存，不执行代码 |

示例使用确定性离线模型替身，不代表真实 LLM 质量。默认 ReAct、Workflow、Provider、工具和预算仍可按需加入，见[默认装配](./docs/default-assembly.md)。`examples` 不包含在 wheel 中；安装用户需从匹配源码或 sdist 复制示例及伴随 JSON，不能把教程文件当成库运行时依赖。

## 按你的方式装配

以下是职责关系，不是必须经过的固定管线：

```text
注解 / 显式 Python / 允许目录中的配置
                 ↓
        AssemblyPlan（依赖与作用域校验）
                 ↓
 ApplicationContext（实例、DI、AOP、生命周期）
                 ↓
  你的 Harness 或可选 ReAct / Workflow 装配
                 ↑
 ApplicationProject / Host ← Python / CLI / TUI
```

| 你要做什么 | 从哪里开始 |
|---|---|
| 接入特殊模型、参数或响应格式 | [Provider 模板](./docs/provider-templates.md) · [模型路由与探测](./docs/model-routing.md) |
| 改写 Agent 推理链路 | [Agent 协议与 Loop](./docs/agents.md) |
| 添加 Python、HTTP、命令或 MCP 工具 | [工具体系](./docs/tools.md) · [MCP 交互](./docs/mcp-interactions.md) |
| 组合流程、状态和审批 | [Workflow](./docs/workflows.md) |
| 接入本地知识、文件或向量检索 | [知识检索](./docs/knowledge-context.md) · [导入与同步](./docs/knowledge-sync-entries.md) |
| 管理用量和上下文 | [Session](./docs/sessions.md) · [共享预算](./docs/shared-budget.md) |
| 编写插件、分享命名版本的装配 | [插件系统](./docs/plugin-system.md) · [工程分享](./docs/project-sharing.md) |

## CLI 与 TUI

安装 `tui` extra 后：

```bash
wagent --help
wagent init
wagent tui
```

`w-agent` 是同一 CLI 的别名。TUI 提供大字符标识与颜文字、运行和审批、会话/用量查看等入口。

2.1.0 还提供 `wagent application run --entry module:create_project --input-file call.json --confirm-code` 与 TUI 的 Application 页，共用公开项目执行入口。项目是受信 Python 代码，确认加载不等于工具副作用批准；完整操作见[三条教程](./docs/harness-development.md)。

`wagent init` 只创建本地 `.wagent` 目录和空的 `config.json`，已有配置不覆盖；**不会配置模型或发起请求**。实际运行前按[Runtime 配置示例](./docs/local-runtime.md#配置)填写配置，再明确授权模型调用。TUI 不替代这些授权边界。

## 能力状态与安全

2.1.0 提供 Harness 开发框架核心；可选高级能力仍可能标记为 `Experimental`。见[版本范围](./docs/releases/2.1.0.md)与[路线图](./docs/roadmap.md)。

- 普通 Python 工具和插件是受信宿主代码，**不是安全沙箱**；不可信代码需要隔离执行。
- 工具权限不等于逐调用审批；导入分享码不自动安装、执行代码或授予权限。
- 模型目录声明不证明连接、鉴权或生成质量；未知用量和价格不表示为零。
- 恢复只保证文档明确支持的边界，不恢复任意 Python 调用栈，也不自动重放结果未知的副作用。
- 多 Agent、分布式 Workflow、在线插件市场等保留或计划项，不是当前开箱即用能力；框架不提供多租户托管服务。

## 文档与贡献

从[使用指南](./docs/guide.md)开始，或查阅[文档目录](./docs/README.md)、[架构](./docs/architecture.md)、[公共 API](./docs/api.md)与[1.x 迁移](./docs/migration-1x.md)。

欢迎通过 [Issues](https://github.com/LuckyStar2456/W-Agent-FrameWork/issues) 提交问题与提案。报告问题时请附 Python/W-Agent 版本、最小复现和脱敏日志；新增能力请先说明扩展点、授权边界，并同步中英文文档。贡献约定见[开发者指南](./docs/developer.md)。

## 许可证

[MIT](./LICENSE)
