Metadata-Version: 2.4
Name: pgworker
Version: 0.1.1
Summary: Thin local CLI relay for the prove-graph backend — spawns codex / claude / deepseek subprocesses on user machines and streams stdout/stderr back over WebSocket.
Author-email: 孙天阳 <tysun@mail.ustc.edu.cn>
License: MIT License
        
        Copyright (c) 2026 孙天阳 / prove-graph contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/ustc-ai4m/prove-graph
Project-URL: Issues, https://github.com/ustc-ai4m/prove-graph/issues
Keywords: prove-graph,pgworker,mathematical-proofs,ai-agent,subprocess-relay,websocket-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=12
Requires-Dist: pydantic>=2.7
Dynamic: license-file

# pgworker — 用户机器的本地守护进程

## 它是什么

一个跑在**用户自己电脑上**的 asyncio 守护进程，作为 prove-graph 后端
的**远程 subprocess 中继**。后端通过 WebSocket 发 `stage.request`
（一段渲染好的 prompt + 调哪个 CLI 的指令），pgworker 起本机
`codex` / `claude` / `deepseek` 子进程，把 stdout 流式回传。

具体职责：

1. 维持一条到 web backend 的长 WebSocket 连接（应用层 ping/pong）
2. 接 `stage.request`，在 `~/.pgworker/scratch/<stage_run_id>/`
   下喂 `stage.request.files`、起 subprocess、流回 stdout/stderr
3. 接 `stage.cancel`，SIGTERM/SIGKILL 当前子进程
4. **不**持有 problem 状态、**不** import `prove_graph`、**不知道**
   当前 stage 是 analyze / attempt / verify、graph 长什么样

也就是说：它是 **backend 在用户机器上的一只胳膊**，仅此而已。
graph、prompt、orchestration、不变量都在服务端，不会进入用户机器。

## 包独立性

pgworker 是个独立的 PyPI 包（`pgworker/pyproject.toml`），依赖只有：

```
httpx>=0.27
websockets>=12
pydantic>=2.7
```

**不**依赖 `prove-graph` 框架包。用户安装：

```bash
pip install pgworker
```

需要 Python 3.10+。装完 `pgworker` 命令在 PATH 上。装好的 pgworker
跑 `python -c "import prove_graph"` 会报 ModuleNotFoundError——这是
有意的：framework 代码不该出现在用户机器上。

## 协议版本

当前 pgworker 上报 `protocol_version: 2`（thin-worker 协议）。
服务端只接受 `protocol_version >= 2` 的连接。pgworker 与服务端的协议
规格在项目内部文档中维护；公开 PyPI 用户只需要 `pgworker pair` +
`pgworker run` 两条命令。

> 注：上游 prove-graph 项目本身是私有仓库；pgworker 是它**唯一公开**
> 的脚手架包。装这个包不会让你访问到 prove-graph 框架代码。

## 为什么单列一个顶级目录

它**不是框架库**，所以不该在 `prove_graph/` 包里。它**不是 web
服务**，所以也不该在 `backend/` 里。它是第三类东西——"用户机器侧
的执行入口 + web 客户端"，与 `backend/` 是同级 peer 部署。

## 它有寿命

**本目录是过渡期产物**。本项目的长期目标是 PydanticAI agent 在云端
全面接管，届时用户机器不再需要跑任何东西，所有 round 都在网页
backend 自己进程里完成。

当下面这两个条件**同时**满足时，整个 `pgworker/` 目录可以一次性删除：

1. PydanticAI agent 在网页端各项任务上稳定性 / 质量 ≥ 现行的
   Claude Code / Codex
2. 用户群体里再没有强烈的"我要用本机 claude/codex"诉求

届时清理步骤：

```bash
git rm -rf pgworker/
# backend/app/routers/pgworker.py 删除
# backend/app/services/{worker_registry, stage_relay}.py 删除
# prove_graph/agents/remote_cli.py + worker_protocol.py 删除
# ModelConfig.kind 移除 local-* 三个 kind
```

这是几十行 diff，没有遗留 cruft——这正是把它顶级单列的目的。

## 使用

```bash
pip install pgworker
pgworker pair <pair-code> --server <网页端 URL>   # 一次性配对（在网页 Settings → Local devices 拿配对码）
pgworker run                                     # 前台跑守护进程；想后台跑请套 systemd / launchd / nohup / screen / tmux
```

诊断：

```bash
pgworker doctor          # 看本机 CLI 版本、token 状态
pgworker capabilities    # 看 capabilities JSON
pgworker revoke          # 删除本机 token
```

日志在 `~/.pgworker/run.log`（5×1MB 轮转）。
