Metadata-Version: 2.4
Name: sotalab-llm-metrics
Version: 0.1.0
Summary: Thin wrapper around posthog-python's AI integrations. Auto-tags LLM calls with project/service/env for unified cost dashboards.
Project-URL: Homepage, https://github.com/SoTALab-ai/llm-metrics
Project-URL: Repository, https://github.com/SoTALab-ai/llm-metrics
Project-URL: Issues, https://github.com/SoTALab-ai/llm-metrics/issues
Author-email: SoTALab <noreply@sotalab.ai>
License: UNLICENSED
Keywords: anthropic,cost-tracking,gemini,llm,metrics,observability,openai,posthog
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: posthog<8,>=7.11
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.39; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic>=0.39; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: openai>=1.50; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Description-Content-Type: text/markdown

# sotalab-llm-metrics

SoTALab 内部 LLM 成本追踪 SDK（Python）。基于 `posthog-python`，自动按 project/service/env/model 维度上报调用成本到 PostHog，内置价格表（含 cache tokens、Gemini 分段定价）。

## 安装

```bash
pip install sotalab-llm-metrics
# 或按需带上 provider extras
pip install 'sotalab-llm-metrics[openai,anthropic]'
```

## 快速使用

### Provider 包装（适合单一 SDK client 生命周期）

```python
from llm_metrics import create_anthropic, create_openai, shutdown

anthropic = create_anthropic()
openai = create_openai()

anthropic.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hi"}],
)

shutdown()
```

### `track_generation`（适合多账号轮转、自定义重试等场景）

```python
from llm_metrics import init, track_generation

init()

# 自己调完 LLM 后手动上报
track_generation(
    model="gpt-4o",
    provider="azure",
    input_tokens=150,
    output_tokens=250,
    latency_ms=1200,
    properties={"account": "azure-02", "job_type": "generate-response"},
)
```

## 配置（环境变量）

| 变量 | 必填 | 说明 |
|------|------|------|
| `POSTHOG_HOST` | ✅ | PostHog 实例 URL |
| `POSTHOG_PROJECT_API_KEY` | ✅ | PostHog Project API Key |
| `LLM_METRICS_PROJECT` | ✅ | 项目名 |
| `LLM_METRICS_SERVICE` | ✅ | 服务名 |
| `LLM_METRICS_ENV` | ⚪ | 环境标签（默认 development） |
| `LLM_METRICS_GIT_SHA` | ⚪ | 部署版本，便于回归排查 |

## 文档

完整文档、架构说明、事件字段契约见 [仓库根目录 README](https://github.com/SoTALab-ai/llm-metrics#readme)。
