atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/progress_reporter.py

@@ -0,0 +1,81 @@
+"""Tier a1 — progress reporter factories for long-running walks.
+
+Provides callable factories that produce ``(idx, total, label) -> None``
+reporters suitable for passing to ``scout_walk.harvest_repo`` (and any
+future long-running pipeline phase).
+
+Pure-by-construction: the factories themselves perform no I/O. The
+returned reporter writes to whatever stream is passed in (default
+``sys.stderr``), which keeps the side effect at the *call site* under
+the caller's control. Tests can pass an ``io.StringIO``; the CLI layer
+passes ``sys.stderr``; ``progress=None`` skips reporting entirely.
+
+Used by Lane B2 of the post-audit plan: long-running ``forge auto`` /
+``forge recon`` invocations on large repos previously gave no on-screen
+feedback, so users couldn't tell the tool from a hung process. This
+module is the cheap fix.
+"""
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import IO
+
+
+def make_stderr_reporter(
+    *,
+    every: int = 25,
+    enabled: bool | None = None,
+    stream: IO[str] | None = None,
+    label: str = "scout",
+) -> Callable[[int, int, str], None]:
+    """Return a progress callback that writes to ``stream`` (default stderr).
+
+    Arguments:
+        every:    Emit a line every Nth file (plus always at the final
+                  file). Keep ≥ 1.
+        enabled:  Force-enable / disable. ``None`` = auto-detect: emit
+                  only when ``stream`` is a TTY. CI tasks (non-TTY) get
+                  silence by default; an explicit ``enabled=True`` forces
+                  output regardless.
+        stream:   Defaults to ``sys.stderr``.
+        label:    Short tag included in each line (``scout``, etc.).
+
+    Returns:
+        A pure callback ``progress(idx, total, rel)`` suitable for
+        passing into ``harvest_repo``. When the reporter is disabled
+        (TTY check fails and ``enabled is not True``), the callback is
+        a no-op — *not* ``None`` — so callers can pass it unconditionally.
+    """
+    if every < 1:
+        raise ValueError("`every` must be >= 1")
+
+    target = stream if stream is not None else sys.stderr
+    if enabled is None:
+        try:
+            active = bool(target.isatty())
+        except (AttributeError, ValueError):
+            active = False
+    else:
+        active = bool(enabled)
+
+    if not active:
+        def _noop(idx: int, total: int, rel: str) -> None:
+            return None
+        return _noop
+
+    def _report(idx: int, total: int, rel: str) -> None:
+        # Emit on every Nth file, plus always on the final one so the
+        # user sees the closing 100%-of-N line.
+        if idx == total or (idx % every) == 0:
+            try:
+                target.write(
+                    f"  [{label}] processed {idx}/{total} files "
+                    f"(latest: {rel})\n"
+                )
+                target.flush()
+            except (OSError, ValueError):
+                # Stream closed or detached mid-run — degrade silently.
+                pass
+
+    return _report

atomadic_forge/a1_at_functions/provider_detect.py

@@ -0,0 +1,157 @@
+"""Tier a1 — pure helpers for LLM provider detection and connection testing."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import time
+import urllib.error
+import urllib.request
+
+
+def detect_ollama(url: str) -> dict:
+    """Ping Ollama at url; return availability, model list, and latency."""
+    t0 = time.monotonic()
+    try:
+        tags_url = f"{url.rstrip('/')}/api/tags"
+        with urllib.request.urlopen(tags_url, timeout=5) as resp:
+            data = json.loads(resp.read())
+        models = [m["name"] for m in data.get("models", [])]
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        return {"available": True, "models": models, "url": url, "latency_ms": latency_ms}
+    except (urllib.error.URLError, OSError, json.JSONDecodeError, KeyError):
+        return {"available": False, "models": [], "url": url, "latency_ms": 0}
+
+
+def list_ollama_models(url: str) -> list[str]:
+    """Return model names available from Ollama at url."""
+    return detect_ollama(url)["models"]
+
+
+def test_provider(provider: str, config: dict) -> dict:
+    """Test an LLM provider connection; return {ok, model, error, latency_ms}."""
+    t0 = time.monotonic()
+
+    if provider == "ollama":
+        return _test_ollama(config, t0)
+
+    if provider == "gemini":
+        return _test_gemini(config, t0)
+
+    if provider in ("anthropic", "claude"):
+        return _test_anthropic(config, t0)
+
+    if provider in ("openai", "gpt"):
+        return _test_openai(config, t0)
+
+    if provider == "auto":
+        return _test_auto(config, t0)
+
+    if provider == "stub":
+        return {"ok": True, "model": "stub", "error": None,
+                "latency_ms": int((time.monotonic() - t0) * 1000)}
+
+    return {"ok": False, "model": "none",
+            "error": f"Unknown provider {provider!r}", "latency_ms": 0}
+
+
+# ── private helpers ──────────────────────────────────────────────────────────
+
+def _test_ollama(config: dict, t0: float) -> dict:
+    url = config.get("ollama_url", "http://localhost:11434")
+    model = config.get("ollama_model", "mistral:7b-instruct")
+    info = detect_ollama(url)
+    latency_ms = int((time.monotonic() - t0) * 1000)
+    if not info["available"]:
+        return {"ok": False, "model": model,
+                "error": f"Ollama not reachable at {url}", "latency_ms": latency_ms}
+    if model not in info["models"] and info["models"]:
+        return {"ok": False, "model": model,
+                "error": f"Model {model!r} not found (available: {info['models']})",
+                "latency_ms": latency_ms}
+    return {"ok": True, "model": model, "error": None, "latency_ms": latency_ms}
+
+
+def _test_gemini(config: dict, t0: float) -> dict:
+    key = config.get("gemini_key") or ""
+    model = config.get("gemini_model") or "gemini-2.5-flash"
+    if not key:
+        return {"ok": False, "model": model, "error": "gemini_key not set", "latency_ms": 0}
+    try:
+        req = urllib.request.Request(
+            f"https://generativelanguage.googleapis.com/v1beta/models?key={key}",
+            headers={"Accept": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            resp.read()
+        return {"ok": True, "model": model, "error": None,
+                "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except urllib.error.HTTPError as exc:
+        return {"ok": False, "model": model,
+                "error": f"HTTP {exc.code}", "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
+        return {"ok": False, "model": model,
+                "error": str(exc), "latency_ms": int((time.monotonic() - t0) * 1000)}
+
+
+def _test_anthropic(config: dict, t0: float) -> dict:
+    key = config.get("anthropic_key") or ""
+    model = config.get("anthropic_model") or "claude-sonnet-4-6"
+    if not key:
+        return {"ok": False, "model": model, "error": "anthropic_key not set", "latency_ms": 0}
+    try:
+        req = urllib.request.Request(
+            "https://api.anthropic.com/v1/models",
+            headers={"x-api-key": key, "anthropic-version": "2023-06-01"},
+        )
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            resp.read()
+        return {"ok": True, "model": model, "error": None,
+                "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except urllib.error.HTTPError as exc:
+        return {"ok": False, "model": model,
+                "error": f"HTTP {exc.code}", "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
+        return {"ok": False, "model": model,
+                "error": str(exc), "latency_ms": int((time.monotonic() - t0) * 1000)}
+
+
+def _test_openai(config: dict, t0: float) -> dict:
+    key = config.get("openai_key") or ""
+    model = config.get("openai_model") or "gpt-4o-mini"
+    if not key:
+        return {"ok": False, "model": model, "error": "openai_key not set", "latency_ms": 0}
+    try:
+        req = urllib.request.Request(
+            "https://api.openai.com/v1/models",
+            headers={"Authorization": f"Bearer {key}"},
+        )
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            resp.read()
+        return {"ok": True, "model": model, "error": None,
+                "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except urllib.error.HTTPError as exc:
+        return {"ok": False, "model": model,
+                "error": f"HTTP {exc.code}", "latency_ms": int((time.monotonic() - t0) * 1000)}
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
+        return {"ok": False, "model": model,
+                "error": str(exc), "latency_ms": int((time.monotonic() - t0) * 1000)}
+
+
+def _test_auto(config: dict, t0: float) -> dict:
+    url = config.get("ollama_url", "http://localhost:11434")
+    info = detect_ollama(url)
+    if info["available"]:
+        model = config.get("ollama_model", "mistral:7b-instruct")
+        return {"ok": True, "model": f"ollama/{model}", "error": None,
+                "latency_ms": int((time.monotonic() - t0) * 1000)}
+    for p, key_field in (
+        ("gemini", "gemini_key"),
+        ("anthropic", "anthropic_key"),
+        ("openai", "openai_key"),
+    ):
+        if config.get(key_field):
+            return test_provider(p, config)
+    return {"ok": False, "model": "none",
+            "error": "No provider available (Ollama unreachable, no API keys set)",
+            "latency_ms": int((time.monotonic() - t0) * 1000)}

atomadic_forge/a1_at_functions/provider_resolver.py

@@ -0,0 +1,48 @@
+"""Tier a1 — shared LLM provider resolver."""
+
+from __future__ import annotations
+
+import os
+
+from .llm_client import (
+    AAAANexusClient,
+    AnthropicClient,
+    GeminiClient,
+    LLMClient,
+    OllamaClient,
+    OpenAIClient,
+    OpenRouterClient,
+    StubLLMClient,
+    resolve_default_client,
+)
+
+PROVIDER_HELP = (
+    "auto | nexus | aaaa-nexus | gemini | anthropic | openai | "
+    "openrouter | ollama | stub"
+)
+
+
+def resolve_provider(name: str = "auto") -> LLMClient:
+    """Resolve a user-facing provider name to an ``LLMClient`` instance."""
+    provider = (name or "auto").lower()
+    if provider == "stub":
+        return StubLLMClient()
+    if provider in ("nexus", "aaaa-nexus", "aaaa_nexus", "helix"):
+        return AAAANexusClient()
+    if provider in ("anthropic", "claude"):
+        return AnthropicClient()
+    if provider in ("gemini", "google"):
+        return GeminiClient(model=os.environ.get("FORGE_GEMINI_MODEL",
+                                                 "gemini-2.5-flash"))
+    if provider in ("openai", "gpt"):
+        return OpenAIClient()
+    if provider in ("openrouter", "router"):
+        return OpenRouterClient()
+    if provider == "ollama":
+        return OllamaClient(
+            model=os.environ.get("FORGE_OLLAMA_MODEL", "qwen2.5-coder:7b"),
+            base_url=os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434"),
+        )
+    if provider == "auto":
+        return resolve_default_client()
+    raise ValueError(f"unknown provider: {name!r}; expected {PROVIDER_HELP}")

atomadic_forge/a1_at_functions/receipt_emitter.py

@@ -0,0 +1,291 @@
+"""Tier a1 — pure CertifyResult+WireReport+ScoutReport → Receipt v1.
+
+Golden Path Lane A W1 (paired with ``card_renderer.py``).
+
+Pure: no I/O. Takes already-computed report dicts (the same ones
+``forge certify`` and ``forge wire`` already produce) plus a few
+context strings, returns a ``ForgeReceiptV1`` dict ready to be
+``json.dumps``-ed and either signed (Lane A W2 ``receipt_signer``)
+or shipped as-is for local development.
+
+The emitter never decides whether a Receipt should be signed. That's
+a policy call the CLI layer makes. Same for lineage — Vanguard's
+``/v1/forge/lineage`` lookup happens at a2; the emitter accepts a
+pre-resolved ``lineage`` dict if the caller has one.
+
+Verdict-decision contract (matches ``docs/RECEIPT.md`` §"How verdict
+is decided"):
+
+  verdict = PASS         when wire.verdict == 'PASS'
+                         AND certify.score >= certify_threshold
+  verdict = FAIL         when wire.verdict == 'FAIL'
+                         OR  certify.score <  certify_threshold
+  verdict = REFINE       when caller passed an explicit
+                         override='REFINE' (iterate stagnation case)
+  verdict = QUARANTINE   when caller passed an explicit
+                         override='QUARANTINE' (hysteresis ratchet
+                         > 0.5; reserved for Lane E)
+
+The emitter never invents REFINE / QUARANTINE on its own.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from ..a0_qk_constants.receipt_schema import (
+    REQUIRED_RECEIPT_V1_FIELDS,
+    SCHEMA_VERSION_V1,
+    VALID_VERDICTS,
+    ForgeReceiptV1,
+    ReceiptArtifact,
+    ReceiptCertify,
+    ReceiptCertifyAxes,
+    ReceiptLean4Attestation,
+    ReceiptLineage,
+    ReceiptPolyglotBreakdown,
+    ReceiptProject,
+    ReceiptScout,
+    ReceiptSignatures,
+    ReceiptWire,
+)
+
+_DEFAULT_THRESHOLD = 100.0
+_ARTIFACT_FILES = ("scout", "cherry", "wire", "certify", "assimilate")
+
+
+def _now_utc_iso() -> str:
+    """Return the current UTC instant as YYYY-MM-DDTHH:MM:SSZ."""
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _decide_verdict(
+    *,
+    wire_verdict: str,
+    certify_score: float,
+    threshold: float,
+    override: str | None,
+) -> str:
+    """See module docstring's verdict-decision contract."""
+    if override is not None:
+        if override not in VALID_VERDICTS:
+            raise ValueError(
+                f"verdict override {override!r} not in {VALID_VERDICTS}"
+            )
+        return override
+    if wire_verdict == "PASS" and certify_score >= threshold:
+        return "PASS"
+    return "FAIL"
+
+
+def _hash_file(path: Path) -> str | None:
+    """Return the SHA-256 hex digest of a file, or None on read failure.
+
+    Pure-ish: deterministic given file contents. The 'I/O' here is a
+    bounded read of a known artifact path the caller controls; no
+    network. Keeps the emitter callable in cheap-mode (caller passes
+    ``compute_artifact_hashes=False`` and we skip).
+    """
+    try:
+        h = hashlib.sha256()
+        with path.open("rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                h.update(chunk)
+        return h.hexdigest()
+    except OSError:
+        return None
+
+
+def _gather_artifacts(
+    project_root: Path,
+    *,
+    compute_hashes: bool,
+) -> list[ReceiptArtifact]:
+    """Build the artifacts pointer list from ``.atomadic-forge/`` files."""
+    base = project_root / ".atomadic-forge"
+    if not base.is_dir():
+        return []
+    out: list[ReceiptArtifact] = []
+    for name in _ARTIFACT_FILES:
+        target = base / f"{name}.json"
+        if not target.exists():
+            continue
+        sha = _hash_file(target) if compute_hashes else None
+        out.append(ReceiptArtifact(
+            name=name,
+            path=str(target.relative_to(project_root).as_posix()),
+            sha256=sha,
+        ))
+    return out
+
+
+def _project_block(
+    *,
+    name: str,
+    root: Path,
+    package: str | None,
+    primary_language: str,
+    languages: dict[str, int],
+    vcs: dict[str, Any] | None,
+) -> ReceiptProject:
+    block: ReceiptProject = ReceiptProject(
+        name=name,
+        root=str(root),
+        package=package,
+        language=primary_language,
+        languages=dict(languages),
+    )
+    if vcs is not None:
+        block["vcs"] = vcs  # type: ignore[typeddict-item]
+    return block
+
+
+def _certify_block(certify_result: dict) -> ReceiptCertify:
+    axes = ReceiptCertifyAxes(
+        documentation_complete=bool(certify_result.get("documentation_complete", False)),
+        tests_present=bool(certify_result.get("tests_present", False)),
+        tier_layout_present=bool(certify_result.get("tier_layout_present", False)),
+        no_upward_imports=bool(certify_result.get("no_upward_imports", False)),
+    )
+    return ReceiptCertify(
+        score=float(certify_result.get("score", 0.0)),
+        axes=axes,
+        issues=list(certify_result.get("issues", []) or []),
+    )
+
+
+def _wire_block(wire_report: dict) -> ReceiptWire:
+    verdict = wire_report.get("verdict", "FAIL")
+    if verdict not in ("PASS", "FAIL"):
+        verdict = "FAIL"
+    return ReceiptWire(
+        verdict=verdict,
+        violation_count=int(wire_report.get("violation_count", 0)),
+        auto_fixable=int(wire_report.get("auto_fixable", 0)),
+    )
+
+
+def _scout_block(scout_report: dict) -> ReceiptScout:
+    return ReceiptScout(
+        symbol_count=int(scout_report.get("symbol_count", 0)),
+        tier_distribution=dict(scout_report.get("tier_distribution", {}) or {}),
+        effect_distribution=dict(scout_report.get("effect_distribution", {}) or {}),
+        primary_language=str(scout_report.get("primary_language", "python")),
+    )
+
+
+def _polyglot_breakdown(scout_report: dict) -> ReceiptPolyglotBreakdown:
+    """Codex-6 — Receipt v1.1 polyglot_breakdown seed.
+
+    Pulls per-language file + symbol counts from the scout report.
+    Per-language certify scores ship in a future minor (Lane A W8 has
+    that on the roadmap once the JS/TS behavioural-pytest gate lands).
+    """
+    languages = (scout_report.get("language_distribution")
+                 or scout_report.get("languages") or {})
+    symbols_by_lang: dict[str, int] = {}
+    for s in scout_report.get("symbols", []) or []:
+        lang = s.get("language", "python")
+        symbols_by_lang[lang] = symbols_by_lang.get(lang, 0) + 1
+    return ReceiptPolyglotBreakdown(
+        file_count=sum(int(v) for v in languages.values()),
+        languages=dict(languages),
+        symbol_count=int(scout_report.get("symbol_count", 0)),
+        symbols_by_language=symbols_by_lang,
+        primary_language=str(scout_report.get("primary_language", "python")),
+    )
+
+
+def build_receipt(
+    *,
+    certify_result: dict,
+    wire_report: dict,
+    scout_report: dict,
+    project_name: str,
+    project_root: Path,
+    forge_version: str,
+    package: str | None = None,
+    vcs: dict[str, Any] | None = None,
+    assimilate_digest: str | None = None,
+    signatures: ReceiptSignatures | None = None,
+    lean4_attestation: ReceiptLean4Attestation | None = None,
+    lineage: ReceiptLineage | None = None,
+    compliance_mappings: dict[str, str] | None = None,
+    notes: list[str] | None = None,
+    extra: dict[str, object] | None = None,
+    certify_threshold: float = _DEFAULT_THRESHOLD,
+    verdict_override: str | None = None,
+    compute_artifact_hashes: bool = True,
+) -> ForgeReceiptV1:
+    """Build a v1 Forge Receipt from already-computed reports.
+
+    Required inputs:
+      certify_result, wire_report, scout_report, project_name,
+      project_root, forge_version.
+
+    Everything else is optional and defaults to a structurally-valid
+    empty / None per the v1.0 spec. Producers MAY emit unsigned
+    Receipts; this is the local-development path.
+
+    Returns a TypedDict suitable for ``json.dumps`` (every value is
+    JSON-serializable: str, int, float, bool, None, list, dict).
+    """
+    languages = scout_report.get("language_distribution") or scout_report.get("languages") or {}
+    primary = scout_report.get("primary_language", "python")
+    receipt: ForgeReceiptV1 = ForgeReceiptV1(
+        schema_version=SCHEMA_VERSION_V1,
+        generated_at_utc=_now_utc_iso(),
+        forge_version=forge_version,
+        verdict=_decide_verdict(
+            wire_verdict=wire_report.get("verdict", "FAIL"),
+            certify_score=float(certify_result.get("score", 0.0)),
+            threshold=certify_threshold,
+            override=verdict_override,
+        ),
+        project=_project_block(
+            name=project_name,
+            root=Path(project_root).resolve(),
+            package=package,
+            primary_language=primary,
+            languages=dict(languages),
+            vcs=vcs,
+        ),
+        certify=_certify_block(certify_result),
+        wire=_wire_block(wire_report),
+        scout=_scout_block(scout_report),
+        assimilate_digest=assimilate_digest,
+        artifacts=_gather_artifacts(
+            Path(project_root).resolve(),
+            compute_hashes=compute_artifact_hashes,
+        ),
+        signatures=signatures or ReceiptSignatures(sigstore=None, aaaa_nexus=None),
+        lean4_attestation=lean4_attestation or ReceiptLean4Attestation(),
+        lineage=lineage or ReceiptLineage(),
+        compliance_mappings=dict(compliance_mappings or {}),
+        notes=list(notes or []),
+        extra=dict(extra or {}),
+        # Codex-6 / Lane A W8 seed: per-language file + symbol breakdown.
+        polyglot_breakdown=_polyglot_breakdown(scout_report),
+    )
+    # Spot-check that we populated every required v1 field. Defensive
+    # — TypedDict does not enforce at runtime.
+    for f in REQUIRED_RECEIPT_V1_FIELDS:
+        if f not in receipt:
+            raise RuntimeError(
+                f"receipt_emitter built a Receipt missing required field "
+                f"{f!r} — schema/emitter drift"
+            )
+    return receipt
+
+
+def receipt_to_json(receipt: ForgeReceiptV1, *, indent: int = 2) -> str:
+    """Serialize a Receipt to a stable JSON string.
+
+    Sorted-keys NOT used — the emitter writes fields in spec order so
+    the wire format is human-readable. ``indent`` defaults to 2 to
+    match Forge's other manifest writers.
+    """
+    import json
+    return json.dumps(receipt, indent=indent, default=str)