Metadata-Version: 2.4
Name: dsh-llm-cost
Version: 0.1.0
Summary: LLM API pricing registry and cost estimation, shared by the DeepSeek Harness dsh-llm-cost plugin and Python agent systems.
Author-email: "Chen (Jarry) Pan" <jarrypan@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/chenyinrusi/dsh-llm-cost
Keywords: llm,pricing,cost,deepseek-harness,dsh,tokens,usage
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# llm-cost

> LLM API 定价表 + 成本估算，作为 `dsh-llm-cost`（DeepSeek Harness 插件）与 Python 智能体系统的**单一事实来源**。

把定价数据（`llm_models.toml [pricing_v2]`）和成本计算逻辑从大项目里解耦出来，让 Python 侧和 DSH 侧对「每个请求花了多少钱」得到完全一致的数字。

## 安装

```bash
pip install dsh-llm-cost
```

## 用法

```python
from dsh_llm_cost import estimate_cost, list_models, resolve_pricing

# 一次请求的成本（input/output/cache 分桶）
est = estimate_cost(
    "deepseek-v4-flash", "deepseek",
    input_tokens=1000, output_tokens=500, cache_read_tokens=2000,
)
print(est.total_usd)   # 0.003xxxx

# 未知模型 → None（绝不静默显示 $0，避免「未知」被误读成「免费」）
assert estimate_cost("made-up-model", "openai", input_tokens=10, output_tokens=10) is None

# 匹配阶梯 + 完整决议
r = resolve_pricing("gpt-5.4-mini-20250601", "openai")
print(r.match)         # 'substring'
print(list_models())   # 所有模型 id
```

## 匹配阶梯（对齐 `models.py:get_pricing`）

```
0. provider === "ollama"  → 免费 (0)
1. 模型 id 精确匹配
2. 最长 key 子串匹配（防 "gpt-5.4" 吞掉 "gpt-5.4-mini"）
3. 未知 → None（显示 "unknown"，不显示 $0.00）
```

成本公式（与 `dsh-llm-cost` 插件一致）：

```
total = input_tokens/1e6 * input_per_m
      + cache_read_tokens/1e6 * cache_read_per_m
      + cache_write_tokens/1e6 * cache_write_per_m
      + output_tokens/1e6 * output_per_m
```

`input_tokens` 是不含缓存的输入（DeepSeek 适配器已把缓存命中从 `prompt_tokens` 里减掉）；reasoning 已含在 `output_tokens` 内；batch/storage/1h 维度 v1 不计入显示值。

## 数据

`src/dsh_llm_cost/_data.py` 由 `gen_data.py` 从 `dsh-llm-cost` 的 `pricing.json` 生成。单一事实来源是 `llm_models.toml [pricing_v2]`，链路：

```
llm_models.toml --(dsh-llm-cost: npm run gen)--> pricing.json --(gen_data.py)--> _data.py
```

重新生成：

```bash
python gen_data.py ../dsh-llm-cost/pricing.json
```

## 开发

```bash
python -m pytest          # 跑测试
python -m build           # 打包 sdist + wheel
python -m twine upload dist/*   # 发布（需 PyPI token）
```

## License

MIT © 2026 Chen (Jarry) Pan
