agent-operations 0.1.0__tar.gz

agent_operations-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WenSongWang
+
+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.

agent_operations-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: agent-operations
+Version: 0.1.0
+Summary: Lightweight self-hosted Agent Operations (AgentOps / LLMOps) toolkit
+Author: WenSongWang
+License: MIT
+Project-URL: Homepage, https://github.com/WenSongWang/agent-operations
+Project-URL: Repository, https://github.com/WenSongWang/agent-operations
+Project-URL: Issues, https://github.com/WenSongWang/agent-operations/issues
+Keywords: agentops,llmops,observability,tracing,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Dynamic: license-file
+
+# agent-operations
+
+Open-source **Agent Operations** (AgentOps / LLMOps) toolkit — trace runs, track latency / tokens / cost, and debug tool failures.
+
+Lightweight and self-hostable. Default storage is one SQLite file. No ClickHouse required.
+
+| 项 | 值 |
+| :--- | :--- |
+| Python | ≥ 3.11 |
+| Install | `pip install -e .`（当前建议从源码安装） |
+| Default UI | http://127.0.0.1:8787 |
+| Default DB | `./data/agentops.db` |
+
+## 5 分钟上手
+
+### 1. 安装
+
+```powershell
+git clone https://github.com/WenSongWang/agent-operations.git
+cd agent-operations
+python -m pip install -e .
+```
+
+可选：跑测试
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+### 2. 用 Python 写入一条 run
+
+```python
+from agentops import connect, ingest_run
+
+conn = connect("./data/agentops.db")
+ingest_run(conn, {
+    "id": "run-001",
+    "project": "demo",
+    "agent": "assistant",
+    "environment": "dev",          # dev | test | uat | prd
+    "name": "answer-question",
+    "status": "ok",                # running | ok | error | timeout | cancelled
+    "started_at": "2026-10-24T10:00:00+00:00",
+    "ended_at": "2026-10-24T10:00:02+00:00",
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "input_tokens": 100,
+    "output_tokens": 50,
+    # cost_usd 可省略：会按内置单价估算
+    "steps": [
+        {
+            "seq": 1,
+            "kind": "llm",         # llm | tool | agent | human
+            "name": "gpt-4o-mini",
+            "status": "ok",
+            "started_at": "2026-10-24T10:00:00+00:00",
+            "ended_at": "2026-10-24T10:00:02+00:00",
+            "input_tokens": 100,
+            "output_tokens": 50,
+        }
+    ],
+})
+conn.close()
+```
+
+或直接跑示例：
+
+```powershell
+python examples/quickstart.py
+python examples/openai_wrap.py
+```
+
+### 2b. 更省事：用 `TracedRun`（推荐）
+
+不用手写 `running` / 终态时间戳；OpenAI 响应可直接抽 token：
+
+```python
+from agentops import connect, TracedRun
+
+conn = connect("./data/agentops.db")
+with TracedRun(
+    conn,
+    project="demo",
+    agent="assistant",
+    environment="dev",
+    name="chat",
+    task_input="Say hi",
+) as tr:
+    # resp = client.chat.completions.create(...)
+    # tr.record_openai(resp, output_text=resp.choices[0].message.content)
+    tr.finish(task_output="hi")
+conn.close()
+```
+
+异常退出时会自动记成 `status=error`。完整示例见 `examples/openai_wrap.py`。
+
+### 3. 启动本机服务与页面
+
+```powershell
+agentops-http
+# 等价：python -m agentops.http
+```
+
+浏览器打开 http://127.0.0.1:8787  
+
+### 4. 用 HTTP / curl 上报
+
+```powershell
+curl -s http://127.0.0.1:8787/api/runs -Method POST -ContentType "application/json" -Body @'
+{
+  "id": "run-002",
+  "project": "demo",
+  "agent": "assistant",
+  "environment": "dev",
+  "name": "via-http",
+  "status": "ok",
+  "started_at": "2026-10-24T11:00:00+00:00",
+  "ended_at": "2026-10-24T11:00:01+00:00",
+  "latency_ms": 1000,
+  "input_tokens": 10,
+  "output_tokens": 5
+}
+'@
+```
+
+查询：
+
+```powershell
+curl -s "http://127.0.0.1:8787/api/runs?project=demo"
+curl -s "http://127.0.0.1:8787/api/runs/summary?project=demo"
+curl -s "http://127.0.0.1:8787/api/failures?project=demo"
+curl -s "http://127.0.0.1:8787/api/runs/run-002"
+```
+
+## API 一览
+
+| 方法 | 路径 | 说明 |
+| :--- | :--- | :--- |
+| `GET` | `/` | 只读调试页 |
+| `POST` | `/api/runs` | 写入 / 终态更新一条 run |
+| `GET` | `/api/runs` | 列表（可按 project/agent/environment/status/时间筛选） |
+| `GET` | `/api/runs/summary` | 次数、成功率、token/费用、p50/p95/p99 |
+| `GET` | `/api/runs/{id}` | 单条详情（含 steps） |
+| `GET` | `/api/failures` | 工具失败归并 |
+
+### 必填字段（run）
+
+`id`, `project`, `agent`, `environment`, `name`, `status`, `started_at`  
+
+终态（`ok` / `error` / `timeout` / `cancelled`）还要 `ended_at`。  
+`status=running` 时可省略 `ended_at`；同一 `id` 再报终态会覆盖更新。
+
+### 常用可选字段
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `latency_ms` / `ttft_ms` | 耗时；不传则尽量从时间戳 / steps 推算 |
+| `input_tokens` / `output_tokens` / `cached_tokens` / `reasoning_tokens` | token；未上报保持空，不是 0 |
+| `cost_usd` | 费用；不传则按 `provider`+`model` 估算 |
+| `provider` / `model` | 厂商与模型 |
+| `steps` | 步骤列表（排错用） |
+| `quality_score` | 0–1 |
+| `thumbs` | `up` / `down` |
+| `prompt_version` / `template_version` | 提示词 / 模板版本 |
+| `tags` | JSON，如 `{"end_user_id":"..."}` |
+| `extra` | 备用 JSON |
+
+步骤必填：`seq`, `kind`, `name`, `status`。
+
+## 可选能力
+
+### 脱敏
+
+```powershell
+$env:AGENTOPS_REDACT = "hash"   # off | hash | drop
+```
+
+作用于 `task_input` / `task_output`、步骤 `input` / `output` / `traceback`、`tags.end_user_id`。
+
+### 价目表
+
+未传 `cost_usd` 时用内置单价估算。自定义 JSON（键为 `provider/model`）：
+
+```powershell
+$env:AGENTOPS_PRICING_PATH = ".\pricing.json"
+```
+
+### 告警（适合 cron）
+
+```powershell
+$env:AGENTOPS_ALERT_WEBHOOK = "https://example.com/hook"
+$env:AGENTOPS_ALERT_FAILURE_RATE = "0.2"
+$env:AGENTOPS_ALERT_P95_MS = "3000"
+$env:AGENTOPS_ALERT_COST_USD = "10"
+agentops-alerts --db .\data\agentops.db
+```
+
+有告警时退出码 `2`。`--dry-run` 只打印不 POST。
+
+### 事件 outbox（Kafka 预留）
+
+```powershell
+$env:AGENTOPS_EVENT_OUTBOX = ".\data\events.jsonl"
+```
+
+每次成功写入追加一行 `agentops.run` v1 事件（`create` / `finalize`）。
+
+### API Key（外网绑定前必配）
+
+```powershell
+$env:AGENTOPS_API_KEYS = '{"dev-key":{"projects":["demo"]},"admin":{"projects":["*"]}}'
+agentops-http --host 0.0.0.0 --port 8787
+```
+
+请求头：`Authorization: Bearer <key>` 或 `X-API-Key: <key>`。  
+未配置密钥时：仅建议本机 `127.0.0.1`，接口开放。非 loopback 绑定必须配置密钥。
+
+## 限制（请先读）
+
+| 限制 | 说明 |
+| :--- | :--- |
+| Alpha | 接口可能继续演进；生产使用请自行评估 |
+| SQLite | 默认单机文件库；多机共享库尚未提供（Postgres 在路线图） |
+| 自报数据 | 延迟 / token / 费用依赖调用方或估算，不是云厂商账单 |
+| 非全链路 APM | 聚焦 agent run + steps，不是通用分布式 tracing |
+| Kafka | 目前只有 JSONL outbox，没有内置 broker |
+| 页面 | 只读调试页；配置了 API Key 后，浏览器调 API 需自行带密钥 |
+| 安装渠道 | 当前以源码 `pip install -e .` 为主；版本见 tag `v0.1.0` / [CHANGELOG](./CHANGELOG.md)，暂未上传 PyPI |
+
+更细的后续项见 [ROADMAP.md](./ROADMAP.md)。
+
+## 开发
+
+```powershell
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+库入口常用符号：`connect`, `ingest_run`, `list_runs`, `summarize_runs`, `get_run`, `list_tool_failures`。

agent_operations-0.1.0/README.md

@@ -0,0 +1,239 @@
+# agent-operations
+
+Open-source **Agent Operations** (AgentOps / LLMOps) toolkit — trace runs, track latency / tokens / cost, and debug tool failures.
+
+Lightweight and self-hostable. Default storage is one SQLite file. No ClickHouse required.
+
+| 项 | 值 |
+| :--- | :--- |
+| Python | ≥ 3.11 |
+| Install | `pip install -e .`（当前建议从源码安装） |
+| Default UI | http://127.0.0.1:8787 |
+| Default DB | `./data/agentops.db` |
+
+## 5 分钟上手
+
+### 1. 安装
+
+```powershell
+git clone https://github.com/WenSongWang/agent-operations.git
+cd agent-operations
+python -m pip install -e .
+```
+
+可选：跑测试
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+### 2. 用 Python 写入一条 run
+
+```python
+from agentops import connect, ingest_run
+
+conn = connect("./data/agentops.db")
+ingest_run(conn, {
+    "id": "run-001",
+    "project": "demo",
+    "agent": "assistant",
+    "environment": "dev",          # dev | test | uat | prd
+    "name": "answer-question",
+    "status": "ok",                # running | ok | error | timeout | cancelled
+    "started_at": "2026-10-24T10:00:00+00:00",
+    "ended_at": "2026-10-24T10:00:02+00:00",
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "input_tokens": 100,
+    "output_tokens": 50,
+    # cost_usd 可省略：会按内置单价估算
+    "steps": [
+        {
+            "seq": 1,
+            "kind": "llm",         # llm | tool | agent | human
+            "name": "gpt-4o-mini",
+            "status": "ok",
+            "started_at": "2026-10-24T10:00:00+00:00",
+            "ended_at": "2026-10-24T10:00:02+00:00",
+            "input_tokens": 100,
+            "output_tokens": 50,
+        }
+    ],
+})
+conn.close()
+```
+
+或直接跑示例：
+
+```powershell
+python examples/quickstart.py
+python examples/openai_wrap.py
+```
+
+### 2b. 更省事：用 `TracedRun`（推荐）
+
+不用手写 `running` / 终态时间戳；OpenAI 响应可直接抽 token：
+
+```python
+from agentops import connect, TracedRun
+
+conn = connect("./data/agentops.db")
+with TracedRun(
+    conn,
+    project="demo",
+    agent="assistant",
+    environment="dev",
+    name="chat",
+    task_input="Say hi",
+) as tr:
+    # resp = client.chat.completions.create(...)
+    # tr.record_openai(resp, output_text=resp.choices[0].message.content)
+    tr.finish(task_output="hi")
+conn.close()
+```
+
+异常退出时会自动记成 `status=error`。完整示例见 `examples/openai_wrap.py`。
+
+### 3. 启动本机服务与页面
+
+```powershell
+agentops-http
+# 等价：python -m agentops.http
+```
+
+浏览器打开 http://127.0.0.1:8787  
+
+### 4. 用 HTTP / curl 上报
+
+```powershell
+curl -s http://127.0.0.1:8787/api/runs -Method POST -ContentType "application/json" -Body @'
+{
+  "id": "run-002",
+  "project": "demo",
+  "agent": "assistant",
+  "environment": "dev",
+  "name": "via-http",
+  "status": "ok",
+  "started_at": "2026-10-24T11:00:00+00:00",
+  "ended_at": "2026-10-24T11:00:01+00:00",
+  "latency_ms": 1000,
+  "input_tokens": 10,
+  "output_tokens": 5
+}
+'@
+```
+
+查询：
+
+```powershell
+curl -s "http://127.0.0.1:8787/api/runs?project=demo"
+curl -s "http://127.0.0.1:8787/api/runs/summary?project=demo"
+curl -s "http://127.0.0.1:8787/api/failures?project=demo"
+curl -s "http://127.0.0.1:8787/api/runs/run-002"
+```
+
+## API 一览
+
+| 方法 | 路径 | 说明 |
+| :--- | :--- | :--- |
+| `GET` | `/` | 只读调试页 |
+| `POST` | `/api/runs` | 写入 / 终态更新一条 run |
+| `GET` | `/api/runs` | 列表（可按 project/agent/environment/status/时间筛选） |
+| `GET` | `/api/runs/summary` | 次数、成功率、token/费用、p50/p95/p99 |
+| `GET` | `/api/runs/{id}` | 单条详情（含 steps） |
+| `GET` | `/api/failures` | 工具失败归并 |
+
+### 必填字段（run）
+
+`id`, `project`, `agent`, `environment`, `name`, `status`, `started_at`  
+
+终态（`ok` / `error` / `timeout` / `cancelled`）还要 `ended_at`。  
+`status=running` 时可省略 `ended_at`；同一 `id` 再报终态会覆盖更新。
+
+### 常用可选字段
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `latency_ms` / `ttft_ms` | 耗时；不传则尽量从时间戳 / steps 推算 |
+| `input_tokens` / `output_tokens` / `cached_tokens` / `reasoning_tokens` | token；未上报保持空，不是 0 |
+| `cost_usd` | 费用；不传则按 `provider`+`model` 估算 |
+| `provider` / `model` | 厂商与模型 |
+| `steps` | 步骤列表（排错用） |
+| `quality_score` | 0–1 |
+| `thumbs` | `up` / `down` |
+| `prompt_version` / `template_version` | 提示词 / 模板版本 |
+| `tags` | JSON，如 `{"end_user_id":"..."}` |
+| `extra` | 备用 JSON |
+
+步骤必填：`seq`, `kind`, `name`, `status`。
+
+## 可选能力
+
+### 脱敏
+
+```powershell
+$env:AGENTOPS_REDACT = "hash"   # off | hash | drop
+```
+
+作用于 `task_input` / `task_output`、步骤 `input` / `output` / `traceback`、`tags.end_user_id`。
+
+### 价目表
+
+未传 `cost_usd` 时用内置单价估算。自定义 JSON（键为 `provider/model`）：
+
+```powershell
+$env:AGENTOPS_PRICING_PATH = ".\pricing.json"
+```
+
+### 告警（适合 cron）
+
+```powershell
+$env:AGENTOPS_ALERT_WEBHOOK = "https://example.com/hook"
+$env:AGENTOPS_ALERT_FAILURE_RATE = "0.2"
+$env:AGENTOPS_ALERT_P95_MS = "3000"
+$env:AGENTOPS_ALERT_COST_USD = "10"
+agentops-alerts --db .\data\agentops.db
+```
+
+有告警时退出码 `2`。`--dry-run` 只打印不 POST。
+
+### 事件 outbox（Kafka 预留）
+
+```powershell
+$env:AGENTOPS_EVENT_OUTBOX = ".\data\events.jsonl"
+```
+
+每次成功写入追加一行 `agentops.run` v1 事件（`create` / `finalize`）。
+
+### API Key（外网绑定前必配）
+
+```powershell
+$env:AGENTOPS_API_KEYS = '{"dev-key":{"projects":["demo"]},"admin":{"projects":["*"]}}'
+agentops-http --host 0.0.0.0 --port 8787
+```
+
+请求头：`Authorization: Bearer <key>` 或 `X-API-Key: <key>`。  
+未配置密钥时：仅建议本机 `127.0.0.1`，接口开放。非 loopback 绑定必须配置密钥。
+
+## 限制（请先读）
+
+| 限制 | 说明 |
+| :--- | :--- |
+| Alpha | 接口可能继续演进；生产使用请自行评估 |
+| SQLite | 默认单机文件库；多机共享库尚未提供（Postgres 在路线图） |
+| 自报数据 | 延迟 / token / 费用依赖调用方或估算，不是云厂商账单 |
+| 非全链路 APM | 聚焦 agent run + steps，不是通用分布式 tracing |
+| Kafka | 目前只有 JSONL outbox，没有内置 broker |
+| 页面 | 只读调试页；配置了 API Key 后，浏览器调 API 需自行带密钥 |
+| 安装渠道 | 当前以源码 `pip install -e .` 为主；版本见 tag `v0.1.0` / [CHANGELOG](./CHANGELOG.md)，暂未上传 PyPI |
+
+更细的后续项见 [ROADMAP.md](./ROADMAP.md)。
+
+## 开发
+
+```powershell
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+库入口常用符号：`connect`, `ingest_run`, `list_runs`, `summarize_runs`, `get_run`, `list_tool_failures`。