datagraph-core 0.8.2__py3-none-any.whl

datagraph/__init__.py

@@ -0,0 +1,59 @@
+"""datagraph — AI-powered Change Impact Graph for data and code systems.
+
+Build a deterministic dependency graph from real engineering artifacts
+(Python AST, dbt manifest, SQL lineage, git diff, OpenLineage / DataHub
+lineage files, warehouse information_schema), then ask:
+"if I change this, what can break?"
+"""
+
+from .graph import EXTRACTED, INFERRED, LLM, DataGraph, Edge, EdgeType, ImpactGraph, Node, NodeType, diff_graphs
+from .analysis import ImpactAnalysis, analyze_impact
+from .knowledge import build_wiki, context
+from .profiling import profile_warehouse
+from .analysis.modeling import classify_tables, propose_from_table, star_schema
+from .extractors.registry import ExtractorPlugin, register
+from .extractors import (
+    DbtExtractor,
+    LineageFileExtractor,
+    OpenLineageExtractor,
+    PythonExtractor,
+    SqlExtractor,
+    WarehouseExtractor,
+    AirflowExtractor,
+    LambdaExtractor,
+    JsExtractor,
+    DataHubExtractor,
+    changed_node_ids,
+    collect_changes,
+)
+
+__version__ = "0.8.2"
+
+__all__ = [
+    "build_wiki", "context", "profile_warehouse", "classify_tables", "star_schema", "propose_from_table", "ExtractorPlugin", "register",
+    "Edge",
+    "EdgeType",
+    "ImpactGraph",
+    "DataGraph",
+    "Node",
+    "NodeType",
+    "EXTRACTED",
+    "INFERRED",
+    "LLM",
+    "diff_graphs",
+    "ImpactAnalysis",
+    "analyze_impact",
+    "DbtExtractor",
+    "PythonExtractor",
+    "SqlExtractor",
+    "OpenLineageExtractor",
+    "LineageFileExtractor",
+    "WarehouseExtractor",
+    "AirflowExtractor",
+    "LambdaExtractor",
+    "JsExtractor",
+    "DataHubExtractor",
+    "changed_node_ids",
+    "collect_changes",
+    "__version__",
+]

datagraph/ai/__init__.py

@@ -0,0 +1,6 @@
+from .explain import explain_impact
+from .lineage import apply_suggestions, schema_summary, suggest_lineage
+from .providers import AnthropicProvider, BedrockProvider, LLMProvider, OpenAICompatibleProvider, get_provider
+
+__all__ = ["explain_impact", "suggest_lineage", "apply_suggestions", "schema_summary",
+           "get_provider", "LLMProvider", "AnthropicProvider", "BedrockProvider", "OpenAICompatibleProvider"]

datagraph/ai/explain.py

@@ -0,0 +1,52 @@
+"""Optional AI layer: explain a deterministic impact analysis in plain language.
+
+The graph itself is never built by an LLM. The model only receives the
+already-computed blast radius and turns it into an explanation, a risk
+narrative, and a review checklist.
+
+Providers: Anthropic (default), Amazon Bedrock (Nova, Claude on Bedrock, ...), or any
+OpenAI-compatible endpoint — see ``datagraph.ai.providers``. Install with
+``pip install datagraph[ai]`` (Anthropic) or ``datagraph[bedrock]`` and set the
+provider's credentials in the environment.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from ..analysis import ImpactAnalysis
+from ..security import UNTRUSTED_NOTICE, wrap_untrusted
+from .providers import get_provider
+
+SYSTEM_PROMPT = (
+    "You are a senior data platform engineer reviewing a proposed change. "
+    "You are given a deterministic change-impact analysis computed from real "
+    "engineering artifacts (Python AST, dbt manifest, SQL lineage, git diff). "
+    "Do not invent nodes or dependencies that are not in the analysis. "
+    "Write for the engineer about to merge this change: explain what was "
+    "changed, what can break and why (walk the propagation paths), whether the "
+    "stated risk level seems right, and what to verify before and after "
+    "deploying. Keep it focused and concrete. " + UNTRUSTED_NOTICE
+)
+
+
+def explain_impact(
+    analysis: ImpactAnalysis,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    max_tokens: int = 16000,
+    provider: Optional[Any] = None,
+) -> str:
+    """Return a plain-language explanation of an impact analysis.
+
+    ``provider`` is an ``LLMProvider`` instance or a name ('anthropic' | 'bedrock' | 'openai');
+    omitted -> ``$DATAGRAPH_LLM_PROVIDER`` or Anthropic. ``model`` overrides the provider default.
+    """
+    llm = get_provider(provider, model=model, api_key=api_key)
+    payload = json.dumps(analysis.to_dict(), indent=2, sort_keys=True)
+    user = ("Here is the change impact analysis as JSON:\n\n"
+            + wrap_untrusted(f"```json\n{payload}\n```")
+            + "\n\nExplain the impact of this change.")
+    text = llm.complete(SYSTEM_PROMPT, user, max_tokens=max_tokens)
+    return text or "(The model declined to analyze this request.)"

datagraph/ai/lineage.py

@@ -0,0 +1,162 @@
+"""LLM-assisted lineage — a clearly-labelled FALLBACK, never the primary source.
+
+Deterministic extractors come first. When they cannot derive a relationship
+(SQL that sqlglot cannot parse, stored procedures, dynamic SQL in code, tables
+with no declared foreign keys but obvious naming conventions), ``suggest_lineage``
+asks Claude for candidate relationships using **structured outputs**, and
+``apply_suggestions`` adds them as edges tagged ``provenance: "llm"`` with a
+confidence and a reason. Those edges are shown with an ``(llm)`` marker,
+excluded by ``--no-inferred``, and can be reviewed in ``relationships --json``.
+
+Providers: Anthropic (default), Amazon Bedrock (Nova / Claude on Bedrock / ...), or any
+OpenAI-compatible endpoint - see ``datagraph.ai.providers``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Dict, List, Optional
+
+from ..security import UNTRUSTED_NOTICE, sanitize_text, wrap_untrusted
+from .providers import extract_json, get_provider
+from ..graph import LLM, Edge, EdgeType, ImpactGraph, Node, NodeType
+
+SYSTEM_PROMPT = (
+    "You are a careful data engineer. You are given a database schema (tables with their columns), "
+    "the relationships that are ALREADY known from deterministic sources, and optionally SQL snippets "
+    "that an automatic parser could not handle. Suggest ADDITIONAL likely relationships only: "
+    "(a) column-to-column dependencies you can read from the SQL, and (b) foreign-key-like links "
+    "implied by naming conventions (e.g. orders.customer_id -> customers.id). "
+    "Use the exact node ids given. Never repeat a known relationship. Give a confidence between 0 and 1 "
+    "and a one-sentence reason. If you are not reasonably confident, omit the relationship."
+    + " " + UNTRUSTED_NOTICE
+)
+
+SUGGESTION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "relationships": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "kind": {"type": "string", "enum": ["table", "column"]},
+                    "source": {"type": "string", "description": "node id that depends on / is derived from the target"},
+                    "target": {"type": "string", "description": "node id that the source depends on"},
+                    "confidence": {"type": "number"},
+                    "reason": {"type": "string"},
+                },
+                "required": ["kind", "source", "target", "confidence", "reason"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["relationships"],
+    "additionalProperties": False,
+}
+
+_TABLE_TYPES = {NodeType.TABLE, NodeType.VIEW, NodeType.DBT_MODEL, NodeType.DBT_SOURCE, NodeType.DBT_SEED, NodeType.DBT_SNAPSHOT}
+
+
+def schema_summary(graph: ImpactGraph, max_tables: Optional[int] = None) -> Dict:
+    """Compact, deterministic description of the graph the model will reason about."""
+    tables = []
+    known = []
+    by_id = {n.id: n for n in graph.nodes()}
+    for n in sorted(graph.nodes(), key=lambda x: x.id):
+        if n.type not in _TABLE_TYPES:
+            continue
+        cols = []
+        for c in graph.nodes(NodeType.COLUMN):
+            if c.meta.get("parent") != n.id:
+                continue
+            entry = {"id": c.id, "name": c.name, "type": c.meta.get("data_type")}
+            prof = c.meta.get("profile") or {}
+            if prof:  # distinct counts / ranges help the model spot join keys
+                entry["profile"] = {k: prof.get(k) for k in ("distinct", "null_pct", "min", "max") if prof.get(k) is not None}
+            cols.append(entry)
+        cols.sort(key=lambda c: c["id"])
+        t_entry = {"id": n.id, "type": n.type.value, "columns": cols}
+        if (n.meta.get("profile") or {}).get("row_count") is not None:
+            t_entry["row_count"] = n.meta["profile"]["row_count"]
+        tables.append(t_entry)
+    if max_tables is not None:
+        tables = tables[:max_tables]
+    for e in graph.edges():
+        if e.type in (EdgeType.DEPENDS_ON, EdgeType.WRITES_TO):
+            s, d = by_id.get(e.src), by_id.get(e.dst)
+            if s and d and (s.type in _TABLE_TYPES or s.type == NodeType.COLUMN):
+                known.append({"source": e.src, "target": e.dst, "via": e.meta.get("via", e.type.value)})
+    return {"tables": tables, "known_relationships": sorted(known, key=lambda r: (r["source"], r["target"]))}
+
+
+def suggest_lineage(
+    graph: ImpactGraph,
+    unparsed_sql: Optional[List[Dict]] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    max_tables: Optional[int] = None,
+    max_tokens: int = 16000,
+    provider=None,
+) -> List[Dict]:
+    """Ask the configured LLM for candidate relationships. Returns a list of suggestion dicts
+    (kind, source, target, confidence, reason) - nothing is added to the graph yet.
+    ``provider``: LLMProvider instance or name ('anthropic' | 'bedrock' | 'openai'); default Anthropic."""
+    llm = get_provider(provider, model=model, api_key=api_key)
+    payload = schema_summary(graph, max_tables=max_tables)
+    payload["unparsed_sql"] = [
+        {"where": sanitize_text(u.get("where"), 300), "sql": sanitize_text(u.get("sql", ""), 4000)} for u in (unparsed_sql or [])
+    ][:50]
+    user = ("Schema, known relationships and unparsed SQL as JSON:\n\n"
+            + wrap_untrusted(f"```json\n{json.dumps(payload, indent=2, sort_keys=True)}\n```")
+            + "\n\nSuggest additional relationships.")
+    text = llm.complete(SYSTEM_PROMPT, user, max_tokens=max_tokens, json_schema=SUGGESTION_SCHEMA)
+    data = extract_json(text)
+    if not isinstance(data, dict):
+        return []
+    out = []
+    for r in data.get("relationships", []):
+        try:
+            out.append({"kind": r["kind"], "source": r["source"], "target": r["target"],
+                        "confidence": float(r["confidence"]), "reason": str(r.get("reason", ""))})
+        except (KeyError, TypeError, ValueError):
+            continue
+    return out
+
+
+def apply_suggestions(graph: ImpactGraph, suggestions: List[Dict], min_confidence: float = 0.6) -> int:
+    """Add accepted suggestions as ``llm``-provenance DEPENDS_ON edges. Returns how many were added.
+
+    Only nodes that already exist in the graph (or columns of existing tables) are
+    linked — the model cannot invent tables."""
+    added = 0
+    for s in suggestions:
+        if s.get("confidence", 0) < min_confidence:
+            continue
+        src, dst = s["source"], s["target"]
+        if src == dst:
+            continue
+        for nid in (src, dst):
+            if nid not in graph:
+                if nid.startswith("column:") and "." in nid:
+                    parent_name = nid[len("column:"):].rpartition(".")[0]
+                    parent = next((n.id for n in graph.nodes() if n.id.split(":", 1)[-1] == parent_name), None)
+                    if parent is None:
+                        break
+                    graph.add_node(Node(id=nid, type=NodeType.COLUMN, name=nid.rsplit(".", 1)[-1], meta={"parent": parent}))
+                    graph.add_edge(Edge(src=parent, dst=nid, type=EdgeType.CONTAINS))
+                else:
+                    break
+        else:
+            before = len(graph.edges())
+            graph.add_edge(Edge(src=src, dst=dst, type=EdgeType.DEPENDS_ON,
+                                meta={"provenance": LLM, "via": "llm", "confidence": s.get("confidence"), "reason": s.get("reason", "")}))
+            if len(graph.edges()) > before:
+                added += 1
+            if s.get("kind") == "column":
+                # also link the owning tables so table-level views show the relationship
+                sp, dp = graph.get_node(src), graph.get_node(dst)
+                if sp and dp and sp.meta.get("parent") and dp.meta.get("parent") and sp.meta["parent"] != dp.meta["parent"]:
+                    graph.add_edge(Edge(src=sp.meta["parent"], dst=dp.meta["parent"], type=EdgeType.DEPENDS_ON,
+                                        meta={"provenance": LLM, "via": "llm", "confidence": s.get("confidence")}))
+    return added

datagraph/ai/providers.py

@@ -0,0 +1,197 @@
+"""LLM providers for the optional AI layer.
+
+The graph is never built by an LLM; these providers only *explain* results or *suggest*
+relationships (tagged ``llm``). Three backends, one tiny interface:
+
+* ``anthropic`` - Claude via the Anthropic API (``pip install datagraph[ai]``, ``ANTHROPIC_API_KEY``)
+* ``bedrock``   - Amazon Bedrock Converse API: Amazon Nova, Claude on Bedrock, Llama, Mistral ...
+                  (``pip install datagraph[bedrock]``; standard AWS credentials / ``AWS_REGION``)
+* ``openai``    - any OpenAI-compatible chat endpoint (OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, Groq ...)
+                  via plain HTTPS - no extra dependency (``DATAGRAPH_LLM_BASE_URL`` / ``DATAGRAPH_LLM_API_KEY``)
+
+Selection: explicit ``provider=`` argument, else ``DATAGRAPH_LLM_PROVIDER``, else ``anthropic``.
+Model: explicit ``model=``, else ``DATAGRAPH_LLM_MODEL``, else the provider default.
+Secrets are read from the environment / the cloud SDK's credential chain - never from the graph.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, Optional
+
+DEFAULT_MODELS = {
+    "anthropic": "claude-opus-5",
+    "bedrock": "amazon.nova-pro-v1:0",
+    "openai": "gpt-4o-mini",
+}
+
+_JSON_INSTRUCTION = (
+    "\n\nRespond with ONLY a single JSON object (no prose, no code fences) that conforms to this JSON schema:\n"
+)
+
+
+class LLMProvider:
+    """Minimal interface: complete(system, user) -> text. Subclasses set ``name`` and ``model``."""
+
+    name = "base"
+    model = ""
+
+    def complete(self, system: str, user: str, *, max_tokens: int = 4096, json_schema: Optional[Dict] = None) -> str:
+        raise NotImplementedError
+
+    # shared helper for providers without native structured output
+    @staticmethod
+    def _with_schema(user: str, json_schema: Optional[Dict]) -> str:
+        if not json_schema:
+            return user
+        return user + _JSON_INSTRUCTION + json.dumps(json_schema)
+
+
+def extract_json(text: str) -> Optional[Any]:
+    """Parse JSON from a model reply, tolerating code fences and surrounding prose."""
+    if not text:
+        return None
+    t = text.strip()
+    m = re.search(r"```(?:json)?\s*(.*?)```", t, re.S)
+    if m:
+        t = m.group(1).strip()
+    try:
+        return json.loads(t)
+    except json.JSONDecodeError:
+        pass
+    start, end = t.find("{"), t.rfind("}")
+    if start != -1 and end > start:
+        try:
+            return json.loads(t[start:end + 1])
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+class AnthropicProvider(LLMProvider):
+    name = "anthropic"
+
+    def __init__(self, model: Optional[str] = None, api_key: Optional[str] = None, client=None):
+        self.model = model or DEFAULT_MODELS["anthropic"]
+        if client is not None:
+            self.client = client
+        else:
+            try:
+                import anthropic
+            except ImportError as e:
+                raise ImportError("The Anthropic provider requires the 'anthropic' package: pip install datagraph[ai]") from e
+            self.client = anthropic.Anthropic(api_key=api_key) if api_key else anthropic.Anthropic()
+
+    def complete(self, system: str, user: str, *, max_tokens: int = 4096, json_schema: Optional[Dict] = None) -> str:
+        kwargs: Dict[str, Any] = dict(model=self.model, max_tokens=max_tokens, system=system,
+                                      messages=[{"role": "user", "content": user}])
+        if json_schema:
+            kwargs["output_config"] = {"format": {"type": "json_schema", "schema": json_schema}}
+        if max_tokens > 8000 and not json_schema:
+            with self.client.messages.stream(**kwargs) as stream:  # long outputs: stream to avoid timeouts
+                response = stream.get_final_message()
+        else:
+            response = self.client.messages.create(**kwargs)
+        if getattr(response, "stop_reason", None) == "refusal":
+            return ""
+        return "".join(getattr(b, "text", "") for b in response.content if getattr(b, "type", "") == "text")
+
+
+class BedrockProvider(LLMProvider):
+    """Amazon Bedrock Converse API - works for Amazon Nova, Anthropic Claude on Bedrock, Llama, Mistral, ..."""
+
+    name = "bedrock"
+
+    def __init__(self, model: Optional[str] = None, region: Optional[str] = None, client=None, profile: Optional[str] = None):
+        self.model = model or os.environ.get("DATAGRAPH_LLM_MODEL") or DEFAULT_MODELS["bedrock"]
+        if client is not None:
+            self.client = client
+        else:
+            try:
+                import boto3
+            except ImportError as e:
+                raise ImportError("The Bedrock provider requires 'boto3': pip install datagraph[bedrock]") from e
+            session = boto3.Session(profile_name=profile) if profile else boto3.Session()
+            self.client = session.client("bedrock-runtime", region_name=region or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or "us-east-1")
+
+    # Bedrock models have per-model output caps (Nova: 10k, many others 4k-8k); clamp and retry once on the model's limit.
+    DEFAULT_MAX_TOKENS = int(os.environ.get("DATAGRAPH_LLM_MAX_TOKENS", "8000"))
+
+    def complete(self, system: str, user: str, *, max_tokens: int = 4096, json_schema: Optional[Dict] = None) -> str:
+        budget = min(int(max_tokens), self.DEFAULT_MAX_TOKENS)
+        for attempt in (1, 2):
+            try:
+                response = self.client.converse(
+                    modelId=self.model,
+                    system=[{"text": system}],
+                    messages=[{"role": "user", "content": [{"text": self._with_schema(user, json_schema)}]}],
+                    inferenceConfig={"maxTokens": budget, "temperature": 0.0},
+                )
+                break
+            except Exception as e:  # botocore ValidationException carries the limit in its message
+                m = re.search(r"model limit of (\d+)", str(e))
+                if attempt == 1 and m and int(m.group(1)) < budget:
+                    budget = max(256, int(m.group(1)) - 1)
+                    continue
+                raise
+        content = ((response.get("output") or {}).get("message") or {}).get("content") or []
+        return "".join(part.get("text", "") for part in content if isinstance(part, dict))
+
+
+class OpenAICompatibleProvider(LLMProvider):
+    """Any /v1/chat/completions endpoint (OpenAI, Azure OpenAI, Ollama, vLLM, Groq, LM Studio ...). No SDK needed."""
+
+    name = "openai"
+
+    def __init__(self, model: Optional[str] = None, api_key: Optional[str] = None, base_url: Optional[str] = None, transport=None):
+        self.model = model or os.environ.get("DATAGRAPH_LLM_MODEL") or DEFAULT_MODELS["openai"]
+        self.api_key = api_key or os.environ.get("DATAGRAPH_LLM_API_KEY") or os.environ.get("OPENAI_API_KEY") or ""
+        self.base_url = (base_url or os.environ.get("DATAGRAPH_LLM_BASE_URL") or os.environ.get("OPENAI_BASE_URL") or "https://api.openai.com/v1").rstrip("/")
+        self._transport = transport  # callable(url, headers, payload) -> dict, injectable for tests
+
+    def _post(self, url: str, headers: Dict[str, str], payload: Dict) -> Dict:
+        if self._transport:
+            return self._transport(url, headers, payload)
+        import urllib.request
+
+        req = urllib.request.Request(url, data=json.dumps(payload).encode("utf-8"), headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=300) as resp:  # nosec - URL comes from configuration, not data
+            return json.loads(resp.read().decode("utf-8"))
+
+    def complete(self, system: str, user: str, *, max_tokens: int = 4096, json_schema: Optional[Dict] = None) -> str:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        payload: Dict[str, Any] = {
+            "model": self.model, "max_tokens": int(max_tokens), "temperature": 0,
+            "messages": [{"role": "system", "content": system}, {"role": "user", "content": self._with_schema(user, json_schema)}],
+        }
+        if json_schema:
+            payload["response_format"] = {"type": "json_object"}
+        data = self._post(f"{self.base_url}/chat/completions", headers, payload)
+        choices = data.get("choices") or []
+        if not choices:
+            return ""
+        msg = choices[0].get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, list):  # some servers return content parts
+            content = "".join(p.get("text", "") for p in content if isinstance(p, dict))
+        return content or ""
+
+
+def get_provider(provider: Optional[Any] = None, model: Optional[str] = None, api_key: Optional[str] = None, **kwargs) -> LLMProvider:
+    """Resolve a provider: an LLMProvider instance is returned as-is; a name ('anthropic' | 'bedrock' | 'openai')
+    or None (-> $DATAGRAPH_LLM_PROVIDER, default anthropic) builds one."""
+    if isinstance(provider, LLMProvider):
+        return provider
+    name = (provider or os.environ.get("DATAGRAPH_LLM_PROVIDER") or "anthropic").lower()
+    model = model or os.environ.get("DATAGRAPH_LLM_MODEL")
+    if name == "anthropic":
+        return AnthropicProvider(model=model, api_key=api_key, **kwargs)
+    if name in ("bedrock", "aws", "nova"):
+        return BedrockProvider(model=model, **kwargs)
+    if name in ("openai", "openai-compatible", "ollama", "azure", "vllm", "groq"):
+        return OpenAICompatibleProvider(model=model, api_key=api_key, **kwargs)
+    raise ValueError(f"unknown LLM provider '{name}' (use anthropic | bedrock | openai)")

datagraph/analysis/__init__.py

@@ -0,0 +1,5 @@
+from .impact import ImpactAnalysis, analyze_impact
+from .risk import risk_score
+from .tests_recommender import recommend_tests
+
+__all__ = ["ImpactAnalysis", "analyze_impact", "risk_score", "recommend_tests"]

datagraph/analysis/impact.py

@@ -0,0 +1,85 @@
+"""High-level impact analysis: blast radius + risk + owners + test plan in one call."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from ..graph import ImpactGraph
+from .risk import risk_score
+from .tests_recommender import recommend_tests
+
+
+@dataclass
+class ImpactAnalysis:
+    changed: List[str]
+    affected: Dict[str, int]  # node id -> depth
+    risk: Dict  # {"score": float, "level": str}
+    recommended_tests: List[str]
+    trees: List[Dict] = field(default_factory=list)
+    owners: Dict[str, List[str]] = field(default_factory=dict)  # owner -> affected node names
+    include_inferred: bool = True
+    _graph: Optional[ImpactGraph] = None
+
+    def summary_by_type(self) -> Dict[str, int]:
+        counts: Dict[str, int] = {}
+        if self._graph is None:
+            return counts
+        for node_id in self.affected:
+            node = self._graph.get_node(node_id)
+            if node:
+                counts[node.type.value] = counts.get(node.type.value, 0) + 1
+        return counts
+
+    def to_dict(self) -> Dict:
+        return {
+            "changed": self.changed,
+            "affected": self.affected,
+            "affected_by_type": self.summary_by_type(),
+            "risk": self.risk,
+            "owners": self.owners,
+            "recommended_tests": self.recommended_tests,
+            "include_inferred": self.include_inferred,
+            "trees": self.trees,
+        }
+
+
+def analyze_impact(
+    graph: ImpactGraph,
+    changed: List[str],
+    max_depth: Optional[int] = None,
+    include_inferred: bool = True,
+) -> ImpactAnalysis:
+    """Compute the blast radius, risk level, owners to notify, and test plan."""
+    resolved: List[str] = []
+    for ref in changed:
+        node = graph.resolve(ref)
+        if node is not None:
+            if node.id not in resolved:
+                resolved.append(node.id)
+        elif ref in graph and ref not in resolved:
+            resolved.append(ref)
+
+    affected = graph.impact(resolved, max_depth=max_depth, include_inferred=include_inferred)
+    risk = risk_score(graph, affected)
+    tests = recommend_tests(graph, affected)
+    trees = [graph.impact_tree(nid, max_depth=max_depth, include_inferred=include_inferred) for nid in resolved]
+
+    owners: Dict[str, List[str]] = {}
+    for nid in affected:
+        node = graph.get_node(nid)
+        if node and node.owner:
+            owners.setdefault(str(node.owner), []).append(node.name)
+    for k in owners:
+        owners[k] = sorted(set(owners[k]))
+
+    return ImpactAnalysis(
+        changed=resolved,
+        affected=affected,
+        risk=risk,
+        recommended_tests=tests,
+        trees=trees,
+        owners=dict(sorted(owners.items())),
+        include_inferred=include_inferred,
+        _graph=graph,
+    )