Metadata-Version: 2.4
Name: showholdings-agentmon
Version: 0.3.1
Summary: Python SDK for Show Holdings AgentOps monitoring
Author: Show Holdings
License-Expression: MIT
Project-URL: Homepage, https://agentops.showholdings.com
Project-URL: Repository, https://github.com/showholdings/showholdings-agentmon
Project-URL: Issues, https://github.com/showholdings/showholdings-agentmon/issues
Keywords: agentops,monitoring,ai-agent,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# showholdings-agentmon

`showholdings-agentmon` 是 Show Holdings AgentOps 的 Python SDK。

它讓你可以在自己的 Python 程式中，用最小改動接入 run-level 與 step-level monitoring。

## 安裝

```bash
pip install showholdings-agentmon
```

## 最小使用範例

```python
from showholdings_agentmon import Monitor

monitor = Monitor(
    api_key="YOUR_API_KEY",
    base_url="https://agentops.showholdings.com",
    project_name="my-agent",
)

with monitor.run(agent_name="general-agent", session_id="session-123"):
    result = run_my_agent()
```

## auto_instrumentation v1（預設啟用）

在 v1 中，`Monitor(...)` 初始化後就會在 `monitor.run(...)` 期間自動補抓常見 steps，
你不需要額外呼叫 `auto_instrument()` 或新增 setup code。

目前預設自動補抓：
- OpenAI / Anthropic / Gemini 模型呼叫（`llm_call`）
- 模型層 tool use 事件（`tool_call`）
- 外部 HTTP(S) 呼叫（`http_call`，requests / httpx）
- 常見 DB 查詢（`db_query`，SQLite / SQLAlchemy 第一版）
- exception / timeout（自動標記 failed 並保留錯誤訊息）
- fallback step（`執行中`）：即使你只寫 `monitor.run(...)`，也會有基本 step 動態可視化

fallback step 行為：
- run 開始時會先建立一個粗粒度 `執行中` step（`processing`）
- 若 run 內出現手動 step 或 auto-detected step，fallback step 會先結束，避免和真實 step 長時間重疊
- 若 run 內完全沒有其他 step，fallback step 會持續到 run 結束（success / failed）

> 說明：v1 是 deterministic runtime instrumentation，不包含 AI assist setup 或 function-level 自動建議插樁。

## 標準版（含步驟監測）

```python
from showholdings_agentmon import Monitor

monitor = Monitor(
    api_key="YOUR_API_KEY",
    base_url="https://agentops.showholdings.com",
    project_name="my-agent"
)

with monitor.run(agent_name="填入你的 agent 名稱", session_id="填入你自訂的 session 編號"):
    # 記錄步驟 1
    with monitor.step("填入步驟 1 的名稱", step_type="例如：資料處理 / 模型呼叫 / 輸出結果"):
        result_1 = code_of_step_1()

    # 記錄步驟 2
    with monitor.step("填入步驟 2 的名稱", step_type="例如：資料處理 / 模型呼叫 / 輸出結果"):
        result_2 = code_of_step_2()
```

## SDK 行為說明

- 進入 `with monitor.run(...)` 時，自動呼叫 `POST /api/sdk/runs/start`
- 離開 context 時，自動呼叫 `POST /api/sdk/runs/end`
- 進入 `with monitor.step(...)` 時，自動呼叫 `POST /api/sdk/steps/start`
- 離開 step context 時，自動呼叫 `POST /api/sdk/steps/end`
- auto-detected steps 也會走同一組 `steps/start` / `steps/end` API
- 成功結束會送出 `status=success`
- 區塊內拋出例外會送出 `status=failed`，並附帶：
  - `failure_reason_type`（例外類別名稱）
  - `error_count=1`
- step 區塊內拋出例外會送出 `status=failed` 與 `error_message`
- SDK 對監控 API 採 best effort；監控 API 失敗不會中斷你的主要業務流程

## 本地開發

```bash
pip install -e .[dev]
pytest
python -m build
```

## 發布概要

本專案已提供 GitHub Actions：

- `ci.yml`：在 push / pull_request 執行測試
- `publish.yml`：以 PyPI Trusted Publishing 為目標的正式發布流程

你可先用 TestPyPI 驗證流程，再切換到正式 PyPI 發布。
