prgenius-core 0.7.8__tar.gz

prgenius_core-0.7.8/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: prgenius-core
+Version: 0.7.8
+Summary: Evidence-backed lookup for big-repo PR contributions. Local-only, zero-runtime, stdlib-first. Renamed from `prgenius` to avoid PyPI name collision with an unrelated 2024 GPT-3 PR-description tool. Distribution renamed again in v0.7.8: `prgenius-kb` → `prgenius-core` (aligned with `misakanet-core` convention).
+Author: pr-genius contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zsxh1990/pr-genius
+Project-URL: Issues, https://github.com/zsxh1990/pr-genius/issues
+Keywords: okf,pr-knowledge,agent-readable,contribution-intelligence,evidence
+Classifier: Development Status :: 4 - Beta
+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: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+---
+type: Schema Reference
+title: prgenius
+description: Evidence-backed lookup library for big-repo PR contributions — stdlib-first CLI + stdio MCP shell.
+version: 0.7.0
+created: 2026-07-04
+updated: 2026-07-05
+author: zsxh1990
+---
+
+# prgenius
+
+**Evidence-backed lookup for big-repo PR contributions. Local-only. Stdlib-first.**
+
+A pure-Python (zero hard deps) library + CLI that reads the markdown knowledge
+base in this repo and exposes it through structured tool calls.
+
+## Install
+
+```bash
+pip install prgenius-core
+```
+
+Or run from a checkout:
+
+```bash
+cd prgenius
+PYTHONPATH=src python3 -m prgenius --version
+```
+
+## Important: PyPI package is the *interface*, not the data
+
+The PyPI wheel ships only the Python code (`prgenius/` package).
+**The knowledge base (profile markdown, case studies, OKF schemas) lives
+in the GitHub repo** at <https://github.com/zsxh1990/pr-genius> and is
+**not** bundled into the wheel. To use `prgenius-core` after `pip install`,
+point it at a checkout of the knowledge base:
+
+```bash
+git clone https://github.com/zsxh1990/pr-genius
+prgenius-core --repo-root ./pr-genius profile get astral-sh/uv
+```
+
+If you cloned a specific tag/commit, the package's `__version__` should
+match (e.g. v0.7.7 ↔ `prgenius-core==0.7.7`).
+
+### Optional: MCP server
+
+The MCP entry point (`prgenius-core mcp serve`) requires the `mcp` package:
+
+```bash
+pip install "prgenius-core[mcp]"
+```
+
+## Quick Start
+
+```bash
+# 1) Schema reference
+PYTHONPATH=src python3 -m prgenius schema info
+
+# 2) Look up one repo
+PYTHONPATH=src python3 -m prgenius profile get astral-sh/uv
+
+# 3) List currently-open case studies
+PYTHONPATH=src python3 -m prgenius case list --status=open
+
+# 4) NDJSON dump of every case study (for benchmarks / agent context)
+PYTHONPATH=src python3 -m prgenius dump > cases.ndjson
+
+# 5) Run as stdio MCP server (for Cursor/Cline/Claude Code)
+PYTHONPATH=src python3 -m prgenius mcp serve
+```
+
+## Programmatic use
+
+```python
+from prgenius.parser import profile_get, iter_case_studies, schema_info
+
+prof = profile_get("path/to/repo_root", "astral-sh/uv")
+print(prof["frontmatter"]["title"])
+
+for case in iter_case_studies("path/to/repo_root"):
+    fm = case["frontmatter"]
+    if fm.get("final_status") == "open":
+        print(fm.get("pr_number"), fm.get("repo"))
+```
+
+## What's exposed
+
+| Tool | Description |
+|---|---|
+| `prgenius profile get <org/name>` | One Repo Profile (frontmatter + first lines) |
+| `prgenius case list [--status=...]` | All PR Case Study rows |
+| `prgenius schema info` | Supported schema versions + enums |
+| `prgenius dump` | NDJSON dump (one case per line) |
+| `prgenius mcp serve` | Stdio MCP server (4 tools) |
+
+## MCP surface (when `mcp` is installed)
+
+The MCP shell exposes 4 tools to local agents:
+
+- `get_repo_profile(repo)` — one Profile dict
+- `list_open_prs()` — currently-open PRs
+- `get_case_study(repo, pr_number)` — one Case Study
+- `schema_info()` — schema versions + enums
+
+No network, no auth, no rate-limiting. Agent calls go through stdio only.
+
+### `--repo-root` flag
+
+The MCP server defaults to a path computed from its install location
+(`<package>/../..` × 3 to reach the knowledge base). When that path is
+wrong (editable install, venv, worktree, fork), pass `--repo-root`:
+
+```bash
+python3 -m prgenius --repo-root /path/to/big-repo-pr-knowledge mcp serve
+```
+
+### Wiring into Cursor / Claude Code / Cline
+
+These editors all read MCP server config from JSON. Point `command` at
+`python3 -m prgenius` and `args` at `mcp serve` (add `--repo-root` if the
+auto-detected path doesn't match your checkout). No `env` keys, no auth.
+
+**Claude Code** (`~/.claude/mcp.json` or project-local `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3 -m prgenius",
+      "args": ["--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cline** (VS Code `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"],
+      "disabled": false
+    }
+  }
+}
+```
+
+Replace `/abs/path/to/big-repo-pr-knowledge` with the actual checkout.
+Omit `--repo-root` only if you installed prgenius from this exact
+checkout (then the default path resolves correctly).
+
+## Schema we honor
+
+- **rounds v0.5.0** — `action` enum + `delta` object + case-level `close_decision`
+- **rounds v0.7.0** — adds optional `verified_at`, `evidence_urls`, `confidence`
+  to round + case level (BC over v0.5.0)
+
+See [../ROUNDS_SCHEMA.md](../ROUNDS_SCHEMA.md) for the canonical schema.
+
+## Why this exists
+
+The repo is meant to be human-readable (`<org>-<repo>/index.md`) AND
+machine-readable via this package. People get the narrative; agents get
+structured tool calls. Both views share one source of truth.
+
+## License
+
+MIT (same as parent repo).

prgenius_core-0.7.8/README.md

@@ -0,0 +1,185 @@
+---
+type: Schema Reference
+title: prgenius
+description: Evidence-backed lookup library for big-repo PR contributions — stdlib-first CLI + stdio MCP shell.
+version: 0.7.0
+created: 2026-07-04
+updated: 2026-07-05
+author: zsxh1990
+---
+
+# prgenius
+
+**Evidence-backed lookup for big-repo PR contributions. Local-only. Stdlib-first.**
+
+A pure-Python (zero hard deps) library + CLI that reads the markdown knowledge
+base in this repo and exposes it through structured tool calls.
+
+## Install
+
+```bash
+pip install prgenius-core
+```
+
+Or run from a checkout:
+
+```bash
+cd prgenius
+PYTHONPATH=src python3 -m prgenius --version
+```
+
+## Important: PyPI package is the *interface*, not the data
+
+The PyPI wheel ships only the Python code (`prgenius/` package).
+**The knowledge base (profile markdown, case studies, OKF schemas) lives
+in the GitHub repo** at <https://github.com/zsxh1990/pr-genius> and is
+**not** bundled into the wheel. To use `prgenius-core` after `pip install`,
+point it at a checkout of the knowledge base:
+
+```bash
+git clone https://github.com/zsxh1990/pr-genius
+prgenius-core --repo-root ./pr-genius profile get astral-sh/uv
+```
+
+If you cloned a specific tag/commit, the package's `__version__` should
+match (e.g. v0.7.7 ↔ `prgenius-core==0.7.7`).
+
+### Optional: MCP server
+
+The MCP entry point (`prgenius-core mcp serve`) requires the `mcp` package:
+
+```bash
+pip install "prgenius-core[mcp]"
+```
+
+## Quick Start
+
+```bash
+# 1) Schema reference
+PYTHONPATH=src python3 -m prgenius schema info
+
+# 2) Look up one repo
+PYTHONPATH=src python3 -m prgenius profile get astral-sh/uv
+
+# 3) List currently-open case studies
+PYTHONPATH=src python3 -m prgenius case list --status=open
+
+# 4) NDJSON dump of every case study (for benchmarks / agent context)
+PYTHONPATH=src python3 -m prgenius dump > cases.ndjson
+
+# 5) Run as stdio MCP server (for Cursor/Cline/Claude Code)
+PYTHONPATH=src python3 -m prgenius mcp serve
+```
+
+## Programmatic use
+
+```python
+from prgenius.parser import profile_get, iter_case_studies, schema_info
+
+prof = profile_get("path/to/repo_root", "astral-sh/uv")
+print(prof["frontmatter"]["title"])
+
+for case in iter_case_studies("path/to/repo_root"):
+    fm = case["frontmatter"]
+    if fm.get("final_status") == "open":
+        print(fm.get("pr_number"), fm.get("repo"))
+```
+
+## What's exposed
+
+| Tool | Description |
+|---|---|
+| `prgenius profile get <org/name>` | One Repo Profile (frontmatter + first lines) |
+| `prgenius case list [--status=...]` | All PR Case Study rows |
+| `prgenius schema info` | Supported schema versions + enums |
+| `prgenius dump` | NDJSON dump (one case per line) |
+| `prgenius mcp serve` | Stdio MCP server (4 tools) |
+
+## MCP surface (when `mcp` is installed)
+
+The MCP shell exposes 4 tools to local agents:
+
+- `get_repo_profile(repo)` — one Profile dict
+- `list_open_prs()` — currently-open PRs
+- `get_case_study(repo, pr_number)` — one Case Study
+- `schema_info()` — schema versions + enums
+
+No network, no auth, no rate-limiting. Agent calls go through stdio only.
+
+### `--repo-root` flag
+
+The MCP server defaults to a path computed from its install location
+(`<package>/../..` × 3 to reach the knowledge base). When that path is
+wrong (editable install, venv, worktree, fork), pass `--repo-root`:
+
+```bash
+python3 -m prgenius --repo-root /path/to/big-repo-pr-knowledge mcp serve
+```
+
+### Wiring into Cursor / Claude Code / Cline
+
+These editors all read MCP server config from JSON. Point `command` at
+`python3 -m prgenius` and `args` at `mcp serve` (add `--repo-root` if the
+auto-detected path doesn't match your checkout). No `env` keys, no auth.
+
+**Claude Code** (`~/.claude/mcp.json` or project-local `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3 -m prgenius",
+      "args": ["--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cline** (VS Code `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"],
+      "disabled": false
+    }
+  }
+}
+```
+
+Replace `/abs/path/to/big-repo-pr-knowledge` with the actual checkout.
+Omit `--repo-root` only if you installed prgenius from this exact
+checkout (then the default path resolves correctly).
+
+## Schema we honor
+
+- **rounds v0.5.0** — `action` enum + `delta` object + case-level `close_decision`
+- **rounds v0.7.0** — adds optional `verified_at`, `evidence_urls`, `confidence`
+  to round + case level (BC over v0.5.0)
+
+See [../ROUNDS_SCHEMA.md](../ROUNDS_SCHEMA.md) for the canonical schema.
+
+## Why this exists
+
+The repo is meant to be human-readable (`<org>-<repo>/index.md`) AND
+machine-readable via this package. People get the narrative; agents get
+structured tool calls. Both views share one source of truth.
+
+## License
+
+MIT (same as parent repo).

prgenius_core-0.7.8/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "prgenius-core"
+version = "0.7.8"
+description = "Evidence-backed lookup for big-repo PR contributions. Local-only, zero-runtime, stdlib-first. Renamed from `prgenius` to avoid PyPI name collision with an unrelated 2024 GPT-3 PR-description tool. Distribution renamed again in v0.7.8: `prgenius-kb` → `prgenius-core` (aligned with `misakanet-core` convention)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "pr-genius contributors"}]
+keywords = ["okf", "pr-knowledge", "agent-readable", "contribution-intelligence", "evidence"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = []  # stdlib only
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+dev = ["build", "twine", "pytest"]
+
+[project.scripts]
+prgenius-core = "prgenius.cli:main"
+
+[project.urls]
+"Homepage" = "https://github.com/zsxh1990/pr-genius"
+"Issues" = "https://github.com/zsxh1990/pr-genius/issues"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+prgenius = ["py.typed"]

prgenius_core-0.7.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prgenius_core-0.7.8/src/prgenius/__init__.py

@@ -0,0 +1,21 @@
+"""prgenius — Evidence-backed lookup for big-repo PR contributions.
+
+Local-only. Zero runtime ops. Stdlib-only (PyYAML opt-in via extras).
+
+Public surface:
+- load()       — parse one markdown file into a dict (frontmatter + body)
+- iter_profiles(repo_root) — yield Repo Profile dicts
+- iter_case_studies(repo_root) — yield PR Case Study dicts
+- profile_get(repo_root, "<org>/<repo>") — look up a single profile
+- schema_info() — return supported OKF schema versions
+"""
+
+__version__ = "0.7.8"
+__all__ = [
+    "__version__",
+    "load",
+    "iter_profiles",
+    "iter_case_studies",
+    "profile_get",
+    "schema_info",
+]

prgenius_core-0.7.8/src/prgenius/__main__.py

@@ -0,0 +1,3 @@
+from prgenius.cli import main
+import sys
+sys.exit(main())

prgenius_core-0.7.8/src/prgenius/cli.py

@@ -0,0 +1,149 @@
+"""CLI entry point for `prgenius`.
+
+Usage examples (run from repo root):
+    python3 -m prgenius profile get astral-sh/uv
+    python3 -m prgenius case list --status=open
+    python3 -m prgenius schema info
+    python3 -m prgenius dump --format=ndjson  > cases.ndjson
+    python3 -m prgenius mcp serve  # stdio MCP shell
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .parser import (
+    iter_profiles,
+    iter_case_studies,
+    profile_get,
+    schema_info,
+)
+
+
+REPO_ROOT_DEFAULT = Path(__file__).resolve().parents[3]  # up to big-repo-pr-knowledge
+
+
+def _get_repo_root(args) -> Path:
+    if args.repo_root:
+        return Path(args.repo_root).resolve()
+    return REPO_ROOT_DEFAULT
+
+
+def cmd_profile_get(args) -> int:
+    p = profile_get(_get_repo_root(args), args.repo)
+    if p is None:
+        print(f"profile not found: {args.repo}", file=sys.stderr)
+        return 2
+    out = {
+        "path": p["path"],
+        "folder": p["folder"],
+        "frontmatter": p["frontmatter"],
+        "first_lines": p["body"].splitlines()[:30],
+    }
+    print(json.dumps(out, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_case_list(args) -> int:
+    rows = []
+    for c in iter_case_studies(_get_repo_root(args)):
+        fm = c["frontmatter"]
+        fs = fm.get("final_status", "?")
+        if args.status and fs != args.status:
+            continue
+        rows.append({
+            "folder": c["folder"],
+            "pr_number": fm.get("pr_number"),
+            "pr_url": fm.get("pr_url"),
+            "final_status": fs,
+            "schema_version": fm.get("schema_version", "legacy v0.1"),
+            "verified_at": fm.get("verified_at"),
+        })
+    print(json.dumps(rows, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_schema_info(_args) -> int:
+    print(json.dumps(schema_info(), indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_dump(args) -> int:
+    """Dump everything in NDJSON (one PR per line) for benchmark use."""
+    root = _get_repo_root(args)
+    for c in iter_case_studies(root):
+        fm = c["frontmatter"]
+        record = {
+            "folder": c["folder"],
+            "pr_file": c["pr_file"],
+            "pr_number": fm.get("pr_number"),
+            "pr_url": fm.get("pr_url"),
+            "repo": fm.get("repo"),
+            "final_status": fm.get("final_status"),
+            "opened_at": fm.get("opened_at"),
+            "merged_at": fm.get("merged_at"),
+            "closed_at": fm.get("closed_at"),
+            "schema_version": fm.get("schema_version", "legacy v0.1"),
+            "verified_at": fm.get("verified_at"),
+            "evidence_urls": fm.get("evidence_urls", []),
+            "confidence": fm.get("confidence"),
+            "rounds": fm.get("rounds", []),
+            "close_decision": fm.get("close_decision"),
+        }
+        print(json.dumps(record, ensure_ascii=False))
+    return 0
+
+
+def cmd_mcp_serve(args) -> int:
+    """stdio MCP shell. See prgenius/mcp.py for the small facade.
+
+    Pass --repo-root to point the MCP server at a non-default location
+    (e.g. an isolated worktree or a forked copy of the knowledge base).
+    """
+    from .mcp import serve
+    repo_root = _get_repo_root(args)
+    return serve(repo_root=repo_root)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="prgenius",
+        description="Evidence-backed lookup for big-repo PR contributions.",
+    )
+    parser.add_argument("--repo-root", help="Path to big-repo-pr-knowledge (default: auto-detect)")
+    parser.add_argument("--version", action="version", version=f"prgenius {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_get = sub.add_parser("profile", help="Profile operations")
+    p_get_sub = p_get.add_subparsers(dest="profile_cmd", required=True)
+    pp = p_get_sub.add_parser("get", help="Get one profile")
+    pp.add_argument("repo", help="org/name (e.g. astral-sh/uv)")
+    pp.set_defaults(func=cmd_profile_get)
+
+    c_list = sub.add_parser("case", help="Case study operations")
+    c_list_sub = c_list.add_subparsers(dest="case_cmd", required=True)
+    cl = c_list_sub.add_parser("list", help="List case studies")
+    cl.add_argument("--status", help="Filter by final_status (open/merged/...)")
+    cl.set_defaults(func=cmd_case_list)
+
+    s_info = sub.add_parser("schema", help="Schema info")
+    s_info_sub = s_info.add_subparsers(dest="schema_cmd", required=True)
+    si = s_info_sub.add_parser("info", help="Show supported schema versions")
+    si.set_defaults(func=cmd_schema_info)
+
+    dmp = sub.add_parser("dump", help="NDJSON dump of all cases (for benchmarks)")
+    dmp.set_defaults(func=cmd_dump)
+
+    m_serve = sub.add_parser("mcp", help="MCP server (stdio)")
+    m_serve_sub = m_serve.add_subparsers(dest="mcp_cmd", required=True)
+    ms = m_serve_sub.add_parser("serve", help="Run stdio MCP shell")
+    ms.set_defaults(func=cmd_mcp_serve)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

prgenius_core-0.7.8/src/prgenius/mcp.py

@@ -0,0 +1,103 @@
+"""stdio MCP shell for prgenius — a thin façade.
+
+This module is optional: only loaded if `mcp` is installed (the only runtime
+dependency we ever take). Calling `python3 -m prgenius mcp serve` starts a
+stdio MCP server that exposes the prgenius lookup surface to local agents
+(Cursor/Cline/Claude Code). No network, no auth, no rate-limiting.
+
+Promoted tools (intentionally small — ACD rule "first to simplify wins"):
+- get_repo_profile(repo) → returns one Repo Profile dict
+- list_open_prs() → list of PRs with final_status=open
+- get_case_study(repo, pr_number) → one PR Case Study
+- schema_info() → enumerated schema versions
+
+This file is ~70 lines (one per tool + boilerplate). Anyone reading it should
+be able to verify the surface and the path-resolution logic in under 5 min.
+"""
+from __future__ import annotations
+import json
+import sys
+from pathlib import Path
+
+# mcp SDK: only imported at serve() time so the rest of the package stays stdlib.
+REPO_ROOT_DEFAULT = Path(__file__).resolve().parents[3]  # up to big-repo-pr-knowledge
+
+
+def _load_tools(repo_root: Path | None = None):
+    from mcp.server.fastmcp import FastMCP
+    from .parser import (
+        iter_case_studies,
+        profile_get,
+        schema_info,
+    )
+
+    mcp = FastMCP(name="prgenius", instructions=(
+        "Evidence-backed lookup for big-repo PR contributions. "
+        "Local stdio; no network calls."
+    ))
+
+    rr = repo_root or REPO_ROOT_DEFAULT
+
+    @mcp.tool()
+    def get_repo_profile(repo: str) -> dict:
+        """Return one Repo Profile by `org/name` (e.g. astral-sh/uv)."""
+        p = profile_get(rr, repo)
+        if p is None:
+            return {"error": f"profile not found: {repo}"}
+        return p["frontmatter"]
+
+    @mcp.tool()
+    def list_open_prs() -> list:
+        """List every PR Case Study with final_status=open."""
+        out = []
+        for c in iter_case_studies(rr):
+            fm = c["frontmatter"]
+            if fm.get("final_status") == "open":
+                out.append({
+                    "repo": fm.get("repo"),
+                    "pr_number": fm.get("pr_number"),
+                    "pr_url": fm.get("pr_url"),
+                    "folder": c["folder"],
+                    "schema_version": fm.get("schema_version", "legacy v0.1"),
+                    "verified_at": fm.get("verified_at"),
+                })
+        return out
+
+    @mcp.tool()
+    def get_case_study(repo: str, pr_number: int) -> dict:
+        """Return one PR Case Study by `org/name` + `pr_number`."""
+        for c in iter_case_studies(rr):
+            fm = c["frontmatter"]
+            if (
+                fm.get("repo", "").strip("/").lower() == repo.strip("/").lower()
+                and str(fm.get("pr_number")) == str(pr_number)
+            ):
+                return {
+                    "frontmatter": fm,
+                    "body": c["body"],
+                    "path": c["path"],
+                }
+        return {"error": f"case study not found: {repo}#{pr_number}"}
+
+    @mcp.tool()
+    def schema_info() -> dict:
+        """Return supported schema versions + enum values."""
+        return schema_info()
+
+    return mcp
+
+
+def serve(repo_root: Path | None = None) -> int:
+    """Run stdio MCP server. Blocks until the host disconnects.
+
+    Args:
+        repo_root: Override the knowledge base location. If None, uses
+            the auto-detected default (parents[3] of this file).
+    """
+    mcp = _load_tools(repo_root=repo_root)
+    mcp.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(serve())

prgenius_core-0.7.8/src/prgenius/parser.py

@@ -0,0 +1,225 @@
+"""Markdown frontmatter parsing — pure-stdlib YAML-subset.
+
+Goals:
+- Zero hard deps (no PyYAML) — package works after `pip install prgenius-core`
+- Just enough fidelity for OKF v0.1 / rounds v0.5.0 / v0.7.0 frontmatter
+- Honest: returns the AST we can parse; preserves raw text for the rest
+
+Strategy: 2-pass indent-stack parser.
+- Pass 1: collect (line, indent, raw_line)
+- Pass 2: walk lines; push/pop stack based on indent depth
+
+Limitations:
+- top-level key: value (string/int/bool/null/list-inline)
+- 2-space indent for nested mapping
+- `- item` lists (with optional inline key: value on first line)
+"""
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Iterator
+
+
+_FM_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
+
+
+def load(path: str | Path) -> dict:
+    """Load a markdown file: return {frontmatter, body, path}."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    fm_match = _FM_RE.match(text)
+    if not fm_match:
+        return {"frontmatter": {}, "body": text, "path": str(p)}
+    fm_text = fm_match.group(1)
+    body = text[fm_match.end():].lstrip("\n")
+    return {
+        "frontmatter": parse_frontmatter(fm_text),
+        "body": body,
+        "path": str(p),
+    }
+
+
+def _unquote(s: str) -> str:
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
+        return s[1:-1]
+    return s
+
+
+def _coerce(v: str):
+    """Coerce a scalar string to a Python value."""
+    if v == "" or v in ("null", "~"):
+        return None
+    if v == "true":
+        return True
+    if v == "false":
+        return False
+    if v.startswith("[") and v.endswith("]"):
+        inner = v[1:-1].strip()
+        if not inner:
+            return []
+        return [_coerce(x.strip()) for x in inner.split(",")]
+    if re.match(r"^-?\d+$", v):
+        return int(v)
+    if re.match(r"^-?\d+\.\d+$", v):
+        return float(v)
+    if len(v) >= 2 and v[0] == v[-1] and v[0] in ('"', "'"):
+        return v[1:-1]
+    return v
+
+
+def _last_list_key(d: dict):
+    for k in reversed(d.keys()):
+        if isinstance(d[k], list):
+            return k
+    return None
+
+
+def _normalize_lists(node):
+    """Recursively replace `{'_': [items]}` or `{'_items': [items]}` (parser quirk)
+    with the bare list.
+    """
+    if isinstance(node, dict):
+        keys = list(node.keys())
+        if (
+            len(keys) == 1
+            and keys[0] in ("_", "_items")
+            and isinstance(node[keys[0]], list)
+        ):
+            return [_normalize_lists(x) for x in node[keys[0]]]
+        return {k: _normalize_lists(v) for k, v in node.items()}
+    if isinstance(node, list):
+        return [_normalize_lists(x) for x in node]
+    return node
+
+
+def parse_frontmatter(text: str) -> dict:
+    """Parse a YAML-subset frontmatter block.
+
+    Strategy: walk lines, push/pop an indent-aware stack. Lists get attached
+    to the most recent dict-key (the "current list"). After the walk we
+    normalize any `{'_': [...]}` quirk wrappers to plain lists.
+    """
+    tokens = []
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        if raw.lstrip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip(" "))
+        tokens.append((indent, raw.strip()))
+
+    root: dict = {}
+    # stack of (indent_level, container); root container indent = -1
+    stack = [(-1, root)]
+
+    for indent, line in tokens:
+        # pop until stack top has smaller indent than current
+        while len(stack) > 1 and stack[-1][0] >= indent:
+            stack.pop()
+        parent_indent, parent = stack[-1]
+
+        if line.startswith("- "):
+            content = line[2:].strip()
+            if not isinstance(parent, dict):
+                # shouldn't happen in our schema
+                continue
+            last_key = _last_list_key(parent)
+            if last_key is None:
+                parent["_items"] = []
+                current_list = parent["_items"]
+                last_key = "_items"
+            else:
+                current_list = parent[last_key]
+
+            if ":" in content and not content.startswith(('"', "'")):
+                k, _, v = content.partition(":")
+                k = _unquote(k.strip())
+                v = v.strip()
+                item: dict = {k: _coerce(v)}
+                current_list.append(item)
+                stack.append((indent, item))
+            else:
+                current_list.append(_coerce(content))
+            continue
+
+        if ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        k = _unquote(k.strip())
+        v = v.strip()
+
+        if not isinstance(parent, dict):
+            continue
+
+        if v == "":
+            new = {}
+            parent[k] = new
+            stack.append((indent, new))
+        else:
+            parent[k] = _coerce(v)
+
+    return _normalize_lists(root)
+
+
+# ---------- higher-level iterators ----------
+
+def iter_profiles(repo_root: str | Path) -> Iterator[dict]:
+    """Yield each Repo Profile dict under `<repo_root>/<folder>/index.md`."""
+    root = Path(repo_root)
+    skip = {
+        "anti-patterns", "misakanet-50", ".github", "docs",
+        "scripts", "prgenius", "__pycache__", ".git",
+        "federation.yaml",
+    }
+    for sub in sorted(root.iterdir()):
+        if not sub.is_dir() or sub.name in skip or sub.name.startswith("."):
+            continue
+        idx = sub / "index.md"
+        if not idx.exists():
+            continue
+        loaded = load(idx)
+        if loaded["frontmatter"].get("type") == "Repo Profile":
+            loaded["folder"] = sub.name
+            yield loaded
+
+
+def iter_case_studies(repo_root: str | Path) -> Iterator[dict]:
+    """Yield each PR Case Study dict under repo root."""
+    root = Path(repo_root)
+    for path in sorted(root.rglob("pr-*.md")):
+        try:
+            loaded = load(path)
+        except Exception:
+            continue
+        if loaded["frontmatter"].get("type") == "PR Case Study":
+            loaded["folder"] = path.parent.name
+            loaded["pr_file"] = path.name
+            yield loaded
+
+
+def profile_get(repo_root: str | Path, repo: str) -> dict | None:
+    """Look up a Repo Profile by `org/name`. None if missing."""
+    target = repo.strip("/").lower()
+    target_folder = target.replace("/", "-")
+    for profile in iter_profiles(repo_root):
+        if profile["folder"].lower() == target_folder:
+            return profile
+        if profile["frontmatter"].get("repo", "").strip("/").lower() == target:
+            return profile
+    return None
+
+
+def schema_info() -> dict:
+    return {
+        "schema_versions": ["rounds v0.5.0", "rounds v0.7.0 (BC over v0.5.0)"],
+        "delta_kinds": ["code_change", "no_code_change", "unknown"],
+        "close_decision_status": ["pending", "close", "keep_open", "merged", "superseded"],
+        "evidence_fields_round_level": ["verified_at", "evidence_urls", "confidence"],
+        "evidence_fields_case_level": ["verified_at", "evidence_urls", "confidence"],
+        "confidence_values": ["high", "medium", "low"],
+        "action_enum": [
+            "open", "amend", "bot_review", "human_review",
+            "check_in", "bump", "close", "merge", "decision",
+        ],
+    }

prgenius_core-0.7.8/src/prgenius_core.egg-info/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: prgenius-core
+Version: 0.7.8
+Summary: Evidence-backed lookup for big-repo PR contributions. Local-only, zero-runtime, stdlib-first. Renamed from `prgenius` to avoid PyPI name collision with an unrelated 2024 GPT-3 PR-description tool. Distribution renamed again in v0.7.8: `prgenius-kb` → `prgenius-core` (aligned with `misakanet-core` convention).
+Author: pr-genius contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zsxh1990/pr-genius
+Project-URL: Issues, https://github.com/zsxh1990/pr-genius/issues
+Keywords: okf,pr-knowledge,agent-readable,contribution-intelligence,evidence
+Classifier: Development Status :: 4 - Beta
+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: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+---
+type: Schema Reference
+title: prgenius
+description: Evidence-backed lookup library for big-repo PR contributions — stdlib-first CLI + stdio MCP shell.
+version: 0.7.0
+created: 2026-07-04
+updated: 2026-07-05
+author: zsxh1990
+---
+
+# prgenius
+
+**Evidence-backed lookup for big-repo PR contributions. Local-only. Stdlib-first.**
+
+A pure-Python (zero hard deps) library + CLI that reads the markdown knowledge
+base in this repo and exposes it through structured tool calls.
+
+## Install
+
+```bash
+pip install prgenius-core
+```
+
+Or run from a checkout:
+
+```bash
+cd prgenius
+PYTHONPATH=src python3 -m prgenius --version
+```
+
+## Important: PyPI package is the *interface*, not the data
+
+The PyPI wheel ships only the Python code (`prgenius/` package).
+**The knowledge base (profile markdown, case studies, OKF schemas) lives
+in the GitHub repo** at <https://github.com/zsxh1990/pr-genius> and is
+**not** bundled into the wheel. To use `prgenius-core` after `pip install`,
+point it at a checkout of the knowledge base:
+
+```bash
+git clone https://github.com/zsxh1990/pr-genius
+prgenius-core --repo-root ./pr-genius profile get astral-sh/uv
+```
+
+If you cloned a specific tag/commit, the package's `__version__` should
+match (e.g. v0.7.7 ↔ `prgenius-core==0.7.7`).
+
+### Optional: MCP server
+
+The MCP entry point (`prgenius-core mcp serve`) requires the `mcp` package:
+
+```bash
+pip install "prgenius-core[mcp]"
+```
+
+## Quick Start
+
+```bash
+# 1) Schema reference
+PYTHONPATH=src python3 -m prgenius schema info
+
+# 2) Look up one repo
+PYTHONPATH=src python3 -m prgenius profile get astral-sh/uv
+
+# 3) List currently-open case studies
+PYTHONPATH=src python3 -m prgenius case list --status=open
+
+# 4) NDJSON dump of every case study (for benchmarks / agent context)
+PYTHONPATH=src python3 -m prgenius dump > cases.ndjson
+
+# 5) Run as stdio MCP server (for Cursor/Cline/Claude Code)
+PYTHONPATH=src python3 -m prgenius mcp serve
+```
+
+## Programmatic use
+
+```python
+from prgenius.parser import profile_get, iter_case_studies, schema_info
+
+prof = profile_get("path/to/repo_root", "astral-sh/uv")
+print(prof["frontmatter"]["title"])
+
+for case in iter_case_studies("path/to/repo_root"):
+    fm = case["frontmatter"]
+    if fm.get("final_status") == "open":
+        print(fm.get("pr_number"), fm.get("repo"))
+```
+
+## What's exposed
+
+| Tool | Description |
+|---|---|
+| `prgenius profile get <org/name>` | One Repo Profile (frontmatter + first lines) |
+| `prgenius case list [--status=...]` | All PR Case Study rows |
+| `prgenius schema info` | Supported schema versions + enums |
+| `prgenius dump` | NDJSON dump (one case per line) |
+| `prgenius mcp serve` | Stdio MCP server (4 tools) |
+
+## MCP surface (when `mcp` is installed)
+
+The MCP shell exposes 4 tools to local agents:
+
+- `get_repo_profile(repo)` — one Profile dict
+- `list_open_prs()` — currently-open PRs
+- `get_case_study(repo, pr_number)` — one Case Study
+- `schema_info()` — schema versions + enums
+
+No network, no auth, no rate-limiting. Agent calls go through stdio only.
+
+### `--repo-root` flag
+
+The MCP server defaults to a path computed from its install location
+(`<package>/../..` × 3 to reach the knowledge base). When that path is
+wrong (editable install, venv, worktree, fork), pass `--repo-root`:
+
+```bash
+python3 -m prgenius --repo-root /path/to/big-repo-pr-knowledge mcp serve
+```
+
+### Wiring into Cursor / Claude Code / Cline
+
+These editors all read MCP server config from JSON. Point `command` at
+`python3 -m prgenius` and `args` at `mcp serve` (add `--repo-root` if the
+auto-detected path doesn't match your checkout). No `env` keys, no auth.
+
+**Claude Code** (`~/.claude/mcp.json` or project-local `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3 -m prgenius",
+      "args": ["--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cline** (VS Code `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "pr-genius": {
+      "command": "python3",
+      "args": ["-m", "prgenius", "--repo-root", "/abs/path/to/big-repo-pr-knowledge", "mcp", "serve"],
+      "disabled": false
+    }
+  }
+}
+```
+
+Replace `/abs/path/to/big-repo-pr-knowledge` with the actual checkout.
+Omit `--repo-root` only if you installed prgenius from this exact
+checkout (then the default path resolves correctly).
+
+## Schema we honor
+
+- **rounds v0.5.0** — `action` enum + `delta` object + case-level `close_decision`
+- **rounds v0.7.0** — adds optional `verified_at`, `evidence_urls`, `confidence`
+  to round + case level (BC over v0.5.0)
+
+See [../ROUNDS_SCHEMA.md](../ROUNDS_SCHEMA.md) for the canonical schema.
+
+## Why this exists
+
+The repo is meant to be human-readable (`<org>-<repo>/index.md`) AND
+machine-readable via this package. People get the narrative; agents get
+structured tool calls. Both views share one source of truth.
+
+## License
+
+MIT (same as parent repo).

prgenius_core-0.7.8/src/prgenius_core.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/prgenius/__init__.py
+src/prgenius/__main__.py
+src/prgenius/cli.py
+src/prgenius/mcp.py
+src/prgenius/parser.py
+src/prgenius/py.typed
+src/prgenius_core.egg-info/PKG-INFO
+src/prgenius_core.egg-info/SOURCES.txt
+src/prgenius_core.egg-info/dependency_links.txt
+src/prgenius_core.egg-info/entry_points.txt
+src/prgenius_core.egg-info/requires.txt
+src/prgenius_core.egg-info/top_level.txt
+tests/test_parser_smoke.py

prgenius_core-0.7.8/src/prgenius_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prgenius_core-0.7.8/src/prgenius_core.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prgenius-core = prgenius.cli:main

prgenius_core-0.7.8/src/prgenius_core.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[dev]
+build
+twine
+pytest
+
+[mcp]
+mcp>=1.0

prgenius_core-0.7.8/src/prgenius_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+prgenius

prgenius_core-0.7.8/tests/test_parser_smoke.py

@@ -0,0 +1,163 @@
+"""Smoke tests for prgenius parser + CLI.
+
+These tests deliberately avoid framework/fixture infrastructure
+(per ponytail "lazy code ≠ no check" rule). Each test creates
+minimal temp inputs and asserts the public API behavior.
+
+Run from repo root:
+
+    cd prgenius
+    PYTHONPATH=src python3 -m pytest tests/ -v
+    # or
+    PYTHONPATH=src python3 tests/test_parser_smoke.py
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+# Allow running without pytest installed (stdlib unittest)
+try:
+    import pytest  # noqa: F401
+    HAS_PYTEST = True
+except ImportError:
+    HAS_PYTEST = False
+
+from prgenius.parser import (
+    iter_profiles,
+    iter_case_studies,
+    load,
+    parse_frontmatter,
+    profile_get,
+    schema_info,
+)
+from prgenius import __version__
+
+
+class TestVersion(unittest.TestCase):
+    def test_version_is_string(self):
+        self.assertIsInstance(__version__, str)
+        # semver-ish: X.Y.Z
+        parts = __version__.split(".")
+        self.assertEqual(len(parts), 3, f"version not semver: {__version__}")
+        for p in parts:
+            self.assertTrue(p.isdigit(), f"non-numeric version part: {p}")
+
+
+class TestParseFrontmatter(unittest.TestCase):
+    def test_basic_yaml(self):
+        text = """---
+type: Profile
+title: Test
+tags: [a, b]
+---
+# Body here
+"""
+        fm = parse_frontmatter(text)
+        self.assertEqual(fm.get("type"), "Profile")
+        self.assertEqual(fm.get("title"), "Test")
+        # tags normalized to list
+        self.assertEqual(fm.get("tags"), ["a", "b"])
+
+    def test_empty_frontmatter(self):
+        text = "# Body only, no frontmatter\n"
+        fm = parse_frontmatter(text)
+        # Should not raise — returns empty dict or default
+        self.assertIsInstance(fm, dict)
+
+
+class TestLoadAndIter(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.root = Path(self.tmp)
+        # Create one profile + one case study
+        (self.root / "fake-org-fake-repo").mkdir()
+        (self.root / "fake-org-fake-repo" / "index.md").write_text(
+            "---\n"
+            "type: Repo Profile\n"
+            "title: fake-org/fake-repo\n"
+            "agent_guidelines:\n"
+            "  default_branch: main\n"
+            "---\n"
+            "# Profile body\n",
+            encoding="utf-8",
+        )
+        (self.root / "fake-org-fake-repo" / "pr-1-test.md").write_text(
+            "---\n"
+            "type: PR Case Study\n"
+            "title: Test case\n"
+            "rounds:\n"
+            "  - action: open\n"
+            "    at: 2026-01-01\n"
+            "---\n"
+            "# Case body\n",
+            encoding="utf-8",
+        )
+
+    def test_load_single_file(self):
+        profile_md = self.root / "fake-org-fake-repo" / "index.md"
+        result = load(profile_md)
+        self.assertEqual(result["frontmatter"]["title"], "fake-org/fake-repo")
+        self.assertIn("Profile body", result["body"])
+
+    def test_iter_profiles_finds_one(self):
+        profiles = list(iter_profiles(self.root))
+        self.assertEqual(len(profiles), 1)
+        self.assertEqual(profiles[0]["frontmatter"]["type"], "Repo Profile")
+
+    def test_iter_case_studies_finds_one(self):
+        cases = list(iter_case_studies(self.root))
+        self.assertEqual(len(cases), 1)
+        self.assertEqual(cases[0]["frontmatter"]["type"], "PR Case Study")
+
+    def test_profile_get_hit(self):
+        prof = profile_get(self.root, "fake-org/fake-repo")
+        self.assertIsNotNone(prof)
+        self.assertEqual(prof["frontmatter"]["title"], "fake-org/fake-repo")
+
+    def test_profile_get_miss(self):
+        prof = profile_get(self.root, "nonexistent/repo")
+        self.assertIsNone(prof)
+
+
+class TestSchemaInfo(unittest.TestCase):
+    def test_returns_dict(self):
+        info = schema_info()
+        self.assertIsInstance(info, dict)
+        # Should advertise at least one OKF version
+        self.assertTrue(any("okf" in str(k).lower() for k in info.keys())
+                        or "version" in info
+                        or len(info) >= 1)
+
+
+class TestCliSmoke(unittest.TestCase):
+    """Verify the CLI entry point actually launches."""
+
+    def test_cli_version(self):
+        repo_root = Path(__file__).resolve().parents[2]  # up to pr-genius/
+        env_python = sys.executable
+        # Use `python -m prgenius` with PYTHONPATH pointing at src/
+        env_add = str(repo_root / "prgenius" / "src")
+        import os
+        env = os.environ.copy()
+        env["PYTHONPATH"] = (
+            env_add + os.pathsep + env.get("PYTHONPATH", "")
+        )
+        result = subprocess.run(
+            [env_python, "-m", "prgenius", "--version"],
+            capture_output=True, text=True, env=env, timeout=15,
+        )
+        self.assertEqual(result.returncode, 0,
+                         f"stderr={result.stderr!r}")
+        self.assertIn(__version__, result.stdout)
+
+
+if __name__ == "__main__":
+    if HAS_PYTEST:
+        sys.exit(pytest.main([__file__, "-v"]))  # noqa
+    else:
+        unittest.main(verbosity=2)