lab-cost-tracker 0.1.0__tar.gz

lab_cost_tracker-0.1.0/LICENSE

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

lab_cost_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: lab-cost-tracker
+Version: 0.1.0
+Summary: Lightweight API cost tracker for research labs
+License: MIT
+Project-URL: Repository, https://github.com/your-org/lab-cost-tracker
+Keywords: llm,cost-tracking,openai,gemini,anthropic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == "gemini"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: google
+Requires-Dist: google-auth>=2.0; extra == "google"
+Requires-Dist: google-auth-oauthlib>=1.0; extra == "google"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: google-genai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.30; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# Lab Cost Tracker SDK
+
+轻量级 Python SDK，为研究组透明追踪 LLM API 调用费用。一行 `tracker.wrap()` 包裹现有 client，自动记录每次调用的模型、token 数和费用。
+
+## 支持的 Provider
+
+| Provider | Client 类型 | 拦截方法 |
+|----------|------------|---------|
+| OpenAI 官方 | `openai.OpenAI` | `chat.completions.create()` |
+| Google Gemini | `google.genai.Client` | `models.generate_content()` |
+| Anthropic | `anthropic.Anthropic` | `messages.create()` |
+| 第三方代理 | `openai.OpenAI(base_url=...)` | 同 OpenAI（自动记录 `base_url`） |
+
+## 安装
+
+```bash
+# 基础安装（仅需 pyyaml + requests）
+pip install -e .
+
+# 安装 OpenAI 支持
+pip install -e ".[openai]"
+
+# 安装 Google OAuth 支持（可选，用于身份验证）
+pip install -e ".[google]"
+
+# 全部安装
+pip install -e ".[openai,google]"
+```
+
+## 快速开始
+
+### 1. OpenAI
+
+```python
+from openai import OpenAI
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(
+    project="DentalVLM",
+    user="kyle@aucklanduni.ac.nz",
+    storage_dir="./.cost-tracker",  # 费用数据保存目录（默认值，可省略）
+)
+
+client = tracker.wrap(OpenAI(api_key="sk-..."))
+
+# 正常使用，费用自动记录
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(tracker.summary())
+```
+
+### 2. Google Gemini
+
+```python
+from google import genai
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+client = tracker.wrap(genai.Client(api_key="..."))
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    contents="用一句话介绍新西兰奥克兰大学。",
+)
+
+print(tracker.summary())
+```
+
+### 3. Anthropic
+
+```python
+import anthropic
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+client = tracker.wrap(anthropic.Anthropic(api_key="..."))
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(tracker.summary())
+```
+
+### 4. 第三方代理（如 apiyihe.org）
+
+```python
+from openai import OpenAI
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+# 使用 OpenAI SDK + 自定义 base_url
+client = tracker.wrap(OpenAI(
+    api_key="...",
+    base_url="https://z.apiyihe.org/v1",
+))
+
+# 可以调用任何模型，base_url 会自动记录在 detail.jsonl 中
+response = client.chat.completions.create(
+    model="gemini-2.5-flash-lite-preview-06-17",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+### 5. 手动记录（不支持的 Provider）
+
+```python
+tracker.record(
+    model="llama-3-8b",
+    prompt_tokens=1000,
+    completion_tokens=500,
+    task="inference",
+    dataset="DentalBench",
+)
+```
+
+## 数据存储
+
+运行后会在 `storage_dir`（默认 `{项目根目录}/.cost-tracker/`）下生成两个文件：
+
+### `detail.jsonl` — 逐条调用记录
+
+```json
+{"id": "42ae...", "timestamp": "2026-05-19T...", "project": "DentalVLM", "user": "kyle@aucklanduni.ac.nz", "model": "gpt-4o-mini-2024-07-18", "prompt_tokens": 19, "completion_tokens": 33, "cost_usd": 0.00059, "metadata": {"provider": "openai", "base_url": "https://api.openai.com/v1"}, "synced": false}
+```
+
+### `summary.json` — 聚合统计
+
+```json
+{
+  "project": "DentalVLM",
+  "total_cost_usd": 0.012,
+  "total_requests": 5,
+  "by_model": {
+    "gpt-4o-mini": {"cost_usd": 0.0006, "requests": 2},
+    "gemini-2.5-flash": {"cost_usd": 0.0005, "requests": 1}
+  },
+  "by_user": {
+    "kyle@aucklanduni.ac.nz": {"cost_usd": 0.012, "requests": 5}
+  }
+}
+```
+
+## 内置定价表
+
+SDK 内置了常用模型的定价（USD / 1M tokens）：
+
+| 模型 | 输入价格 | 输出价格 |
+|------|---------|---------|
+| gpt-4o | $5.00 | $15.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+| o1 | $15.00 | $60.00 |
+| o3-mini | $1.10 | $4.40 |
+| gemini-2.5-pro | $1.25 | $10.00 |
+| gemini-2.5-flash | $0.15 | $0.60 |
+| claude-3-5-sonnet | $3.00 | $15.00 |
+| claude-3-5-haiku | $0.80 | $4.00 |
+
+自定义定价：
+
+```python
+tracker.pricing.set("my-local-model", "ollama", input_per_1m=0.0, output_per_1m=0.0)
+```
+
+或通过 `.cost-tracker.yaml` 配置文件：
+
+```yaml
+project: DentalVLM
+costs_dir: .cost-tracker
+pricing:
+  my-local-model:
+    provider: ollama
+    input_per_1m: 0.0
+    output_per_1m: 0.0
+```
+
+## 配置优先级
+
+```
+显式参数  >  环境变量  >  .cost-tracker.yaml  >  默认值
+```
+
+| 环境变量 | 说明 |
+|----------|------|
+| `COST_TRACKER_PROJECT` | 项目名称 |
+| `COST_TRACKER_USER` | 用户邮箱 |
+| `COST_TRACKER_REMOTE_URL` | 远端 API 地址 |
+
+## 项目结构
+
+```
+sdk/
+├── lab_cost_tracker/         # SDK 包（发布到 PyPI 的内容）
+│   ├── __init__.py           # 公共 API: CostTracker, PricingCatalog
+│   ├── tracker.py            # 主入口，wrap() / record() / summary()
+│   ├── wrapper.py            # 多 Provider 适配器（自动检测 + monkey-patch）
+│   ├── pricing.py            # 内置定价表 + 自定义覆盖
+│   ├── storage.py            # 本地双文件存储（detail.jsonl + summary.json）
+│   ├── sync.py               # 后台同步到远端 API（可选）
+│   ├── config.py             # YAML / env 配置加载
+│   └── auth.py               # Google OAuth 登录（可选）
+├── tests/                    # 自动化测试（Mock，不需要 API key）
+│   └── test_all_providers.py
+├── examples/                 # 使用示例（需要 API key）
+│   ├── openai_demo.py
+│   ├── gemini_demo.py
+│   └── proxy_demo.py
+├── pyproject.toml            # 包配置
+├── README.md
+└── LICENSE
+```

lab_cost_tracker-0.1.0/README.md

@@ -0,0 +1,219 @@
+# Lab Cost Tracker SDK
+
+轻量级 Python SDK，为研究组透明追踪 LLM API 调用费用。一行 `tracker.wrap()` 包裹现有 client，自动记录每次调用的模型、token 数和费用。
+
+## 支持的 Provider
+
+| Provider | Client 类型 | 拦截方法 |
+|----------|------------|---------|
+| OpenAI 官方 | `openai.OpenAI` | `chat.completions.create()` |
+| Google Gemini | `google.genai.Client` | `models.generate_content()` |
+| Anthropic | `anthropic.Anthropic` | `messages.create()` |
+| 第三方代理 | `openai.OpenAI(base_url=...)` | 同 OpenAI（自动记录 `base_url`） |
+
+## 安装
+
+```bash
+# 基础安装（仅需 pyyaml + requests）
+pip install -e .
+
+# 安装 OpenAI 支持
+pip install -e ".[openai]"
+
+# 安装 Google OAuth 支持（可选，用于身份验证）
+pip install -e ".[google]"
+
+# 全部安装
+pip install -e ".[openai,google]"
+```
+
+## 快速开始
+
+### 1. OpenAI
+
+```python
+from openai import OpenAI
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(
+    project="DentalVLM",
+    user="kyle@aucklanduni.ac.nz",
+    storage_dir="./.cost-tracker",  # 费用数据保存目录（默认值，可省略）
+)
+
+client = tracker.wrap(OpenAI(api_key="sk-..."))
+
+# 正常使用，费用自动记录
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(tracker.summary())
+```
+
+### 2. Google Gemini
+
+```python
+from google import genai
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+client = tracker.wrap(genai.Client(api_key="..."))
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    contents="用一句话介绍新西兰奥克兰大学。",
+)
+
+print(tracker.summary())
+```
+
+### 3. Anthropic
+
+```python
+import anthropic
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+client = tracker.wrap(anthropic.Anthropic(api_key="..."))
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(tracker.summary())
+```
+
+### 4. 第三方代理（如 apiyihe.org）
+
+```python
+from openai import OpenAI
+from lab_cost_tracker import CostTracker
+
+tracker = CostTracker(project="DentalVLM", user="kyle@aucklanduni.ac.nz")
+
+# 使用 OpenAI SDK + 自定义 base_url
+client = tracker.wrap(OpenAI(
+    api_key="...",
+    base_url="https://z.apiyihe.org/v1",
+))
+
+# 可以调用任何模型，base_url 会自动记录在 detail.jsonl 中
+response = client.chat.completions.create(
+    model="gemini-2.5-flash-lite-preview-06-17",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+### 5. 手动记录（不支持的 Provider）
+
+```python
+tracker.record(
+    model="llama-3-8b",
+    prompt_tokens=1000,
+    completion_tokens=500,
+    task="inference",
+    dataset="DentalBench",
+)
+```
+
+## 数据存储
+
+运行后会在 `storage_dir`（默认 `{项目根目录}/.cost-tracker/`）下生成两个文件：
+
+### `detail.jsonl` — 逐条调用记录
+
+```json
+{"id": "42ae...", "timestamp": "2026-05-19T...", "project": "DentalVLM", "user": "kyle@aucklanduni.ac.nz", "model": "gpt-4o-mini-2024-07-18", "prompt_tokens": 19, "completion_tokens": 33, "cost_usd": 0.00059, "metadata": {"provider": "openai", "base_url": "https://api.openai.com/v1"}, "synced": false}
+```
+
+### `summary.json` — 聚合统计
+
+```json
+{
+  "project": "DentalVLM",
+  "total_cost_usd": 0.012,
+  "total_requests": 5,
+  "by_model": {
+    "gpt-4o-mini": {"cost_usd": 0.0006, "requests": 2},
+    "gemini-2.5-flash": {"cost_usd": 0.0005, "requests": 1}
+  },
+  "by_user": {
+    "kyle@aucklanduni.ac.nz": {"cost_usd": 0.012, "requests": 5}
+  }
+}
+```
+
+## 内置定价表
+
+SDK 内置了常用模型的定价（USD / 1M tokens）：
+
+| 模型 | 输入价格 | 输出价格 |
+|------|---------|---------|
+| gpt-4o | $5.00 | $15.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+| o1 | $15.00 | $60.00 |
+| o3-mini | $1.10 | $4.40 |
+| gemini-2.5-pro | $1.25 | $10.00 |
+| gemini-2.5-flash | $0.15 | $0.60 |
+| claude-3-5-sonnet | $3.00 | $15.00 |
+| claude-3-5-haiku | $0.80 | $4.00 |
+
+自定义定价：
+
+```python
+tracker.pricing.set("my-local-model", "ollama", input_per_1m=0.0, output_per_1m=0.0)
+```
+
+或通过 `.cost-tracker.yaml` 配置文件：
+
+```yaml
+project: DentalVLM
+costs_dir: .cost-tracker
+pricing:
+  my-local-model:
+    provider: ollama
+    input_per_1m: 0.0
+    output_per_1m: 0.0
+```
+
+## 配置优先级
+
+```
+显式参数  >  环境变量  >  .cost-tracker.yaml  >  默认值
+```
+
+| 环境变量 | 说明 |
+|----------|------|
+| `COST_TRACKER_PROJECT` | 项目名称 |
+| `COST_TRACKER_USER` | 用户邮箱 |
+| `COST_TRACKER_REMOTE_URL` | 远端 API 地址 |
+
+## 项目结构
+
+```
+sdk/
+├── lab_cost_tracker/         # SDK 包（发布到 PyPI 的内容）
+│   ├── __init__.py           # 公共 API: CostTracker, PricingCatalog
+│   ├── tracker.py            # 主入口，wrap() / record() / summary()
+│   ├── wrapper.py            # 多 Provider 适配器（自动检测 + monkey-patch）
+│   ├── pricing.py            # 内置定价表 + 自定义覆盖
+│   ├── storage.py            # 本地双文件存储（detail.jsonl + summary.json）
+│   ├── sync.py               # 后台同步到远端 API（可选）
+│   ├── config.py             # YAML / env 配置加载
+│   └── auth.py               # Google OAuth 登录（可选）
+├── tests/                    # 自动化测试（Mock，不需要 API key）
+│   └── test_all_providers.py
+├── examples/                 # 使用示例（需要 API key）
+│   ├── openai_demo.py
+│   ├── gemini_demo.py
+│   └── proxy_demo.py
+├── pyproject.toml            # 包配置
+├── README.md
+└── LICENSE
+```

lab_cost_tracker-0.1.0/lab_cost_tracker/__init__.py

@@ -0,0 +1,7 @@
+"""lab_cost_tracker — lightweight API cost tracking SDK."""
+
+from lab_cost_tracker.tracker import CostTracker
+from lab_cost_tracker.pricing import PricingCatalog
+
+__all__ = ["CostTracker", "PricingCatalog"]
+__version__ = "0.1.0"

lab_cost_tracker-0.1.0/lab_cost_tracker/auth.py

@@ -0,0 +1,162 @@
+"""
+Google OAuth authentication for lab members.
+
+Uses Google OAuth 2.0 to authenticate users with their university email.
+Tokens are cached locally to avoid repeated login prompts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+_TOKEN_CACHE_DIR = Path.home() / ".config" / "lab-cost-tracker"
+_TOKEN_CACHE_FILE = _TOKEN_CACHE_DIR / "credentials.json"
+
+# Default OAuth client — users can override via env or config
+_DEFAULT_CLIENT_ID = os.getenv("COST_TRACKER_GOOGLE_CLIENT_ID", "")
+_DEFAULT_CLIENT_SECRET = os.getenv("COST_TRACKER_GOOGLE_CLIENT_SECRET", "")
+_SCOPES = ["openid", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile"]
+
+
+class AuthInfo:
+    """Authenticated user info."""
+    def __init__(self, email: str, name: str, id_token: str, access_token: str):
+        self.email = email
+        self.name = name
+        self.id_token = id_token
+        self.access_token = access_token
+
+    def to_dict(self) -> dict:
+        return {"email": self.email, "name": self.name}
+
+
+def login(
+    client_id: Optional[str] = None,
+    client_secret: Optional[str] = None,
+    allowed_domains: Optional[list[str]] = None,
+) -> AuthInfo:
+    """
+    Perform Google OAuth login. Opens a browser for consent on first use,
+    then caches the refresh token for subsequent runs.
+
+    Args:
+        client_id: Google OAuth client ID (or set COST_TRACKER_GOOGLE_CLIENT_ID)
+        client_secret: Google OAuth client secret (or set COST_TRACKER_GOOGLE_CLIENT_SECRET)
+        allowed_domains: If set, reject emails not matching these domains (e.g. ["aucklanduni.ac.nz"])
+
+    Returns:
+        AuthInfo with email, name, and tokens.
+    """
+    try:
+        from google_auth_oauthlib.flow import InstalledAppFlow
+        from google.oauth2.credentials import Credentials
+        from google.auth.transport.requests import Request
+    except ImportError:
+        raise ImportError(
+            "Google auth libraries required. Install with: "
+            "pip install google-auth google-auth-oauthlib"
+        )
+
+    cid = client_id or _DEFAULT_CLIENT_ID
+    csecret = client_secret or _DEFAULT_CLIENT_SECRET
+    if not cid or not csecret:
+        raise ValueError(
+            "Google OAuth client_id and client_secret are required. "
+            "Set COST_TRACKER_GOOGLE_CLIENT_ID and COST_TRACKER_GOOGLE_CLIENT_SECRET "
+            "environment variables, or pass them directly."
+        )
+
+    creds = _load_cached_credentials()
+
+    # Try to refresh existing credentials
+    if creds and creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except Exception:
+            creds = None
+
+    # No valid credentials — run OAuth flow
+    if not creds or not creds.valid:
+        client_config = {
+            "installed": {
+                "client_id": cid,
+                "client_secret": csecret,
+                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                "token_uri": "https://oauth2.googleapis.com/token",
+                "redirect_uris": ["http://localhost"],
+            }
+        }
+        flow = InstalledAppFlow.from_client_config(client_config, _SCOPES)
+        creds = flow.run_local_server(port=0, prompt="consent")
+        _save_cached_credentials(creds)
+
+    # Get user info
+    import requests as req
+    resp = req.get(
+        "https://www.googleapis.com/oauth2/v3/userinfo",
+        headers={"Authorization": f"Bearer {creds.token}"},
+    )
+    resp.raise_for_status()
+    user_info = resp.json()
+
+    email = user_info.get("email", "")
+    name = user_info.get("name", email.split("@")[0])
+
+    # Domain check
+    if allowed_domains:
+        domain = email.split("@")[-1] if "@" in email else ""
+        if domain not in allowed_domains:
+            raise PermissionError(
+                f"Email domain '{domain}' is not allowed. "
+                f"Allowed domains: {allowed_domains}"
+            )
+
+    return AuthInfo(
+        email=email,
+        name=name,
+        id_token=creds.token,
+        access_token=creds.token,
+    )
+
+
+def _load_cached_credentials():
+    """Load cached Google OAuth credentials from disk."""
+    try:
+        from google.oauth2.credentials import Credentials
+    except ImportError:
+        return None
+
+    if not _TOKEN_CACHE_FILE.exists():
+        return None
+    try:
+        with open(_TOKEN_CACHE_FILE, "r") as f:
+            data = json.load(f)
+        return Credentials(
+            token=data.get("token"),
+            refresh_token=data.get("refresh_token"),
+            token_uri=data.get("token_uri", "https://oauth2.googleapis.com/token"),
+            client_id=data.get("client_id"),
+            client_secret=data.get("client_secret"),
+            scopes=data.get("scopes"),
+        )
+    except Exception:
+        return None
+
+
+def _save_cached_credentials(creds):
+    """Cache credentials to disk for reuse."""
+    _TOKEN_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    data = {
+        "token": creds.token,
+        "refresh_token": creds.refresh_token,
+        "token_uri": creds.token_uri,
+        "client_id": creds.client_id,
+        "client_secret": creds.client_secret,
+        "scopes": list(creds.scopes) if creds.scopes else _SCOPES,
+    }
+    with open(_TOKEN_CACHE_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+    os.chmod(_TOKEN_CACHE_FILE, 0o600)  # restrict permissions