llmcapa 0.1.0__tar.gz

llmcapa-0.1.0/.gitignore

@@ -0,0 +1,144 @@
+# Byte-compiled / optimized / DLL support
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.flatpak-builder/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check those in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#1255, pipenv should generally not be check into control.
+#   However, if you're deploying an application, you can change this to include Pipfile.lock:
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially true for applications, but for libraries it is also recommended.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+
+# virtualenv
+.venv/
+venv/
+ENV/
+env/
+./env/
+./venv/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local env files
+.env
+.env.sec
+.env.local
+.env.*.local

llmcapa-0.1.0/DEVELOP.ja.md

@@ -0,0 +1,189 @@
+# 開発者ガイド
+
+このドキュメントでは、`llmcapa` ライブラリの開発、拡張、およびメンテナンス方法について説明します。
+
+---
+
+## プロジェクト構成
+
+```
+llmcapa/
+├── pyproject.toml          # ビルド設定 (Hatchling / PEP 621)
+├── LICENSE                 # Apache License 2.0
+├── README.md               # ユーザー向けドキュメント（英語）
+├── README.ja.md            # ユーザー向けドキュメント（日本語）
+├── DEVELOP.md              # 開発者ガイド（英語）
+├── DEVELOP.ja.md           # 開発者ガイド（日本語）
+├── src/llmcapa/
+│   ├── __init__.py         # 公開APIのエントリーポイント
+│   ├── models.py           # 機能データクラスと機能評価
+│   ├── registry.py         # インメモリレジストリ、ロード、およびOpenRouter取得
+│   ├── cli.py              # コマンドラインインターフェース
+│   └── data/               # 同梱されているオフライン機能データ (JSON)
+│       ├── __init__.py
+│       ├── openai.json
+│       ├── anthropic.json
+│       └── ...
+└── tests/                  # ユニットテスト (pytest)
+    ├── test_registry.py
+    ├── test_cache.py
+    └── test_advanced.py
+```
+
+---
+
+## 設計思想
+
+1. **オフラインファースト**: すべてのコア機能データは、パッケージ内にJSONファイルとして静的に同梱されています。標準的な検索時にネットワークリクエストは発生しません。
+2. **実行時依存関係ゼロ**: ライブラリはPython標準ライブラリのみで動作する必要があります。外部パッケージ（`pytest` や `build` など）は、開発およびテスト専用です。
+3. **不変性とパフォーマンス**: `Capability` データクラスは `frozen=True` です。機能チェック時の冗長な計算を避けるため、評価結果はメモ化（内部キャッシュ）されます。
+
+---
+
+## 新しいプロバイダーの追加
+
+新しいモデルプロバイダー（例: `cohere`）を追加する場合:
+
+### 1. データファイルの作成
+`src/llmcapa/data/<provider_name>.json` に新しいJSONファイルを作成します。
+
+```json
+{
+  "models": [
+    {
+      "provider": "cohere",
+      "model_id": "command-r-plus",
+      "display_name": "Command R+",
+      "context_window": 128000,
+      "max_output_tokens": 4000,
+      "input_modalities": ["text"],
+      "output_modalities": ["text"],
+      "supports_chat_completion": true,
+      "supports_function_calling": true,
+      "supports_json_mode": true,
+      "supports_streaming": true,
+      "supports_vision": false,
+      "supports_reasoning": false,
+      "tokenizer_name": "cohere-command",
+      "pricing": {
+        "input_per_1m": 2.5,
+        "output_per_1m": 10.0,
+        "currency": "USD"
+      },
+      "knowledge_cutoff": "2024-01",
+      "aliases": ["cohere/command-r-plus"]
+    }
+  ]
+}
+```
+
+### 2. プロバイダーテストリストの更新
+`tests/test_registry.py` を開き、`test_providers()` 内の `expected` セットに新しいプロバイダー名を追加します:
+
+```python
+def test_providers():
+    provs = llmcapa.providers()
+    expected = {
+        "openai", "anthropic", "google",
+        "xai", "meta", "mistral", "qwen", "deepseek", "nvidia",
+        "microsoft", "amazon", "ntt", "customer-cloud", "elyza",
+        "softbank", "nec", "fujitsu", "pfn",
+        "cohere",  # ここに追加
+    }
+    assert expected <= set(provs)
+```
+
+---
+
+## 新しい機能フラグの追加
+
+新しい機能フラグ（例: `supports_structured_outputs`）を追加する場合:
+
+### 1. データクラスの更新
+`src/llmcapa/models.py` を開き、`Capability` データクラスにデフォルト値を持つ新しいフィールドを追加します:
+
+```python
+@dataclass(frozen=True)
+class Capability:
+    ...
+    supports_structured_outputs: bool = False
+    ...
+```
+
+### 2. 代替モデルチェッカーの更新（任意）
+追加する機能が、あるモデルが別のモデルを代替できるか検証する際に必須となる重要な機能である場合、`src/llmcapa/models.py` 内の `can_be_replaced_by()` の `features_to_check` リリストに追加します:
+
+```python
+    def can_be_replaced_by(self, other: "Capability", required_features: Optional[List[str]] = None) -> bool:
+        ...
+        if required_features is None:
+            features_to_check = [
+                "vision", "function_calling", "json_mode", "streaming",
+                "reasoning", "chat_completion", "responses_api",
+                "reasoning_effort", "thinking_budget", "image_output",
+                "audio_output", "video_output",
+                "structured_outputs"  # ここに追加
+            ]
+            required_features = [f for f in features_to_check if self.supports(f)]
+        ...
+```
+
+### 3. JSONデータファイルの更新
+`src/llmcapa/data/` 配下の関連するモデルのJSONファイルに、新しいフィールドを追加します。
+
+### 4. ユニットテストの追加
+`tests/test_advanced.py` または `tests/test_registry.py` にテストケースを追加し、新しい機能フラグが正しくパース、評価、およびキャッシュされることを検証します。
+
+---
+
+## 開発ワークフロー
+
+### テストの実行
+テストには `pytest` を使用します。プロジェクトのルートディレクトリから以下のコマンドを実行します:
+
+```bash
+# PYTHONPATHにsrcディレクトリを追加
+set "PYTHONPATH=src;%PYTHONPATH%"
+python -m pytest -v
+```
+
+### コードの検証
+ビルドやコミットを行う前に、すべてのPythonファイルが正常にコンパイルできるか確認します:
+
+```bash
+python -m py_compile src/llmcapa/*.py tests/*.py
+```
+
+### パッケージのビルド
+ソース配布物（sdist）とwheelバイナリをビルドする場合:
+
+```bash
+# ビルド依存関係がインストールされていない場合はインストール
+pip install build hatchling
+
+# パッケージをビルド
+python -m build
+```
+
+ビルドされたファイルは `dist/` ディレクトリ配下に生成されます。
+
+---
+
+## OpenRouter マッピング詳細
+
+`fetch_openrouter()` が呼び出されると、OpenRouter APIのモデルスキーマは以下のように `Capability` データクラスにマッピングされます:
+
+| 機能フィールド | OpenRouter API フィールド | マッピングロジック / フォールバック |
+|---|---|---|
+| `model_id` | `id` | 完全一致 |
+| `display_name` | `name` | 存在しない場合は `id` にフォールバック |
+| `context_window` | `context_length` | `int` にキャスト、デフォルトは `0` |
+| `max_output_tokens` | `top_provider.max_completion_tokens` | `int` にキャスト、デフォルトは `0` |
+| `input_modalities` | `architecture.input_modalities` | デフォルトは `["text"]` |
+| `output_modalities` | `architecture.output_modalities` | デフォルトは `["text"]` |
+| `supports_function_calling` | `supported_parameters` | `"tools"` または `"tool_choice"` が存在すれば `True` |
+| `supports_json_mode` | `supported_parameters` | `"structured_outputs"` または `"response_format"` が存在すれば `True` |
+| `supports_reasoning` | `supported_parameters` | `"reasoning"` または `"include_reasoning"` が存在すれば `True` |
+| `supports_reasoning_effort` | `supported_parameters` | `"reasoning"` が存在すれば `True` |
+| `pricing` | `pricing` | `prompt` と `completion` のレートを100万トークンあたりのレートに変換 |
+| `aliases` | `id` | 小文字に変換された `id` がエイリアスとして追加されます |

llmcapa-0.1.0/DEVELOP.md

@@ -0,0 +1,187 @@
+# Developer Guide
+
+This document explains how to develop, extend, and maintain the `llmcapa` library.
+
+---
+
+## Project Structure
+
+```
+llmcapa/
+├── pyproject.toml          # Build configuration (Hatchling / PEP 621)
+├── LICENSE                 # Apache License 2.0
+├── README.md               # User documentation
+├── DEVELOP.md              # This guide
+├── src/llmcapa/
+│   ├── __init__.py         # Public API entry point
+│   ├── models.py           # Capability dataclass and feature evaluation
+│   ├── registry.py         # In-memory registry, loading, and OpenRouter fetching
+│   ├── cli.py              # Command-line interface
+│   └── data/               # Bundled offline capability data (JSON)
+│       ├── __init__.py
+│       ├── openai.json
+│       ├── anthropic.json
+│       └── ...
+└── tests/                  # Unit tests (pytest)
+    ├── test_registry.py
+    ├── test_cache.py
+    └── test_advanced.py
+```
+
+---
+
+## Design Philosophy
+
+1. **Offline-First**: All core capability data is bundled statically inside the package as JSON files. No network requests are made during standard lookups.
+2. **Zero Runtime Dependencies**: The library must run using only the Python standard library. External packages (like `pytest` or `build`) are strictly for development/testing.
+3. **Immutability & Performance**: The `Capability` dataclass is `frozen=True`. To avoid redundant calculations during feature checks, evaluation results are cached internally using memoization.
+
+---
+
+## Adding a New Provider
+
+To add a new model provider (e.g., `cohere`):
+
+### 1. Create a Data File
+Create a new JSON file under `src/llmcapa/data/<provider_name>.json`.
+
+```json
+{
+  "models": [
+    {
+      "provider": "cohere",
+      "model_id": "command-r-plus",
+      "display_name": "Command R+",
+      "context_window": 128000,
+      "max_output_tokens": 4000,
+      "input_modalities": ["text"],
+      "output_modalities": ["text"],
+      "supports_chat_completion": true,
+      "supports_function_calling": true,
+      "supports_json_mode": true,
+      "supports_streaming": true,
+      "supports_vision": false,
+      "supports_reasoning": false,
+      "tokenizer_name": "cohere-command",
+      "pricing": {
+        "input_per_1m": 2.5,
+        "output_per_1m": 10.0,
+        "currency": "USD"
+      },
+      "knowledge_cutoff": "2024-01",
+      "aliases": ["cohere/command-r-plus"]
+    }
+  ]
+}
+```
+
+### 2. Update the Provider Test List
+Open `tests/test_registry.py` and add your new provider name to the `expected` set in `test_providers()`:
+
+```python
+def test_providers():
+    provs = llmcapa.providers()
+    expected = {
+        "openai", "anthropic", "google",
+        "xai", "meta", "mistral", "qwen", "deepseek", "nvidia",
+        "microsoft", "amazon", "ntt", "customer-cloud", "elyza",
+        "softbank", "nec", "fujitsu", "pfn",
+        "cohere",  # Add here
+    }
+    assert expected <= set(provs)
+```
+
+---
+
+## Adding a New Feature Flag
+
+To add a new capability/feature flag (e.g., `supports_structured_outputs`):
+
+### 1. Update the Dataclass
+Open `src/llmcapa/models.py` and add the new field to the `Capability` dataclass with a default value:
+
+```python
+@dataclass(frozen=True)
+class Capability:
+    ...
+    supports_structured_outputs: bool = False
+    ...
+```
+
+### 2. Update the Replacement Checker (Optional)
+If the new feature is a critical capability that should be verified when checking if one model can replace another, add it to the `features_to_check` list in `can_be_replaced_by()` inside `src/llmcapa/models.py`:
+
+```python
+    def can_be_replaced_by(self, other: "Capability", required_features: Optional[List[str]] = None) -> bool:
+        ...
+        if required_features is None:
+            features_to_check = [
+                "vision", "function_calling", "json_mode", "streaming",
+                "reasoning", "chat_completion", "responses_api",
+                "reasoning_effort", "thinking_budget", "image_output",
+                "audio_output", "video_output",
+                "structured_outputs"  # Add here
+            ]
+            required_features = [f for f in features_to_check if self.supports(f)]
+        ...
+```
+
+### 3. Update JSON Data Files
+Add the new field to the relevant models in the JSON files under `src/llmcapa/data/`.
+
+### 4. Add Unit Tests
+Add test cases in `tests/test_advanced.py` or `tests/test_registry.py` to verify that the new feature flag is correctly parsed, evaluated, and cached.
+
+---
+
+## Development Workflow
+
+### Running Tests
+We use `pytest` for testing. Run the following command from the project root directory:
+
+```bash
+# Set PYTHONPATH to include the src directory
+set "PYTHONPATH=src;%PYTHONPATH%"
+python -m pytest -v
+```
+
+### Code Verification
+Before building or committing, verify that all Python files compile successfully:
+
+```bash
+python -m py_compile src/llmcapa/*.py tests/*.py
+```
+
+### Building the Package
+To build the source distribution (sdist) and wheel binary:
+
+```bash
+# Install build dependencies if not already installed
+pip install build hatchling
+
+# Build the package
+python -m build
+```
+
+The built files will be generated under the `dist/` directory.
+
+---
+
+## OpenRouter Mapping Details
+
+When `fetch_openrouter()` is called, it maps the OpenRouter API model schema to our `Capability` dataclass as follows:
+
+| Capability Field | OpenRouter API Field | Mapping Logic / Fallback |
+|---|---|---|
+| `model_id` | `id` | Exact match |
+| `display_name` | `name` | Falls back to `id` if missing |
+| `context_window` | `context_length` | Cast to `int`, default `0` |
+| `max_output_tokens` | `top_provider.max_completion_tokens` | Cast to `int`, default `0` |
+| `input_modalities` | `architecture.input_modalities` | Default `["text"]` |
+| `output_modalities` | `architecture.output_modalities` | Default `["text"]` |
+| `supports_function_calling` | `supported_parameters` | `True` if `"tools"` or `"tool_choice"` is present |
+| `supports_json_mode` | `supported_parameters` | `True` if `"structured_outputs"` or `"response_format"` is present |
+| `supports_reasoning` | `supported_parameters` | `True` if `"reasoning"` or `"include_reasoning"` is present |
+| `supports_reasoning_effort` | `supported_parameters` | `True` if `"reasoning"` is present |
+| `pricing` | `pricing` | Converts `prompt` and `completion` rates to per-1M token rates |
+| `aliases` | `id` | Lowercased `id` is added as an alias |