cfgit-impact 0.1.0__py3-none-any.whl

cfg_impact/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Optional cfgit system-impact plugin."""
+
+from cfg_impact.overview import deterministic_overview, overview, overview_with_optional_llm
+
+__all__ = ["deterministic_overview", "overview", "overview_with_optional_llm"]

cfg_impact/overview.py

@@ -0,0 +1,432 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Whole-system impact overview for cfgit diffs."""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Any
+
+from cfg.core.engine import Engine, RecordRef
+from cfg.core.hashing import strip_for_hash
+from cfg.interfaces.actions import parse_record, to_json
+from cfg_impact.providers.factory import ImpactProviderFactory
+
+
+RISKY_TOKENS = {
+    "enabled", "active", "jobrouter", "provider", "model", "fallback",
+    "retry", "timeout", "pricing", "price", "cost", "tool", "tools",
+    "skill", "skills", "contract", "schema", "instructions", "prompt",
+}
+
+HIGH_TOKENS = {
+    "enabled", "active", "jobrouter", "provider", "model", "fallback",
+    "contract", "schema", "tool", "tools",
+}
+
+_CONSENT_LOGGED: set[tuple[str, tuple[str, ...]]] = set()
+
+
+def deterministic_overview(
+    engine: Engine,
+    record: str,
+    *,
+    a: str = "=HEAD",
+    b: str = "=live",
+) -> dict[str, Any]:
+    ref = parse_record(record)
+    coll = engine.config.collection(ref.collection)
+    changes = engine.diff(ref, a, b)
+    left = strip_for_hash(engine.resolve_ref(ref, a)["doc"], coll)
+    right = strip_for_hash(engine.resolve_ref(ref, b)["doc"], coll)
+    paths = [str(change.get("path", "")) for change in changes]
+    changed_values = _changed_string_values(changes)
+    affected = _find_affected_records(engine, source=ref, values=[ref.record_id, *changed_values])
+    declared_links = _declared_links(engine, paths)
+    categories = _categories(paths)
+    risk_level = _risk_level(paths, changes, affected)
+    summary = _deterministic_summary(record, changes, categories, affected, declared_links, risk_level)
+
+    return {
+        "record": record,
+        "from": a,
+        "to": b,
+        "risk_level": risk_level,
+        "summary": summary,
+        "categories": categories,
+        "changed_paths": paths,
+        "change_count": len(changes),
+        "declared_links_changed": declared_links,
+        "affected_records": affected,
+        "rollback_note": "Use restore on this record or restore system by tag/as-of if this change already shipped.",
+        "unknowns": _unknowns(left, right, affected),
+        "changes": changes,
+    }
+
+
+async def overview_with_optional_llm(
+    engine: Engine,
+    record: str,
+    *,
+    a: str = "=HEAD",
+    b: str = "=live",
+    provider: str | None = None,
+    model: str | None = None,
+    use_llm: bool = False,
+    against: list[str] | None = None,
+) -> dict[str, Any]:
+    overview_data = deterministic_overview(engine, record, a=a, b=b)
+    if not use_llm:
+        overview_data["llm"] = {"enabled": False}
+        return overview_data
+
+    allowed, reason = _llm_allowed(engine, record)
+    provider_name = provider or engine.config.connections.ai_provider
+    if not allowed:
+        overview_data["llm"] = {
+            "enabled": False,
+            "blocked": True,
+            "provider": provider_name,
+            "reason": reason,
+        }
+        return overview_data
+
+    llm = ImpactProviderFactory.create_provider(provider_name, model=model)
+    # cross-config context. If the caller selected records (`against`), reason against
+    # ONLY those; otherwise auto-build from the whole system. Text always gated by allowlist.
+    ref = parse_record(record)
+    allow = set(engine.config.connections.share_with_ai)
+    against_set = {a.strip() for a in against if a and a.strip()} if against else None
+    system_map = _system_map(engine, exclude=ref, allow=allow, against=against_set)
+    shared = [c["record_id"] for c in system_map.get("configs", []) if "instructions_excerpt" in c or "contract" in c]
+    _log_llm_consent(llm.provider_name, [record, *shared])
+    payload = _overview_prompt_payload(overview_data)
+    payload["system"] = system_map
+    result = await llm.narrate(
+        payload,
+        json_dumps=lambda payload: json.dumps(payload, indent=2, sort_keys=True),
+        temperature=0.1,
+        max_tokens=1100,
+    )
+    parsed = _parse_jsonish(result.get("content", ""))
+    overview_data["llm"] = {
+        "enabled": True,
+        "provider": llm.provider_name,
+        "model": result.get("model") or llm.model,
+        "usage": result.get("usage") or {},
+        "overview": parsed or {"summary": result.get("content", "")},
+    }
+    return overview_data
+
+
+def overview(
+    engine: Engine,
+    record: str,
+    *,
+    a: str = "=HEAD",
+    b: str = "=live",
+    provider: str | None = None,
+    model: str | None = None,
+    use_llm: bool = False,
+    against: list[str] | None = None,
+) -> dict[str, Any]:
+    return asyncio.run(
+        overview_with_optional_llm(
+            engine,
+            record,
+            a=a,
+            b=b,
+            provider=provider,
+            model=model,
+            use_llm=use_llm,
+            against=against,
+        )
+    )
+
+
+_ROLE_FIELDS = ("agent_type", "role", "phase", "category", "description", "display_name")
+_CONTRACT_FIELDS = ("phase_contract", "contract", "output_schema", "custom_input_schema")
+_SYS_TEXT_CAP = 600    # per-field text excerpt sent in the system map
+_SYS_MAX_CONFIGS = 40  # cap how many sibling configs we send
+
+
+def _excerpt(value: Any, cap: int) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    s = " ".join(value.split())
+    return s[:cap] + ("…" if len(s) > cap else "")
+
+
+def _config_card(doc: dict[str, Any], *, with_text: bool) -> dict[str, Any]:
+    card: dict[str, Any] = {}
+    for f in _ROLE_FIELDS:
+        if doc.get(f):
+            card[f] = doc[f]
+            break
+    tools = doc.get("tools")
+    if isinstance(tools, list) and tools:
+        card["tools"] = tools[:12]
+    skills = doc.get("skills")
+    if isinstance(skills, list) and skills:
+        card["skills"] = skills[:12]
+    if with_text:
+        for f in _CONTRACT_FIELDS:
+            ex = _excerpt(doc.get(f), _SYS_TEXT_CAP)
+            if ex:
+                card["contract"] = ex
+                break
+    if doc.get("model"):
+        card["model"] = doc["model"]
+    if with_text:
+        instr = doc.get("instructions") or doc.get("prompt")
+        ex = _excerpt(instr, _SYS_TEXT_CAP)
+        if ex:
+            card["instructions_excerpt"] = ex
+    return card
+
+
+def _system_map(
+    engine: Engine,
+    *,
+    exclude: RecordRef,
+    allow: set[str],
+    against: set[str] | None = None,
+) -> dict[str, Any]:
+    """Compact view of the OTHER live configs so the model reasons cross-system.
+    A config's text (instructions/contract) is included only if that config is in
+    the share_with_ai allowlist; otherwise just id + collection are sent.
+
+    If `against` is given, ONLY records the user explicitly selected are included
+    (matched by 'collection:record_id' or bare 'record_id'), and the non-rich tail
+    is suppressed: the user scoped the context, so we send exactly that set."""
+
+    def _allowed(coll: str, rid: str) -> bool:
+        return "*" in allow or rid in allow or f"{coll}:{rid}" in allow or f"{coll}:*" in allow
+
+    def _selected(coll: str, rid: str) -> bool:
+        return against is None or f"{coll}:{rid}" in against or rid in against
+
+    scoped = against is not None
+    out: list[dict[str, Any]] = []
+    for row in engine.status():
+        if row.collection == exclude.collection and row.record_id == exclude.record_id:
+            continue
+        if not _selected(row.collection, row.record_id):
+            continue
+        entry: dict[str, Any] = {"collection": row.collection, "record_id": row.record_id, "state": row.state}
+        with_text = _allowed(row.collection, row.record_id)
+        card: dict[str, Any] = {}
+        try:
+            doc = engine.resolve_ref(RecordRef(row.collection, row.record_id), "=live")["doc"]
+            coll = engine.config.collection(row.collection)
+            doc = strip_for_hash(doc, coll)  # drop ignored/secret fields before egress
+            card = _config_card(doc, with_text=with_text)
+        except Exception:
+            pass
+        # When the user explicitly selected this record, always include it (that's the
+        # whole point of selecting). Otherwise (auto mode) only include rich cards that
+        # carry reasoning-relevant content, to avoid noise and needless egress.
+        rich = any(k in card for k in ("instructions_excerpt", "contract", "tools", "skills"))
+        if scoped or rich:
+            entry.update(card)
+            if not with_text:
+                entry["text_withheld"] = "not in share_with_ai"
+            out.append(entry)
+        if not scoped and len(out) >= _SYS_MAX_CONFIGS:
+            break
+    result: dict[str, Any] = {"configs": out, "scoped": scoped}
+    if not scoped:
+        # auto mode: append a compact tail of the remaining record ids so the model
+        # knows what else exists, without sending their bodies
+        result["other_record_ids"] = [
+            f"{r.collection}:{r.record_id}"
+            for r in engine.status()
+            if not (r.collection == exclude.collection and r.record_id == exclude.record_id)
+        ][:200]
+    return result
+
+
+def _find_affected_records(
+    engine: Engine,
+    *,
+    source: RecordRef,
+    values: list[str],
+) -> list[dict[str, Any]]:
+    needles = [value for value in values if isinstance(value, str) and len(value) >= 3]
+    affected: list[dict[str, Any]] = []
+    for row in engine.status():
+        if row.collection == source.collection and row.record_id == source.record_id:
+            continue
+        try:
+            doc = engine.resolve_ref(RecordRef(row.collection, row.record_id), "=live")["doc"]
+        except Exception:
+            continue
+        text = json.dumps(to_json(doc), sort_keys=True)
+        matches = sorted({needle for needle in needles if needle in text})
+        if matches:
+            affected.append(
+                {
+                    "collection": row.collection,
+                    "record_id": row.record_id,
+                    "state": row.state,
+                    "matched_values": matches[:8],
+                }
+            )
+    return affected
+
+
+def _changed_string_values(changes: list[dict[str, Any]]) -> list[str]:
+    values: list[str] = []
+    for change in changes:
+        for key in ("before", "after", "old", "new"):
+            value = change.get(key)
+            if isinstance(value, str) and 3 <= len(value) <= 120:
+                values.append(value)
+            elif isinstance(value, list):
+                values.extend(
+                    str(item)
+                    for item in value
+                    if isinstance(item, str) and 3 <= len(item) <= 120
+                )
+    return values
+
+
+def _categories(paths: list[str]) -> list[str]:
+    out: set[str] = set()
+    for path in paths:
+        lowered = path.lower()
+        if any(token in lowered for token in ("instructions", "prompt", "system")):
+            out.add("agent_behavior")
+        if any(token in lowered for token in ("tool", "skill", "contract", "schema")):
+            out.add("interface_or_contract")
+        if any(token in lowered for token in ("provider", "model", "fallback")):
+            out.add("model_routing")
+        if any(token in lowered for token in ("enabled", "active", "jobrouter", "retry", "timeout")):
+            out.add("runtime_routing")
+        if any(token in lowered for token in ("pricing", "price", "cost")):
+            out.add("cost")
+    return sorted(out) or ["data_change"]
+
+
+def _declared_links(engine: Engine, paths: list[str]) -> list[dict[str, Any]]:
+    links = getattr(engine.config.connections, "links", ())
+    changed: list[dict[str, Any]] = []
+    for link in links:
+        field = str(link.get("field", ""))
+        if not field:
+            continue
+        field_path = f"/{field}".lower()
+        if any(path.lower() == field_path or path.lower().startswith(field_path + "/") for path in paths):
+            changed.append({"field": field, "means": link.get("means", "")})
+    return changed
+
+
+def _risk_level(paths: list[str], changes: list[dict[str, Any]], affected: list[dict[str, Any]]) -> str:
+    lowered_paths = " ".join(paths).lower()
+    if any(token in lowered_paths for token in HIGH_TOKENS) or len(affected) >= 3:
+        return "high"
+    if any(token in lowered_paths for token in RISKY_TOKENS) or len(changes) >= 5 or affected:
+        return "medium"
+    return "low"
+
+
+def _deterministic_summary(
+    record: str,
+    changes: list[dict[str, Any]],
+    categories: list[str],
+    affected: list[dict[str, Any]],
+    declared_links: list[dict[str, Any]],
+    risk_level: str,
+) -> str:
+    category_text = ", ".join(categories)
+    affected_text = f"{len(affected)} related record(s)" if affected else "no related records found by static scan"
+    link_text = (
+        f" Declared connection fields changed: {', '.join(item['field'] for item in declared_links)}."
+        if declared_links
+        else ""
+    )
+    return (
+        f"{record} changes {len(changes)} path(s), mainly {category_text}. "
+        f"Static scan found {affected_text}.{link_text} Risk is {risk_level}."
+    )
+
+
+def _unknowns(left: dict[str, Any], right: dict[str, Any], affected: list[dict[str, Any]]) -> list[str]:
+    unknowns = []
+    if not affected:
+        unknowns.append("Static reference scan may miss dynamic references built in application code.")
+    if left == right:
+        unknowns.append("No effective diff after ignored and secret fields were stripped.")
+    return unknowns
+
+
+_DIFF_FIELD_CAP = 6000  # per-side char cap so the prompt stays bounded
+
+
+def _truncate(value: Any, cap: int = _DIFF_FIELD_CAP) -> Any:
+    if isinstance(value, str) and len(value) > cap:
+        return value[:cap] + f"\n…[truncated {len(value) - cap} chars]"
+    return value
+
+
+def _overview_prompt_payload(overview_data: dict[str, Any]) -> dict[str, Any]:
+    payload = {key: value for key, value in overview_data.items() if key != "changes"}
+    # Include the ACTUAL field-level before/after so the model can read what changed,
+    # not just which fields changed. The diff is already secret-stripped upstream
+    # (engine.diff -> strip_for_hash), so no secret/ignored content reaches here.
+    payload["field_diffs"] = [
+        {
+            "path": change.get("path"),
+            "op": change.get("op"),
+            "before": _truncate(change.get("before")),
+            "after": _truncate(change.get("after")),
+        }
+        for change in overview_data.get("changes", [])
+    ]
+    payload["affected_records"] = [
+        {
+            "collection": item.get("collection"),
+            "record_id": item.get("record_id"),
+            "state": item.get("state"),
+            "match_count": len(item.get("matched_values") or []),
+        }
+        for item in payload.get("affected_records", [])
+    ]
+    return payload
+
+
+def _llm_allowed(engine: Engine, record: str) -> tuple[bool, str]:
+    allow = set(engine.config.connections.share_with_ai)
+    ref = parse_record(record)
+    if "*" in allow or record in allow or ref.record_id in allow or f"{ref.collection}:*" in allow:
+        return True, "allowed by connections.share_with_ai"
+    return (
+        False,
+        f"{record} is not listed in [connections].share_with_ai; returning local structure only",
+    )
+
+
+def _log_llm_consent(provider_name: str, records: list[str]) -> None:
+    key = (provider_name, tuple(sorted(records)))
+    if key in _CONSENT_LOGGED:
+        return
+    _CONSENT_LOGGED.add(key)
+    print(
+        f"cfg-impact: sending redacted structural diff for {', '.join(records)} to {provider_name}",
+        file=sys.stderr,
+    )
+
+
+def _parse_jsonish(text: str) -> dict[str, Any] | None:
+    raw = text.strip()
+    if not raw:
+        return None
+    if raw.startswith("```"):
+        raw = raw.strip("`")
+        if raw.startswith("json"):
+            raw = raw[4:]
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None

cfg_impact/providers/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Provider-agnostic LLM clients for cfg-impact."""
+
+from cfg_impact.providers.base import BaseImpactProvider, ProviderError
+from cfg_impact.providers.factory import ImpactProviderFactory
+
+__all__ = ["BaseImpactProvider", "ImpactProviderFactory", "ProviderError"]

cfg_impact/providers/base.py

@@ -0,0 +1,79 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Lean provider interface for cfg-impact narration."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import json
+from typing import Any
+
+
+class BaseImpactProvider(ABC):
+    def __init__(self, api_key: str, model: str | None = None, **_: Any):
+        if not api_key:
+            raise ValueError(f"{self.__class__.__name__} requires an API key")
+        self.api_key = api_key
+        self.model = model or self.default_model
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        ...
+
+    @property
+    @abstractmethod
+    def default_model(self) -> str:
+        ...
+
+    @abstractmethod
+    async def complete(self, messages: list[dict[str, Any]], **kwargs: Any) -> dict[str, Any]:
+        ...
+
+    async def narrate(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+        json_dumps = kwargs.get(
+            "json_dumps",
+            lambda value: json.dumps(value, indent=2, sort_keys=True),
+        )
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are a senior engineer reviewing a change to a live agent/config control "
+                    "plane. The JSON gives you `field_diffs` (the ACTUAL before/after of each changed "
+                    "field) and `system` (a compact map of the OTHER live configs: their ids, roles, "
+                    "instruction excerpts, tools, and contracts). If `system.scoped` is true, reason "
+                    "about the change only against the selected records in `system.configs`; otherwise "
+                    "reason about it against the whole system.\n"
+                    "Be concrete. Say what the edit actually changes in behavior, quoting or paraphrasing "
+                    "the specific rule, threshold, tool, or wording that changed. Then identify which OTHER "
+                    "configs in `system` are affected and why (shared contracts, shared tools, hand-offs, "
+                    "upstream/downstream roles, overlapping responsibilities), naming the specific "
+                    "config_ids. Do NOT say 'impact unknown' when the diff is present, read it. Only list a "
+                    "genuine unknown if it truly cannot be inferred from the provided data.\n"
+                    "Return concise JSON with keys: summary (one concrete sentence), behavior_change (what "
+                    "the agent will now do differently, specifically), blast_radius (which named configs or "
+                    "consumers are affected and why), risk_level (low|medium|high), rollback_note, unknowns "
+                    "(array of only real unknowns)."
+                ),
+            },
+            {"role": "user", "content": json_dumps(payload)},
+        ]
+        return await self.complete(
+            messages,
+            temperature=kwargs.get("temperature", 0.1),
+            max_tokens=kwargs.get("max_tokens", 1100),
+        )
+
+
+class ProviderError(Exception):
+    def __init__(self, message: str, provider: str | None = None, model: str | None = None):
+        super().__init__(message)
+        self.provider = provider
+        self.model = model
+
+
+class ProviderRateLimitError(ProviderError):
+    pass
+
+
+class ProviderAuthError(ProviderError):
+    pass

cfg_impact/providers/claude.py

@@ -0,0 +1,103 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Claude provider for cfg-impact narration."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from cfg_impact.providers.base import (
+    BaseImpactProvider,
+    ProviderAuthError,
+    ProviderError,
+    ProviderRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+CLAUDE_API_BASE = "https://api.anthropic.com/v1"
+ANTHROPIC_VERSION = "2023-06-01"
+
+
+class ClaudeProvider(BaseImpactProvider):
+    def __init__(self, api_key: str | None = None, model: str | None = None, **kwargs: Any):
+        super().__init__(api_key=api_key or os.getenv("ANTHROPIC_API_KEY", ""), model=model, **kwargs)
+
+    @property
+    def provider_name(self) -> str:
+        return "claude"
+
+    @property
+    def default_model(self) -> str:
+        return os.getenv("CFGIT_CLAUDE_MODEL", "claude-sonnet-4-20250514")
+
+    async def complete(self, messages: list[dict[str, Any]], **kwargs: Any) -> dict[str, Any]:
+        formatted, system_prompt = _format_messages(messages)
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": formatted,
+            "max_tokens": kwargs.get("max_tokens", 900),
+        }
+        if system_prompt:
+            payload["system"] = system_prompt
+        if kwargs.get("temperature") is not None:
+            payload["temperature"] = kwargs["temperature"]
+
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": self.api_key,
+            "anthropic-version": ANTHROPIC_VERSION,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=90.0) as client:
+                response = await client.post(
+                    f"{CLAUDE_API_BASE}/messages",
+                    json=payload,
+                    headers=headers,
+                )
+            if response.status_code == 401:
+                raise ProviderAuthError("invalid Anthropic API key", provider="claude")
+            if response.status_code == 429:
+                raise ProviderRateLimitError("Anthropic rate limit exceeded", provider="claude")
+            if response.status_code != 200:
+                raise ProviderError(
+                    f"Claude API error ({response.status_code}): {response.text[:500]}",
+                    provider="claude",
+                    model=self.model,
+                )
+            data = response.json()
+            content = "".join(
+                block.get("text", "")
+                for block in data.get("content", [])
+                if block.get("type") == "text"
+            )
+            return {
+                "content": content,
+                "usage": data.get("usage") or {},
+                "model": data.get("model") or self.model,
+                "stop_reason": data.get("stop_reason"),
+            }
+        except ProviderError:
+            raise
+        except json.JSONDecodeError as exc:
+            raise ProviderError("Claude returned invalid JSON", provider="claude", model=self.model) from exc
+        except Exception as exc:
+            logger.error("Claude impact provider error: %s", exc)
+            raise ProviderError(str(exc), provider="claude", model=self.model) from exc
+
+
+def _format_messages(messages: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], str | None]:
+    formatted: list[dict[str, Any]] = []
+    system_prompt = None
+    for msg in messages:
+        role = msg.get("role")
+        content = msg.get("content", "")
+        if role == "system":
+            system_prompt = content
+            continue
+        formatted.append({"role": "assistant" if role == "assistant" else "user", "content": content})
+    return formatted, system_prompt

cfg_impact/providers/factory.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Factory for cfg-impact LLM providers."""
+from __future__ import annotations
+
+from typing import Any
+
+from cfg_impact.providers.base import BaseImpactProvider
+from cfg_impact.providers.claude import ClaudeProvider
+from cfg_impact.providers.gemini import GeminiProvider
+from cfg_impact.providers.openai_provider import OpenAIProvider
+
+
+class ImpactProviderFactory:
+    _providers = {
+        "claude": ClaudeProvider,
+        "openai": OpenAIProvider,
+        "gemini": GeminiProvider,
+        "google": GeminiProvider,
+    }
+
+    @classmethod
+    def create_provider(
+        cls,
+        provider: str,
+        *,
+        model: str | None = None,
+        api_key: str | None = None,
+        **kwargs: Any,
+    ) -> BaseImpactProvider:
+        provider_name = provider.lower()
+        if provider_name not in cls._providers:
+            raise ValueError(
+                f"unsupported impact provider '{provider_name}'. "
+                f"Available: {', '.join(sorted(cls._providers))}"
+            )
+        return cls._providers[provider_name](api_key=api_key, model=model, **kwargs)

cfg_impact/providers/gemini.py

@@ -0,0 +1,105 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Google Gemini provider for cfg-impact narration."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from cfg_impact.providers.base import (
+    BaseImpactProvider,
+    ProviderAuthError,
+    ProviderError,
+    ProviderRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta"
+
+
+class GeminiProvider(BaseImpactProvider):
+    def __init__(self, api_key: str | None = None, model: str | None = None, **kwargs: Any):
+        super().__init__(
+            api_key=api_key or os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY", ""),
+            model=model,
+            **kwargs,
+        )
+
+    @property
+    def provider_name(self) -> str:
+        return "gemini"
+
+    @property
+    def default_model(self) -> str:
+        return os.getenv("CFGIT_GEMINI_MODEL", "gemini-3.5-flash")
+
+    async def complete(self, messages: list[dict[str, Any]], **kwargs: Any) -> dict[str, Any]:
+        contents, system_instruction = _format_messages(messages)
+        payload: dict[str, Any] = {"contents": contents}
+        if system_instruction:
+            payload["system_instruction"] = {"parts": [{"text": system_instruction}]}
+        gen_config: dict[str, Any] = {}
+        if kwargs.get("temperature") is not None:
+            gen_config["temperature"] = kwargs["temperature"]
+        if kwargs.get("max_tokens") is not None:
+            gen_config["maxOutputTokens"] = kwargs["max_tokens"]
+        if gen_config:
+            payload["generationConfig"] = gen_config
+
+        url = f"{GEMINI_API_BASE}/models/{self.model}:generateContent"
+        headers = {"Content-Type": "application/json", "x-goog-api-key": self.api_key}
+
+        try:
+            async with httpx.AsyncClient(timeout=90.0) as client:
+                response = await client.post(url, json=payload, headers=headers)
+            if response.status_code in (401, 403):
+                raise ProviderAuthError("invalid Google API key", provider="gemini")
+            if response.status_code == 429:
+                raise ProviderRateLimitError("Gemini rate limit exceeded", provider="gemini")
+            if response.status_code != 200:
+                raise ProviderError(
+                    f"Gemini API error ({response.status_code}): {response.text[:500]}",
+                    provider="gemini",
+                    model=self.model,
+                )
+            data = response.json()
+            candidate = (data.get("candidates") or [{}])[0]
+            parts = ((candidate.get("content") or {}).get("parts")) or []
+            content = "".join(part.get("text", "") for part in parts)
+            usage = data.get("usageMetadata") or {}
+            return {
+                "content": content,
+                "usage": {
+                    "input_tokens": usage.get("promptTokenCount"),
+                    "output_tokens": usage.get("candidatesTokenCount"),
+                    "total_tokens": usage.get("totalTokenCount"),
+                },
+                "model": self.model,
+                "stop_reason": candidate.get("finishReason"),
+            }
+        except ProviderError:
+            raise
+        except json.JSONDecodeError as exc:
+            raise ProviderError("Gemini returned invalid JSON", provider="gemini", model=self.model) from exc
+        except Exception as exc:
+            logger.error("Gemini impact provider error: %s", exc)
+            raise ProviderError(str(exc), provider="gemini", model=self.model) from exc
+
+
+def _format_messages(messages: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], str | None]:
+    contents: list[dict[str, Any]] = []
+    system_instruction = None
+    for msg in messages:
+        role = msg.get("role")
+        text = msg.get("content", "")
+        if role == "system":
+            system_instruction = text
+            continue
+        contents.append(
+            {"role": "model" if role == "assistant" else "user", "parts": [{"text": text}]}
+        )
+    return contents, system_instruction

cfg_impact/providers/openai_provider.py

@@ -0,0 +1,83 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""OpenAI provider for cfg-impact narration."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from cfg_impact.providers.base import (
+    BaseImpactProvider,
+    ProviderAuthError,
+    ProviderError,
+    ProviderRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+OPENAI_API_BASE = "https://api.openai.com/v1"
+
+
+class OpenAIProvider(BaseImpactProvider):
+    def __init__(self, api_key: str | None = None, model: str | None = None, **kwargs: Any):
+        super().__init__(api_key=api_key or os.getenv("OPENAI_API_KEY", ""), model=model, **kwargs)
+
+    @property
+    def provider_name(self) -> str:
+        return "openai"
+
+    @property
+    def default_model(self) -> str:
+        return os.getenv("CFGIT_OPENAI_MODEL", "gpt-4o-mini")
+
+    async def complete(self, messages: list[dict[str, Any]], **kwargs: Any) -> dict[str, Any]:
+        payload: dict[str, Any] = {"model": self.model, "messages": messages}
+        if self.model.startswith(("o1", "o3")):
+            if kwargs.get("max_tokens") is not None:
+                payload["max_completion_tokens"] = kwargs["max_tokens"]
+        else:
+            if kwargs.get("temperature") is not None:
+                payload["temperature"] = kwargs["temperature"]
+            if kwargs.get("max_tokens") is not None:
+                payload["max_tokens"] = kwargs["max_tokens"]
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=90.0) as client:
+                response = await client.post(
+                    f"{OPENAI_API_BASE}/chat/completions",
+                    json=payload,
+                    headers=headers,
+                )
+            if response.status_code == 401:
+                raise ProviderAuthError("invalid OpenAI API key", provider="openai")
+            if response.status_code == 429:
+                raise ProviderRateLimitError("OpenAI rate limit exceeded", provider="openai")
+            if response.status_code != 200:
+                raise ProviderError(
+                    f"OpenAI API error ({response.status_code}): {response.text[:500]}",
+                    provider="openai",
+                    model=self.model,
+                )
+            data = response.json()
+            choice = (data.get("choices") or [{}])[0]
+            return {
+                "content": ((choice.get("message") or {}).get("content") or ""),
+                "usage": data.get("usage") or {},
+                "model": data.get("model") or self.model,
+                "stop_reason": choice.get("finish_reason"),
+            }
+        except ProviderError:
+            raise
+        except json.JSONDecodeError as exc:
+            raise ProviderError("OpenAI returned invalid JSON", provider="openai", model=self.model) from exc
+        except Exception as exc:
+            logger.error("OpenAI impact provider error: %s", exc)
+            raise ProviderError(str(exc), provider="openai", model=self.model) from exc

cfgit_impact-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: cfgit-impact
+Version: 0.1.0
+Summary: Optional cfgit plugin for deterministic system-impact summaries and opt-in LLM narration of database record diffs
+Project-URL: Homepage, https://github.com/AusafMo/cfgit
+Project-URL: Repository, https://github.com/AusafMo/cfgit
+Project-URL: Issues, https://github.com/AusafMo/cfgit/issues
+Project-URL: Documentation, https://github.com/AusafMo/cfgit/tree/main/plugins/cfg_impact#readme
+Author: Mohammad Ausaf
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: cfgit<0.2.0,>=0.1.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# cfg-impact
+
+Optional system-impact analysis for cfgit.
+
+This package is deliberately outside `src/cfg/core/`. The cfgit core stays LLM-free and provider-free; this plugin owns both deterministic impact analysis and optional LLM narration.
+
+## Boundary
+
+- `src/cfg/core/` never imports this plugin.
+- `src/cfg/core/` never imports vendor SDKs or provider clients.
+- The main action layer imports `cfg_impact.overview` only when `cfg impact` or the UI/MCP impact action is called.
+- Provider selection comes from `[connections].ai_provider` unless a caller passes `provider`.
+
+## Provider Pattern
+
+The provider layer uses a small factory pattern:
+
+- `cfg_impact.providers.base.BaseImpactProvider`
+- `cfg_impact.providers.factory.ImpactProviderFactory`
+- `cfg_impact.providers.claude.ClaudeProvider`
+- `cfg_impact.providers.openai_provider.OpenAIProvider`
+- `cfg_impact.providers.gemini.GeminiProvider`
+
+The impact engine calls `narrate()` or `complete()`. It never imports a vendor module directly.
+
+## Commands
+
+Deterministic local analysis:
+
+`cfg impact agent_configs:agent_planner =HEAD =live --json`
+
+Opt-in LLM narration:
+
+`cfg impact agent_configs:agent_planner =HEAD =live --llm --json`
+
+Scope narration to selected records instead of the whole system:
+
+`cfg impact agent_configs:agent_planner --against agent_configs:critic --against modelgarden_models:openai/gpt-4o-mini --llm --json`
+
+LLM narration is refused unless the record is listed in
+`[connections].share_with_ai`. The payload sent to the provider is bounded and
+secret-stripped. It includes real before/after field diffs for the changed record,
+plus only allowlisted text from related records. In scoped mode, only selected
+records are included in the system map.
+
+The plugin uses `ANTHROPIC_API_KEY` for `claude`, `OPENAI_API_KEY` for `openai`,
+and `GEMINI_API_KEY` or `GOOGLE_API_KEY` for `gemini`.

cfgit_impact-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+cfg_impact/__init__.py,sha256=VVFVEyLyEZZOtK8ldG_r3dHCwD_BjdwXVDBXS0qz9ZM,298
+cfg_impact/overview.py,sha256=sGUbdak5t1VDQPJ35fgGBULwrLwAc_mnByBFowU24kY,15998
+cfg_impact/providers/__init__.py,sha256=Mj4gSv-eLceldwaNTPn8rYsvyD62qssm-HzVbDxBvhQ,345
+cfg_impact/providers/base.py,sha256=wBjRScHPYfJGVBYRIQG30E4XjtbN07O75NCIGg5V9KA,3361
+cfg_impact/providers/claude.py,sha256=RAviXGgPXF04O0EzUQG1qviN2rUl9O9i_lJXndQHEvw,3751
+cfg_impact/providers/factory.py,sha256=NlM3s4wAWySKL7gnAkE9rfYrGHV4VO54-Rnhn6Dn4rc,1171
+cfg_impact/providers/gemini.py,sha256=dC3ivJjGv1aNYLti6Dnh4UUTVmTfPNIc3LYUGDftI0E,4155
+cfg_impact/providers/openai_provider.py,sha256=97eS4gWL_PLLL9UgiI11mo58MBM2t-toBvsQzPREeuU,3180
+cfgit_impact-0.1.0.dist-info/METADATA,sha256=49qqC3baiLcqCeT6Yw7L1xZjNfI7TGwSX1aJ5RhY8oU,2501
+cfgit_impact-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cfgit_impact-0.1.0.dist-info/RECORD,,

cfgit_impact-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