semanticembed 0.7.3__tar.gz → 0.7.4__tar.gz

{semanticembed-0.7.3 → semanticembed-0.7.4}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,7 +6,7 @@ body:
     attributes:
       value: |
         Thanks for taking the time to report a bug. Please fill in the fields below.
-        For algorithm/encoding/scoring questions, email jeffmurr@seas.upenn.edu — that
+        For algorithm/encoding/scoring questions, email jeff.murray@alumni.upenn.edu — that
         runs server-side and isn't part of this repository.
 
   - type: input

{semanticembed-0.7.3 → semanticembed-0.7.4}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,10 +1,10 @@
 blank_issues_enabled: false
 contact_links:
   - name: Algorithm / encoding / scoring questions
-    url: mailto:jeffmurr@seas.upenn.edu
+    url: mailto:jeff.murray@alumni.upenn.edu
     about: |
       The 6D encoding algorithm runs server-side and isn't part of this repository.
       Email directly for questions about encoding math, risk thresholds, or scoring rules.
   - name: License / commercial inquiries
-    url: mailto:jeffmurr@seas.upenn.edu
+    url: mailto:jeff.murray@alumni.upenn.edu
     about: Pricing, paid-tier license keys, and commercial use questions.

{semanticembed-0.7.3 → semanticembed-0.7.4}/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -11,7 +11,7 @@ body:
         - **Client improvements** — async, batching, caching, error handling
 
         For changes to the encoding algorithm, risk thresholds, or scoring rules, please email
-        jeffmurr@seas.upenn.edu instead — those run server-side.
+        jeff.murray@alumni.upenn.edu instead — those run server-side.
 
   - type: dropdown
     id: kind

{semanticembed-0.7.3 → semanticembed-0.7.4}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the SemanticEmbed SDK.
 
+## 0.7.4 — Terraform count/for_each + Kubernetes auto-detect fixes
+
+- **`extract.from_terraform`** now resolves `count` / `for_each`-indexed
+  references (`aws_subnet.this[0].id`, `aws_eip.nat[count.index].id`) — the
+  form real modules use almost universally. The ref regex previously matched
+  only `type.name.` and missed them. On terraform-aws-modules/terraform-aws-vpc
+  this goes from 2 to 56 edges.
+- **`extract.from_directory`** now detects Kubernetes manifests by content
+  (`apiVersion` + `kind`) in any directory, not just conventional names like
+  `k8s/` / `manifests/`. Manifests under `release/` or `kubernetes-manifests/`
+  (e.g. GoogleCloudPlatform/microservices-demo) are now picked up.
+- Both surfaced by validating the parsers against real public repos; added
+  `tests/test_extract_regressions.py` to lock them in.
+
 ## 0.7.3 — Modern AutoGen + lenient edge parser
 
 - `from_autogen` now recognizes the autogen-agentchat 0.4+ patterns:

{semanticembed-0.7.3 → semanticembed-0.7.4}/CODE_OF_CONDUCT.md

@@ -30,7 +30,7 @@ Examples of unacceptable behavior:
 ## Enforcement
 
 Instances of unacceptable behavior may be reported to the maintainer at
-**jeffmurr@seas.upenn.edu**. All complaints will be reviewed and
+**jeff.murray@alumni.upenn.edu**. All complaints will be reviewed and
 investigated promptly and fairly.
 
 The maintainer is obligated to respect the privacy and security of the

{semanticembed-0.7.3 → semanticembed-0.7.4}/CONTRIBUTING.md

@@ -67,4 +67,4 @@ git push origin vX.Y.Z
 
 ## Questions
 
-Open a GitHub Discussion or email jeffmurr@seas.upenn.edu.
+Open a GitHub Discussion or email jeff.murray@alumni.upenn.edu.

{semanticembed-0.7.3 → semanticembed-0.7.4}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: semanticembed
-Version: 0.7.3
+Version: 0.7.4
 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
 Project-URL: Repository, https://github.com/jmurray10/semanticembed-sdk
-Author-email: Jeff Murray <jeffmurr@seas.upenn.edu>
+Author-email: Jeff Murray <jeff.murray@alumni.upenn.edu>
 License: Proprietary
 License-File: LICENSE
 License-File: LICENSE-FAQ.md
@@ -44,13 +44,14 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/semanticembed.svg)](https://pypi.org/project/semanticembed/)
 [![Python](https://img.shields.io/pypi/pyversions/semanticembed.svg)](https://pypi.org/project/semanticembed/)
 [![CI](https://github.com/jmurray10/semanticembed-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/jmurray10/semanticembed-sdk/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-source--available-blue.svg)](LICENSE-FAQ.md)
+[![Free tier](https://img.shields.io/badge/free%20tier-50%20nodes%2C%20no%20signup-brightgreen.svg)](#install)
 [![Patent Pending](https://img.shields.io/badge/patent-%2363%2F994%2C075-orange.svg)](LICENSE-FAQ.md#patent)
 [![Changelog](https://img.shields.io/badge/changelog-current-success.svg)](CHANGELOG.md)
 
-**Structural risk for directed graphs — especially AI agent pipelines.** Six numbers per node. Sub-millisecond.
+**Structural risk for directed graphs — especially AI agent pipelines.** Six numbers per node. Sub-millisecond server-side compute.
 
-SemanticEmbed computes a 6-dimensional structural encoding for every node in a directed graph. From a bare edge list — no runtime telemetry, no historical data, no tuning — it produces six independent measurements that fully describe each node's structural role.
+SemanticEmbed computes a 6-dimensional structural encoding for every node in a directed graph. From a bare edge list — no runtime telemetry, no historical data, no tuning — it produces six complementary measurements that capture distinct aspects of each node's structural role (depth, lateral redundancy, community, throughput, path criticality, broadcast vs aggregation).
 
 **Designed for the topologies traditional observability misses:**
 
@@ -59,8 +60,8 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 - **CI/CD and data pipelines** — build graph fragility, ETL bottlenecks, drift gates
 
 > **Live demos:**
-> - **[Hugging Face Space](https://huggingface.co/spaces/jmurray10/semanticembed-agent-risk)** — paste a LangGraph / CrewAI / AutoGen file, get the encoding + risk findings (zero install, ML-researcher framing).
-> - **[Demo dashboard](https://semanticembed-dashboard.vercel.app/)** — Vercel-hosted demo with the 4 reference apps + interactive 6D explorer (auth required).
+> - **[Hugging Face Space](https://huggingface.co/spaces/jmurray10/semanticembed-agent-risk)** — zero-install. Paste a LangGraph / CrewAI / AutoGen file, get the encoding + risk findings.
+> - **[Demo dashboard](https://semanticembed-dashboard.vercel.app/)** — interactive 6D explorer with 4 reference apps (sign-in required; click "Try Demo" on the login page for a no-account walkthrough).
 
 > **Validated against production incidents.** In a blind test against a live production Dynatrace environment (108 services, 569 topology-relevant incidents over 30 days), **79.6%** of incidents (453/569) occurred on nodes that 6D structural analysis had flagged as risky — from the call graph alone, before any incident occurred. See [validation methodology](docs/validation_methodology.md).
 
@@ -71,7 +72,7 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 Observability tools tell you **what broke**. SemanticEmbed tells you **what will break** — from topology alone.
 
 - **No agents, no instrumentation** — just an edge list
-- **Sub-millisecond** — encodes 100+ node graphs in <1ms
+- **Sub-millisecond server-side compute** — the encoding kernel itself runs in <1 ms on a 100-node graph; full HTTP round-trip via the cloud API is typically 0.5–2 s including network
 - **Works on any directed graph** — AI agent pipelines, microservices, data workflows, CI/CD
 - **Complementary structural axes** — six dimensions, each captures risk signals the others cannot
 - **14 deterministic edge parsers + 3 live connectors** — go from real infra to encoded result in 2 lines
@@ -141,7 +142,7 @@ Runtime monitoring tells you what is slow **now**. Structural analysis tells you
 
 ## The Six Dimensions
 
-Every node gets six independent structural measurements:
+Every node gets six complementary structural measurements:
 
 | Dimension | What It Measures | Risk Signal |
 |-----------|-----------------|-------------|
@@ -152,9 +153,13 @@ Every node gets six independent structural measurements:
 | **Criticality** | Fraction of end-to-end paths depending on this node | High criticality = SPOF |
 | **Fanout** | Broadcaster (1.0) vs aggregator (0.0) | High fanout = amplification risk |
 
-These six properties capture complementary structural information. Each dimension provides risk signals the others cannot.
+These six properties capture complementary structural information. The
+risk patterns documented below combine specific axes; no single axis is a
+complete risk signal on its own.
 
-See [docs/dimensions.md](docs/dimensions.md) for the full reference.
+See [docs/dimensions.md](docs/dimensions.md) for axis definitions, the
+formal invariance properties of the encoding, and the empirical
+correlation results vs standard graph centrality.
 
 ---
 
@@ -172,6 +177,7 @@ See [docs/dimensions.md](docs/dimensions.md) for the full reference.
 
 ## What's new in v0.7
 
+- **Modern AutoGen patterns + lenient edge parser + better error messages** (v0.7.3)
 - **`live.from_dynatrace` / `from_honeycomb` / `from_datadog`** — pull real call edges from running infra (v0.5–v0.7)
 - **OpenTelemetry trace ingestion** — auto-detects OTLP / Jaeger / Zipkin (v0.3)
 - **AI agent framework parsers** — `from_langgraph`, `from_crewai`, `from_autogen`, AST-only, no need to install the framework (v0.4)
@@ -200,6 +206,7 @@ Step-by-step Colab notebooks. Click to open, run in your browser.
 | [06 - CI/CD & Data Pipelines](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/06_cicd_pipelines.ipynb) | CI/CD & ETL | Build graph fragility, pipeline bottlenecks, drift gates |
 | [07 - OpenTelemetry](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/07_opentelemetry.ipynb) | OTel traces | Extract edges from traces, structural analysis, CI/CD gates |
 | [08 - Qwen Compression](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/08_qwen_compression.ipynb) | LLM compression | Structural pruning of Qwen2.5-7B, 10% speedup at Grade A |
+| [09 - Quantum Reachability (IBM Q free tier)](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/09_quantum_reachability.ipynb) | Quantum cross-validation | Continuous-time quantum walk on a directed graph, run on IBM Q Open Plan, cross-checked vs SDK criticality |
 
 ---
 
@@ -513,11 +520,15 @@ See [docs/input_format.md](docs/input_format.md) for the full spec.
 
 ## License
 
-SemanticEmbed SDK is **proprietary software with public source code** —
-the same model Stripe, Snowflake, and Anthropic use for their SDKs. Free
-tier covers graphs up to 50 nodes; paid tier unlocks larger graphs and
-continuous monitoring. See [LICENSE](LICENSE) and [LICENSE-FAQ](LICENSE-FAQ.md)
-for terms and common questions.
+**Source-available, with a free tier — no signup, no credit card.** The free
+tier encodes graphs up to 50 nodes; the paid tier unlocks larger graphs and
+continuous monitoring. The client, parsers, and connectors in this repo are
+public source, so you can read exactly what runs and what leaves your machine.
+
+This is the same "source-available SDK, proprietary service" model Stripe,
+Snowflake, and Anthropic use: the encoding algorithm runs server-side and is
+patent-pending (#63/994,075), but everything in this repo is yours to read.
+See [LICENSE](LICENSE) and [LICENSE-FAQ](LICENSE-FAQ.md) for terms.
 
 **Patent pending.** Application #63/994,075.
 
@@ -527,7 +538,7 @@ for terms and common questions.
 
 Built by **Jeff Murray** ([@jmurray10](https://github.com/jmurray10)).
 
-- Email: **jeffmurr@seas.upenn.edu**
+- Email: **jeff.murray@alumni.upenn.edu**
 - LinkedIn: [linkedin.com/in/jeff-murray-ai](https://www.linkedin.com/in/jeff-murray-ai)
 - GitHub: [@jmurray10](https://github.com/jmurray10)
 - License inquiries, design partnerships, and YC/investor introductions: same email.

{semanticembed-0.7.3 → semanticembed-0.7.4}/README.md

@@ -3,13 +3,14 @@
 [![PyPI](https://img.shields.io/pypi/v/semanticembed.svg)](https://pypi.org/project/semanticembed/)
 [![Python](https://img.shields.io/pypi/pyversions/semanticembed.svg)](https://pypi.org/project/semanticembed/)
 [![CI](https://github.com/jmurray10/semanticembed-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/jmurray10/semanticembed-sdk/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-source--available-blue.svg)](LICENSE-FAQ.md)
+[![Free tier](https://img.shields.io/badge/free%20tier-50%20nodes%2C%20no%20signup-brightgreen.svg)](#install)
 [![Patent Pending](https://img.shields.io/badge/patent-%2363%2F994%2C075-orange.svg)](LICENSE-FAQ.md#patent)
 [![Changelog](https://img.shields.io/badge/changelog-current-success.svg)](CHANGELOG.md)
 
-**Structural risk for directed graphs — especially AI agent pipelines.** Six numbers per node. Sub-millisecond.
+**Structural risk for directed graphs — especially AI agent pipelines.** Six numbers per node. Sub-millisecond server-side compute.
 
-SemanticEmbed computes a 6-dimensional structural encoding for every node in a directed graph. From a bare edge list — no runtime telemetry, no historical data, no tuning — it produces six independent measurements that fully describe each node's structural role.
+SemanticEmbed computes a 6-dimensional structural encoding for every node in a directed graph. From a bare edge list — no runtime telemetry, no historical data, no tuning — it produces six complementary measurements that capture distinct aspects of each node's structural role (depth, lateral redundancy, community, throughput, path criticality, broadcast vs aggregation).
 
 **Designed for the topologies traditional observability misses:**
 
@@ -18,8 +19,8 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 - **CI/CD and data pipelines** — build graph fragility, ETL bottlenecks, drift gates
 
 > **Live demos:**
-> - **[Hugging Face Space](https://huggingface.co/spaces/jmurray10/semanticembed-agent-risk)** — paste a LangGraph / CrewAI / AutoGen file, get the encoding + risk findings (zero install, ML-researcher framing).
-> - **[Demo dashboard](https://semanticembed-dashboard.vercel.app/)** — Vercel-hosted demo with the 4 reference apps + interactive 6D explorer (auth required).
+> - **[Hugging Face Space](https://huggingface.co/spaces/jmurray10/semanticembed-agent-risk)** — zero-install. Paste a LangGraph / CrewAI / AutoGen file, get the encoding + risk findings.
+> - **[Demo dashboard](https://semanticembed-dashboard.vercel.app/)** — interactive 6D explorer with 4 reference apps (sign-in required; click "Try Demo" on the login page for a no-account walkthrough).
 
 > **Validated against production incidents.** In a blind test against a live production Dynatrace environment (108 services, 569 topology-relevant incidents over 30 days), **79.6%** of incidents (453/569) occurred on nodes that 6D structural analysis had flagged as risky — from the call graph alone, before any incident occurred. See [validation methodology](docs/validation_methodology.md).
 
@@ -30,7 +31,7 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 Observability tools tell you **what broke**. SemanticEmbed tells you **what will break** — from topology alone.
 
 - **No agents, no instrumentation** — just an edge list
-- **Sub-millisecond** — encodes 100+ node graphs in <1ms
+- **Sub-millisecond server-side compute** — the encoding kernel itself runs in <1 ms on a 100-node graph; full HTTP round-trip via the cloud API is typically 0.5–2 s including network
 - **Works on any directed graph** — AI agent pipelines, microservices, data workflows, CI/CD
 - **Complementary structural axes** — six dimensions, each captures risk signals the others cannot
 - **14 deterministic edge parsers + 3 live connectors** — go from real infra to encoded result in 2 lines
@@ -100,7 +101,7 @@ Runtime monitoring tells you what is slow **now**. Structural analysis tells you
 
 ## The Six Dimensions
 
-Every node gets six independent structural measurements:
+Every node gets six complementary structural measurements:
 
 | Dimension | What It Measures | Risk Signal |
 |-----------|-----------------|-------------|
@@ -111,9 +112,13 @@ Every node gets six independent structural measurements:
 | **Criticality** | Fraction of end-to-end paths depending on this node | High criticality = SPOF |
 | **Fanout** | Broadcaster (1.0) vs aggregator (0.0) | High fanout = amplification risk |
 
-These six properties capture complementary structural information. Each dimension provides risk signals the others cannot.
+These six properties capture complementary structural information. The
+risk patterns documented below combine specific axes; no single axis is a
+complete risk signal on its own.
 
-See [docs/dimensions.md](docs/dimensions.md) for the full reference.
+See [docs/dimensions.md](docs/dimensions.md) for axis definitions, the
+formal invariance properties of the encoding, and the empirical
+correlation results vs standard graph centrality.
 
 ---
 
@@ -131,6 +136,7 @@ See [docs/dimensions.md](docs/dimensions.md) for the full reference.
 
 ## What's new in v0.7
 
+- **Modern AutoGen patterns + lenient edge parser + better error messages** (v0.7.3)
 - **`live.from_dynatrace` / `from_honeycomb` / `from_datadog`** — pull real call edges from running infra (v0.5–v0.7)
 - **OpenTelemetry trace ingestion** — auto-detects OTLP / Jaeger / Zipkin (v0.3)
 - **AI agent framework parsers** — `from_langgraph`, `from_crewai`, `from_autogen`, AST-only, no need to install the framework (v0.4)
@@ -159,6 +165,7 @@ Step-by-step Colab notebooks. Click to open, run in your browser.
 | [06 - CI/CD & Data Pipelines](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/06_cicd_pipelines.ipynb) | CI/CD & ETL | Build graph fragility, pipeline bottlenecks, drift gates |
 | [07 - OpenTelemetry](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/07_opentelemetry.ipynb) | OTel traces | Extract edges from traces, structural analysis, CI/CD gates |
 | [08 - Qwen Compression](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/08_qwen_compression.ipynb) | LLM compression | Structural pruning of Qwen2.5-7B, 10% speedup at Grade A |
+| [09 - Quantum Reachability (IBM Q free tier)](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/09_quantum_reachability.ipynb) | Quantum cross-validation | Continuous-time quantum walk on a directed graph, run on IBM Q Open Plan, cross-checked vs SDK criticality |
 
 ---
 
@@ -472,11 +479,15 @@ See [docs/input_format.md](docs/input_format.md) for the full spec.
 
 ## License
 
-SemanticEmbed SDK is **proprietary software with public source code** —
-the same model Stripe, Snowflake, and Anthropic use for their SDKs. Free
-tier covers graphs up to 50 nodes; paid tier unlocks larger graphs and
-continuous monitoring. See [LICENSE](LICENSE) and [LICENSE-FAQ](LICENSE-FAQ.md)
-for terms and common questions.
+**Source-available, with a free tier — no signup, no credit card.** The free
+tier encodes graphs up to 50 nodes; the paid tier unlocks larger graphs and
+continuous monitoring. The client, parsers, and connectors in this repo are
+public source, so you can read exactly what runs and what leaves your machine.
+
+This is the same "source-available SDK, proprietary service" model Stripe,
+Snowflake, and Anthropic use: the encoding algorithm runs server-side and is
+patent-pending (#63/994,075), but everything in this repo is yours to read.
+See [LICENSE](LICENSE) and [LICENSE-FAQ](LICENSE-FAQ.md) for terms.
 
 **Patent pending.** Application #63/994,075.
 
@@ -486,7 +497,7 @@ for terms and common questions.
 
 Built by **Jeff Murray** ([@jmurray10](https://github.com/jmurray10)).
 
-- Email: **jeffmurr@seas.upenn.edu**
+- Email: **jeff.murray@alumni.upenn.edu**
 - LinkedIn: [linkedin.com/in/jeff-murray-ai](https://www.linkedin.com/in/jeff-murray-ai)
 - GitHub: [@jmurray10](https://github.com/jmurray10)
 - License inquiries, design partnerships, and YC/investor introductions: same email.

{semanticembed-0.7.3 → semanticembed-0.7.4}/SECURITY.md

@@ -3,7 +3,7 @@
 ## Reporting a vulnerability
 
 If you find a security issue in the SemanticEmbed SDK, please **do not**
-open a public GitHub issue. Email **jeffmurr@seas.upenn.edu** with:
+open a public GitHub issue. Email **jeff.murray@alumni.upenn.edu** with:
 
 - A description of the issue
 - Steps to reproduce (minimum working example)

semanticembed-0.7.4/docs/dimensions.md

@@ -0,0 +1,170 @@
+# The Six Dimensions
+
+SemanticEmbed computes six complementary structural measurements for every node in a directed graph. Together, these six numbers form a coordinate vector in 6-dimensional Euclidean space that summarizes the node's structural role under the invariance properties documented [below](#what-the-encoding-preserves).
+
+---
+
+## Overview
+
+| # | Dimension | What It Measures | Range |
+|---|-----------|-----------------|-------|
+| 1 | **Depth** | Position in the execution pipeline | 0.0 -- 1.0 |
+| 2 | **Independence** | Lateral redundancy at the same stage | 0.0 -- 1.0 |
+| 3 | **Hierarchy** | Module or group membership | 0.0 -- 1.0 |
+| 4 | **Throughput** | Fraction of total traffic through this node | 0.0 -- 1.0 |
+| 5 | **Criticality** | Fraction of end-to-end paths depending on this node | 0.0 -- 1.0 |
+| 6 | **Fanout** | Broadcaster (1.0) vs aggregator (0.0) | 0.0 -- 1.0 |
+
+---
+
+## Depth
+
+Where a node sits in the execution pipeline. Entry points are 0.0, deepest sinks are 1.0.
+
+A failure at low depth cascades forward through more of the graph. A failure at high depth has limited downstream impact.
+
+---
+
+## Independence
+
+How many other nodes operate at the same pipeline stage. Measures lateral redundancy.
+
+A node with independence 0.0 is the only node at its depth level -- a structural chokepoint. A node with high independence has many parallel peers.
+
+**Empirically low correlation with standard graph centrality.** On a benchmark
+of 4 reference topologies (Online Boutique, Sock Shop, AI agent pipeline,
+CI/CD pipeline), Independence shows |r| < 0.15 against degree, betweenness,
+closeness, and eigenvector centrality. Lateral redundancy is a structural
+feature most centrality measures don't model directly; it's captured here as
+a first-class axis. (The benchmark and correlation table are reproducible
+from `examples/` plus the SDK's `extract.from_directory()`.)
+
+---
+
+## Hierarchy
+
+Which module, community, or logical group a node belongs to. Computed via Louvain community detection on the undirected graph.
+
+Nodes in the same community have similar hierarchy values. Cross-community dependencies show up as connections between nodes with different hierarchy values -- these are integration risk points. Independent of depth: nodes at the same pipeline stage can belong to different modules.
+
+---
+
+## Throughput
+
+What fraction of total traffic flows through this node, based on connectivity relative to the graph.
+
+Independent of depth: a deep node can have high or low throughput. High throughput combined with low independence indicates a hidden bottleneck.
+
+---
+
+## Criticality
+
+How many end-to-end paths through the graph depend on this node.
+
+A node with criticality 0.5 sits on half of all source-to-sink paths. If it fails, half of all end-to-end flows break. Independent of throughput: a low-traffic node can be highly critical if it bridges two large subgraphs.
+
+---
+
+## Fanout
+
+Whether a node amplifies (broadcasts to many downstream) or aggregates (collects from many upstream).
+
+High fanout = amplification risk. A failure here multiplies across all downstream dependents. Low fanout = convergence sink. Many upstream services depend on this single point.
+
+---
+
+## What the encoding preserves
+
+The encoding map `f: G → R^(|V|×6)` (where `G` is a directed graph and the
+output is a 6-tuple per vertex) has the following invariance properties.
+These are stated formally so the algorithm's claims can be checked rather
+than trusted:
+
+1. **Vertex-isomorphism invariance.** Let `G = (V, E)` and `G' = (V', E')`
+   with a bijection `π: V → V'` such that `(u, v) ∈ E ⇔ (π(u), π(v)) ∈ E'`.
+   Then `f(G)[v] = f(G')[π(v)]` for every `v ∈ V`. Two graphs that differ
+   only by node-relabeling produce identical 6D fingerprints (after the
+   corresponding relabeling). **Sketch:** each axis is computed from
+   structural quantities (topological depth, BFS-derived path counts,
+   Louvain community indices, edge-weight aggregates) that are themselves
+   defined modulo isomorphism. *Caveat:* the **independence** axis uses
+   lexicographic ordering of nodes within a depth layer for determinism,
+   which means renaming can shift the independence value within a layer
+   even though the underlying lateral-redundancy structure is unchanged.
+   This is a known limitation tracked for a future release.
+
+2. **Self-loop and back-edge invariance.** Self-loops are silently dropped
+   during edge normalization. Back-edges are removed by Kahn's DAG
+   enforcement before any axis is computed. Adding or removing a self-loop
+   or a single back-edge that doesn't change the DAG topology produces an
+   identical encoding.
+
+3. **Locality.** Two nodes that share `(in_neighbors, out_neighbors)`
+   structure within a 2-hop neighborhood produce 6D vectors that differ
+   by at most ε on the first five axes (depth / independence / hierarchy /
+   throughput / criticality). Hierarchy can change discretely if Louvain
+   assigns the nodes to different communities. This is observed
+   empirically across the 4 benchmark topologies; not yet proved formally.
+
+**What the encoding does NOT preserve:**
+
+- **Edge weights for axes other than throughput.** Depth, independence,
+  hierarchy, criticality, and fanout treat all edges equally. Throughput
+  is the only weight-sensitive axis.
+- **Backward-information.** Once the DAG is enforced, the back-edges
+  removed are not represented anywhere in the encoding. A graph with
+  cycles and its acyclic closure produce the same encoding.
+- **Semantic labels.** Node names are used only for identity and
+  ordering. The encoding is invariant under content-preserving renames
+  (per property 1).
+
+The encoding is **not** a lossless representation of `G`. It is a
+6-dimensional summary chosen to capture properties that empirically
+predict structural risk; the [validation methodology](validation_methodology.md)
+documents that empirical claim.
+
+---
+
+## Why six dimensions
+
+The six axes are the result of a design choice: each captures a structural
+property that informs at least one of the [risk patterns below](#structural-risk-patterns).
+We tested 7- and 8-axis variants during development and found:
+
+- A 7th axis (we tried "edge betweenness sum") was strongly correlated
+  (`r > 0.8`) with the existing throughput axis on the benchmark topologies
+  and didn't improve risk-prediction quality measurably.
+- An 8th axis (we tried "spectral gap of the local subgraph") added compute
+  cost without a measurable lift on the same benchmark.
+
+This is **not** a claim that 6 is the canonical dimensionality of
+directed-computational-graph structure — it's the empirical sweet spot
+under the design constraints (sub-millisecond compute, interpretable
+axes, distinct risk-pattern coverage). A different objective function
+might justify a different dimensionality.
+
+---
+
+## Why the dimensions are useful together
+
+- A deep node can have high or low throughput — depth and throughput
+  measure different things
+- A high-traffic node can sit on one path or many paths — throughput and
+  criticality measure different things
+- A node at any depth / throughput / criticality can be a broadcaster
+  (high fanout) or aggregator (low fanout)
+- Independence has empirically low correlation with standard centrality
+  measures — see the Independence section above for the benchmark
+- Hierarchy (community membership) is empirically uncorrelated with
+  pipeline position
+
+---
+
+## Structural Risk Patterns
+
+| Pattern | Dimensions | Risk |
+|---------|-----------|------|
+| **Amplification risk** | High fanout + high criticality | Failure cascades to many services across many paths |
+| **Convergence sink** | Low independence + low fanout | Many services depend on one aggregation point |
+| **Structural SPOF** | Low independence + high criticality | Only node at its depth, on most paths |
+| **Hidden bottleneck** | High throughput + low independence | Carries most traffic with no redundancy |

{semanticembed-0.7.3 → semanticembed-0.7.4}/docs/getting_started.md

@@ -245,7 +245,7 @@ Or via environment variable:
 export SEMANTICEMBED_LICENSE_KEY=se-xxxxxxxxxxxxxxxxxxxx
 ```
 
-Contact jeffmurr@seas.upenn.edu for license keys.
+Contact jeff.murray@alumni.upenn.edu for license keys.
 
 ---
 

{semanticembed-0.7.3 → semanticembed-0.7.4}/docs/license_keys.md

@@ -6,7 +6,7 @@ The SemanticEmbed SDK is free for graphs up to 50 nodes. For larger graphs, acti
 
 ## Get a License Key
 
-Email jeffmurr@seas.upenn.edu with your use case and expected node count.
+Email jeff.murray@alumni.upenn.edu with your use case and expected node count.
 Public pricing page coming soon.
 
 ---
@@ -50,4 +50,4 @@ Enterprise plans include priority support, SLA, and on-prem deployment options.
 
 ## Questions
 
-Email jeffmurr@seas.upenn.edu.
+Email jeff.murray@alumni.upenn.edu.

{semanticembed-0.7.3 → semanticembed-0.7.4}/docs/validation_methodology.md

@@ -157,7 +157,7 @@ publicly available tools:
    a sanity check.
 
 We're glad to walk a design partner through this on their own data;
-email **jeffmurr@seas.upenn.edu** with `[validation]` in the subject.
+email **jeff.murray@alumni.upenn.edu** with `[validation]` in the subject.
 
 ---
 
@@ -194,5 +194,5 @@ documented above and reproducible end-to-end with this SDK.
 
 ## Questions
 
-Email **jeffmurr@seas.upenn.edu** — happy to walk through the design or
+Email **jeff.murray@alumni.upenn.edu** — happy to walk through the design or
 run a similar experiment on your data.