forgesight-github 0.1.0__py3-none-any.whl

forgesight_github/__init__.py

@@ -0,0 +1,34 @@
+"""ForgeSight GitHub Actions integration — one-line CI bootstrap; run↔commit/PR/job link.
+
+```python
+from forgesight_github import bootstrap
+bootstrap()   # configure() + attach GITHUB_* metadata + job summary on exit
+```
+"""
+
+from __future__ import annotations
+
+from .bootstrap import bootstrap, in_github_actions, install, run_exit_hook
+from .interceptor import GitHubMetadataInterceptor
+from .metadata import GITHUB_ENV_MAP, github_metadata, pr_number
+from .oidc import fetch_oidc_token
+from .summary import DEFAULT_SUMMARY_METRICS, SummaryCollector, format_summary, write_summary
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_SUMMARY_METRICS",
+    "GITHUB_ENV_MAP",
+    "GitHubMetadataInterceptor",
+    "SummaryCollector",
+    "__version__",
+    "bootstrap",
+    "fetch_oidc_token",
+    "format_summary",
+    "github_metadata",
+    "in_github_actions",
+    "install",
+    "pr_number",
+    "run_exit_hook",
+    "write_summary",
+]

forgesight_github/bootstrap.py

@@ -0,0 +1,127 @@
+"""``bootstrap()`` — the one-line CI wiring, plus the ``forgesight.integrations`` ``install``.
+
+``bootstrap()`` does three things in order: read ``GITHUB_*`` metadata, ``configure()`` the
+SDK and attach that metadata to every record (FR-5), and register an exit hook that flushes
+telemetry (so a deploy/ephemeral runner never drops it) and writes a job summary. Outside CI
+it falls back to a plain ``configure()`` and warns once, so the same script runs locally.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+from collections.abc import Mapping, Sequence
+
+from forgesight_core import Runtime, configure
+
+from .interceptor import GitHubMetadataInterceptor
+from .metadata import github_metadata
+from .oidc import fetch_oidc_token
+from .summary import DEFAULT_SUMMARY_METRICS, SummaryCollector, write_summary
+
+_log = logging.getLogger("forgesight.github")
+
+OIDC_TOKEN_ENV = "FORGESIGHT_OTLP_TOKEN"  # documented hand-off for the collector/exporter
+_warned_not_ci = False
+_installed_config: dict[str, object] = {}
+
+
+def in_github_actions(env: Mapping[str, str] | None = None) -> bool:
+    source = os.environ if env is None else env
+    return source.get("GITHUB_ACTIONS") == "true"
+
+
+def bootstrap(
+    *,
+    write_summary: bool = True,
+    summary_metrics: Sequence[str] = DEFAULT_SUMMARY_METRICS,
+    oidc: bool = False,
+    extra_metadata: Mapping[str, str] | None = None,
+    _register_exit: bool = True,
+) -> None:
+    """One-line CI bootstrap: ``configure()``, attach ``GITHUB_*`` metadata, summary-on-exit."""
+    in_ci = in_github_actions()
+    if not in_ci:
+        _warn_not_ci()
+
+    metadata: dict[str, str] = github_metadata() if in_ci else {}
+    if extra_metadata:
+        metadata.update(extra_metadata)
+
+    if oidc:
+        _apply_oidc()
+
+    runtime = configure()
+    if metadata:
+        runtime.add_interceptor(GitHubMetadataInterceptor(metadata))
+
+    do_summary = write_summary and in_ci and _summary_enabled()
+    collector: SummaryCollector | None = None
+    if do_summary:
+        collector = SummaryCollector()
+        runtime.add_listener(collector)
+
+    fields = tuple(summary_metrics)
+    if _register_exit:
+        atexit.register(run_exit_hook, runtime, collector, fields)
+
+
+def run_exit_hook(
+    runtime: Runtime, collector: SummaryCollector | None, fields: Sequence[str]
+) -> None:
+    """Flush telemetry then (best-effort) write the job summary. Safe to call directly."""
+    timeout = runtime.config.export_timeout_millis
+    try:
+        runtime.force_flush(timeout)
+    finally:
+        runtime.shutdown(timeout)
+    if collector is not None:
+        write_summary(collector, fields)
+
+
+def _apply_oidc() -> None:
+    token = fetch_oidc_token()
+    if token is None:
+        _log.warning(
+            "forgesight-github: OIDC requested but no runner id-token endpoint; "
+            "falling back to configured exporter auth"
+        )
+        return
+    os.environ.setdefault(OIDC_TOKEN_ENV, token)
+    _log.info("forgesight-github: obtained runner OIDC token (handed off via %s)", OIDC_TOKEN_ENV)
+
+
+def _summary_enabled() -> bool:
+    env = os.environ.get("FORGESIGHT_GITHUB_SUMMARY")
+    if env is not None:
+        return env.strip().lower() in ("1", "true", "yes", "on")
+    if "write_summary" in _installed_config:
+        return bool(_installed_config["write_summary"])
+    return True
+
+
+def _warn_not_ci() -> None:
+    global _warned_not_ci
+    if not _warned_not_ci:
+        _log.warning(
+            "forgesight-github: GITHUB_ACTIONS unset; bootstrap() falls back to plain configure()"
+        )
+        _warned_not_ci = True
+
+
+def install(config: dict[str, object] | None = None) -> bool:
+    """The ``forgesight.integrations`` entry point: stash config defaults for ``bootstrap()``."""
+    cfg = dict(config or {})
+    _installed_config.clear()
+    if not cfg.get("enabled", True):
+        return False
+    _installed_config.update(cfg)
+    return True
+
+
+def _reset_for_tests() -> None:
+    """Clear module state so tests don't leak the not-in-CI warning / installed config."""
+    global _warned_not_ci
+    _warned_not_ci = False
+    _installed_config.clear()

forgesight_github/interceptor.py

@@ -0,0 +1,30 @@
+"""``GitHubMetadataInterceptor`` — attach CI correlation metadata to every record.
+
+``bootstrap()`` runs once at process start, before any run opens, so there is no live run
+to ``set_metadata`` on. Instead this interceptor merges the ``GITHUB_*`` metadata onto every
+record's attributes (FR-5) — so each span carries the repo / sha / PR / workflow / job and
+"spend on PR #1234" is a one-line backend query. Per-call metadata wins (``setdefault``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from types import MappingProxyType
+
+from forgesight_api import Record
+
+
+class GitHubMetadataInterceptor:
+    """Merge fixed CI metadata into each record's attributes without overwriting per-call keys."""
+
+    def __init__(self, metadata: Mapping[str, str]) -> None:
+        self._metadata = dict(metadata)
+
+    def intercept(self, record: Record) -> Record | None:
+        if not self._metadata:
+            return record
+        attrs = dict(record.attributes)
+        for key, value in self._metadata.items():
+            attrs.setdefault(key, value)  # don't clobber metadata the caller set explicitly
+        return replace(record, attributes=MappingProxyType(attrs))

forgesight_github/metadata.py

@@ -0,0 +1,73 @@
+"""``GITHUB_*`` → business-metadata mapping (FR-5), per the OTel VCS / CICD conventions.
+
+Pure: reads the runner environment and parses the PR number from the event payload JSON
+(the one field that is not a plain env var). Maps onto the current ``vcs.*`` / ``cicd.*``
+semconv, with ``agentforge.*`` extensions where no convention exists yet. Absent fields are
+omitted, never fabricated.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections.abc import Mapping, Sequence
+
+_log = logging.getLogger("forgesight.github")
+
+# GITHUB_* env var → telemetry attribute key (the documented capture set).
+GITHUB_ENV_MAP: Mapping[str, str] = {
+    "GITHUB_REPOSITORY": "vcs.repository.name",
+    "GITHUB_SHA": "vcs.ref.head.revision",
+    "GITHUB_REF": "vcs.ref.head.name",
+    "GITHUB_RUN_ID": "cicd.pipeline.run.id",
+    "GITHUB_RUN_ATTEMPT": "cicd.pipeline.run.attempt",
+    "GITHUB_WORKFLOW": "cicd.pipeline.name",
+    "GITHUB_JOB": "cicd.pipeline.task.name",
+    "GITHUB_ACTOR": "vcs.change.author",  # agentforge extension where no semconv exists
+    "GITHUB_EVENT_NAME": "cicd.pipeline.run.trigger",
+}
+PR_NUMBER_KEY = "vcs.change.id"
+
+
+def github_metadata(
+    *,
+    capture_env: Sequence[str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Return the ``GITHUB_*`` → metadata mapping (repo, sha, ref, run id/attempt, workflow,
+    job, actor, event, PR number). ``capture_env`` restricts which ``GITHUB_*`` keys to read.
+    """
+    source = os.environ if env is None else env
+    allowed = set(capture_env) if capture_env is not None else None
+    out: dict[str, str] = {}
+    for env_key, attr in GITHUB_ENV_MAP.items():
+        if allowed is not None and env_key not in allowed:
+            continue
+        value = source.get(env_key)
+        if value:
+            out[attr] = value
+    pr = pr_number(source)
+    if pr is not None:
+        out[PR_NUMBER_KEY] = pr
+    return out
+
+
+def pr_number(env: Mapping[str, str]) -> str | None:
+    """PR number from the event payload JSON for ``pull_request*`` events, else ``None``."""
+    event_name = env.get("GITHUB_EVENT_NAME", "")
+    if not event_name.startswith("pull_request"):
+        return None
+    path = env.get("GITHUB_EVENT_PATH")
+    if not path or not os.path.exists(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, ValueError):  # unreadable / malformed payload — don't fabricate
+        _log.warning("forgesight-github: could not read event payload at %s", path)
+        return None
+    candidate = payload.get("pull_request", {}).get("number")
+    if candidate is None:
+        candidate = payload.get("number")
+    return str(candidate) if candidate is not None else None

forgesight_github/oidc.py

@@ -0,0 +1,48 @@
+"""Best-effort GitHub Actions OIDC id-token fetch (stdlib HTTP, no GitHub SDK).
+
+CI should authenticate to the collector with the runner's short-lived OIDC token rather than
+a static secret. The runner exposes a token endpoint via ``ACTIONS_ID_TOKEN_REQUEST_URL`` +
+``ACTIONS_ID_TOKEN_REQUEST_TOKEN`` (only when the job has ``id-token: write``). This fetch is
+best-effort: any failure returns ``None`` so ``bootstrap`` falls back to configured exporter
+auth and never fails the job (P6).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from typing import Any
+
+_log = logging.getLogger("forgesight.github")
+
+_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL"
+_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN"
+
+
+def fetch_oidc_token(
+    *, audience: str | None = None, env: Mapping[str, str] | None = None, timeout: float = 5.0
+) -> str | None:
+    """Return the runner OIDC id-token, or ``None`` if unavailable / on any error."""
+    import os
+
+    source = os.environ if env is None else env
+    url = source.get(_URL_ENV)
+    bearer = source.get(_TOKEN_ENV)
+    if not url or not bearer:
+        return None
+    if audience:
+        url = f"{url}&audience={urllib.parse.quote(audience)}"
+    request = urllib.request.Request(url, headers={"Authorization": f"Bearer {bearer}"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload: Any = json.loads(response.read().decode("utf-8"))
+    except Exception:  # network / parse / auth — best-effort, never raise (P6)
+        _log.warning(
+            "forgesight-github: OIDC token request failed; falling back to configured auth"
+        )
+        return None
+    value = payload.get("value") if isinstance(payload, dict) else None
+    return str(value) if value else None

forgesight_github/summary.py

@@ -0,0 +1,90 @@
+"""Per-job run summary written to ``$GITHUB_STEP_SUMMARY`` on exit.
+
+A :class:`SummaryCollector` (an ``EventListener``) tallies the runs the SDK saw in the
+process — status, cost (summed from LLM calls), duration, tool-call count. On exit a markdown
+block is appended to the Actions job summary so the UI shows "run: ok · cost $0.12 · 38s · 3
+tool calls" with no author effort. The write is best-effort and never fails the job (P6).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+
+from forgesight_api import EventType, LifecycleEvent, RunStatus
+
+_log = logging.getLogger("forgesight.github")
+
+DEFAULT_SUMMARY_METRICS: tuple[str, ...] = ("status", "cost_usd", "duration_ms", "n_tool_calls")
+_RUN_DONE = frozenset({EventType.RUN_COMPLETED, EventType.RUN_FAILED})
+_TOOL_DONE = frozenset({EventType.TOOL_EXECUTED, EventType.MCP_EXECUTED})
+
+
+class SummaryCollector:
+    """Tally runs / cost / tool-calls from lifecycle events (an ``EventListener``)."""
+
+    def __init__(self) -> None:
+        self.run_statuses: list[str] = []
+        self.total_duration_ms: float = 0.0
+        self.total_cost_usd: float = 0.0
+        self.n_tool_calls: int = 0
+
+    def on_event(self, event: LifecycleEvent) -> None:
+        record = event.record
+        if event.type in _RUN_DONE and record is not None:
+            self.run_statuses.append(record.status.value)
+            if record.duration_ms is not None:
+                self.total_duration_ms += record.duration_ms
+        elif event.type is EventType.LLM_EXECUTED and record is not None and record.llm is not None:
+            if record.llm.cost_usd is not None:
+                self.total_cost_usd += record.llm.cost_usd
+        elif event.type in _TOOL_DONE:
+            self.n_tool_calls += 1
+
+    # --- rendering --------------------------------------------------------
+    def status(self) -> str:
+        if not self.run_statuses:
+            return "no runs"
+        if all(s == RunStatus.OK.value for s in self.run_statuses):
+            return "ok"
+        return "error"
+
+    def values(self) -> dict[str, str]:
+        return {
+            "status": self.status(),
+            "cost_usd": f"${self.total_cost_usd:.4f}",
+            "duration_ms": f"{self.total_duration_ms:.0f}",
+            "n_tool_calls": str(self.n_tool_calls),
+            "runs": str(len(self.run_statuses)),
+        }
+
+
+def format_summary(collector: SummaryCollector, fields: Sequence[str]) -> str:
+    """Render the markdown block appended to the job summary."""
+    n = len(collector.run_statuses)
+    values = collector.values()
+    heading = f"### 🤖 ForgeSight agent run{'s' if n != 1 else ''}"
+    lines = [heading]
+    if n > 1:
+        lines.append(f"- **runs**: {n}")
+    for field in fields:
+        if field in values:
+            lines.append(f"- **{field}**: {values[field]}")
+    return "\n".join(lines) + "\n"
+
+
+def write_summary(
+    collector: SummaryCollector, fields: Sequence[str], *, path: str | None = None
+) -> bool:
+    """Append the summary to ``$GITHUB_STEP_SUMMARY`` (or ``path``). Never raises (P6)."""
+    target = path or os.environ.get("GITHUB_STEP_SUMMARY")
+    if not target:
+        return False
+    try:
+        with open(target, "a", encoding="utf-8") as handle:
+            handle.write(format_summary(collector, fields))
+    except OSError:  # a failed summary write must never fail the job (P6)
+        _log.warning("forgesight-github: could not write job summary to %s", target)
+        return False
+    return True

forgesight_github-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: forgesight-github
+Version: 0.1.0
+Summary: ForgeSight GitHub Actions integration — one-line CI bootstrap; run↔commit/PR/job correlation.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,ci,forgesight,github-actions,observability
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Description-Content-Type: text/markdown
+
+# forgesight-github
+
+The GitHub Actions integration for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+One line in your CI entry script correlates every agent run with the commit / PR / job /
+workflow that triggered it, and writes a cost+duration+status summary to the job page.
+
+```bash
+pip install forgesight-github
+```
+
+```python
+from forgesight_github import bootstrap
+bootstrap()   # configure() + attach GITHUB_* metadata + job summary on exit
+
+# Unchanged agent code — every run in this job is now correlated and flushed cleanly.
+result = await pr_reviewer.run(task)
+```
+
+```yaml
+# .github/workflows/review.yml
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write          # only if using OIDC exporter auth
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install forgesight-github
+      - run: python review_agent.py
+        env:
+          FORGESIGHT_EXPORTERS: otlp
+          FORGESIGHT_OTLP_ENDPOINT: ${{ vars.OTEL_COLLECTOR }}
+```
+
+## What you get
+
+- **Run↔commit/PR/job link for free.** Every run carries `vcs.repository.name`,
+  `vcs.ref.head.revision` (sha), `vcs.ref.head.name` (ref), `vcs.change.id` (PR number),
+  `cicd.pipeline.run.id` / `.attempt`, `cicd.pipeline.name` (workflow), and
+  `cicd.pipeline.task.name` (job) as run-scoped metadata (FR-5), so "agent spend on PR #1234"
+  or "spend by workflow" is a one-line backend query.
+- **PR number resolved correctly.** Parsed from the event payload JSON (`$GITHUB_EVENT_PATH`)
+  for `pull_request*` events — absent (not fabricated) otherwise.
+- **A useful job summary, automatically.** A markdown block —
+  `status · cost_usd · duration_ms · n_tool_calls` — is appended to `$GITHUB_STEP_SUMMARY`
+  on exit. Best-effort; never fails the job.
+- **Zero lost CI telemetry.** An `atexit` hook calls `force_flush()` + `shutdown()` so the
+  ephemeral runner never drops the buffered batch.
+- **Safe exporter auth (opt-in).** `bootstrap(oidc=True)` fetches the runner's short-lived
+  OIDC id-token (requires `id-token: write`) instead of a static secret; falls back to
+  configured auth if unavailable.
+- **Runs locally too.** Outside CI (`GITHUB_ACTIONS` unset) it falls back to a plain
+  `configure()` and warns once.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `write_summary` | `FORGESIGHT_GITHUB_SUMMARY` | `true` |
+| `oidc` | — (kwarg) | `false` |
+| `capture_env` | — (kwarg) | the documented `GITHUB_*` set |
+
+## License
+
+Apache-2.0

forgesight_github-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+forgesight_github/__init__.py,sha256=B1ulGxvM4vQ8ewryALhWw0QAgO5MIGcW7OXetY-dbNQ,940
+forgesight_github/bootstrap.py,sha256=GMbN05lGPpTpOWTWewtSsIhgtLNsy4xXGYkAR8CRV4k,4146
+forgesight_github/interceptor.py,sha256=NBUWhQotF9YCyUHXxZJ2ZDtUHeUvPDWod48-fRppdPE,1233
+forgesight_github/metadata.py,sha256=LvD9ouY9KOfAt2axBOa4MZbuUGnd-M74lTqDzk_n6gU,2822
+forgesight_github/oidc.py,sha256=4nRwVDVyw-V4mRD2WkMdLxvUQwaVMnkNsCmophwqpno,1858
+forgesight_github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forgesight_github/summary.py,sha256=IerdIhcrbWETQF4u-ScyUavGCF_XNuIuaqDKTSZwXA4,3543
+forgesight_github-0.1.0.dist-info/METADATA,sha256=cMlU_F22KY3utJHWgf4Q2OVH-RxH3w3T7u08BmUrQtM,3660
+forgesight_github-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+forgesight_github-0.1.0.dist-info/entry_points.txt,sha256=1Py8HkDOmrMdALmWqkZYIEJlSuxxfoDyElU2a9glmDM,61
+forgesight_github-0.1.0.dist-info/RECORD,,

forgesight_github-0.1.0.dist-info/WHEEL

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

forgesight_github-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[forgesight.integrations]
+github = forgesight_github:install