Metadata-Version: 2.5
Name: pyharness-ai
Version: 0.6.2
Summary: PyHarness: Everything is a Plugin. A Python Agent Framework.
Project-URL: Homepage, https://github.com/pyharness/pyharness
Project-URL: Repository, https://github.com/pyharness/pyharness
Project-URL: Issues, https://github.com/pyharness/pyharness/issues
Author-email: PyHarness <contact@pyharness.io>
License: MIT
License-File: LICENSE
Keywords: agent,ai,framework,llm,mcp,plugin,rag,workflow
Classifier: Development Status :: 4 - Beta
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: pluggy>=1.5
Requires-Dist: pydantic>=2.7
Provides-Extra: all
Requires-Dist: aiofiles>=23.0; extra == 'all'
Requires-Dist: aiosqlite>=0.20; extra == 'all'
Requires-Dist: beautifulsoup4>=4.12; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: markdownify>=0.12; extra == 'all'
Requires-Dist: numpy>=1.26; extra == 'all'
Requires-Dist: rich>=13.7; extra == 'all'
Requires-Dist: typer>=0.12; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
Requires-Dist: websockets>=12; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich>=13.7; extra == 'cli'
Requires-Dist: typer>=0.12; extra == 'cli'
Provides-Extra: dev
Requires-Dist: aiofiles>=23.0; extra == 'dev'
Requires-Dist: fastapi[standard]>=0.110; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: websockets>=12; extra == 'dev'
Provides-Extra: llm
Requires-Dist: httpx>=0.27; extra == 'llm'
Provides-Extra: mcp
Requires-Dist: httpx>=0.27; extra == 'mcp'
Provides-Extra: memory
Requires-Dist: aiosqlite>=0.20; extra == 'memory'
Provides-Extra: rag
Requires-Dist: numpy>=1.26; extra == 'rag'
Provides-Extra: server
Requires-Dist: aiofiles>=23.0; extra == 'server'
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
Requires-Dist: websockets>=12; extra == 'server'
Provides-Extra: web
Requires-Dist: beautifulsoup4>=4.12; extra == 'web'
Requires-Dist: httpx>=0.27; extra == 'web'
Requires-Dist: markdownify>=0.12; extra == 'web'
Description-Content-Type: text/markdown

# PyHarness — Everything is a Plugin

[![PyPI version](https://badge.fury.io/py/pyharness.svg)](https://badge.fury.io/py/pyharness)
[![CI Status](https://github.com/pyharness/pyharness/actions/workflows/ci.yml/badge.svg)](https://github.com/pyharness/pyharness/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

> **万物皆插件。** 一个基于 pluggy + Pydantic V2 的极简 Python Agent 框架，对标 DeepSeek Harness。

---

## ✨ Features

| 特性 | 说明 |
|------|------|
| 🧩 **万物皆插件** | LLM 提供方、工具执行器、CLI、Web UI 全部通过 `@hookimpl` 注册，核心零依赖 |
| 🧠 **流式思考** | 支持 SSE 流式输出，实时展示 Agent 思考过程 |
| 📋 **Plan 编排** | LLM 生成结构化执行计划，拓扑排序 + TaskGroup 并行执行 |
| 🤖 **Subagent 并行** | 自动派生子 Agent，TaskGroup 并行执行，支持超时与重试 |
| 🔒 **Human-in-the-loop** | 异步审批机制，高危工具执行前人工确认 |
| 💾 **SQLite 持久化** | 会话状态 + FTS5 全文检索，重启后恢复执行 |
| 🌐 **Web UI** | FastAPI + WebSocket 实时推送，三栏式对话界面 |
| ⏪ **可逆状态** | Frozen Pydantic + `model_copy`，支持分支、回滚、多分支搜索 |

---

## 🚀 Quick Start

```bash
# 安装（含全部可选依赖）
pip install pyharness[all]

# 配置 API Key
export DEEPSEEK_API_KEY="sk-..."

# 启动 Web UI
pyharness serve
# → 打开浏览器访问 http://127.0.0.1:3080
```

### CLI 模式

```bash
# 单轮对话
pyharness run --provider http -m deepseek-chat -i "Hello"

# 流式 REPL
pyharness chat --provider http -m deepseek-chat

# 查看版本
pyharness version
```

### Python API

```python
from pyharness import Harness, AgentConfig
from pyharness.plugins.llm import entry as llm

# 初始化 Harness（自动加载内置插件）
h = Harness()

# 配置 LLM 提供方
llm.use_http(
    models=("deepseek-chat",),
    base_url="https://api.deepseek.com/v1",
    api_key="sk-...",
)

# 运行 Agent 会话
ctx = await h.run_session(
    AgentConfig(name="demo", model="deepseek-chat"),
    initial_text="用 Python 写一个快速排序",
)

# 流式输出
async for chunk in h.stream_session(
    AgentConfig(name="demo", model="deepseek-chat"),
    initial_text="用 Python 写一个快速排序",
):
    print(chunk.delta, end="")
```

---

## 🏗️ Architecture

```mermaid
graph TD
    subgraph Core["🧠 PyHarness Core"]
        Harness["Harness<br/>(EventBus + Session Lifecycle)"]
        Specs["AgentHooks<br/>(pluggy contract)"]
        Schema["Pydantic V2 Schema<br/>(Frozen + model_copy)"]
    end

    subgraph Plugins["🔌 Plugins"]
        LLM["LLM Provider<br/>(dummy / http / stream)"]
        Tools["Tool Executors<br/>(python / fs / web)"]
        CLI["CLI Plugin<br/>(typer + rich)"]
        WebUI["Web UI Plugin<br/>(FastAPI + WebSocket)"]
        Store["Session Store<br/>(SQLite + FTS5)"]
        Guard["Guard Approval<br/>(human-in-the-loop)"]
        Workflow["Workflow<br/>(Plan + Subagent)"]
    end

    Harness --> Specs
    Harness --> Schema
    Harness --> Plugins

    style Core fill:#1a1a2e,color:#fff,stroke:#e94560,stroke-width:2px
    style Plugins fill:#16213e,color:#fff,stroke:#0f3460,stroke-width:2px
```

**设计哲学**：核心只做三件事 —— 事件总线 (`pluggy`)、上下文管理 (`contextvars`)、插件加载。所有领域能力（LLM、工具、UI）都通过插件注入。

---

## 🛠️ Built-in Plugins

| 插件 | 入口 | 说明 |
|------|------|------|
| `builtin` | `pyharness.plugins.builtin` | Echo 工具示例 |
| `llm` | `pyharness.plugins.llm.entry` | LLM 提供方：Dummy / HTTP (OpenAI 兼容) |
| `ui-cli` | `pyharness.plugins.ui_cli` | 终端 CLI：`pyharness chat` / `run` |
| `web` | `pyharness.plugins.web_ui` | Web UI：FastAPI REST + WebSocket |
| `memory` | `pyharness.plugins.session_store` | SQLite 持久化 + FTS5 全文检索 |
| `guard-approval` | `pyharness.plugins.guard_approval` | 异步人工审批 |
| `context-compaction` | `pyharness.plugins.context_compaction` | 上下文压缩 |
| `subagent` | `pyharness.plugins.tool_subagent` | 子 Agent 并行编排 |
| `workflow` | `pyharness.plugins.workflow` | Plan 拓扑调度 + 自动重试 |
| `fs` | `pyharness.plugins.tool_fs` | 文件系统工具 |
| `web` | `pyharness.plugins.tool_web` | 网页抓取工具 |

---

## 🧪 Testing

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# Lint
ruff check src/ tests/
```

> **75 个测试全绿**，覆盖 Core、LLM、CLI、Web UI、Workflow、Session Store。

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feat/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a Pull Request

---

## License

Distributed under the MIT License. See `LICENSE` for more information.
