sediment-api 0.1.0__py3-none-any.whl

sediment_api/reports/precision_report.py

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Attribution ground-truth precision report.
+
+Loads a JSONL ground-truth manifest, derives one org's attributions, and
+prints notes-attributed and jaccard-attributed precision/recall separately.
+The reusable schema and scoring logic live in
+``sediment_derive.precision_report`` beside the scorer precision harness; this
+script is only the operator-facing stdout wrapper.
+
+    sediment report precision --org acme-corp \
+        --manifest packages/derive/tests/fixtures/ground_truth/illustrative_manifest.jsonl
+    sediment report precision --org acme-corp --manifest gt.jsonl --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict
+
+from sediment_core import normalize_org_id
+from sediment_derive import MirrorManager
+from sediment_derive.precision_report import (
+    DEFAULT_SWEEP_THRESHOLDS,
+    DEFAULT_THRESHOLD,
+    AttributionPrecisionReport,
+    generate_precision_report_for_org,
+    load_ground_truth_manifest,
+)
+
+from ..database import add_database_url_argument, one_shot_fact_store
+
+_DEFAULT_MIRROR_PATH = "./mirrors"
+
+
+def _parse_thresholds(raw: str) -> list[float]:
+    try:
+        thresholds = [float(part.strip()) for part in raw.split(",") if part.strip()]
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "thresholds must be comma-separated numbers"
+        ) from exc
+    if not thresholds:
+        raise argparse.ArgumentTypeError("at least one threshold is required")
+    for threshold in thresholds:
+        if threshold < 0.0 or threshold > 1.0:
+            raise argparse.ArgumentTypeError("thresholds must be between 0.0 and 1.0")
+    return thresholds
+
+
+def _result_dict(report: AttributionPrecisionReport) -> dict[str, object]:
+    return {
+        "threshold": report.threshold,
+        "by_source": {
+            source.value: _source_dict(source_report)
+            for source, source_report in report.by_source.items()
+        },
+    }
+
+
+def _source_dict(report: AttributionPrecisionReport) -> dict[str, object]:
+    return {
+        "default": asdict(report.default),
+        "sweep": [asdict(row) for row in report.sweep],
+        "skipped_unlabelled_predictions": report.skipped_unlabelled_predictions,
+        "skipped_repository_ground_truth": report.skipped_repository_ground_truth,
+        "skipped_repository_predictions": report.skipped_repository_predictions,
+    }
+
+
+def _print_table(report: AttributionPrecisionReport) -> None:
+    print(f"default_threshold: {report.threshold:.2f}")
+    for source, source_report in report.by_source.items():
+        row = source_report.default
+        print(f"{source.value}:")
+        print(
+            "  "
+            f"precision={row.precision:.4f} recall={row.recall:.4f} "
+            f"tp={row.true_positives} fp={row.false_positives} "
+            f"fn={row.false_negatives} tn={row.true_negatives}"
+        )
+        print(
+            "  "
+            f"skipped_unlabelled_predictions="
+            f"{source_report.skipped_unlabelled_predictions}"
+        )
+        print(
+            f"  skipped_repository_ground_truth={source_report.skipped_repository_ground_truth} "
+            f"skipped_repository_predictions={source_report.skipped_repository_predictions}"
+        )
+        print("  sweep:")
+        for sweep_row in source_report.sweep:
+            print(
+                "    "
+                f"threshold={sweep_row.threshold:.2f} "
+                f"precision={sweep_row.precision:.4f} "
+                f"recall={sweep_row.recall:.4f} "
+                f"tp={sweep_row.true_positives} "
+                f"fp={sweep_row.false_positives} "
+                f"fn={sweep_row.false_negatives} "
+                f"tn={sweep_row.true_negatives}"
+            )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argv contract for this report, extracted so the generated
+    CLI reference can walk it."""
+    parser = argparse.ArgumentParser(
+        prog="precision_report",
+        description="Score derived attributions against a ground-truth manifest.",
+    )
+    parser.add_argument(
+        "--org",
+        default=os.environ.get("SEDIMENT_ORG_ID"),
+        required=not os.environ.get("SEDIMENT_ORG_ID"),
+        help="org id (default: $SEDIMENT_ORG_ID)",
+    )
+    parser.add_argument("--manifest", required=True, help="JSONL ground-truth manifest")
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=DEFAULT_THRESHOLD,
+        help=f"default scoring threshold (default: {DEFAULT_THRESHOLD})",
+    )
+    parser.add_argument(
+        "--sweep-thresholds",
+        type=_parse_thresholds,
+        default=list(DEFAULT_SWEEP_THRESHOLDS),
+        help="comma-separated sweep thresholds (default: 0.1,0.2,...,0.9)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="emit JSON instead of a text report"
+    )
+    add_database_url_argument(parser)
+    parser.add_argument(
+        "--mirror-path",
+        default=os.environ.get("SEDIMENT_MIRROR_PATH", _DEFAULT_MIRROR_PATH),
+        help="base dir for git mirrors (default: $SEDIMENT_MIRROR_PATH or "
+        f"{_DEFAULT_MIRROR_PATH!r})",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not 0.0 <= args.threshold <= 1.0:
+        print(
+            "error: --threshold must be between 0.0 and 1.0",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        org_id = normalize_org_id(args.org)
+        manifest = load_ground_truth_manifest(args.manifest)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    with one_shot_fact_store(
+        args.database_url, operation="generate precision report"
+    ) as store:
+        report = generate_precision_report_for_org(
+            store,
+            MirrorManager(args.mirror_path),
+            org_id,
+            manifest,
+            threshold=args.threshold,
+            sweep_threshold_values=args.sweep_thresholds,
+        )
+
+    if args.json:
+        print(json.dumps(_result_dict(report), indent=2))
+    else:
+        _print_table(report)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sediment_api/reports/recovery_yield_report.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Recovery-pair yield report: failed CI runs, emitted pairs, skips.
+
+Prints ``sediment_export.generate_recovery_yield_report`` for one org: a
+compact stdout summary by default, or ``--json`` for machines.
+
+    sediment report recovery-yield --org acme-corp
+    sediment report recovery-yield --org acme-corp --json
+
+Storage is read the same way ``model_report.py`` reads it:
+``--database-url``/``SEDIMENT_DATABASE_URL`` and ``--mirror-path``/
+``SEDIMENT_MIRROR_PATH``. A missing mirror path is not fatal; unmirrored repos
+are counted in the recovery derivation's ``mirror_absent`` skip tally.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict
+
+from sediment_core import normalize_org_id
+from sediment_derive import MirrorManager
+from sediment_export import (
+    DiffSizeStats,
+    RecoveryYieldReport,
+    generate_recovery_yield_report,
+)
+
+from ..database import add_database_url_argument, one_shot_fact_store
+
+_DEFAULT_MIRROR_PATH = "./mirrors"
+
+
+def _print_table(row: RecoveryYieldReport) -> None:
+    print(f"failed_ci_runs: {row.total_failed_ci_runs}")
+    print(f"recovery_pairs: {row.recovery_pairs}")
+    print(f"recovery_yield: {row.recovery_yield_rate:.1%}")
+    print("skipped:")
+    if not row.skipped:
+        print("  none")
+    else:
+        for reason, count in sorted(row.skipped.items()):
+            print(f"  {reason}: {count}")
+    distribution = row.diff_size_distribution
+    print("diff_size_distribution:")
+    print(f"  max_recovery_diff_lines: {distribution.max_recovery_diff_lines}")
+    print("  kept:")
+    _print_diff_size_stats(distribution.kept)
+    print("  dropped:")
+    _print_diff_size_stats(distribution.dropped)
+
+
+def _print_diff_size_stats(stats: DiffSizeStats) -> None:
+    print(f"    count: {stats.count}")
+    print(f"    min: {stats.min}")
+    print(f"    median: {stats.median}")
+    print(f"    p90: {stats.p90}")
+    print(f"    max: {stats.max}")
+    print("    histogram:")
+    if not stats.histogram:
+        print("      none")
+        return
+    for bucket, count in stats.histogram.items():
+        print(f"      {bucket}: {count}")
+
+
+def _row_dict(row: RecoveryYieldReport) -> dict:
+    return {
+        "total_failed_ci_runs": row.total_failed_ci_runs,
+        "recovery_pairs": row.recovery_pairs,
+        "recovery_yield_rate": row.recovery_yield_rate,
+        "skipped": dict(row.skipped),
+        "diff_size_distribution": asdict(row.diff_size_distribution),
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argv contract for this report, extracted so the generated
+    CLI reference can walk it."""
+    parser = argparse.ArgumentParser(
+        prog="recovery_yield_report", description=__doc__.splitlines()[0]
+    )
+    parser.add_argument(
+        "--org",
+        default=os.environ.get("SEDIMENT_ORG_ID"),
+        required=not os.environ.get("SEDIMENT_ORG_ID"),
+        help="org id (default: $SEDIMENT_ORG_ID)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="emit a JSON row instead of a table"
+    )
+    add_database_url_argument(parser)
+    parser.add_argument(
+        "--mirror-path",
+        default=os.environ.get("SEDIMENT_MIRROR_PATH", _DEFAULT_MIRROR_PATH),
+        help="base dir for git mirrors (default: $SEDIMENT_MIRROR_PATH or "
+        f"{_DEFAULT_MIRROR_PATH!r})",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        org_id = normalize_org_id(args.org)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    with one_shot_fact_store(
+        args.database_url, operation="generate recovery-yield report"
+    ) as store:
+        row = generate_recovery_yield_report(
+            store,
+            MirrorManager(args.mirror_path),
+            org_id,
+        )
+
+    if args.json:
+        print(json.dumps(_row_dict(row), indent=2))
+    else:
+        print(f"org: {org_id}")
+        _print_table(row)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sediment_api/routers/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Ingest routers — one module per door. Routers write facts only: no
+attribution, no derivation at ingest (ADR 0001)."""

sediment_api/routers/ci_vendor.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+POST /ingest/ci — vendor-neutral CI ingest. The GitHub webhook door lives
+at /ingest/github/ci, so the plain name belongs to the door any CI can
+call.
+
+One authenticated bearer POST any CI pipeline can ``curl`` to store a
+``CIOutcome`` fact. The caller normalizes its own CI system into a
+``CIProvider`` value and the known ``CIResult`` vocabulary; the server
+validates at the trust boundary and stores — no per-vendor parsing, no
+new fact shape.
+
+Dedup: the store's ``uq_ci_run`` UNIQUE index on provider run id and attempt
+collapses redeliveries; ``stored: false`` means success, not an error.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from sediment_core import (
+    BranchName,
+    CIOutcome,
+    CIReason,
+    CIProvider,
+    CIResult,
+    CommitSha,
+    FactStore,
+    ForgeProvider,
+    ForgeHost,
+    ProviderRepositoryId,
+    NonEmptyId,
+    NonEmptyContent,
+    RepoSlug,
+    WorkflowName,
+    WorkflowPath,
+)
+
+from ..config import settings
+from ..deps import get_store, verify_ingest_token
+
+router = APIRouter(tags=["ci-vendor"])
+
+
+class VendorCIRequest(BaseModel):
+    """The vendor-neutral CI outcome payload — callers normalize their own
+    CI system into this shape. ``extra=\"forbid\"`` so a caller naming
+    an org or fabricating fields is rejected at the boundary.
+
+    The identity fields carry the shared core definitions on
+    the envelope, so malformed input 422s at the door rather than
+    surfacing as a ValidationError-turned-500 inside the handler:
+    ``CommitSha`` (40- and 64-char object names — a SHA-256 repo can use
+    this door), ``RepoSlug`` (required — a vendor fact without a repo has
+    no CI-attach join), ``BranchName`` (``refs/heads/x`` normalizes to
+    ``x``, one recovery lineage bucket per pipeline), and a required
+    non-empty ``run_id``. ``run_url`` is optional location metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: CIProvider = Field(
+        description=(
+            "The normalized CI system. The sender declares it from integration "
+            "configuration; Sediment does not infer it from a URL"
+        )
+    )
+    run_id: NonEmptyId = Field(
+        description=(
+            "The provider-issued pipeline-run id, unique within the deployment "
+            "organization and provider namespace"
+        )
+    )
+    run_attempt: int | None = Field(default=None, ge=1, le=2**63 - 1, strict=True)
+    repo: RepoSlug
+    repository_provider: ForgeProvider | None = None
+    repository_host: ForgeHost | None = None
+    repository_id: ProviderRepositoryId | None = None
+    commit_sha: CommitSha
+    branch: BranchName
+    # Workflow names preserve descriptive content; paths identify definitions.
+    workflow_name: WorkflowName = ""
+    workflow_id: NonEmptyId | None = None
+    workflow_path: WorkflowPath | None = None
+    result: CIResult
+    run_url: NonEmptyContent | None = None
+    provider_result: NonEmptyContent | None = None
+    error_type: NonEmptyContent | None = None
+    reason: CIReason | None = None
+    source_event_type: NonEmptyContent | None = None
+    source_spec_version: NonEmptyContent | None = None
+    source_event_id: NonEmptyId | None = None
+
+    @model_validator(mode="after")
+    def _complete_repository_identity(self):
+        present = tuple(
+            value is not None
+            for value in (
+                self.repository_provider,
+                self.repository_host,
+                self.repository_id,
+            )
+        )
+        if any(present) and not all(present):
+            raise ValueError("repository identity must be wholly present or absent")
+        return self
+
+    @field_validator("repo")
+    @classmethod
+    def _repo_required(cls, v: str) -> str:
+        # RepoSlug admits "" as the webhook parsers' absent sentinel; a
+        # vendor caller controls its own pipeline and must name the repo.
+        if not v:
+            raise ValueError("repo is required (owner/repo)")
+        return v
+
+
+@router.post("/ci")
+def ingest_ci_vendor(
+    body: VendorCIRequest,
+    _: None = Depends(verify_ingest_token),
+    store: FactStore = Depends(get_store),
+) -> dict[str, Any]:
+    outcome = CIOutcome(
+        org_id=settings.org_id,
+        provider=body.provider,
+        run_id=body.run_id,
+        run_attempt=body.run_attempt,
+        repo=body.repo,
+        repository_provider=body.repository_provider,
+        repository_host=body.repository_host,
+        repository_id=body.repository_id,
+        commit_sha=body.commit_sha,
+        branch=body.branch,
+        result=body.result,
+        workflow_name=body.workflow_name,
+        workflow_id=body.workflow_id,
+        workflow_path=body.workflow_path or None,
+        run_url=body.run_url,
+        provider_result=body.provider_result,
+        error_type=body.error_type,
+        reason=body.reason,
+        source_event_type=body.source_event_type,
+        source_spec_version=body.source_spec_version,
+        source_event_id=body.source_event_id,
+    )
+    receipt = store.store_ci_outcome_receipt(outcome)
+    return {"fact_id": receipt.fact_id, "stored": receipt.stored}