Metadata-Version: 2.4
Name: vokit
Version: 0.1.6
Summary: VirtualOffice Agent SDK — 透明拦截转发 + 平台 API 封装
Author: VirtualOffice Team
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: wrapt>=1.15
Requires-Dist: httpx>=0.24
Requires-Dist: pyjwt[crypto]>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: aiohttp>=3.8; extra == "dev"
Requires-Dist: requests>=2.28; extra == "dev"
Requires-Dist: urllib3>=1.26; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# vokit — VirtualOffice Agent SDK

一行 `import vokit` 完成拦截激活 + API 就绪。

## 安装

```bash
# 稳定版
pip install vokit

# 指定版本
pip install vokit==0.1.3

# 升级
pip install --upgrade vokit
```

## 快速开始

### 1. 拦截 LLM 请求

在 Agent 的**入口文件最顶部** import 一次即可：

```python
import vokit
```

- **只需 import 一次**：patch 注册在进程级别的 HTTP 库入口，全局生效。
- **放在最顶部**：确保在所有 LLM SDK 被 import 之前 patch 已注册好。
- **幂等安全**：多次 import 不会重复注册。

### 2. 使用平台 API

```python
import vokit

# 提交产出物
vokit.submit_output(
    output_type="file",
    content="base64编码的内容",
    filename="report.pdf",
    mime_type="application/pdf"
)

# 上报指标数据
vokit.report_metrics(metrics=[
    {"metricType": "token_usage", "metricValue": 1500, "snapshotDate": "2026-04-14"},
])

# 上报费用记录
vokit.report_billing(
    cost=150,
    request_id="unique-request-id",
    call_date="2026-04-14",
    api_type="chat",
)
```

### 3. Token Override & Claims

```python
import vokit

# Override token for a scope
with vokit.use_access_token("custom-token"):
    vokit.submit_output("url", "https://...")

# Read JWT claims
claims = vokit.get_claims()
print(claims.enterprise_id, claims.agent_id)
```

## 运行模式

### 开发模式

不设置 `VO_GATEWAY_URL` 和 `VO_ACCESS_TOKEN` 时自动进入：
- LLM 请求**直连** Provider，不被拦截
- 平台 API 返回 Mock 数据

```bash
export OPENAI_API_KEY="your-key"
python your_agent.py
```

### 生产模式

设置环境变量后自动进入：

```bash
export VO_GATEWAY_URL=http://localhost:8888
export VO_ACCESS_TOKEN=<your-jwt-token>
export OPENAI_API_KEY="your-key"
python your_agent.py
```

## 环境变量

| 变量 | 说明 |
|------|------|
| `VO_GATEWAY_URL` | 内网网关地址，缺失则进入开发模式 |
| `VO_ACCESS_TOKEN` | 网关 Bearer Token，缺失则进入开发模式 |
| `VO_DEV_MODE` | 设为 `1` 强制进入开发模式 |
| `VO_RSA_PUBLIC_KEY_PATH` | RSA public key PEM path for `get_claims()` |

## Python 版本

要求 Python 3.10+

## License

MIT
