cloudmap 1.0.0__py3-none-any.whl

cloudmap/__init__.py

@@ -0,0 +1,3 @@
+"""cloudmap - trace an Azure resource's full dependency graph and export it."""
+
+__version__ = "1.0.0"

cloudmap/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cloudmap/adapters/__init__.py

@@ -0,0 +1,91 @@
+"""Adapters: turn a raw export into the neutral cloudmap Graph.
+
+The rest of the tool never learns which cloud (or file shape) the data came from
+- that knowledge is quarantined here. Adding a cloud = adding one adapter.
+The neutral shape and accepted inputs are documented in FORMAT.md.
+
+Today:
+- AzureAdapter        raw Azure Resource Graph  -> Graph  (runs extraction rules)
+- neutral graph JSON  a file cloudmap wrote     -> Graph  (loaded back, no re-extract)
+"""
+
+import json
+
+from ..graph import build_graph
+from ..model import Edge, Graph, Node
+
+
+class AzureAdapter:
+    """Raw Azure Resource Graph (a list of resources, each with `properties`) ->
+    neutral Graph. The Azure-specific rules live in extract/extractors.py; this
+    just names the seam and delegates."""
+
+    name = "azure"
+
+    @staticmethod
+    def matches(data):
+        resources = _azure_resources(data)
+        return bool(resources) and any(
+            str(r.get("type", "")).lower().startswith("microsoft.") for r in resources
+        )
+
+    @staticmethod
+    def to_graph(data):
+        return build_graph(_azure_resources(data))
+
+
+def _azure_resources(data):
+    if isinstance(data, dict):
+        return data.get("data") or data.get("resources") or []
+    if isinstance(data, list):
+        return data
+    return []
+
+
+def _looks_neutral(data):
+    """A graph cloudmap itself wrote: a dict carrying both `nodes` and `edges`."""
+    return isinstance(data, dict) and isinstance(data.get("nodes"), list) \
+        and isinstance(data.get("edges"), list)
+
+
+def graph_from_neutral(data):
+    """Reconstruct a Graph from cloudmap's own JSON output (post-extraction, so no
+    rules run). Provenance (origin/evidence), hop distances and the map's own meta
+    (seed, complete, read_gaps) are preserved - a reloaded map keeps its caveats."""
+    nodes = {}
+    for n in data.get("nodes", []):
+        nodes[n["id"]] = Node(
+            id=n["id"],
+            name=n.get("name", ""),
+            type=n.get("type", ""),
+            resource_group=n.get("resourceGroup", ""),
+            location=n.get("location", ""),
+            external=bool(n.get("external")),
+            note=n.get("note", ""),
+        )
+    edges = [
+        Edge(
+            source=e["source"],
+            target=e["target"],
+            kind=e.get("kind", ""),
+            origin=e.get("origin", "extracted"),
+            evidence=e.get("evidence", ""),
+        )
+        for e in data.get("edges", [])
+    ]
+    distances = {n["id"]: n["hops"] for n in data.get("nodes", []) if n.get("hops") is not None}
+    meta = dict(data.get("meta") or {})
+    if data.get("seed"):
+        meta.setdefault("seed", data["seed"])
+    return Graph(nodes=nodes, edges=edges, distances=distances, meta=meta)
+
+
+def load_graph(path):
+    """Read a file and return a neutral Graph, auto-detecting the input shape:
+    a neutral cloudmap graph is loaded as-is; anything else is treated as a raw
+    cloud export and sent through the matching adapter (Azure today)."""
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if _looks_neutral(data):
+        return graph_from_neutral(data)
+    return AzureAdapter.to_graph(data)

cloudmap/ask/__init__.py

@@ -0,0 +1,111 @@
+"""Ask: answer questions about a map that has already been verified.
+
+Read-only by construction, and that is this layer's whole trust story. The facts
+in an answer are computed from the graph (`queries.py`); a local model may at most
+route an unusual phrasing (`intent.py`) or put the computed facts into prose
+(`narration.py`). Because the model never produces the facts, it cannot turn a guess
+into a fact - the worst it can do is choose the wrong query, which the printed
+query name and subject make immediately obvious.
+
+An answer also inherits the map's honesty: if the artifact says it is incomplete,
+every answer drawn from it carries that warning.
+"""
+
+from ..graph import HIGH_LEVEL_PREFIXES, is_high_level
+from . import queries
+from .intent import SUPPORTED, llm_parse, parse
+from .narration import narrate
+
+__all__ = ["SUPPORTED", "answer", "narrate", "warnings"]
+
+
+def answer(graph, question, allow_llm_intent=False, max_hops=None, model=None):
+    """Route `question` to one deterministic query and run it against `graph`."""
+    plan = parse(question, graph)
+    if plan is None and allow_llm_intent:
+        plan = llm_parse(question, graph, model=model)
+    if plan is None:
+        result = _error("I could not turn that into a query over this map.")
+    else:
+        result = _run(graph, plan, max_hops=max_hops)
+    result["question"] = question
+    result["warnings"] = warnings(graph)
+    return result
+
+
+def _run(graph, plan, max_hops=None):
+    query = plan.get("query")
+    subject, target = plan.get("subject"), plan.get("target")
+
+    if query in ("impact", "depends") and not subject:
+        return _error(_no_subject(graph, "Name a resource from this map in the question."),
+                      query=query)
+    if query == "paths" and not (subject and target):
+        return _error(_no_subject(graph, "Name two resources: 'how does <resource> reach "
+                                         "<other>'."), query=query)
+
+    if query == "impact":
+        return queries.impact(graph, subject, max_hops=max_hops)
+    if query == "depends":
+        return queries.depends(graph, subject, max_hops=max_hops)
+    if query == "paths":
+        return queries.paths(graph, subject, target)
+    if query == "shared":
+        return queries.shared(graph)
+    if query == "guesses":
+        return queries.guesses(graph)
+    if query == "summary":
+        return queries.summary(graph)
+    return _error(f"Unknown query '{query}'.")
+
+
+def _no_subject(graph, default):
+    """Why the resource was not found matters. In a collapsed map the instance is
+    usually right there on the diagram, inside a group box - saying "name a
+    resource" sends the reader looking for a typo that does not exist."""
+    if not is_high_level(graph):
+        return default
+    groups = sorted({n.name for n in graph.nodes.values()
+                     if str(n.id).startswith(HIGH_LEVEL_PREFIXES)})
+    return ("This map is the high-level view: resources are grouped into one box per "
+            "type, so instance names do not exist in it. Ask about a group instead "
+            f"({', '.join(groups[:6])}{', ...' if len(groups) > 6 else ''}), or re-run "
+            "the trace with --level detail to keep instance names.")
+
+
+def _error(message, query=None):
+    return {"query": query, "subject": None, "subject_name": None, "error": message,
+            "headline": message, "findings": [], "facts": {}, "supported": list(SUPPORTED)}
+
+
+def warnings(graph):
+    """What the reader must know before believing the answer: the map's own limits."""
+    meta = getattr(graph, "meta", None) or {}
+    out = []
+    if meta.get("complete") is False:
+        out.append("This map is marked INCOMPLETE - resources and edges may be missing, "
+                   "so this answer can be missing them too.")
+    if meta.get("truncated"):
+        out.append("The scan behind this map hit its pagination cap.")
+    for gap in meta.get("read_gaps") or []:
+        out.append(f"read gap in the source scan: {gap}")
+    # a class of edge the scan never went looking for: an empty answer here means
+    # "not looked for", not "nothing found"
+    for spot in meta.get("blind_spots") or []:
+        out.append(f"blind spot in the source scan: {spot}")
+
+    grouped = sum(1 for nid in graph.nodes if str(nid).startswith(HIGH_LEVEL_PREFIXES))
+    if grouped:
+        out.append(f"This is the high-level view: {grouped} box(es) each stand for every "
+                   "instance of a resource type, so counts and names here are per type, "
+                   "not per instance.")
+
+    model_edges = sum(1 for e in graph.edges if e.origin != "extracted")
+    if model_edges:
+        out.append(f"{model_edges} edge(s) in this map are model-proposed guesses; findings "
+                   "that rely on them are marked unverified.")
+    external = sum(1 for n in graph.nodes.values() if n.external)
+    if external:
+        out.append(f"{external} node(s) are referenced but were never verified as real "
+                   "resources.")
+    return out

cloudmap/ask/intent.py

@@ -0,0 +1,133 @@
+"""Turn a developer's question into ONE deterministic query.
+
+Rules first, deliberately: the phrasings people actually type are keyword-shaped,
+a rule match costs nothing, and it works on a machine with no model installed. A
+local model is only a FALLBACK for phrasings the rules miss (opt-in, `--llm`), and
+even then it may do exactly two things - name a query from a fixed list and name a
+resource - both of which are validated against this graph before anything runs.
+The model picks a route; it never supplies an answer. A wrong route is visible,
+because the query and subject it chose are printed with the answer.
+"""
+
+import re
+
+from ..local_model import generate_json
+from .queries import QUERIES
+
+SUPPORTED = (
+    "what breaks if I touch <resource>     - what depends on it (blast radius)",
+    "what does <resource> depend on        - what it needs to work",
+    "how does <resource> reach <other>     - the paths between two resources",
+    "what is shared in this map            - resources several others depend on",
+    "what should I not trust               - the model-proposed guesses",
+    "explain this map                      - a summary of what was traced",
+)
+
+# Checked in order: the specific, whole-map questions first, so "which paths cross
+# a shared vault" is understood as a question about sharing, not as a path lookup.
+_RULES = (
+    ("guesses", (r"(not trust|untrusted|unverified|guess|how sure|confidence|"
+                 r"model[- ]proposed|reliable)")),
+    ("shared", (r"(shared|in common|common dependenc|several (apps|resources|teams)|"
+                r"more than one (app|resource|team))")),
+    ("impact", (r"(what breaks|breaks if|what depends|who depends|dependents|blast radius|"
+                r"impact|affected|if i (touch|change|delete|remove|restart|move|redeploy|"
+                r"rotate|break))")),
+    # The verbs of "I am about to change this": whatever the sentence around them
+    # looks like, the question is always who else feels it. Catching them with a
+    # rule keeps the common real-world phrasings off the model entirely.
+    ("impact", (r"\b(rotat\w*|restart\w*|delet\w*|decommission\w*|redeploy\w*|resiz\w*|"
+                r"migrat\w*|patch\w*|upgrad\w*|drain\w*|scal\w*|reboot\w*)\b")),
+    ("depends", r"(depends? on|dependenc(y|ies)|what does .*(need|use)|needs|uses|downstream)"),
+    ("paths", r"(paths?|reach|route|how does .*(talk|connect|get) )"),
+    ("summary", r"(explain|summar|overview|what is (this|in this)|describe|shape of)"),
+)
+
+_NEEDS_SUBJECT = ("impact", "depends")
+
+
+def parse(question, graph):
+    """Rule-based routing. Returns a plan dict, or None if no rule recognised it."""
+    text = (question or "").strip()
+    if not text:
+        return None
+    subjects = match_nodes(graph, text)
+    for query, pattern in _RULES:
+        if re.search(pattern, text, re.I):
+            return _plan(query, subjects)
+    return None
+
+
+def _plan(query, subjects):
+    plan = {"query": query}
+    if query == "paths":
+        if subjects:
+            plan["subject"] = subjects[0]
+        if len(subjects) > 1:
+            plan["target"] = subjects[1]
+    elif query in _NEEDS_SUBJECT and subjects:
+        plan["subject"] = subjects[0]
+    return plan
+
+
+def match_nodes(graph, text):
+    """Resource names mentioned in `text`, in the order they appear.
+
+    Longest name wins on overlap, so a question about `myapi` is not read as a
+    question about `api` - the same label-boundary discipline the extractors use.
+    """
+    low = text.lower()
+    hits = []
+    for nid, node in graph.nodes.items():
+        name = (node.name or "").lower()
+        if len(name) < 3 or name not in low:
+            continue
+        hits.append((low.index(name), len(name), nid))
+
+    hits.sort(key=lambda h: (-h[1], h[0]))
+    claimed, chosen = [], []
+    for pos, length, nid in hits:
+        span = (pos, pos + length)
+        if any(span[0] >= c[0] and span[1] <= c[1] for c in claimed):
+            continue
+        claimed.append(span)
+        chosen.append((pos, nid))
+    chosen.sort()
+    return [nid for _pos, nid in chosen]
+
+
+_PROMPT = """You route a question to ONE query over a cloud dependency map.
+Output ONLY JSON: {{"query":"<name>","subject":"<resource name or empty>","target":"<resource name or empty>"}}
+Allowed query names and what they mean:
+- impact: what breaks if the subject changes (what depends on it)
+- depends: what the subject itself depends on
+- paths: how subject reaches target
+- shared: resources that several others depend on
+- guesses: which parts of the map are unverified
+- summary: explain the whole map
+Use ONLY resource names from this list, copied exactly: {names}
+Question: {question}
+"""
+
+
+def llm_parse(question, graph, model=None, timeout=120):
+    """Fallback routing by the local model. Anything it returns is validated: an
+    unknown query name is refused, and a resource it invents is dropped because it
+    resolves against this graph or not at all."""
+    names = sorted({n.name for n in graph.nodes.values() if n.name})
+    out = generate_json(
+        _PROMPT.format(names=", ".join(names[:200]), question=question),
+        model=model, timeout=timeout)
+
+    query = str(out.get("query", "")).strip().lower()
+    if query not in QUERIES:
+        return None
+    plan = {"query": query}
+    for key in ("subject", "target"):
+        hint = str(out.get(key) or "").strip()
+        if not hint:
+            continue
+        resolved = match_nodes(graph, hint)
+        if resolved:
+            plan[key] = resolved[0]
+    return plan

cloudmap/ask/narration.py

@@ -0,0 +1,54 @@
+"""Optional prose over an answer the graph already produced.
+
+The model is handed the computed FACTS only - names, relationships, hop counts,
+trust labels - and told to add nothing. The deterministic answer is printed above
+the narration either way, so if the prose drifts, what the reader sees is a
+narration disagreeing with the facts printed right above it, not a wrong answer.
+
+Empty string on any failure: no ollama means no prose, never a missing answer.
+"""
+
+import json
+
+from ..local_model import generate
+
+_PROMPT = """You explain a cloud dependency answer to a developer, in 2-4 sentences.
+Rules:
+- Use ONLY the facts in the JSON. Never add a resource, relationship or cause that is not there.
+- Say plainly which findings are unverified guesses, if any are.
+- No headings, no bullet lists, no restating the JSON field names.
+
+Question: {question}
+
+Facts:
+{facts}
+"""
+
+
+def narrate(result, model=None, timeout=120, max_findings=20):
+    """Prose for a deterministic answer. Returns "" if there is nothing to narrate
+    or the local model is unavailable."""
+    if not result or result.get("error"):
+        return ""
+
+    findings = [
+        {
+            "name": f.get("name"),
+            "type": f.get("type"),
+            "hops": f.get("hops"),
+            "trust": f.get("trust"),
+            "relationships": [h.get("kind") for h in (f.get("path") or [])],
+        }
+        for f in (result.get("findings") or [])[:max_findings]
+    ]
+    facts = {
+        "query": result.get("query"),
+        "subject": result.get("subject_name"),
+        "headline": result.get("headline"),
+        "counts": result.get("facts"),
+        "findings": findings,
+        "caveats": result.get("warnings") or [],
+    }
+    prompt = _PROMPT.format(question=result.get("question", ""),
+                            facts=json.dumps(facts, indent=2))
+    return generate(prompt, model=model, timeout=timeout, json_format=False).strip()