cloudmap 1.0.0__tar.gz → 1.1.0__tar.gz

{cloudmap-1.0.0 → cloudmap-1.1.0}/ARCHITECTURE.md

@@ -67,7 +67,7 @@ flowchart TD
 | `cloudmap/ask/queries.py` | **The Ask layer's heart**: the six queries, each computed by traversal | An answer must be auditable, so it is derived from edges, never generated. `_trust()` grades a whole path by its weakest hop, and distinguishes *passing through* an unverified node (whole finding becomes a guess) from *ending* at one (the reference is proven; the target is flagged). |
 | `cloudmap/ask/intent.py` | Question → one query | Rules first so the common phrasings need no model at all (including the "rotate / restart / decommission" verbs). The model is a fallback that may only name a query from a fixed list and a resource, both validated against the graph — it routes, it never answers. |
 | `cloudmap/ask/narration.py` | Optional prose (`--explain`) | Handed the computed facts only, and printed *below* them, so drifting prose is visibly a narration disagreeing with the facts, not a wrong answer. |
-| `cloudmap/local_model.py` | The single outbound model call | One module = one auditable promise: the call goes to localhost (ollama) and failure returns an empty value, because cloudmap must be fully useful with no model installed. |
+| `cloudmap/local_model.py` | The single outbound model call | One module = one auditable promise: the call goes to localhost (ollama's API by default, any OpenAI-compatible server via `CLOUDMAP_LLM_URL`) and failure returns an empty value, because cloudmap must be fully useful with no model installed. |
 | `cloudmap/cli.py` | Orchestration + argparse | `_cmd_trace` wires the trace stages together (live enrichment + external merge live here); `_cmd_ask` loads a saved map and prints the computed answer, proof lines included. |
 | `fixtures/contoso.json` | 100% synthetic estate | Fixture-first development → zero cloud contact in tests. |
 | `tests/test_graph.py` | 5 unit tests | Lock in the hub-boundary behaviour + edge-kinds against the fixture. |

{cloudmap-1.0.0 → cloudmap-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudmap
-Version: 1.0.0
+Version: 1.1.0
 Summary: Trace the blast radius of an Azure resource: one name in, a verified dependency graph out.
 Project-URL: Homepage, https://github.com/KatsaounisThanasis/cloudmap
 Project-URL: Repository, https://github.com/KatsaounisThanasis/cloudmap
@@ -32,16 +32,29 @@ Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# cloudmap
+<div align="center">
 
-[![CI](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml/badge.svg)](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
-[![Python](https://img.shields.io/pypi/pyversions/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+<img src="docs/social-preview.png" alt="cloudmap — one Azure resource name in, its whole blast radius out" width="820">
 
-**Give it the name of one Azure resource. Get back its full dependency graph -
-the blast radius - as an editable draw.io diagram with native Azure icons, plus
-an interactive HTML viewer, Mermaid, JSON and CSV.**
+<p>
+  <a href="https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml"><img src="https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/cloudmap/"><img src="https://img.shields.io/pypi/v/cloudmap?color=1f7a8c" alt="PyPI"></a>
+  <a href="https://pypi.org/project/cloudmap/"><img src="https://img.shields.io/pypi/pyversions/cloudmap?color=1f7a8c" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
+</p>
+
+<p>
+  <a href="#install"><b>Install</b></a> ·
+  <a href="#60-second-demo"><b>Demo</b></a> ·
+  <a href="#interactive-wizard"><b>Wizard</b></a> ·
+  <a href="#why"><b>Why</b></a> ·
+  <a href="#how-it-works"><b>How it works</b></a> ·
+  <a href="#ask-a-map-questions"><b>Ask</b></a>
+</p>
+
+</div>
+
+---
 
 Azure Resource Graph has no "dependencies" table. The relationships that matter
 - what an App Service is hosted on, which Key Vault it reads, which subnet it
@@ -50,15 +63,6 @@ Endpoint fronts, which App Gateway routes to it - are buried inside each
 resource's `properties`. cloudmap reads them out, correlates them into one
 graph, and draws it.
 
-![The interactive HTML viewer: the seed at the centre, dependencies fanned out with native Azure icons, each edge carrying its relationship and proof](estate-viewer.png)
-
-**Contents** · [Install](#install) · [60-second demo](#60-second-demo) ·
-[Interactive wizard](#interactive-wizard) · [Why](#why) ·
-[What it maps](#what-it-maps) · [How it works](#how-it-works) ·
-[Ask a map questions](#ask-a-map-questions) · [Live Azure](#live-azure-opt-in) ·
-[Capture and scrub](#capture-a-real-export-so-the-tests-can-be-wrong) ·
-[Usage reference](#usage-reference)
-
 ## Install
 
 ```
@@ -67,15 +71,25 @@ pip install cloudmap
 
 Python 3.9+. Two runtime dependencies (`rich` and `questionary`, both for the
 terminal UI). Live mode additionally needs the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
-on your PATH, and the optional AI passes need a local [ollama](https://ollama.com).
+on your PATH. The optional AI passes need a local model server - [ollama](https://ollama.com)
+works out of the box, and any OpenAI-compatible server (LM Studio, llama.cpp,
+vLLM, LocalAI) works via two env vars:
+
+```
+export CLOUDMAP_LLM_URL=http://localhost:1234/v1/chat/completions   # your server
+export CLOUDMAP_LLM_MODEL=<model name>                              # default: qwen2.5-coder:3b
+```
 
-To work on it instead:
+<details>
+<summary>Working on it instead</summary>
 
 ```
 git clone https://github.com/KatsaounisThanasis/cloudmap && cd cloudmap
 pip install -e ".[dev]" && pytest
 ```
 
+</details>
+
 ## 60-second demo
 
 No Azure account needed - the repo ships a synthetic estate:
@@ -99,7 +113,12 @@ Blast radius: 9 resources (0 external), 9 dependencies
 🔗 draw.io: contoso-web.drawio
 ```
 
-On a real estate it goes several layers deep:
+That is the default **high-level** view - resources grouped by type. Add
+`--level detail` to see every instance with its real name, and on a real estate
+it goes several layers deep:
+
+<details>
+<summary>A deeper map</summary>
 
 ```text
 Blast radius: 15 resources (0 external), 14 dependencies
@@ -122,19 +141,26 @@ Blast radius: 15 resources (0 external), 14 dependencies
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
-(That is the default **high-level** view - resources grouped by type. Add
-`--level detail` to see every instance with its real name.)
+</details>
 
-### Output formats
+### What you get out
 
-| Flag | You get |
+| Flag | Output |
 |---|---|
 | `-o FILE` | **draw.io** diagram with native Azure icons - open it in [draw.io](https://app.diagrams.net), the desktop app or the VS Code extension and edit it like any hand-drawn diagram |
-| `--html FILE` | **Interactive viewer**: one self-contained file, no server and no CDN. Dark mode, edges colour-coded by relationship type (security / data / network), resource-group filters and search, SVG + PNG export, and direct links into the Azure portal |
+| `--html FILE` | **Interactive viewer** - one self-contained file, no server and no CDN |
 | `--mermaid FILE` | Mermaid source, for embedding in Markdown docs |
 | `--json FILE` | The graph itself - this is what `cloudmap ask` reads |
 | `--csv FILE` | Flat edge list with evidence, for a spreadsheet or an auditor |
 
+<div align="center">
+  <img src="estate-viewer.png" alt="The interactive HTML viewer: the seed at the centre, dependencies fanned out with native Azure icons, each edge carrying its relationship and proof">
+</div>
+
+The `--html` viewer has a dark mode, edges colour-coded by relationship type
+(security / data / network), resource-group filters and search, SVG and PNG
+export, and direct links into the Azure portal.
+
 ## Interactive wizard
 
 Run it with no arguments and it walks you through the whole thing:
@@ -198,20 +224,6 @@ App Insights, VNets, Private Endpoints and managed identities.
 
 ## Ask a map questions
 
-```
-cloudmap ask <map.json> "<question>"
-
-  --explain      also narrate the answer with a LOCAL model (ollama)
-  --llm          if no built-in rule understands the phrasing, let a LOCAL model
-                 pick the query (its choice is validated against the map)
-  --max-hops N   limit traversal depth
-  --json         print the answer as JSON (for scripting)
-```
-
-Instance names only exist in a `--level detail` map; the default high-level map
-groups by type, so ask it about a group (`"what breaks if I touch Key Vault"`) or
-trace with `--level detail` first:
-
 ```
 $ cloudmap trace contoso-web --from fixtures/contoso.json --level detail --json out.json
 $ cloudmap ask out.json "what breaks if I touch contoso-kv"
@@ -238,11 +250,50 @@ cannot promote a guess to one. Every finding shows the hops behind it and the pr
 of each hop, and a finding that leans on a model-proposed edge is marked `[GUESS]`.
 If the map itself says it is incomplete, every answer from it repeats that warning.
 
-## Live Azure (opt-in)
+<details>
+<summary><b>Flags</b></summary>
+
+```
+cloudmap ask <map.json> "<question>"
+
+  --explain      also narrate the answer with a LOCAL model
+  --llm          if no built-in rule understands the phrasing, let a LOCAL model
+                 pick the query (its choice is validated against the map)
+  --max-hops N   limit traversal depth
+  --json         print the answer as JSON (for scripting)
+```
+
+Instance names only exist in a `--level detail` map; the default high-level map
+groups by type, so ask it about a group (`"what breaks if I touch Key Vault"`) or
+trace with `--level detail` first.
+
+</details>
+
+## Live Azure
+
+Fixtures are the default. Live mode is opt-in and **not sandboxed**: `--allow-live`
+is the deliberate switch, and cloudmap reads whatever subscription `az` is pointed
+at. The read is read-only, but it is a read of live infrastructure, so point it on
+purpose. **Do not point this at data you are not authorized to read.**
 
 ```
 cloudmap trace my-app --live --allow-live
+```
 
+**cloudmap runs as you.** It has no credentials of its own - every read goes through
+the Azure CLI with your `az login` token, so it sees exactly what your account can
+see and nothing more. Resource Graph filters by RBAC, so resources you cannot read
+simply do not appear (Azure raises no error for them - they are invisible, not
+denied). Deep reads your role does not allow (app settings, Key Vault values, AKS
+manifests) fail visibly instead: cloudmap **reports the gap** on the map rather than
+silently dropping edges, and warns when a scan is truncated - so a small graph on a
+low-privilege account reads as "this is what I was allowed to see", not "this is
+everything".
+
+<details>
+<summary><b>Flags, enrichment and the subscription pin</b></summary>
+
+```
   --single-sub          query only the active subscription (default: every enabled
                         subscription in the tenant)
   --enrich MODE         which web apps to deep-enrich for the dependencies that only
@@ -251,7 +302,7 @@ cloudmap trace my-app --live --allow-live
                         all | seed | none
   --resolve-secrets     read KV secret values in-memory to see through KV-backed
                         connection strings (never printed or written)
-  --llm                 let a LOCAL model (ollama) propose extra edges, each
+  --llm                 let a LOCAL model propose extra edges, each
                         verified against scanned resources before it is trusted
 ```
 
@@ -265,22 +316,18 @@ Anything left un-enriched is reported as a **blind spot** on the map and repeate
 every `ask` answer drawn from it, so an empty result never passes for "nothing depends
 on this".
 
-Live mode is opt-in, not sandboxed: `--allow-live` is the deliberate switch, and
-cloudmap reads whatever subscription `az` is pointed at. The read is read-only, but
-it is a read of live infrastructure, so point it on purpose. As an optional guard
-against a stale `az` context silently redirecting a scan, pin the subscription you
-mean - if set, cloudmap refuses to run against any other active subscription:
+As an optional guard against a stale `az` context silently redirecting a scan, pin the
+subscription you mean - if set, cloudmap refuses to run against any other active
+subscription:
 
 ```
 export CLOUDMAP_ALLOW_SUBSCRIPTION=<subscription-id>   # optional
 ```
 
-If a live read fails (e.g. missing RBAC), cloudmap **reports the gap** instead of
-silently dropping edges, and warns when a scan is truncated - so you know when the
-picture is incomplete. Fixtures are always the default.
-**Do not point this at data you are not authorized to read.**
+</details>
 
-## Capture a real export (so the tests can be wrong)
+<details>
+<summary><b>Capture a real export (so the tests can be wrong)</b></summary>
 
 A fixture you wrote yourself can only confirm what you already believe. `capture`
 saves what Azure actually returned, scrubs it, and gives you something that can
@@ -305,7 +352,10 @@ printed, the mapping is not. **A scrubber is not a proof: read the file before y
 commit it.** `--no-scrub` exists for local debugging and writes credentials to
 disk; keep those files named `*.live.json` so `.gitignore` catches them.
 
-## Usage reference
+</details>
+
+<details>
+<summary><b>Usage reference</b></summary>
 
 ```
 cloudmap trace <name> (--from <fixture.json> | --live) [options]
@@ -325,7 +375,9 @@ cloudmap trace <name> (--from <fixture.json> | --live) [options]
   -d, --out-dir DIR          write every artifact into DIR, named after the seed
 ```
 
-Other subcommands: `cloudmap capture`, `cloudmap scrub`, `cloudmap ask` (see above).
+Other subcommands: `cloudmap capture`, `cloudmap scrub`, `cloudmap ask`.
+
+</details>
 
 ## Roadmap
 

{cloudmap-1.0.0 → cloudmap-1.1.0}/README.md

@@ -1,13 +1,26 @@
-# cloudmap
+<div align="center">
 
-[![CI](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml/badge.svg)](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
-[![Python](https://img.shields.io/pypi/pyversions/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+<img src="docs/social-preview.png" alt="cloudmap — one Azure resource name in, its whole blast radius out" width="820">
 
-**Give it the name of one Azure resource. Get back its full dependency graph -
-the blast radius - as an editable draw.io diagram with native Azure icons, plus
-an interactive HTML viewer, Mermaid, JSON and CSV.**
+<p>
+  <a href="https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml"><img src="https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/cloudmap/"><img src="https://img.shields.io/pypi/v/cloudmap?color=1f7a8c" alt="PyPI"></a>
+  <a href="https://pypi.org/project/cloudmap/"><img src="https://img.shields.io/pypi/pyversions/cloudmap?color=1f7a8c" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
+</p>
+
+<p>
+  <a href="#install"><b>Install</b></a> ·
+  <a href="#60-second-demo"><b>Demo</b></a> ·
+  <a href="#interactive-wizard"><b>Wizard</b></a> ·
+  <a href="#why"><b>Why</b></a> ·
+  <a href="#how-it-works"><b>How it works</b></a> ·
+  <a href="#ask-a-map-questions"><b>Ask</b></a>
+</p>
+
+</div>
+
+---
 
 Azure Resource Graph has no "dependencies" table. The relationships that matter
 - what an App Service is hosted on, which Key Vault it reads, which subnet it
@@ -16,15 +29,6 @@ Endpoint fronts, which App Gateway routes to it - are buried inside each
 resource's `properties`. cloudmap reads them out, correlates them into one
 graph, and draws it.
 
-![The interactive HTML viewer: the seed at the centre, dependencies fanned out with native Azure icons, each edge carrying its relationship and proof](estate-viewer.png)
-
-**Contents** · [Install](#install) · [60-second demo](#60-second-demo) ·
-[Interactive wizard](#interactive-wizard) · [Why](#why) ·
-[What it maps](#what-it-maps) · [How it works](#how-it-works) ·
-[Ask a map questions](#ask-a-map-questions) · [Live Azure](#live-azure-opt-in) ·
-[Capture and scrub](#capture-a-real-export-so-the-tests-can-be-wrong) ·
-[Usage reference](#usage-reference)
-
 ## Install
 
 ```
@@ -33,15 +37,25 @@ pip install cloudmap
 
 Python 3.9+. Two runtime dependencies (`rich` and `questionary`, both for the
 terminal UI). Live mode additionally needs the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
-on your PATH, and the optional AI passes need a local [ollama](https://ollama.com).
+on your PATH. The optional AI passes need a local model server - [ollama](https://ollama.com)
+works out of the box, and any OpenAI-compatible server (LM Studio, llama.cpp,
+vLLM, LocalAI) works via two env vars:
+
+```
+export CLOUDMAP_LLM_URL=http://localhost:1234/v1/chat/completions   # your server
+export CLOUDMAP_LLM_MODEL=<model name>                              # default: qwen2.5-coder:3b
+```
 
-To work on it instead:
+<details>
+<summary>Working on it instead</summary>
 
 ```
 git clone https://github.com/KatsaounisThanasis/cloudmap && cd cloudmap
 pip install -e ".[dev]" && pytest
 ```
 
+</details>
+
 ## 60-second demo
 
 No Azure account needed - the repo ships a synthetic estate:
@@ -65,7 +79,12 @@ Blast radius: 9 resources (0 external), 9 dependencies
 🔗 draw.io: contoso-web.drawio
 ```
 
-On a real estate it goes several layers deep:
+That is the default **high-level** view - resources grouped by type. Add
+`--level detail` to see every instance with its real name, and on a real estate
+it goes several layers deep:
+
+<details>
+<summary>A deeper map</summary>
 
 ```text
 Blast radius: 15 resources (0 external), 14 dependencies
@@ -88,19 +107,26 @@ Blast radius: 15 resources (0 external), 14 dependencies
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
-(That is the default **high-level** view - resources grouped by type. Add
-`--level detail` to see every instance with its real name.)
+</details>
 
-### Output formats
+### What you get out
 
-| Flag | You get |
+| Flag | Output |
 |---|---|
 | `-o FILE` | **draw.io** diagram with native Azure icons - open it in [draw.io](https://app.diagrams.net), the desktop app or the VS Code extension and edit it like any hand-drawn diagram |
-| `--html FILE` | **Interactive viewer**: one self-contained file, no server and no CDN. Dark mode, edges colour-coded by relationship type (security / data / network), resource-group filters and search, SVG + PNG export, and direct links into the Azure portal |
+| `--html FILE` | **Interactive viewer** - one self-contained file, no server and no CDN |
 | `--mermaid FILE` | Mermaid source, for embedding in Markdown docs |
 | `--json FILE` | The graph itself - this is what `cloudmap ask` reads |
 | `--csv FILE` | Flat edge list with evidence, for a spreadsheet or an auditor |
 
+<div align="center">
+  <img src="estate-viewer.png" alt="The interactive HTML viewer: the seed at the centre, dependencies fanned out with native Azure icons, each edge carrying its relationship and proof">
+</div>
+
+The `--html` viewer has a dark mode, edges colour-coded by relationship type
+(security / data / network), resource-group filters and search, SVG and PNG
+export, and direct links into the Azure portal.
+
 ## Interactive wizard
 
 Run it with no arguments and it walks you through the whole thing:
@@ -164,20 +190,6 @@ App Insights, VNets, Private Endpoints and managed identities.
 
 ## Ask a map questions
 
-```
-cloudmap ask <map.json> "<question>"
-
-  --explain      also narrate the answer with a LOCAL model (ollama)
-  --llm          if no built-in rule understands the phrasing, let a LOCAL model
-                 pick the query (its choice is validated against the map)
-  --max-hops N   limit traversal depth
-  --json         print the answer as JSON (for scripting)
-```
-
-Instance names only exist in a `--level detail` map; the default high-level map
-groups by type, so ask it about a group (`"what breaks if I touch Key Vault"`) or
-trace with `--level detail` first:
-
 ```
 $ cloudmap trace contoso-web --from fixtures/contoso.json --level detail --json out.json
 $ cloudmap ask out.json "what breaks if I touch contoso-kv"
@@ -204,11 +216,50 @@ cannot promote a guess to one. Every finding shows the hops behind it and the pr
 of each hop, and a finding that leans on a model-proposed edge is marked `[GUESS]`.
 If the map itself says it is incomplete, every answer from it repeats that warning.
 
-## Live Azure (opt-in)
+<details>
+<summary><b>Flags</b></summary>
+
+```
+cloudmap ask <map.json> "<question>"
+
+  --explain      also narrate the answer with a LOCAL model
+  --llm          if no built-in rule understands the phrasing, let a LOCAL model
+                 pick the query (its choice is validated against the map)
+  --max-hops N   limit traversal depth
+  --json         print the answer as JSON (for scripting)
+```
+
+Instance names only exist in a `--level detail` map; the default high-level map
+groups by type, so ask it about a group (`"what breaks if I touch Key Vault"`) or
+trace with `--level detail` first.
+
+</details>
+
+## Live Azure
+
+Fixtures are the default. Live mode is opt-in and **not sandboxed**: `--allow-live`
+is the deliberate switch, and cloudmap reads whatever subscription `az` is pointed
+at. The read is read-only, but it is a read of live infrastructure, so point it on
+purpose. **Do not point this at data you are not authorized to read.**
 
 ```
 cloudmap trace my-app --live --allow-live
+```
 
+**cloudmap runs as you.** It has no credentials of its own - every read goes through
+the Azure CLI with your `az login` token, so it sees exactly what your account can
+see and nothing more. Resource Graph filters by RBAC, so resources you cannot read
+simply do not appear (Azure raises no error for them - they are invisible, not
+denied). Deep reads your role does not allow (app settings, Key Vault values, AKS
+manifests) fail visibly instead: cloudmap **reports the gap** on the map rather than
+silently dropping edges, and warns when a scan is truncated - so a small graph on a
+low-privilege account reads as "this is what I was allowed to see", not "this is
+everything".
+
+<details>
+<summary><b>Flags, enrichment and the subscription pin</b></summary>
+
+```
   --single-sub          query only the active subscription (default: every enabled
                         subscription in the tenant)
   --enrich MODE         which web apps to deep-enrich for the dependencies that only
@@ -217,7 +268,7 @@ cloudmap trace my-app --live --allow-live
                         all | seed | none
   --resolve-secrets     read KV secret values in-memory to see through KV-backed
                         connection strings (never printed or written)
-  --llm                 let a LOCAL model (ollama) propose extra edges, each
+  --llm                 let a LOCAL model propose extra edges, each
                         verified against scanned resources before it is trusted
 ```
 
@@ -231,22 +282,18 @@ Anything left un-enriched is reported as a **blind spot** on the map and repeate
 every `ask` answer drawn from it, so an empty result never passes for "nothing depends
 on this".
 
-Live mode is opt-in, not sandboxed: `--allow-live` is the deliberate switch, and
-cloudmap reads whatever subscription `az` is pointed at. The read is read-only, but
-it is a read of live infrastructure, so point it on purpose. As an optional guard
-against a stale `az` context silently redirecting a scan, pin the subscription you
-mean - if set, cloudmap refuses to run against any other active subscription:
+As an optional guard against a stale `az` context silently redirecting a scan, pin the
+subscription you mean - if set, cloudmap refuses to run against any other active
+subscription:
 
 ```
 export CLOUDMAP_ALLOW_SUBSCRIPTION=<subscription-id>   # optional
 ```
 
-If a live read fails (e.g. missing RBAC), cloudmap **reports the gap** instead of
-silently dropping edges, and warns when a scan is truncated - so you know when the
-picture is incomplete. Fixtures are always the default.
-**Do not point this at data you are not authorized to read.**
+</details>
 
-## Capture a real export (so the tests can be wrong)
+<details>
+<summary><b>Capture a real export (so the tests can be wrong)</b></summary>
 
 A fixture you wrote yourself can only confirm what you already believe. `capture`
 saves what Azure actually returned, scrubs it, and gives you something that can
@@ -271,7 +318,10 @@ printed, the mapping is not. **A scrubber is not a proof: read the file before y
 commit it.** `--no-scrub` exists for local debugging and writes credentials to
 disk; keep those files named `*.live.json` so `.gitignore` catches them.
 
-## Usage reference
+</details>
+
+<details>
+<summary><b>Usage reference</b></summary>
 
 ```
 cloudmap trace <name> (--from <fixture.json> | --live) [options]
@@ -291,7 +341,9 @@ cloudmap trace <name> (--from <fixture.json> | --live) [options]
   -d, --out-dir DIR          write every artifact into DIR, named after the seed
 ```
 
-Other subcommands: `cloudmap capture`, `cloudmap scrub`, `cloudmap ask` (see above).
+Other subcommands: `cloudmap capture`, `cloudmap scrub`, `cloudmap ask`.
+
+</details>
 
 ## Roadmap
 

{cloudmap-1.0.0 → cloudmap-1.1.0}/cloudmap/__init__.py

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

{cloudmap-1.0.0 → cloudmap-1.1.0}/cloudmap/ask/narration.py

@@ -5,7 +5,7 @@ trust labels - and told to add nothing. The deterministic answer is printed abov
 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.
+Empty string on any failure: no local model means no prose, never a missing answer.
 """
 
 import json

{cloudmap-1.0.0 → cloudmap-1.1.0}/cloudmap/cli.py

@@ -38,7 +38,7 @@ def main(argv=None):
                    help="live: read KV secret values in-memory to see through KV-backed "
                         "connection strings (never printed or written)")
     t.add_argument("--llm", action="store_true",
-                   help="also let a LOCAL model (ollama) propose edges from the seed's JSON; "
+                   help="also let a LOCAL model propose edges from the seed's JSON; "
                         "each proposal is verified against scanned resources (nothing leaves the machine)")
     t.add_argument("--enrich", choices=["auto", "seed", "all", "none"], default="auto",
                    help="live: which web apps to deep-enrich for the dependencies that live "
@@ -85,7 +85,7 @@ def main(argv=None):
     a.add_argument("map", help="a cloudmap graph JSON (written by `trace --json`) or a raw export")
     a.add_argument("question", help='e.g. "what breaks if I touch kv-orders-dev"')
     a.add_argument("--explain", action="store_true",
-                   help="also narrate the answer with a LOCAL model (ollama); the computed "
+                   help="also narrate the answer with a LOCAL model; the computed "
                         "answer is printed either way")
     a.add_argument("--llm", action="store_true",
                    help="if no built-in rule understands the question, let a LOCAL model pick "
@@ -142,7 +142,7 @@ def _cmd_trace(args):
         from rich.console import Console
         from rich.progress import Progress, SpinnerColumn, TextColumn
         console = Console(stderr=True)
-        console.print("[bold yellow]Running local model (ollama) on blast radius nodes to propose hidden edges...[/bold yellow]")
+        console.print("[bold yellow]Running local model on blast radius nodes to propose hidden edges...[/bold yellow]")
         from .extract.extractors import Resolver, merge_model_edges
         from .extract.llm import llm_edges_for_seed
         

{cloudmap-1.0.0 → cloudmap-1.1.0}/cloudmap/extract/llm.py

@@ -12,13 +12,15 @@ Trust is preserved by two rails, not by trusting the model:
    is exactly what must not reach the map. Verified edges are still marked
    origin="model" (drawn dashed), because the model supplied the relationship.
 
-Local by design (ollama) - the resource JSON never leaves the machine.
+Local by design - the model runs on your machine (ollama by default, any
+OpenAI-compatible server via CLOUDMAP_LLM_URL) and the resource JSON never
+leaves it.
 """
 
 import json
 import re
 
-from ..local_model import DEFAULT_MODEL, OLLAMA_URL, generate_json  # noqa: F401  (re-exported)
+from ..local_model import DEFAULT_MODEL, LLM_URL, OLLAMA_URL, generate_json  # noqa: F401  (re-exported)
 from ..model import Edge
 
 # A plausible dependency target is a hostname / resource name / ARM id - never a
@@ -47,7 +49,7 @@ Resource JSON:
 
 def propose_edges(resource_raw, model=None, timeout=600):
     """Ask the local model for candidate edges. Returns [(target, relationship)].
-    Empty list on any failure (ollama down, bad JSON, timeout)."""
+    Empty list on any failure (model server down, bad JSON, timeout)."""
     prompt = _PROMPT.format(rtype=resource_raw.get("type", "unknown"),
                             resource=json.dumps(resource_raw, indent=2))
     parsed = generate_json(prompt, model=model, timeout=timeout)

{cloudmap-1.0.0 → cloudmap-1.1.0}/cloudmap/interactive.py

@@ -175,7 +175,7 @@ def interactive_main():
         
     # 3.2 AI Edge Proposals (Phase 3)
     use_llm = questionary.confirm(
-        "Use local AI (Ollama) to discover hidden dependencies? (Slower, but finds undocumented links)",
+        "Use a local AI model to discover hidden dependencies? (Slower, but finds undocumented links)",
         default=False,
         style=custom_style
     ).ask()

cloudmap-1.1.0/cloudmap/local_model.py

@@ -0,0 +1,92 @@
+"""The one place cloudmap talks to a model - and it talks to a LOCAL one.
+
+Keeping the transport in a single module is a design promise rather than tidiness:
+there is exactly one outbound call in the whole tool, it points at localhost, and
+it serves the only two jobs a model is allowed to do here - proposing candidate
+edges that a deterministic rule then verifies, and narrating an answer the graph
+already produced. No resource JSON ever reaches a third party.
+
+Two wire formats are spoken, chosen from the URL:
+- ollama's native /api/generate (the default, http://localhost:11434)
+- the OpenAI-compatible /v1/chat/completions that LM Studio, llama.cpp server,
+  vLLM, LocalAI (and ollama itself) expose - any URL whose path contains /v1/
+  or ends in /chat/completions is treated as OpenAI-compatible.
+
+Configure with CLOUDMAP_LLM_URL and CLOUDMAP_LLM_MODEL. CLOUDMAP_OLLAMA_URL is
+honoured as a legacy alias.
+
+Every failure returns an empty value instead of raising: cloudmap must stay fully
+useful with no model installed, so "no model" is a normal state, not an error.
+"""
+
+import json
+import os
+import urllib.parse
+import urllib.request
+
+LLM_URL = (os.environ.get("CLOUDMAP_LLM_URL")
+           or os.environ.get("CLOUDMAP_OLLAMA_URL")
+           or "http://localhost:11434/api/generate")
+DEFAULT_MODEL = os.environ.get("CLOUDMAP_LLM_MODEL", "qwen2.5-coder:3b")
+
+# Legacy alias: extract.llm re-exported this name in earlier releases.
+OLLAMA_URL = LLM_URL
+
+
+def _is_openai_compatible(url):
+    path = urllib.parse.urlparse(url).path
+    return "/v1/" in path or path.rstrip("/").endswith("chat/completions")
+
+
+def _request_body(prompt, model, json_format):
+    if _is_openai_compatible(LLM_URL):
+        body = {
+            "model": model or DEFAULT_MODEL,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+            "stream": False,
+        }
+        if json_format:
+            body["response_format"] = {"type": "json_object"}
+        return body
+    body = {
+        "model": model or DEFAULT_MODEL,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0},
+    }
+    if json_format:
+        body["format"] = "json"
+    return body
+
+
+def _response_text(resp):
+    if _is_openai_compatible(LLM_URL):
+        choices = resp.get("choices") or []
+        if not choices:
+            return ""
+        return (choices[0].get("message") or {}).get("content", "") or ""
+    return resp.get("response", "") or ""
+
+
+def generate(prompt, model=None, timeout=600, json_format=True):
+    """Ask the local model once. Returns the response text, or "" on any failure
+    (server absent, not running, timeout, malformed payload)."""
+    try:
+        req = urllib.request.Request(
+            LLM_URL, data=json.dumps(_request_body(prompt, model, json_format)).encode(),
+            headers={"Content-Type": "application/json"})
+        resp = json.load(urllib.request.urlopen(req, timeout=timeout))
+        return _response_text(resp)
+    except Exception:
+        return ""
+
+
+def generate_json(prompt, model=None, timeout=600):
+    """generate() plus a strict JSON parse. Returns {} on any failure, so callers
+    never have to distinguish "model down" from "model answered nonsense"."""
+    try:
+        parsed = json.loads(generate(prompt, model=model, timeout=timeout, json_format=True))
+    except Exception:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}

{cloudmap-1.0.0 → cloudmap-1.1.0}/tests/test_ask.py

@@ -300,7 +300,7 @@ def test_llm_routing_result_is_still_computed_by_the_query(monkeypatch):
 # --- degradation and honesty ----------------------------------------------------
 
 def test_answer_works_with_no_model_available():
-    # local_model.generate() returns "" when ollama is absent; the deterministic
+    # local_model.generate() returns "" when no local model is running; the deterministic
     # answer must be complete anyway and the narration simply empty.
     graph, seed = _real()
     res = answer(graph, f"what does {graph.nodes[seed].name} depend on")

{cloudmap-1.0.0 → cloudmap-1.1.0}/tests/test_llm.py

@@ -1,7 +1,7 @@
 """The LLM path must stay a proposer behind a verifier: only proposals whose
 target resolves to a real scanned resource survive, secret-looking targets are
-rejected, and with no model available it contributes nothing. No ollama needed -
-generate_json is monkeypatched."""
+rejected, and with no model available it contributes nothing. No model server
+needed - generate_json is monkeypatched."""
 
 from cloudmap.extract import llm
 from cloudmap.extract.extractors import Resolver
@@ -41,6 +41,6 @@ def test_secretish_targets_are_rejected(monkeypatch):
 
 def test_no_model_available_contributes_nothing(monkeypatch):
     seed, resolver = _seed_and_resolver()
-    monkeypatch.setattr(llm, "generate_json", lambda *a, **k: {})   # ollama down -> {}
+    monkeypatch.setattr(llm, "generate_json", lambda *a, **k: {})   # model down -> {}
 
     assert llm_edges_for_seed(seed, resolver) == ([], [])

cloudmap-1.1.0/tests/test_local_model.py

@@ -0,0 +1,92 @@
+"""The model transport: one module, two wire formats, and a hard promise that
+every failure returns an empty value - cloudmap must stay fully useful with no
+model installed, so "no model" is a normal state, not an error.
+
+No real server is contacted: urllib.request.urlopen is faked per test.
+"""
+
+import io
+import json
+
+import pytest
+
+from cloudmap import local_model
+
+
+class _Served:
+    """Capture the request body and serve a canned JSON response."""
+
+    def __init__(self, response):
+        self.response, self.body = response, None
+
+    def __call__(self, req, timeout=None):
+        self.body = json.loads(req.data.decode())
+        return io.BytesIO(json.dumps(self.response).encode())
+
+
+# --- wire-format selection --------------------------------------------------------
+
+@pytest.mark.parametrize("url,openai", [
+    ("http://localhost:11434/api/generate", False),
+    ("http://localhost:11434", False),
+    ("http://localhost:1234/v1/chat/completions", True),
+    ("http://localhost:8080/v1/completions", True),
+    ("http://gpu-box:8000/openai/v1/chat/completions", True),
+    ("http://localhost:9000/chat/completions", True),
+])
+def test_the_url_shape_selects_the_wire_format(url, openai):
+    assert local_model._is_openai_compatible(url) is openai
+
+
+def test_ollama_speaks_prompt_and_reads_response(monkeypatch):
+    served = _Served({"response": "hello"})
+    monkeypatch.setattr(local_model, "LLM_URL", "http://localhost:11434/api/generate")
+    monkeypatch.setattr(local_model.urllib.request, "urlopen", served)
+
+    assert local_model.generate("hi") == "hello"
+    assert served.body["prompt"] == "hi"
+    assert served.body["format"] == "json"
+    assert served.body["options"] == {"temperature": 0}
+
+
+def test_openai_compatible_speaks_messages_and_reads_choices(monkeypatch):
+    served = _Served({"choices": [{"message": {"content": "hello"}}]})
+    monkeypatch.setattr(local_model, "LLM_URL", "http://localhost:1234/v1/chat/completions")
+    monkeypatch.setattr(local_model.urllib.request, "urlopen", served)
+
+    assert local_model.generate("hi") == "hello"
+    assert served.body["messages"] == [{"role": "user", "content": "hi"}]
+    assert served.body["response_format"] == {"type": "json_object"}
+    assert "prompt" not in served.body
+
+
+# --- the never-raises contract ----------------------------------------------------
+
+def test_a_dead_server_returns_empty_never_raises(monkeypatch):
+    def down(req, timeout=None):
+        raise OSError("connection refused")
+
+    monkeypatch.setattr(local_model.urllib.request, "urlopen", down)
+
+    assert local_model.generate("hi") == ""
+    assert local_model.generate_json("hi") == {}
+
+
+@pytest.mark.parametrize("response", [
+    {},                                        # no recognisable field
+    {"choices": []},                           # openai shape, empty
+    {"response": None},                        # ollama shape, null
+])
+def test_a_malformed_payload_returns_empty(monkeypatch, response):
+    monkeypatch.setattr(local_model, "LLM_URL", "http://localhost:1234/v1/chat/completions"
+                        if "choices" in response else "http://localhost:11434/api/generate")
+    monkeypatch.setattr(local_model.urllib.request, "urlopen", _Served(response))
+
+    assert local_model.generate("hi") == ""
+
+
+@pytest.mark.parametrize("text", ["not json", "[]", "null", ""])
+def test_generate_json_returns_a_dict_or_nothing(monkeypatch, text):
+    monkeypatch.setattr(local_model, "generate", lambda *a, **k: text)
+
+    assert local_model.generate_json("hi") == {}

cloudmap-1.0.0/cloudmap/local_model.py

@@ -1,49 +0,0 @@
-"""The one place cloudmap talks to a model - and it talks to a LOCAL one.
-
-Keeping the transport in a single module is a design promise rather than tidiness:
-there is exactly one outbound call in the whole tool, it points at localhost
-(ollama), and it serves the only two jobs a model is allowed to do here -
-proposing candidate edges that a deterministic rule then verifies, and narrating
-an answer the graph already produced. No resource JSON ever reaches a third party.
-
-Every failure returns an empty value instead of raising: cloudmap must stay fully
-useful with no model installed, so "no model" is a normal state, not an error.
-"""
-
-import json
-import os
-import urllib.request
-
-OLLAMA_URL = os.environ.get("CLOUDMAP_OLLAMA_URL", "http://localhost:11434/api/generate")
-DEFAULT_MODEL = os.environ.get("CLOUDMAP_LLM_MODEL", "qwen2.5-coder:3b")
-
-
-def generate(prompt, model=None, timeout=600, json_format=True):
-    """Ask the local model once. Returns the response text, or "" on any failure
-    (ollama absent, not running, timeout, malformed payload)."""
-    body = {
-        "model": model or DEFAULT_MODEL,
-        "prompt": prompt,
-        "stream": False,
-        "options": {"temperature": 0},
-    }
-    if json_format:
-        body["format"] = "json"
-    try:
-        req = urllib.request.Request(
-            OLLAMA_URL, data=json.dumps(body).encode(),
-            headers={"Content-Type": "application/json"})
-        resp = json.load(urllib.request.urlopen(req, timeout=timeout))
-    except Exception:
-        return ""
-    return resp.get("response", "") or ""
-
-
-def generate_json(prompt, model=None, timeout=600):
-    """generate() plus a strict JSON parse. Returns {} on any failure, so callers
-    never have to distinguish "model down" from "model answered nonsense"."""
-    try:
-        parsed = json.loads(generate(prompt, model=model, timeout=timeout, json_format=True))
-    except Exception:
-        return {}
-    return parsed if isinstance(parsed, dict) else {}