Metadata-Version: 2.4
Name: oss-metrics-kit
Version: 0.0.1
Summary: Unified toolkit to fetch, normalize, score, and export OSS contribution metrics.
Project-URL: Homepage, https://github.com/refactoring-my-path/oss-metrics-kit
Project-URL: Repository, https://github.com/refactoring-my-path/oss-metrics-kit
Project-URL: Issues, https://github.com/refactoring-my-path/oss-metrics-kit/issues
Project-URL: Documentation, https://github.com/refactoring-my-path/oss-metrics-kit/tree/main/docs
Author: refactoring-my-path
License: Apache-2.0
License-File: LICENSE
Keywords: cli,github,metrics,oss,parquet,scoring
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: rich>=13
Requires-Dist: structlog>=24.1
Requires-Dist: tenacity>=8.2
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: duckdb>=1.0; extra == 'all'
Requires-Dist: pyarrow>=15; extra == 'all'
Provides-Extra: exporters-parquet
Requires-Dist: pyarrow>=15; extra == 'exporters-parquet'
Provides-Extra: exporters-postgres
Requires-Dist: psycopg[binary]>=3.2; extra == 'exporters-postgres'
Provides-Extra: github-app
Requires-Dist: pyjwt[crypto]>=2.9; extra == 'github-app'
Provides-Extra: llm-anthropic
Requires-Dist: anthropic>=0.34; extra == 'llm-anthropic'
Provides-Extra: llm-openai
Requires-Dist: openai>=1.40; extra == 'llm-openai'
Provides-Extra: metrics
Requires-Dist: opentelemetry-api>=1.24; extra == 'metrics'
Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
Provides-Extra: redis
Requires-Dist: redis>=5; extra == 'redis'
Provides-Extra: sentry
Requires-Dist: sentry-sdk>=2.13; extra == 'sentry'
Provides-Extra: storage-duckdb
Requires-Dist: duckdb>=1.0; extra == 'storage-duckdb'
Requires-Dist: pyarrow>=15; extra == 'storage-duckdb'
Description-Content-Type: text/markdown

# oss-metrics-kit

OSSの貢献データを「収集 → 正規化 → 指標算出 → 出力」まで一気通貫で扱うための基盤ライブラリ。

現状: スタブ実装（CLI/エントリポイント/型モデルのみ）。ここから段階的に機能を追加します。

## インストール（開発モード）

以下はいずれかを実行してください。Conda/venv など任意の仮想環境上で実行を推奨します。

- `pip install -e .` もしくは
- `python -m pip install -e .`

インストール後、以下でCLIのヘルプを確認できます。

- `ossmk --help`

注意: インストールせずに `ossmk` は使えません。開発中に直接実行したい場合は `pip install -e .` を行うか、`PYTHONPATH=src` を設定しつつエントリポイント経由で呼び出してください。

## 開発環境（uv推奨）

超高速パッケージマネージャー「uv」を利用すると、依存解決・仮想環境の同期が簡単になります。

1) uvのインストール（どれか一つ）
- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Homebrew: `brew install uv`
- pipx: `pipx install uv`

2) 仮想環境の作成と同期
- `uv venv .venv`（任意）→ `source .venv/bin/activate`
- 依存同期（本体＋開発用）: `uv sync --dev`
- すべてのエクストラも入れる場合: `uv sync --dev --extra all`

3) 実行
- `ossmk --help`（アクティベート済みの場合）
- もしくは環境を活性化せずに: `uv run ossmk --help`

## PyPIインストール（利用者向け）

- 安定版のインストール: `pip install oss-metrics-kit`
- Postgres連携込み: `pip install "oss-metrics-kit[exporters-postgres]"`

インストール後に `ossmk --help` が動作すればOKです。

## あなたのGitHubアカウントで試す

前提: GitHubトークンを環境に設定します（read-only 権限で十分）。

```bash
export GITHUB_TOKEN=ghp_xxx   # or GH_TOKEN
```

分析（サマリ＋スコア出力）

```bash
ossmk analyze-user <your_github_login> --out -
```

スコアをPostgresに保存（任意）

```bash
export OSSMK_PG_DSN="postgresql://user:pass@host:5432/db"
ossmk analyze-user <your_github_login> --save-pg
```

プロプライエタリな重み付け（任意）

```bash
export OSSMK_RULES_FILE=/absolute/path/to/private/rules.toml
ossmk analyze-user <your_github_login> --out -
```

## 使い方（概要）

- バージョン表示: `ossmk version`
- GitHubユーザーを分析（並列取得・since/GraphQL対応）: `ossmk analyze-user <login> --since 90d --api auto --out -`
- `<login>` は GitHub のユーザー名（プロフィールURLが `https://github.com/<login>` の `<login>` 部分。例: `torvalds`, `octocat`, `refactoring-my-path`）
- 単一リポのイベント取得: `ossmk fetch --provider github --repo owner/name --since 30d --out -`
- スコア保存（DB切替え可能）: `ossmk save postgresql://... --input scores.json` または `ossmk save sqlite:///./metrics.db --input scores.json`

ストレージはDSNで切り替え（Postgres/SQLite）。Parquetはオプション機能（分析用）です。

### LLMベースのルール支援（任意）

- ルール提案: `ossmk rules-llm --input events.json --provider openai --model gpt-4o-mini --out rules.toml`
- 必要なエクストラ: `pip install "oss-metrics-kit[llm-openai]"` または `oss-metrics-kit[llm-anthropic]`
- 詳細: `docs/LLM_RULES.md`

## セキュリティと運用の要点

- トークンは環境変数（`GITHUB_TOKEN`/`GH_TOKEN`）で管理し、ログに出さない。
- レート制限はバックエンドの責務。例として `ossmk.security.ratelimit.RateLimiter` を提供（本番はRedis等で共有化）。
- 私有ルール（TOML）はリポ外に保管し、`OSSMK_RULES_FILE` で指定。`rules=auto|default` で自動ロード。
- 依存はエクストラで分離（Postgres/Parquet/LLM）。最小構成で運用可能。

バックエンド統合の詳細は `docs/INTEGRATION.md` を参照。開発時の型/リント方針は `docs/dev.md`。
一般ユーザー向けの詳しい使い方は `docs/usage.md` を参照。

## 環境変数（まとめ）

- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub APIトークン（必須）
- `OSSMK_RULES_FILE`: 私有ルールTOMLへのパス（任意）
- `OSSMK_PG_DSN` or `DATABASE_URL`: Postgres DSN（保存時に使用する場合）
- `REDIS_URL`: Redisレートリミッタで使用（任意）
- `OSSMK_MAX_SINCE_DAYS`: `since` の最大日数（デフォルト180）

## PyPI公開手順（メンテナ向け）

準備

- PyPIアカウント作成 → API Token発行（スコープ: Upload）。
- ローカルでビルド&公開に使うツールを準備。

バージョニング/タグ

- `pyproject.toml` の `version` を SemVer で更新
- `git commit` → `git tag vX.Y.Z` → `git push --tags`

ビルド（uv 推奨）

```bash
uv build                 # sdist(.tar.gz) + wheel(.whl) を dist/ に出力

# TestPyPIに公開（推奨）
export PYPI_TOKEN_TEST=...  # pypi- で始まるトークン
uv publish --repository testpypi --token "$PYPI_TOKEN_TEST"

# 本番PyPIに公開（Tagと一致する版を公開）
export PYPI_TOKEN=...
uv publish --token "$PYPI_TOKEN"
```

twineを使う場合（代替）

```bash
python -m pip install build twine
python -m build          # sdist + wheel を dist/ に出力

# アーカイブの健全性チェック（署名/メタデータ）
python -m twine check dist/*

# TestPyPI
twine upload --repository testpypi -u __token__ -p "$PYPI_TOKEN_TEST" dist/*

# PyPI
twine upload -u __token__ -p "$PYPI_TOKEN" dist/*
```

注意点

- バージョンはSemVerで更新し、同じ版の再アップロードは不可です。
- `pyproject.toml` のメタデータ（URL/ライセンス/説明）が公開ページに反映されます。
- sdist と wheel の両方を用意すると、利用者環境でのインストール成功率が上がります。
- TestPyPI で動作確認→本番PyPIへ昇格の順を推奨します。

## 設計ハイライト

- `src/` レイアウト＋ `py.typed` による型配布。
- CLIはTyperで薄く、ビジネスロジックは `ossmk.core` に集約。
- providers/exporters/storage/rules はエントリポイントでプラガブル。

## トラブルシューティング

- `pip._vendor.tomli.TOMLDecodeError: Invalid initial character for a key part (at line 1, column 2)`
  - 原因: `pyproject.toml` の先頭セクションが不正（`[build-system]` の直前に余計な文字がある）
  - 対処: 先頭行を `[build-system]` に修正済み。リトライ前にキャッシュを避けるため `pip install -e .` を再実行してください。

- `ossmk: command not found`
  - 原因: パッケージ未インストール、または別環境でインストール。
  - 対処: リポジトリ直下で `pip install -e .` を実行。Conda/venv を使用している場合は、同じ環境を `activate` 済みか確認。
  - uv利用時: `uv sync --dev` 後に `source .venv/bin/activate`、または `uv run ossmk --help` を使用。

## ライセンス

Apache-2.0
