semanticembed 0.7.1__tar.gz → 0.7.2__tar.gz

{semanticembed-0.7.1 → semanticembed-0.7.2}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the SemanticEmbed SDK.
 
+## 0.7.2 — Live-connector retry
+
+- All three live connectors (`from_dynatrace`, `from_honeycomb`, `from_datadog`)
+  now retry once with 0.5s backoff on transient failures: 502 / 503 / 504 /
+  ConnectError / ReadTimeout. 4xx responses (auth errors etc.) propagate
+  immediately. Matches the behavior already shipped on `encode()` / `aencode()`.
+- Notebooks 02 / 03 / 04 / 06 refreshed to point at the v0.7.x APIs
+  (`cache=True`, `aencode_diff`, `find_edges`, `dedupe_edges`,
+  `from_github_actions`).
+
 ## 0.7.1 — Async surface
 
 - New: `aencode`, `aencode_file`, `aencode_diff` — async siblings of the

{semanticembed-0.7.1 → semanticembed-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semanticembed
-Version: 0.7.1
+Version: 0.7.2
 Summary: 6D structural intelligence for directed graphs. Six numbers per node. Sub-millisecond.
 Project-URL: Homepage, https://github.com/jmurray10/semanticembed-sdk
 Project-URL: Documentation, https://github.com/jmurray10/semanticembed-sdk

semanticembed-0.7.2/notebooks/01_quickstart.ipynb

@@ -0,0 +1,294 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+  "colab": {
+   "provenance": [],
+   "name": "01_quickstart"
+  },
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# SemanticEmbed: Quickstart\n",
+    "\n",
+    "**6D structural intelligence for directed graphs.**\n",
+    "\n",
+    "This notebook walks you through:\n",
+    "1. Installing the SDK\n",
+    "2. Encoding a microservice graph\n",
+    "3. Reading the 6D output\n",
+    "4. Generating a structural risk report\n",
+    "\n",
+    "**No GPU needed. Runs in seconds.**\n",
+    "\n",
+    "[GitHub](https://github.com/jmurray10/semanticembed-sdk)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Install the SDK\n",
+    "!pip install -q semanticembed\n",
+    "\n",
+    "from semanticembed import encode, report\n",
+    "print(\"SemanticEmbed installed.\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 1: Define a Graph\n",
+    "\n",
+    "The only input is an edge list -- a list of `(source, target)` pairs. This is Google's Online Boutique, an 11-service e-commerce application.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Google Online Boutique -- 11 microservices\n",
+    "edges = [\n",
+    "    (\"frontend\",              \"ad-service\"),\n",
+    "    (\"frontend\",              \"cart-service\"),\n",
+    "    (\"frontend\",              \"checkout-service\"),\n",
+    "    (\"frontend\",              \"currency-service\"),\n",
+    "    (\"frontend\",              \"product-catalog-service\"),\n",
+    "    (\"frontend\",              \"recommendation-service\"),\n",
+    "    (\"frontend\",              \"shipping-service\"),\n",
+    "    (\"checkout-service\",      \"cart-service\"),\n",
+    "    (\"checkout-service\",      \"currency-service\"),\n",
+    "    (\"checkout-service\",      \"email-service\"),\n",
+    "    (\"checkout-service\",      \"payment-service\"),\n",
+    "    (\"checkout-service\",      \"product-catalog-service\"),\n",
+    "    (\"checkout-service\",      \"shipping-service\"),\n",
+    "    (\"recommendation-service\",\"product-catalog-service\"),\n",
+    "    (\"cart-service\",          \"redis-cart\"),\n",
+    "]\n",
+    "\n",
+    "print(f\"Edges: {len(edges)}\")\n",
+    "for src, tgt in edges:\n",
+    "    print(f\"  {src} -> {tgt}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 2: Compute the 6D Encoding\n",
+    "\n",
+    "One function call. Sub-millisecond.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "result = encode(edges)\n",
+    "\n",
+    "print(f\"Encoding time: {result.encoding_time_ms:.2f}ms\")\n",
+    "print(f\"Nodes: {result.graph_info['nodes']}\")\n",
+    "print(f\"Edges: {result.graph_info['edges']}\")\n",
+    "print(f\"Max depth: {result.graph_info['max_depth']}\")\n",
+    "print()\n",
+    "print(result.table)\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 3: Understand the Output\n",
+    "\n",
+    "Each node now has six numbers -- its coordinates in 6-dimensional structural space:\n",
+    "\n",
+    "| Dimension | What It Measures |\n",
+    "|-----------|-----------------|\n",
+    "| **Depth** | Position in the execution pipeline (0.0 = entry, 1.0 = deepest) |\n",
+    "| **Independence** | Lateral redundancy at this pipeline stage (0.0 = only node at this depth) |\n",
+    "| **Hierarchy** | Module / group membership |\n",
+    "| **Throughput** | Fraction of total traffic flowing through this node |\n",
+    "| **Criticality** | Fraction of end-to-end paths that depend on this node |\n",
+    "| **Fanout** | Broadcaster (1.0) vs aggregator (0.0) |\n",
+    "\n",
+    "These six dimensions are mathematically independent. Knowing any five tells you nothing about the sixth.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Inspect specific nodes\n",
+    "dim_names = [\"depth\", \"independence\", \"hierarchy\", \"throughput\", \"criticality\", \"fanout\"]\n",
+    "\n",
+    "for node in [\"frontend\", \"checkout-service\", \"redis-cart\"]:\n",
+    "    v = result.vectors[node]\n",
+    "    print(f\"\\n{node}:\")\n",
+    "    for name, val in zip(dim_names, v):\n",
+    "        bar = \"#\" * int(val * 30)\n",
+    "        print(f\"  {name:<15} {val:.3f}  {bar}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 4: Structural Risk Report\n",
+    "\n",
+    "The encoding identifies architectural risks purely from topology. No runtime data, no historical incidents.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "risk = report(result)\n",
+    "print(risk)\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 5: Try a Different Graph\n",
+    "\n",
+    "Same SDK, different architecture. Weaveworks Sock Shop -- 14 services on Kubernetes.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "sock_shop = [\n",
+    "    (\"edge-router\",   \"frontend\"),\n",
+    "    (\"frontend\",      \"catalogue\"),\n",
+    "    (\"frontend\",      \"orders\"),\n",
+    "    (\"frontend\",      \"user\"),\n",
+    "    (\"frontend\",      \"carts\"),\n",
+    "    (\"orders\",        \"shipping\"),\n",
+    "    (\"orders\",        \"payment\"),\n",
+    "    (\"orders\",        \"carts\"),\n",
+    "    (\"orders\",        \"user\"),\n",
+    "    (\"catalogue\",     \"catalogue-db\"),\n",
+    "    (\"carts\",         \"carts-db\"),\n",
+    "    (\"orders\",        \"orders-db\"),\n",
+    "    (\"user\",          \"user-db\"),\n",
+    "    (\"shipping\",      \"rabbitmq\"),\n",
+    "    (\"queue-master\",  \"rabbitmq\"),\n",
+    "]\n",
+    "\n",
+    "result_shop = encode(sock_shop)\n",
+    "print(result_shop.table)\n",
+    "print()\n",
+    "print(report(result_shop))\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 6: Your Own Graph\n",
+    "\n",
+    "Paste your edge list below. Any directed graph -- microservices, data pipelines, CI/CD workflows, agent orchestrations.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Replace with your own edges\n",
+    "my_edges = [\n",
+    "    (\"service-a\", \"service-b\"),\n",
+    "    (\"service-a\", \"service-c\"),\n",
+    "    (\"service-b\", \"service-d\"),\n",
+    "    (\"service-c\", \"service-d\"),\n",
+    "    (\"service-d\", \"service-e\"),\n",
+    "]\n",
+    "\n",
+    "my_result = encode(my_edges)\n",
+    "print(my_result.table)\n",
+    "print()\n",
+    "print(report(my_result))\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## What's Next?\n",
+    "\n",
+    "- **[02 - Dimensions Deep Dive](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/02_dimensions.ipynb)** -- what each dimension means with worked examples\n",
+    "- **[03 - Drift Detection](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/03_drift_detection.ipynb)** -- compare graph versions, detect structural changes\n",
+    "- **[04 - Bring Your Own Graph](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/04_bring_your_own.ipynb)** -- load from JSON, OTel traces, or Kubernetes\n",
+    "\n",
+    "**Free tier:** 50 nodes. **Paid tier:** unlimited nodes + continuous monitoring.\n",
+    "\n",
+    "[GitHub](https://github.com/jmurray10/semanticembed-sdk) | [Contact](mailto:jeffmurr@seas.upenn.edu)\n",
+    "\n",
+    "*Patent pending. Application #63/994,075.*\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Auto-discover edges from your repo\n",
+    "\n",
+    "The SDK parses 14 different infrastructure formats \u2014 docker-compose, Kubernetes,\n",
+    "Terraform, CloudFormation, AWS CDK, Pulumi, GitHub Actions, package.json,\n",
+    "pyproject.toml, OpenTelemetry traces, Python imports, and the LangGraph /\n",
+    "CrewAI / AutoGen agent frameworks. `extract.from_directory()` auto-detects\n",
+    "whatever's there:\n",
+    "\n",
+    "```python\n",
+    "import semanticembed as se\n",
+    "\n",
+    "edges, sources = se.extract.from_directory(\".\")\n",
+    "print(f\"Found {len(edges)} edges from {sources}\")\n",
+    "\n",
+    "result = se.encode(edges)\n",
+    "```\n",
+    "\n",
+    "For *running* infra (not just repo files), see `semanticembed.live`:\n",
+    "\n",
+    "```python\n",
+    "edges = se.live.from_dynatrace(env_url=..., api_token=...)\n",
+    "edges = se.live.from_honeycomb(dataset=..., api_key=...)\n",
+    "edges = se.live.from_datadog(api_key=..., app_key=...)\n",
+    "```\n"
+   ]
+  }
+ ]
+}

semanticembed-0.7.2/notebooks/02_dimensions.ipynb

@@ -0,0 +1,327 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+  "colab": {
+   "provenance": [],
+   "name": "02_dimensions"
+  },
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# SemanticEmbed: The Six Dimensions\n",
+    "\n",
+    "A deep dive into what each of the six structural measurements means, why they matter, and how to read them.\n",
+    "\n",
+    "[GitHub](https://github.com/jmurray10/semanticembed-sdk)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "!pip install -q semanticembed\n",
+    "from semanticembed import encode, report\n",
+    "print(\"Ready.\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## The Encoding at a Glance\n",
+    "\n",
+    "Every node in a directed graph gets six numbers. Together they form a coordinate vector in 6-dimensional Euclidean space that fully describes the node's structural role.\n",
+    "\n",
+    "| # | Dimension | What It Measures | Range |\n",
+    "|---|-----------|-----------------|-------|\n",
+    "| 1 | **Depth** | Pipeline position (entry to sink) | 0.0 -- 1.0 |\n",
+    "| 2 | **Independence** | Lateral redundancy at same stage | 0.0 -- 1.0 |\n",
+    "| 3 | **Hierarchy** | Module / group membership | 0.0 -- 1.0 |\n",
+    "| 4 | **Throughput** | Share of total traffic | 0.0 -- 1.0 |\n",
+    "| 5 | **Criticality** | Share of end-to-end paths | 0.0 -- 1.0 |\n",
+    "| 6 | **Fanout** | Broadcaster (1.0) vs aggregator (0.0) | 0.0 -- 1.0 |\n",
+    "\n",
+    "These are mathematically independent. Knowing any five tells you nothing about the sixth.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 1: Depth\n",
+    "\n",
+    "**What:** Where a node sits in the execution pipeline -- from entry point (0.0) to deepest sink (1.0).\n",
+    "\n",
+    "**Why it matters:** Depth tells you the blast radius direction. A failure at depth 0.0 cascades forward through the entire graph. A failure at depth 1.0 affects nothing downstream.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# A simple pipeline -- depth increases left to right\n",
+    "pipeline = [\n",
+    "    (\"ingestion\", \"validation\"),\n",
+    "    (\"validation\", \"transform\"),\n",
+    "    (\"transform\", \"enrichment\"),\n",
+    "    (\"enrichment\", \"storage\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(pipeline)\n",
+    "print(\"LINEAR PIPELINE -- depth increases with each hop\")\n",
+    "print(\"=\" * 60)\n",
+    "for node, v in sorted(result.vectors.items(), key=lambda x: x[1][0]):\n",
+    "    print(f\"  {node:<15} depth={v[0]:.3f}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 2: Independence\n",
+    "\n",
+    "**What:** How many other nodes exist at the same depth level. Measures lateral redundancy.\n",
+    "\n",
+    "**Why it matters:** Independence = 0.0 means this node is the ONLY node at its depth. There is no parallel alternative. It is a structural chokepoint regardless of whether it is healthy today.\n",
+    "\n",
+    "**This dimension has no equivalent in standard graph centrality.** Maximum correlation with all 10 standard centrality measures across real applications: |r| = 0.369.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Wide fan-out -- services at depth 1 have high independence\n",
+    "wide = [\n",
+    "    (\"gateway\", \"service-a\"),\n",
+    "    (\"gateway\", \"service-b\"),\n",
+    "    (\"gateway\", \"service-c\"),\n",
+    "    (\"gateway\", \"service-d\"),\n",
+    "    (\"service-a\", \"db\"),\n",
+    "    (\"service-b\", \"db\"),\n",
+    "    (\"service-c\", \"db\"),\n",
+    "    (\"service-d\", \"db\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(wide)\n",
+    "print(\"WIDE ARCHITECTURE -- high independence at depth 1\")\n",
+    "print(\"=\" * 60)\n",
+    "for node, v in sorted(result.vectors.items(), key=lambda x: x[1][0]):\n",
+    "    print(f\"  {node:<15} depth={v[0]:.3f}  independence={v[1]:.3f}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 3: Hierarchy\n",
+    "\n",
+    "**What:** Which module or logical group a node belongs to.\n",
+    "\n",
+    "**Why it matters:** Hierarchy captures community structure. Nodes in the same module have similar hierarchy values. Useful for detecting cross-module dependencies and module boundary violations.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Two separate modules feeding into a shared database\n",
+    "two_modules = [\n",
+    "    (\"orders-api\",    \"orders-processor\"),\n",
+    "    (\"orders-processor\", \"orders-db\"),\n",
+    "    (\"users-api\",     \"users-processor\"),\n",
+    "    (\"users-processor\", \"users-db\"),\n",
+    "    (\"orders-processor\", \"shared-cache\"),\n",
+    "    (\"users-processor\",  \"shared-cache\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(two_modules)\n",
+    "print(\"TWO-MODULE ARCHITECTURE\")\n",
+    "print(\"=\" * 60)\n",
+    "for node, v in sorted(result.vectors.items(), key=lambda x: x[1][2]):\n",
+    "    print(f\"  {node:<20} hierarchy={v[2]:.3f}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 4: Throughput\n",
+    "\n",
+    "**What:** What fraction of total traffic flows through this node.\n",
+    "\n",
+    "**Why it matters:** High throughput + low independence = hidden bottleneck. The node carries a disproportionate share of traffic with no backup.\n",
+    "\n",
+    "Independent of depth: a deep node can have high or low throughput.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Hub-and-spoke -- the hub has high throughput\n",
+    "hub_spoke = [\n",
+    "    (\"client-1\", \"api-hub\"),\n",
+    "    (\"client-2\", \"api-hub\"),\n",
+    "    (\"client-3\", \"api-hub\"),\n",
+    "    (\"api-hub\",  \"backend-a\"),\n",
+    "    (\"api-hub\",  \"backend-b\"),\n",
+    "    (\"api-hub\",  \"backend-c\"),\n",
+    "    (\"backend-a\", \"database\"),\n",
+    "    (\"backend-b\", \"database\"),\n",
+    "    (\"backend-c\", \"database\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(hub_spoke)\n",
+    "print(\"HUB-AND-SPOKE -- hub carries most traffic\")\n",
+    "print(\"=\" * 60)\n",
+    "for node, v in sorted(result.vectors.items(), key=lambda x: -x[1][3]):\n",
+    "    print(f\"  {node:<15} throughput={v[3]:.3f}  independence={v[1]:.3f}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 5: Criticality\n",
+    "\n",
+    "**What:** How many end-to-end paths through the graph depend on this node.\n",
+    "\n",
+    "**Why it matters:** A node with criticality 0.5 sits on half of all paths. If it fails, half of all end-to-end flows break. This is independent of throughput -- a low-traffic node can be highly critical if it bridges two large subgraphs.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Diamond shape -- the middle nodes are critical bridges\n",
+    "diamond = [\n",
+    "    (\"source\",  \"left-branch\"),\n",
+    "    (\"source\",  \"right-branch\"),\n",
+    "    (\"left-branch\",  \"merge-point\"),\n",
+    "    (\"right-branch\", \"merge-point\"),\n",
+    "    (\"merge-point\", \"sink-a\"),\n",
+    "    (\"merge-point\", \"sink-b\"),\n",
+    "    (\"merge-point\", \"sink-c\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(diamond)\n",
+    "print(\"DIAMOND -- merge-point bridges source to all sinks\")\n",
+    "print(\"=\" * 60)\n",
+    "for node, v in sorted(result.vectors.items(), key=lambda x: -x[1][4]):\n",
+    "    print(f\"  {node:<15} criticality={v[4]:.3f}  fanout={v[5]:.3f}\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Dimension 6: Fanout\n",
+    "\n",
+    "**What:** Whether a node amplifies (broadcasts to many) or aggregates (collects from many). Out-degree / total degree.\n",
+    "\n",
+    "**Why it matters:** High fanout = amplification risk. If this node fails or slows, the impact multiplies across all downstream dependents. Low fanout = convergence sink. Many services depend on this single aggregation point.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Contrasting broadcaster vs aggregator\n",
+    "fanout_example = [\n",
+    "    (\"broadcaster\", \"target-1\"),\n",
+    "    (\"broadcaster\", \"target-2\"),\n",
+    "    (\"broadcaster\", \"target-3\"),\n",
+    "    (\"broadcaster\", \"target-4\"),\n",
+    "    (\"broadcaster\", \"target-5\"),\n",
+    "    (\"source-1\", \"aggregator\"),\n",
+    "    (\"source-2\", \"aggregator\"),\n",
+    "    (\"source-3\", \"aggregator\"),\n",
+    "    (\"source-4\", \"aggregator\"),\n",
+    "    (\"source-5\", \"aggregator\"),\n",
+    "]\n",
+    "\n",
+    "result = encode(fanout_example)\n",
+    "print(\"BROADCASTER vs AGGREGATOR\")\n",
+    "print(\"=\" * 60)\n",
+    "for node in [\"broadcaster\", \"aggregator\"]:\n",
+    "    v = result.vectors[node]\n",
+    "    label = \"broadcasts to 5\" if v[5] > 0.5 else \"collects from 5\"\n",
+    "    print(f\"  {node:<15} fanout={v[5]:.3f}  ({label})\")\n"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Structural Risk Patterns\n",
+    "\n",
+    "Combinations of dimension values reveal risk:\n",
+    "\n",
+    "| Pattern | Dimensions | Risk |\n",
+    "|---------|-----------|------|\n",
+    "| **Amplification risk** | High fanout + high criticality | Failure cascades to many services across many paths |\n",
+    "| **Convergence sink** | Low independence + low fanout | Many services depend on one aggregation point |\n",
+    "| **Structural SPOF** | Low independence + high criticality | Only node at its depth, on most paths |\n",
+    "| **Hidden bottleneck** | High throughput + low independence | Carries most traffic with no redundancy |\n",
+    "\n",
+    "The risk report detects these automatically. See [01 - Quickstart](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/01_quickstart.ipynb) for the full walkthrough.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "*Patent pending. Application #63/994,075.*\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Cache repeat encodes during exploration\n",
+    "\n",
+    "When you're iterating on the same edge list (tweaking visualizations, building\n",
+    "slides), set ``cache=True`` to skip the HTTP round trip on repeat calls:\n",
+    "\n",
+    "```python\n",
+    "result = se.encode(edges, cache=True)   # 1st call: HTTP\n",
+    "result = se.encode(edges, cache=True)   # 2nd call: 0ms, no HTTP\n",
+    "se.clear_encode_cache()                 # explicit eviction if needed\n",
+    "```\n",
+    "\n",
+    "The cache key is order-independent, so reordering the same edges still hits.\n"
+   ]
+  }
+ ]
+}