# oss-metrics-kit
Toolkit to fetch, normalize, score, and export OSS contribution data — end to end.
Status: early stage; CLI and core models are available and expanding.
What you can do in 5 minutes
- Analyze a GitHub user’s activity and get a simple score summary.
- Save scores into SQLite or Postgres for dashboards.
- Export scores to Parquet for data tools.
- Optionally, let an LLM suggest a rules TOML from your events.
## Quick Start (Beginner-friendly)
1) Install the package (pick one)
- pip (recommended for users): `pip install oss-metrics-kit`
- uv (recommended for devs): `uv venv .venv && source .venv/bin/activate && uv sync --dev`
2) Set a GitHub token (read-only is enough)
```
export GITHUB_TOKEN=ghp_xxx # or GH_TOKEN
```
3) Analyze your account and print results
```
ossmk analyze-user <your_github_login> --since 90d --api auto --out -
```
4) Save scores (SQLite for a quick try)
```
ossmk analyze-user <your_github_login> --out scores.json
ossmk save sqlite:///./metrics.db --input scores.json
```
5) Export scores to Parquet (for data tools)
```
pip install "oss-metrics-kit[exporters-parquet]"
ossmk analyze-user <your_github_login> --out parquet:./scores.parquet
```
That’s it. See Getting Started for more step‑by‑step details.
## Getting Started (Step-by-step)
If you are new to Python tools or GitHub APIs, read:
- docs/getting-started.md — a gentle, copy‑paste tutorial with expected outputs.
- docs/usage.md — command reference with CI examples.
## Install (development)
Use a virtual environment (venv/conda/uv) and install editable:
- `pip install -e .` or `python -m pip install -e .`
- Check CLI help with `ossmk --help`
Note: Running `ossmk` requires installation. For direct runs during development, either install editable or set `PYTHONPATH=src` and run the entry point.
## Dev environment (uv recommended)
1) Install uv
- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Homebrew: `brew install uv`
- pipx: `pipx install uv`
2) Create venv and sync deps
- `uv venv .venv` → `source .venv/bin/activate`
- `uv sync --dev`
- All extras: `uv sync --dev --extra all`
3) Run
- `ossmk --help` (in venv) or `uv run ossmk --help`
## Install from PyPI (users)
- Stable: `pip install oss-metrics-kit`
- With Postgres exporter: `pip install "oss-metrics-kit[exporters-postgres]"`
## Examples
- Persist scores to Postgres:
```
export OSSMK_PG_DSN="postgresql://user:pass@host:5432/db"
ossmk analyze-user <your_github_login> --save-pg
```
- Load proprietary rules (TOML):
```
export OSSMK_RULES_FILE=/absolute/path/to/private/rules.toml
ossmk analyze-user <your_github_login> --out -
```
## Usage (overview)
- Version: `ossmk version`
- Analyze GitHub user (parallel fetch, since/GraphQL aware): `ossmk analyze-user <login> --since 90d --api auto --out -`
- Fetch repo events: `ossmk fetch --provider github --repo owner/name --since 30d --out -`
- Save scores: `ossmk save postgresql://... --input scores.json` or `ossmk save sqlite:///./metrics.db --input scores.json`
Storage is selected via DSN (Postgres/SQLite). Parquet output is available as an optional exporter.
### LLM-assisted rules (optional)
- Suggest rules: `ossmk rules-llm --input events.json --provider openai --model gpt-4o-mini --out rules.toml`
- Extras: `pip install "oss-metrics-kit[llm-openai]"` or `oss-metrics-kit[llm-anthropic]`
- See `docs/LLM_RULES.md`
## Security & operations
- Keep tokens in env (`GITHUB_TOKEN`/`GH_TOKEN`) and never log them.
- Rate limiting is a backend responsibility; a simple example is provided at `ossmk.security.ratelimit.RateLimiter` (use Redis for production).
- Store private rule TOMLs outside the repo and point `OSSMK_RULES_FILE` to them. `rules=auto|default` will load it.
- Optional features (Postgres/Parquet/LLM) are separated as extras.
See `docs/INTEGRATION.md` for backend integration. Development typing/lint policy: `docs/dev.md`. Detailed usage: `docs/usage.md`. A beginner tutorial is in `docs/getting-started.md`.
## Python API (import)
The canonical import is:
```
import ossmk
```
For convenience, the underscore variant also works and maps to the same package:
```
import oss_metrics_kit as ossmk
```
## Environment variables
- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub API token (required)
- `OSSMK_RULES_FILE`: path to a private rules TOML (optional)
- `OSSMK_PG_DSN` or `DATABASE_URL`: Postgres DSN (if persisting)
- `REDIS_URL`: Redis rate limiter (optional)
- `OSSMK_MAX_SINCE_DAYS`: max backward window for `since` (default 180)
## Publishing to PyPI (maintainers)
See `docs/RELEASING.md` for the full release flow (versioning, tagging, CI-based publish, and manual alternatives).
## Design highlights
- `src/` layout with `py.typed` for type distribution.
- Thin CLI with Typer; business logic in `ossmk.core`.
- Providers/exporters/storage/rules via entry points.
## Troubleshooting
- `pip._vendor.tomli.TOMLDecodeError: Invalid initial character...`
- Cause: malformed leading section in `pyproject.toml`
- Fix: ensure first section is `[build-system]`, reinstall `pip install -e .`
- `ossmk: command not found`
- Cause: not installed or wrong environment activated.
- Fix: `pip install -e .` in the repo, and activate the same environment.
- With uv: `uv sync --dev` then `source .venv/bin/activate`, or `uv run ossmk --help`.
## License
Apache-2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "oss-metrics-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, github, metrics, oss, parquet, scoring",
"author": "refactoring-my-path",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/74/fb/50b9d38aef38dfb9b6526f24c40107a3681d94582fe3222a420f3286d878/oss_metrics_kit-0.1.1.tar.gz",
"platform": null,
"description": "# oss-metrics-kit\n\nToolkit to fetch, normalize, score, and export OSS contribution data \u2014 end to end.\n\nStatus: early stage; CLI and core models are available and expanding.\n\nWhat you can do in 5 minutes\n- Analyze a GitHub user\u2019s activity and get a simple score summary.\n- Save scores into SQLite or Postgres for dashboards.\n- Export scores to Parquet for data tools.\n- Optionally, let an LLM suggest a rules TOML from your events.\n\n## Quick Start (Beginner-friendly)\n\n1) Install the package (pick one)\n\n- pip (recommended for users): `pip install oss-metrics-kit`\n- uv (recommended for devs): `uv venv .venv && source .venv/bin/activate && uv sync --dev`\n\n2) Set a GitHub token (read-only is enough)\n\n```\nexport GITHUB_TOKEN=ghp_xxx # or GH_TOKEN\n```\n\n3) Analyze your account and print results\n\n```\nossmk analyze-user <your_github_login> --since 90d --api auto --out -\n```\n\n4) Save scores (SQLite for a quick try)\n\n```\nossmk analyze-user <your_github_login> --out scores.json\nossmk save sqlite:///./metrics.db --input scores.json\n```\n\n5) Export scores to Parquet (for data tools)\n\n```\npip install \"oss-metrics-kit[exporters-parquet]\"\nossmk analyze-user <your_github_login> --out parquet:./scores.parquet\n```\n\nThat\u2019s it. See Getting Started for more step\u2011by\u2011step details.\n\n## Getting Started (Step-by-step)\n\nIf you are new to Python tools or GitHub APIs, read:\n- docs/getting-started.md \u2014 a gentle, copy\u2011paste tutorial with expected outputs.\n- docs/usage.md \u2014 command reference with CI examples.\n\n## Install (development)\n\nUse a virtual environment (venv/conda/uv) and install editable:\n\n- `pip install -e .` or `python -m pip install -e .`\n- Check CLI help with `ossmk --help`\n\nNote: Running `ossmk` requires installation. For direct runs during development, either install editable or set `PYTHONPATH=src` and run the entry point.\n\n## Dev environment (uv recommended)\n\n1) Install uv\n- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- Homebrew: `brew install uv`\n- pipx: `pipx install uv`\n\n2) Create venv and sync deps\n- `uv venv .venv` \u2192 `source .venv/bin/activate`\n- `uv sync --dev`\n- All extras: `uv sync --dev --extra all`\n\n3) Run\n- `ossmk --help` (in venv) or `uv run ossmk --help`\n\n## Install from PyPI (users)\n\n- Stable: `pip install oss-metrics-kit`\n- With Postgres exporter: `pip install \"oss-metrics-kit[exporters-postgres]\"`\n\n## Examples\n\n- Persist scores to Postgres:\n\n```\nexport OSSMK_PG_DSN=\"postgresql://user:pass@host:5432/db\"\nossmk analyze-user <your_github_login> --save-pg\n```\n\n- Load proprietary rules (TOML):\n\n```\nexport OSSMK_RULES_FILE=/absolute/path/to/private/rules.toml\nossmk analyze-user <your_github_login> --out -\n```\n\n## Usage (overview)\n\n- Version: `ossmk version`\n- Analyze GitHub user (parallel fetch, since/GraphQL aware): `ossmk analyze-user <login> --since 90d --api auto --out -`\n- Fetch repo events: `ossmk fetch --provider github --repo owner/name --since 30d --out -`\n- Save scores: `ossmk save postgresql://... --input scores.json` or `ossmk save sqlite:///./metrics.db --input scores.json`\n\nStorage is selected via DSN (Postgres/SQLite). Parquet output is available as an optional exporter.\n\n### LLM-assisted rules (optional)\n\n- Suggest rules: `ossmk rules-llm --input events.json --provider openai --model gpt-4o-mini --out rules.toml`\n- Extras: `pip install \"oss-metrics-kit[llm-openai]\"` or `oss-metrics-kit[llm-anthropic]`\n- See `docs/LLM_RULES.md`\n\n## Security & operations\n\n- Keep tokens in env (`GITHUB_TOKEN`/`GH_TOKEN`) and never log them.\n- Rate limiting is a backend responsibility; a simple example is provided at `ossmk.security.ratelimit.RateLimiter` (use Redis for production).\n- Store private rule TOMLs outside the repo and point `OSSMK_RULES_FILE` to them. `rules=auto|default` will load it.\n- Optional features (Postgres/Parquet/LLM) are separated as extras.\n\nSee `docs/INTEGRATION.md` for backend integration. Development typing/lint policy: `docs/dev.md`. Detailed usage: `docs/usage.md`. A beginner tutorial is in `docs/getting-started.md`.\n\n## Python API (import)\n\nThe canonical import is:\n\n```\nimport ossmk\n```\n\nFor convenience, the underscore variant also works and maps to the same package:\n\n```\nimport oss_metrics_kit as ossmk\n```\n\n## Environment variables\n\n- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub API token (required)\n- `OSSMK_RULES_FILE`: path to a private rules TOML (optional)\n- `OSSMK_PG_DSN` or `DATABASE_URL`: Postgres DSN (if persisting)\n- `REDIS_URL`: Redis rate limiter (optional)\n- `OSSMK_MAX_SINCE_DAYS`: max backward window for `since` (default 180)\n\n## Publishing to PyPI (maintainers)\n\nSee `docs/RELEASING.md` for the full release flow (versioning, tagging, CI-based publish, and manual alternatives).\n\n## Design highlights\n\n- `src/` layout with `py.typed` for type distribution.\n- Thin CLI with Typer; business logic in `ossmk.core`.\n- Providers/exporters/storage/rules via entry points.\n\n## Troubleshooting\n\n- `pip._vendor.tomli.TOMLDecodeError: Invalid initial character...`\n - Cause: malformed leading section in `pyproject.toml`\n - Fix: ensure first section is `[build-system]`, reinstall `pip install -e .`\n\n- `ossmk: command not found`\n - Cause: not installed or wrong environment activated.\n - Fix: `pip install -e .` in the repo, and activate the same environment.\n - With uv: `uv sync --dev` then `source .venv/bin/activate`, or `uv run ossmk --help`.\n\n## License\n\nApache-2.0\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Unified toolkit to fetch, normalize, score, and export OSS contribution metrics.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/refactoring-my-path/oss-metrics-kit/tree/main/docs",
"Homepage": "https://github.com/refactoring-my-path/oss-metrics-kit",
"Issues": "https://github.com/refactoring-my-path/oss-metrics-kit/issues",
"Repository": "https://github.com/refactoring-my-path/oss-metrics-kit"
},
"split_keywords": [
"cli",
" github",
" metrics",
" oss",
" parquet",
" scoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "840641351bf473c2819018b8ebe8fe264d610ae41d3b63cae50a3403c39b2c64",
"md5": "808bfcb01a83efbce0726aa21e4f9352",
"sha256": "5f42405217f6d751180c7f414ee68e6cf79a7f86409e52f616bbe651aba14eae"
},
"downloads": -1,
"filename": "oss_metrics_kit-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "808bfcb01a83efbce0726aa21e4f9352",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 34362,
"upload_time": "2025-09-17T16:05:28",
"upload_time_iso_8601": "2025-09-17T16:05:28.920196Z",
"url": "https://files.pythonhosted.org/packages/84/06/41351bf473c2819018b8ebe8fe264d610ae41d3b63cae50a3403c39b2c64/oss_metrics_kit-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "74fb50b9d38aef38dfb9b6526f24c40107a3681d94582fe3222a420f3286d878",
"md5": "f7c5d201142b5d439289aec3523348cf",
"sha256": "0c1d1891b4c1114410c53b28bacdefe638b74a49bb53565a54fb7f017261c5c0"
},
"downloads": -1,
"filename": "oss_metrics_kit-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f7c5d201142b5d439289aec3523348cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 36945,
"upload_time": "2025-09-17T16:05:30",
"upload_time_iso_8601": "2025-09-17T16:05:30.310199Z",
"url": "https://files.pythonhosted.org/packages/74/fb/50b9d38aef38dfb9b6526f24c40107a3681d94582fe3222a420f3286d878/oss_metrics_kit-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 16:05:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "refactoring-my-path",
"github_project": "oss-metrics-kit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "oss-metrics-kit"
}
JSON
