github-dkg 0.1.0__py3-none-any.whl

github_dkg/__init__.py

@@ -0,0 +1,8 @@
+"""github-dkg: Ingest GitHub issues, PRs, and reviews into DKG v10 Working Memory."""
+
+from .client import DKGClient
+from .github_client import GitHubClient
+from .ingestor import GitHubDKGIngestor
+
+__all__ = ["DKGClient", "GitHubClient", "GitHubDKGIngestor"]
+__version__ = "0.1.0"

github_dkg/cli.py

@@ -0,0 +1,187 @@
+"""CLI entry point for github-dkg."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+import click
+
+from .client import DKGClient
+from .github_client import GitHubClient
+from .ingestor import GitHubDKGIngestor
+
+
+def _make_clients(
+    dkg_token: str | None,
+    dkg_url: str | None,
+    github_token: str | None,
+) -> tuple[DKGClient, GitHubClient]:
+    dkg = DKGClient(base_url=dkg_url, token=dkg_token)
+    gh = GitHubClient(token=github_token)
+    return dkg, gh
+
+
+@click.group()
+def main() -> None:
+    """github-dkg: Ingest GitHub knowledge into DKG v10 Working Memory."""
+
+
+@main.command()
+@click.argument("repo")  # owner/repo
+@click.option("--context-graph", required=True, envvar="DKG_CONTEXT_GRAPH", help="Context Graph ID")
+@click.option("--layer", default="wm", show_default=True, type=click.Choice(["wm", "swm"]))
+@click.option("--since", default=None, help="ISO 8601 date — only ingest items updated after this date")
+@click.option("--no-issues", is_flag=True, default=False, help="Skip issues")
+@click.option("--no-pulls", is_flag=True, default=False, help="Skip pull requests")
+@click.option("--concurrency", default=5, show_default=True, help="Parallel DKG writes")
+@click.option("--dkg-token", envvar="DKG_TOKEN", default=None)
+@click.option("--dkg-url", envvar="DKG_BASE_URL", default=None)
+@click.option("--github-token", envvar="GITHUB_TOKEN", default=None)
+def ingest(
+    repo: str,
+    context_graph: str,
+    layer: str,
+    since: str | None,
+    no_issues: bool,
+    no_pulls: bool,
+    concurrency: int,
+    dkg_token: str | None,
+    dkg_url: str | None,
+    github_token: str | None,
+) -> None:
+    """Bulk-ingest all issues and PRs from OWNER/REPO into Working Memory."""
+    if "/" not in repo:
+        click.echo("Error: REPO must be in owner/repo format", err=True)
+        sys.exit(1)
+    owner, repo_name = repo.split("/", 1)
+
+    async def run() -> int:
+        dkg, gh = _make_clients(dkg_token, dkg_url, github_token)
+
+        click.echo("Connecting to DKG node...")
+        if not await dkg.ping():
+            click.echo("Error: DKG node unreachable or token invalid", err=True)
+            return 1
+
+        ingestor = GitHubDKGIngestor(
+            dkg=dkg,
+            github=gh,
+            context_graph_id=context_graph,
+            layer=layer,
+            concurrency=concurrency,
+        )
+
+        click.echo(f"Ingesting {owner}/{repo_name} → context graph '{context_graph}' (layer={layer})")
+        result = await ingestor.ingest_repo(
+            owner=owner,
+            repo=repo_name,
+            since=since,
+            include_issues=not no_issues,
+            include_pulls=not no_pulls,
+        )
+
+        click.echo(f"Done: {result.issues_ingested} issues, {result.pulls_ingested} PRs ingested")
+        if result.errors:
+            click.echo(f"Errors ({len(result.errors)}):")
+            for err in result.errors:
+                click.echo(f"  {err}", err=True)
+            return 1
+        return 0
+
+    sys.exit(asyncio.run(run()))
+
+
+@main.command()
+@click.argument("repo")  # owner/repo
+@click.argument("number", type=int)
+@click.option("--type", "item_type", required=True, type=click.Choice(["issue", "pr"]))
+@click.option("--context-graph", required=True, envvar="DKG_CONTEXT_GRAPH")
+@click.option("--layer", default="wm", show_default=True, type=click.Choice(["wm", "swm"]))
+@click.option("--dkg-token", envvar="DKG_TOKEN", default=None)
+@click.option("--dkg-url", envvar="DKG_BASE_URL", default=None)
+@click.option("--github-token", envvar="GITHUB_TOKEN", default=None)
+def ingest_one(
+    repo: str,
+    number: int,
+    item_type: str,
+    context_graph: str,
+    layer: str,
+    dkg_token: str | None,
+    dkg_url: str | None,
+    github_token: str | None,
+) -> None:
+    """Ingest a single issue or PR by number."""
+    if "/" not in repo:
+        click.echo("Error: REPO must be in owner/repo format", err=True)
+        sys.exit(1)
+    owner, repo_name = repo.split("/", 1)
+
+    async def run() -> None:
+        dkg, gh = _make_clients(dkg_token, dkg_url, github_token)
+        ingestor = GitHubDKGIngestor(dkg=dkg, github=gh, context_graph_id=context_graph, layer=layer)
+        if item_type == "issue":
+            resp = await ingestor.ingest_issue(owner, repo_name, number)
+        else:
+            resp = await ingestor.ingest_pull(owner, repo_name, number)
+        turn_uri = resp.get("turnUri", "")
+        click.echo(f"Ingested: {turn_uri}")
+
+    asyncio.run(run())
+
+
+@main.command()
+@click.argument("turn-uri")
+@click.option("--context-graph", required=True, envvar="DKG_CONTEXT_GRAPH")
+@click.option("--dkg-token", envvar="DKG_TOKEN", default=None)
+@click.option("--dkg-url", envvar="DKG_BASE_URL", default=None)
+def promote(
+    turn_uri: str,
+    context_graph: str,
+    dkg_token: str | None,
+    dkg_url: str | None,
+) -> None:
+    """Promote a Working Memory Knowledge Asset to Shared Working Memory (SHARE)."""
+
+    async def run() -> None:
+        dkg = DKGClient(base_url=dkg_url, token=dkg_token)
+        ingestor = GitHubDKGIngestor(dkg=dkg, context_graph_id=context_graph)
+        resp = await ingestor.promote(turn_uri)
+        click.echo(f"Promoted: {resp}")
+
+    asyncio.run(run())
+
+
+@main.command()
+@click.argument("query")
+@click.option("--context-graph", required=True, envvar="DKG_CONTEXT_GRAPH")
+@click.option("--limit", default=10, show_default=True)
+@click.option("--dkg-token", envvar="DKG_TOKEN", default=None)
+@click.option("--dkg-url", envvar="DKG_BASE_URL", default=None)
+def search(
+    query: str,
+    context_graph: str,
+    limit: int,
+    dkg_token: str | None,
+    dkg_url: str | None,
+) -> None:
+    """Search ingested GitHub knowledge in Working Memory."""
+
+    async def run() -> None:
+        dkg = DKGClient(base_url=dkg_url, token=dkg_token)
+        result = await dkg.memory_search(
+            context_graph_id=context_graph,
+            query=query,
+            limit=limit,
+        )
+        count = result.get("resultCount", 0)
+        click.echo(f"{count} result(s) for '{query}':")
+        for item in result.get("results", []):
+            label = item.get("label", item.get("entityUri", ""))
+            snippet = item.get("snippet", "")
+            layer = item.get("memoryLayer", "")
+            click.echo(f"  [{layer}] {label}")
+            if snippet:
+                click.echo(f"    {snippet[:120]}")
+
+    asyncio.run(run())

github_dkg/client.py

@@ -0,0 +1,139 @@
+"""HTTP client for the DKG v10 node API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+
+class DKGClient:
+    """Thin async wrapper around the DKG v10 HTTP API (port 9200).
+
+    All methods raise httpx.HTTPStatusError on non-2xx responses.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = (
+            base_url or os.environ.get("DKG_BASE_URL", "http://localhost:9200")
+        ).rstrip("/")
+        token = token or os.environ.get("DKG_TOKEN", "")
+        if not token:
+            raise ValueError(
+                "DKG bearer token required. Pass token= or set DKG_TOKEN env var."
+            )
+        self._headers = {"Authorization": f"Bearer {token}"}
+        self._timeout = timeout
+
+    async def ping(self) -> bool:
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as http:
+                r = await http.get(
+                    f"{self.base_url}/api/agents", headers=self._headers
+                )
+                return r.status_code == 200
+        except Exception:
+            return False
+
+    async def create_context_graph(self, name: str) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.post(
+                f"{self.base_url}/api/context-graph/create",
+                headers=self._headers,
+                json={"name": name},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def memory_turn(
+        self,
+        context_graph_id: str,
+        markdown: str,
+        session_uri: str | None = None,
+        layer: str = "wm",
+        sub_graph_name: str | None = None,
+    ) -> dict[str, Any]:
+        """Ingest a markdown artifact as a Knowledge Asset in Working Memory."""
+        body: dict[str, Any] = {
+            "contextGraphId": context_graph_id,
+            "markdown": markdown,
+            "layer": layer,
+        }
+        if session_uri:
+            body["sessionUri"] = session_uri
+        if sub_graph_name:
+            body["subGraphName"] = sub_graph_name
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.post(
+                f"{self.base_url}/api/memory/turn",
+                headers=self._headers,
+                json=body,
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def memory_search(
+        self,
+        context_graph_id: str,
+        query: str,
+        limit: int = 20,
+        memory_layers: list[str] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "contextGraphId": context_graph_id,
+            "query": query,
+            "limit": limit,
+        }
+        if memory_layers:
+            body["memoryLayers"] = memory_layers
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.post(
+                f"{self.base_url}/api/memory/search",
+                headers=self._headers,
+                json=body,
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def assertion_promote(
+        self,
+        name: str,
+        context_graph_id: str,
+        entities: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Promote a Working Memory assertion to Shared Working Memory (SHARE)."""
+        body: dict[str, Any] = {"contextGraphId": context_graph_id}
+        if entities:
+            body["entities"] = entities
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.post(
+                f"{self.base_url}/api/assertion/{name}/promote",
+                headers=self._headers,
+                json=body,
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def query(
+        self,
+        sparql: str,
+        include_workspace: bool = True,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "sparql": sparql,
+            "includeWorkspace": include_workspace,
+        }
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.post(
+                f"{self.base_url}/api/query",
+                headers=self._headers,
+                json=body,
+            )
+            r.raise_for_status()
+            return r.json()

github_dkg/formatter.py

@@ -0,0 +1,135 @@
+"""Format GitHub items as Markdown Knowledge Assets for DKG v10 Working Memory."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _label_names(labels: list[dict[str, Any]]) -> str:
+    names = [lbl.get("name", "") for lbl in labels if lbl.get("name")]
+    return ", ".join(names) if names else "none"
+
+
+def _username(user: dict[str, Any] | None) -> str:
+    if not user:
+        return "unknown"
+    return user.get("login", "unknown")
+
+
+def format_issue(
+    issue: dict[str, Any],
+    comments: list[dict[str, Any]],
+    owner: str,
+    repo: str,
+) -> str:
+    number = issue["number"]
+    title = issue.get("title", "")
+    author = _username(issue.get("user"))
+    labels = _label_names(issue.get("labels", []))
+    state = issue.get("state", "unknown")
+    state_reason = issue.get("state_reason") or ""
+    created = (issue.get("created_at") or "")[:10]
+    closed = (issue.get("closed_at") or "")[:10]
+    body = (issue.get("body") or "").strip()
+    url = issue.get("html_url", f"https://github.com/{owner}/{repo}/issues/{number}")
+
+    lines = [
+        f"**GitHub Issue #{number}:** {title}",
+        f"**Repository:** {owner}/{repo}",
+        f"**Author:** {author}  |  **Labels:** {labels}  |  **State:** {state}"
+        + (f" ({state_reason})" if state_reason else ""),
+        f"**Created:** {created}" + (f"  |  **Closed:** {closed}" if closed else ""),
+        f"**URL:** {url}",
+    ]
+
+    if body:
+        lines += ["", "**Description:**", body]
+
+    if comments:
+        lines += ["", "**Comments:**"]
+        for c in comments:
+            commenter = _username(c.get("user"))
+            when = (c.get("created_at") or "")[:10]
+            text = (c.get("body") or "").strip()
+            if text:
+                lines += [f"- **{commenter}** ({when}): {text}"]
+
+    return "\n".join(lines)
+
+
+def format_pull_request(
+    pr: dict[str, Any],
+    reviews: list[dict[str, Any]],
+    inline_comments: list[dict[str, Any]],
+    owner: str,
+    repo: str,
+) -> str:
+    number = pr["number"]
+    title = pr.get("title", "")
+    author = _username(pr.get("user"))
+    labels = _label_names(pr.get("labels", []))
+    state = pr.get("state", "unknown")
+    draft = " (draft)" if pr.get("draft") else ""
+    created = (pr.get("created_at") or "")[:10]
+    merged = (pr.get("merged_at") or "")[:10]
+    closed = (pr.get("closed_at") or "")[:10]
+    body = (pr.get("body") or "").strip()
+    url = pr.get("html_url", f"https://github.com/{owner}/{repo}/pull/{number}")
+
+    base_ref = pr.get("base", {}).get("ref", "")
+    head_ref = pr.get("head", {}).get("ref", "")
+    branch_line = f"**Branch:** {head_ref} → {base_ref}" if base_ref or head_ref else ""
+
+    requested_reviewers = [
+        _username(r) for r in pr.get("requested_reviewers", [])
+    ]
+    reviewer_str = ", ".join(requested_reviewers) if requested_reviewers else ""
+
+    lines = [
+        f"**GitHub PR #{number}:** {title}{draft}",
+        f"**Repository:** {owner}/{repo}",
+        f"**Author:** {author}  |  **Labels:** {labels}  |  **State:** {state}",
+    ]
+    if reviewer_str:
+        lines.append(f"**Requested reviewers:** {reviewer_str}")
+    if branch_line:
+        lines.append(branch_line)
+    lines.append(
+        f"**Created:** {created}"
+        + (f"  |  **Merged:** {merged}" if merged else "")
+        + (f"  |  **Closed:** {closed}" if closed and not merged else "")
+    )
+    lines.append(f"**URL:** {url}")
+
+    if body:
+        lines += ["", "**Description:**", body]
+
+    if reviews:
+        lines += ["", "**Reviews:**"]
+        for rev in reviews:
+            reviewer = _username(rev.get("user"))
+            rev_state = rev.get("state", "")
+            rev_body = (rev.get("body") or "").strip()
+            submitted = (rev.get("submitted_at") or "")[:10]
+            summary = f"- **{reviewer}** {rev_state} ({submitted})"
+            if rev_body:
+                summary += f": {rev_body}"
+            lines.append(summary)
+
+    # Aggregate inline review comments by file path
+    if inline_comments:
+        by_path: dict[str, list[str]] = {}
+        for ic in inline_comments:
+            path = ic.get("path", "unknown")
+            commenter = _username(ic.get("user"))
+            text = (ic.get("body") or "").strip()
+            if text:
+                by_path.setdefault(path, []).append(f"{commenter}: {text}")
+        if by_path:
+            lines += ["", "**Inline review comments:**"]
+            for path, cmts in by_path.items():
+                lines.append(f"- `{path}`:")
+                for cmt in cmts:
+                    lines.append(f"  - {cmt}")
+
+    return "\n".join(lines)

github_dkg/github_client.py

@@ -0,0 +1,182 @@
+"""Thin async wrapper around the GitHub REST API v3."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, AsyncIterator
+
+import httpx
+
+_BASE = "https://api.github.com"
+_PER_PAGE = 100
+
+
+class GitHubRateLimitError(RuntimeError):
+    """Raised when the GitHub API rate limit has been exhausted.
+
+    Attributes:
+        reset_at: Unix timestamp at which the rate limit resets.
+    """
+
+    def __init__(self, reset_at: int | None) -> None:
+        self.reset_at = reset_at
+        msg = "GitHub API rate limit exhausted"
+        if reset_at:
+            msg += f" (resets at unix={reset_at})"
+        super().__init__(msg)
+
+
+def _check_rate_limit(response: httpx.Response) -> None:
+    """Raise GitHubRateLimitError if the response indicates rate-limit exhaustion."""
+    if response.status_code in (403, 429):
+        remaining = response.headers.get("X-RateLimit-Remaining")
+        if remaining == "0":
+            reset = response.headers.get("X-RateLimit-Reset")
+            raise GitHubRateLimitError(int(reset) if reset and reset.isdigit() else None)
+
+
+class GitHubClient:
+    def __init__(self, token: str | None = None, timeout: float = 30.0) -> None:
+        token = token or os.environ.get("GITHUB_TOKEN", "")
+        if not token:
+            raise ValueError(
+                "GitHub token required. Pass token= or set GITHUB_TOKEN env var."
+            )
+        self._headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Issues
+    # ------------------------------------------------------------------
+
+    async def list_issues(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "all",
+        since: str | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield all issues (excluding PRs) page by page."""
+        params: dict[str, Any] = {
+            "state": state,
+            "per_page": _PER_PAGE,
+            "page": 1,
+        }
+        if since:
+            params["since"] = since
+        async for item in self._paginate(f"{_BASE}/repos/{owner}/{repo}/issues", params):
+            # GitHub returns PRs in the issues endpoint; filter them out
+            if "pull_request" not in item:
+                yield item
+
+    async def get_issue(
+        self, owner: str, repo: str, number: int
+    ) -> dict[str, Any]:
+        return await self._get(f"{_BASE}/repos/{owner}/{repo}/issues/{number}")
+
+    async def list_issue_comments(
+        self, owner: str, repo: str, issue_number: int
+    ) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        params: dict[str, Any] = {"per_page": _PER_PAGE, "page": 1}
+        async for comment in self._paginate(
+            f"{_BASE}/repos/{owner}/{repo}/issues/{issue_number}/comments", params
+        ):
+            results.append(comment)
+        return results
+
+    # ------------------------------------------------------------------
+    # Pull Requests
+    # ------------------------------------------------------------------
+
+    async def list_pulls(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "all",
+        since: str | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield PRs page by page.
+
+        ``since`` is an ISO 8601 timestamp. The /pulls endpoint does not support
+        a server-side ``since`` filter, so we sort by ``updated`` desc and stop
+        as soon as we see a PR older than the cutoff.
+        """
+        params: dict[str, Any] = {
+            "state": state,
+            "per_page": _PER_PAGE,
+            "page": 1,
+            "sort": "updated",
+            "direction": "desc",
+        }
+        async for pr in self._paginate(f"{_BASE}/repos/{owner}/{repo}/pulls", params):
+            if since and (pr.get("updated_at") or "") < since:
+                return
+            yield pr
+
+    async def get_pull(
+        self, owner: str, repo: str, number: int
+    ) -> dict[str, Any]:
+        return await self._get(f"{_BASE}/repos/{owner}/{repo}/pulls/{number}")
+
+    async def list_pull_reviews(
+        self, owner: str, repo: str, pull_number: int
+    ) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        params: dict[str, Any] = {"per_page": _PER_PAGE, "page": 1}
+        async for review in self._paginate(
+            f"{_BASE}/repos/{owner}/{repo}/pulls/{pull_number}/reviews", params
+        ):
+            results.append(review)
+        return results
+
+    async def list_pull_comments(
+        self, owner: str, repo: str, pull_number: int
+    ) -> list[dict[str, Any]]:
+        """Inline review comments on a PR."""
+        results: list[dict[str, Any]] = []
+        params: dict[str, Any] = {"per_page": _PER_PAGE, "page": 1}
+        async for comment in self._paginate(
+            f"{_BASE}/repos/{owner}/{repo}/pulls/{pull_number}/comments", params
+        ):
+            results.append(comment)
+        return results
+
+    # ------------------------------------------------------------------
+    # Repository metadata
+    # ------------------------------------------------------------------
+
+    async def get_repo(self, owner: str, repo: str) -> dict[str, Any]:
+        return await self._get(f"{_BASE}/repos/{owner}/{repo}")
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _get(self, url: str) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            r = await http.get(url, headers=self._headers)
+            _check_rate_limit(r)
+            r.raise_for_status()
+            return r.json()
+
+    async def _paginate(
+        self, url: str, params: dict[str, Any]
+    ) -> AsyncIterator[dict[str, Any]]:
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            while True:
+                r = await http.get(url, headers=self._headers, params=params)
+                _check_rate_limit(r)
+                r.raise_for_status()
+                page = r.json()
+                if not page:
+                    break
+                for item in page:
+                    yield item
+                if len(page) < _PER_PAGE:
+                    break
+                params = {**params, "page": params["page"] + 1}

github_dkg/ingestor.py

@@ -0,0 +1,203 @@
+"""Orchestrates fetching from GitHub and writing to DKG v10 Working Memory."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import DKGClient
+from .formatter import format_issue, format_pull_request
+from .github_client import GitHubClient
+
+
+@dataclass
+class IngestResult:
+    issues_ingested: int = 0
+    pulls_ingested: int = 0
+    errors: list[str] = field(default_factory=list)
+    turn_uris: list[str] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return self.issues_ingested + self.pulls_ingested
+
+
+class GitHubDKGIngestor:
+    """Fetch GitHub items and write them to DKG v10 Working Memory.
+
+    Each issue and PR becomes one Knowledge Asset (via /api/memory/turn).
+    All assets for a repo are scoped to a single Context Graph.
+
+    The ``github`` client is optional — required for ingest, but ``promote``
+    only touches DKG so it can be omitted there.
+    """
+
+    def __init__(
+        self,
+        dkg: DKGClient,
+        github: GitHubClient | None = None,
+        context_graph_id: str = "",
+        layer: str = "wm",
+        max_comments_per_issue: int = 20,
+        max_reviews_per_pr: int = 10,
+        concurrency: int = 5,
+    ) -> None:
+        self._dkg = dkg
+        self._gh = github
+        self._context_graph_id = context_graph_id
+        self._layer = layer
+        self._max_comments = max_comments_per_issue
+        self._max_reviews = max_reviews_per_pr
+        self._sem = asyncio.Semaphore(concurrency)
+
+    def _require_github(self) -> GitHubClient:
+        if self._gh is None:
+            raise RuntimeError(
+                "This operation requires a GitHubClient. "
+                "Pass github=... when constructing GitHubDKGIngestor."
+            )
+        return self._gh
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def ingest_repo(
+        self,
+        owner: str,
+        repo: str,
+        since: str | None = None,
+        include_issues: bool = True,
+        include_pulls: bool = True,
+    ) -> IngestResult:
+        gh = self._require_github()
+        result = IngestResult()
+        tasks: list[Any] = []
+
+        if include_issues:
+            async for issue in gh.list_issues(owner, repo, since=since):
+                tasks.append(self._ingest_issue(owner, repo, issue, result))
+
+        if include_pulls:
+            async for pr in gh.list_pulls(owner, repo, since=since):
+                tasks.append(self._ingest_pull(owner, repo, pr, result))
+
+        await asyncio.gather(*tasks)
+        return result
+
+    async def ingest_issue(
+        self, owner: str, repo: str, issue_number: int
+    ) -> dict[str, Any]:
+        """Ingest a single issue by number. Returns the DKG turn response."""
+        gh = self._require_github()
+        issue = await gh.get_issue(owner, repo, issue_number)
+        comments = await gh.list_issue_comments(owner, repo, issue_number)
+        markdown = format_issue(issue, comments[: self._max_comments], owner, repo)
+        return await self._dkg.memory_turn(
+            context_graph_id=self._context_graph_id,
+            markdown=markdown,
+            layer=self._layer,
+            session_uri=_repo_session_uri(owner, repo),
+        )
+
+    async def ingest_pull(
+        self, owner: str, repo: str, pull_number: int
+    ) -> dict[str, Any]:
+        """Ingest a single PR by number. Returns the DKG turn response."""
+        gh = self._require_github()
+        pr, reviews, inline = await asyncio.gather(
+            gh.get_pull(owner, repo, pull_number),
+            gh.list_pull_reviews(owner, repo, pull_number),
+            gh.list_pull_comments(owner, repo, pull_number),
+        )
+        markdown = format_pull_request(
+            pr,
+            reviews[: self._max_reviews],
+            inline,
+            owner,
+            repo,
+        )
+        return await self._dkg.memory_turn(
+            context_graph_id=self._context_graph_id,
+            markdown=markdown,
+            layer=self._layer,
+            session_uri=_repo_session_uri(owner, repo),
+        )
+
+    async def promote(self, turn_uri: str) -> dict[str, Any]:
+        """Promote a Working Memory Knowledge Asset to Shared Working Memory (SHARE)."""
+        name = turn_uri.split("/")[-1]
+        return await self._dkg.assertion_promote(
+            name=name,
+            context_graph_id=self._context_graph_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _ingest_issue(
+        self,
+        owner: str,
+        repo: str,
+        issue: dict[str, Any],
+        result: IngestResult,
+    ) -> None:
+        gh = self._require_github()
+        async with self._sem:
+            try:
+                number = issue["number"]
+                comments = await gh.list_issue_comments(owner, repo, number)
+                markdown = format_issue(
+                    issue, comments[: self._max_comments], owner, repo
+                )
+                resp = await self._dkg.memory_turn(
+                    context_graph_id=self._context_graph_id,
+                    markdown=markdown,
+                    layer=self._layer,
+                    session_uri=_repo_session_uri(owner, repo),
+                )
+                result.issues_ingested += 1
+                if uri := resp.get("turnUri"):
+                    result.turn_uris.append(uri)
+            except Exception as exc:
+                result.errors.append(f"issue #{issue.get('number')}: {exc}")
+
+    async def _ingest_pull(
+        self,
+        owner: str,
+        repo: str,
+        pr: dict[str, Any],
+        result: IngestResult,
+    ) -> None:
+        gh = self._require_github()
+        async with self._sem:
+            try:
+                number = pr["number"]
+                reviews, inline = await asyncio.gather(
+                    gh.list_pull_reviews(owner, repo, number),
+                    gh.list_pull_comments(owner, repo, number),
+                )
+                markdown = format_pull_request(
+                    pr,
+                    reviews[: self._max_reviews],
+                    inline,
+                    owner,
+                    repo,
+                )
+                resp = await self._dkg.memory_turn(
+                    context_graph_id=self._context_graph_id,
+                    markdown=markdown,
+                    layer=self._layer,
+                    session_uri=_repo_session_uri(owner, repo),
+                )
+                result.pulls_ingested += 1
+                if uri := resp.get("turnUri"):
+                    result.turn_uris.append(uri)
+            except Exception as exc:
+                result.errors.append(f"PR #{pr.get('number')}: {exc}")
+
+
+def _repo_session_uri(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}"

github_dkg-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: github-dkg
+Version: 0.1.0
+Summary: Ingest GitHub issues, PRs, and review comments into DKG v10 Working Memory
+Project-URL: Repository, https://github.com/haroldboom/github-dkg
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# github-dkg
+
+Ingest GitHub issues, pull requests, and review comments into [DKG v10](https://docs.origintrail.io) Working Memory as Knowledge Assets.
+
+Every issue and PR becomes a queryable, attributable Knowledge Asset in your DKG v10 node. Key decisions can be promoted to Shared Working Memory — making your team's engineering knowledge accessible to agents.
+
+## Demo
+
+- **Walkthrough notebook:** [`demo.ipynb`](demo.ipynb) — runs end-to-end against a built-in mock of GitHub and the DKG node, no tokens required. Open in [Colab](https://colab.research.google.com/github/haroldboom/github-dkg/blob/master/demo.ipynb).
+- **Live recording script:** [`examples/demo_video.py`](examples/demo_video.py) — drives all three demos against a real DKG node and the GitHub API; this is the script behind the bounty walkthrough video.
+
+## Install
+
+```bash
+pip install github-dkg
+```
+
+## Quickstart
+
+```bash
+export DKG_TOKEN=your-dkg-token
+export DKG_BASE_URL=http://localhost:9200
+export DKG_CONTEXT_GRAPH=your-context-graph-id
+export GITHUB_TOKEN=your-github-token
+
+# Bulk-ingest all issues and PRs from a repository
+github-dkg ingest owner/repo --context-graph $DKG_CONTEXT_GRAPH
+
+# Ingest a single issue
+github-dkg ingest-one owner/repo 42 --type issue --context-graph $DKG_CONTEXT_GRAPH
+
+# Ingest a single PR
+github-dkg ingest-one owner/repo 99 --type pr --context-graph $DKG_CONTEXT_GRAPH
+
+# Search ingested knowledge
+github-dkg search "authentication bug" --context-graph $DKG_CONTEXT_GRAPH
+
+# Promote a Working Memory asset to Shared Working Memory (SHARE)
+github-dkg promote dkg://wm/turn/abc123 --context-graph $DKG_CONTEXT_GRAPH
+```
+
+## GitHub Action
+
+Automatically ingest issues and PRs as they are created or updated. Add to `.github/workflows/dkg-ingest.yml`:
+
+```yaml
+on:
+  issues:
+    types: [opened, edited, closed]
+  pull_request:
+    types: [opened, edited, closed]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  ingest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: haroldboom/github-dkg@v0.1.0
+        id: ingest
+        with:
+          dkg-token: ${{ secrets.DKG_TOKEN }}
+          dkg-base-url: ${{ secrets.DKG_BASE_URL }}
+          dkg-context-graph: ${{ secrets.DKG_CONTEXT_GRAPH }}
+```
+
+See `examples/workflow.yml` for a complete example including automatic promotion of architecture-decision PRs to Shared Working Memory.
+
+## Python API
+
+```python
+import asyncio
+from github_dkg import DKGClient, GitHubClient, GitHubDKGIngestor
+
+async def main():
+    dkg = DKGClient(base_url="http://localhost:9200", token="your-token")
+    gh = GitHubClient(token="your-github-token")
+    ingestor = GitHubDKGIngestor(dkg=dkg, github=gh, context_graph_id="cg-123")
+
+    # Bulk ingest
+    result = await ingestor.ingest_repo("owner", "repo", since="2024-01-01")
+    print(f"Ingested {result.total} items ({len(result.errors)} errors)")
+
+    # Single item
+    resp = await ingestor.ingest_issue("owner", "repo", 42)
+    print(f"Turn URI: {resp['turnUri']}")
+
+    # Promote to Shared Working Memory
+    await ingestor.promote(resp["turnUri"])
+
+asyncio.run(main())
+```
+
+## `--since` filtering
+
+`--since` accepts an ISO 8601 timestamp and limits ingest to items updated after that point.
+
+- **Issues:** filtered server-side by GitHub via the `since` parameter on `/issues`.
+- **Pull requests:** GitHub's `/pulls` endpoint has no `since` filter, so the package requests `sort=updated&direction=desc` and stops paginating once results fall below the cutoff. Net result: only PRs touched after `--since` are fetched and ingested.
+
+Comment-only updates (a new comment without an issue/PR body edit) still bump `updated_at`, so they're included.
+
+## Rate limiting
+
+`GitHubClient` raises `github_dkg.github_client.GitHubRateLimitError` when GitHub returns `403`/`429` with `X-RateLimit-Remaining: 0`. The exception carries `reset_at` (unix timestamp) so callers can decide whether to back off, sleep, or fail. Authenticated tokens get 5,000 requests/hour; bulk-ingesting a large repo with many comment-heavy PRs can approach this limit.
+
+```python
+from github_dkg.github_client import GitHubRateLimitError
+
+try:
+    result = await ingestor.ingest_repo("OriginTrail", "dkg-v9")
+except GitHubRateLimitError as e:
+    print(f"Rate limited; resets at unix={e.reset_at}")
+```
+
+## Memory layers
+
+| Layer | Flag | Visibility |
+|---|---|---|
+| Working Memory | `--layer wm` (default) | Private to your node |
+| Shared Working Memory | `--layer swm` | Gossiped across the paranet |
+
+Promotion from Working Memory to Shared Working Memory is always explicit — nothing is shared automatically.
+
+## License
+
+MIT

github_dkg-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+github_dkg/__init__.py,sha256=pInaVjlLzKX6l_tq0wkik3cQDBrBgyYtOsB2XmgkuHE,281
+github_dkg/cli.py,sha256=tJulW7owe6O0Ex1xTlLRQjRWluFWSORb1KAbpiZOiBM,6391
+github_dkg/client.py,sha256=B_o3XielJTQSV1_fE6TPD1SuQrdQXiQZ372V8b_-IDE,4424
+github_dkg/formatter.py,sha256=II0vHLby0o0RoXWiRb7nI1-8zPdYFp-2lnC7020CVhk,4636
+github_dkg/github_client.py,sha256=9G85qBDAZJMRJtg9GsMUlquwC8egM6pvLbem5VMVu24,6505
+github_dkg/ingestor.py,sha256=xESZxR4ehXEv38ULeWSdXPzykIJvrnmlwgAn7oLRjXQ,7062
+github_dkg-0.1.0.dist-info/METADATA,sha256=260qj5RC7ZtTwes54yyhXQPhrVQ4nqhUVF0gxgxMgD4,5128
+github_dkg-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+github_dkg-0.1.0.dist-info/entry_points.txt,sha256=RRzXzSjXBtEKMnfQ2oLMLfrTv4h8hXUXbOVhgF7COdU,51
+github_dkg-0.1.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+github_dkg-0.1.0.dist-info/RECORD,,

github_dkg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

github_dkg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-dkg = github_dkg.cli:main

github_dkg-0.1.0.dist-info/licenses/LICENSE

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