semanticembed 0.2.0__tar.gz → 0.2.1__tar.gz

{semanticembed-0.2.0 → semanticembed-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semanticembed
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -32,8 +32,6 @@ Requires-Dist: google-genai; extra == 'all'
 Requires-Dist: pyyaml>=6.0; extra == 'all'
 Provides-Extra: extract
 Requires-Dist: pyyaml>=6.0; extra == 'extract'
-Provides-Extra: llm
-Requires-Dist: httpx>=0.24; extra == 'llm'
 Description-Content-Type: text/markdown
 
 # SemanticEmbed SDK

{semanticembed-0.2.0 → semanticembed-0.2.1}/docs/api_reference.md

@@ -6,7 +6,7 @@ Complete reference for the `semanticembed` Python SDK.
 
 ## Functions
 
-### `encode(edges, *, license_key=None, api_url=None, timeout=30.0)`
+### `encode(edges, *, license_key=None, api_url=None, timeout=60.0)`
 
 Encode a directed graph and return 6D structural coordinates.
 

{semanticembed-0.2.0 → semanticembed-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "semanticembed"
-version = "0.2.0"
+version = "0.2.1"
 description = "6D structural intelligence for directed graphs. Six numbers per node. Sub-millisecond."
 readme = "README.md"
 license = {text = "Proprietary"}
@@ -30,7 +30,6 @@ dependencies = [
 
 [project.optional-dependencies]
 extract = ["pyyaml>=6.0"]
-llm = ["httpx>=0.24"]
 agent-claude = ["claude-agent-sdk", "pyyaml>=6.0"]
 agent-gemini = ["google-genai", "pyyaml>=6.0"]
 all = ["pyyaml>=6.0", "claude-agent-sdk", "google-genai"]

semanticembed-0.2.1/skill/SETUP.md

@@ -0,0 +1,59 @@
+# Setup Guide
+
+Two dependencies. That's it.
+
+## 1. SemanticEmbed SDK
+
+```bash
+pip install semanticembed
+```
+
+Optional -- set your license key to unlock graphs with more than 50 nodes:
+```bash
+export SEMANTICEMBED_LICENSE_KEY=se-xxxxxxxxxxxxxxxxxxxx
+```
+
+Add to your shell profile to persist:
+```bash
+echo 'export SEMANTICEMBED_LICENSE_KEY=se-xxxx' >> ~/.zshrc
+```
+
+## 2. Ollama with Gemma 4
+
+Install Ollama: https://ollama.com/download
+
+```bash
+ollama serve
+ollama pull gemma4    # ~16GB, one-time download
+```
+
+Verify:
+```bash
+ollama list
+# gemma4    ...
+```
+
+## Optional environment variables
+
+```bash
+export SEMBED_OLLAMA_URL=http://localhost:11434   # if Ollama is on another host
+export SEMBED_MODEL=gemma4                        # to use a different model
+```
+
+## Verify everything works
+
+```bash
+python3 -c "
+import semanticembed
+result = semanticembed.encode([('a','b'),('b','c')])
+print('SDK OK -- encoding in', result.encoding_time_ms, 'ms')
+"
+```
+
+```bash
+curl -s http://localhost:11434/api/tags | python3 -c "
+import sys, json
+models = json.load(sys.stdin).get('models', [])
+print('Ollama OK --', [m['name'] for m in models])
+"
+```

semanticembed-0.2.1/skill/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: semanticembed
+description: >
+  Run 6D structural analysis on any directed graph -- microservice architectures,
+  AI agent pipelines, CI/CD graphs, data workflows. Use this skill whenever the
+  user wants to understand structural risk, find single points of failure,
+  detect bottlenecks, analyze vendor concentration, or compare two architecture
+  versions. Triggers on: "analyze my pipeline", "find bottlenecks", "which node
+  is the SPOF", "structural analysis", "6D encoding", or when the user describes
+  a system with nodes and connections and wants to understand fragility. Accepts
+  plain English descriptions, source code (LangGraph, CrewAI, Prefect, YAML),
+  or OpenTelemetry trace JSON.
+license: Proprietary. See LICENSE.txt for complete terms.
+compatibility: Requires pip install semanticembed and ollama with gemma4 pulled.
+metadata:
+  author: SemanticEmbed
+  version: "0.1.0"
+  patent: "Pending -- Application #63/994,075"
+allowed-tools: Bash(python3:*) Bash(pip:*) Bash(ollama:*)
+---
+
+# SemanticEmbed 6D Structural Analysis
+
+Analyze directed graphs for structural risk using the SemanticEmbed 6D encoding.
+Computes six structural dimensions per node (depth, independence, hierarchy,
+throughput, criticality, fanout) and identifies SPOFs, bottlenecks, and cascade
+amplification risks from topology alone. No runtime telemetry required.
+
+Two dependencies only:
+- `semanticembed` Python SDK -- calls Railway for encoding (algorithm server-side)
+- `ollama` with `gemma4` -- handles edge extraction and narrative locally
+
+## Step 1: Check dependencies
+
+```bash
+python3 -c "import semanticembed; print('SDK OK')" 2>/dev/null || pip install semanticembed
+python3 -c "import httpx; print('httpx OK')" 2>/dev/null || pip install httpx
+ollama list 2>/dev/null | grep -q gemma4 || ollama pull gemma4
+```
+
+If the license key is set, unlimited nodes are available:
+```bash
+echo $SEMANTICEMBED_LICENSE_KEY   # should be non-empty for production use
+```
+
+## Step 2: Determine input type
+
+| What the user provides | `--type` |
+|------------------------|----------|
+| Plain English description | `text` |
+| Python/YAML/JSON source file | `code` |
+| OpenTelemetry trace JSON | `trace` |
+| Raw edge list | `text` |
+
+## Step 3: Run the analysis
+
+The script is at `scripts/analyze.py` relative to this skill file.
+Always use the absolute path resolved from this skill's location.
+
+**Text description:**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input "supervisor calls planner-agent and research-agent. Both call openai-gpt4." \
+  --type text
+```
+
+**Code file:**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input /path/to/pipeline.py \
+  --type code
+```
+
+**OTel trace:**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input /path/to/trace.json \
+  --type trace
+```
+
+**JSON output (for programmatic use):**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input "..." --type text --json
+```
+
+**Fast mode (no narrative):**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input "..." --type text --no-narrative
+```
+
+**Edge extraction only (preview before encoding):**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --input "..." --type text --edges-only
+```
+
+**Drift detection (before vs after):**
+```bash
+python3 {SKILL_DIR}/scripts/analyze.py \
+  --type text \
+  --before "original architecture description" \
+  --after  "updated architecture description"
+```
+
+## Step 4: Present results to the user
+
+Always show:
+1. The extracted edge list -- let the user confirm the graph was parsed correctly
+2. Risk flags grouped by severity
+3. The 6D table sorted by criticality
+4. The narrative report
+
+**Risk severity markers in output:**
+- `!!!` = critical (SPOF, criticality > 0.08)
+- `!! ` = high (bottleneck, amplifier, concentration)
+- `!  ` = medium (deep dependency)
+
+**What each flag means:**
+
+| Flag | Meaning | Action |
+|------|---------|--------|
+| SPOF | One node on most paths -- single point of failure | Add fallback / redundant path |
+| BOTTLENECK | Throughput concentrated here | Split into parallel workers |
+| AMPLIFIER | Failure fans to many downstream nodes | Add circuit breaker upstream |
+| CONCENTRATION | Zero lateral redundancy | Add alternative path |
+| DEEP | Late-stage, hard to recover from | Add health check / timeout |
+
+## Step 5: Suggest fixes
+
+After presenting risks, always offer concrete next steps. Example:
+
+> "The `openai_gpt4` node has criticality=0.44, meaning it sits on 44% of all
+> paths through this pipeline. Adding a fallback to a second provider (e.g.
+> `anthropic_claude`) would reduce its criticality score. Want me to show you
+> what that would look like structurally?"
+
+Then offer to re-run with the proposed change to show the drift.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `SEMBED_OLLAMA_URL` | `http://localhost:11434` | Ollama instance URL |
+| `SEMBED_MODEL` | `gemma4` | Model name |
+| `SEMANTICEMBED_LICENSE_KEY` | (none) | Unlocks >50 nodes |
+
+## Example interactions
+
+**"Analyze my LangGraph pipeline"**
+→ Ask for the file path, run with `--type code`
+
+**"Which service is my biggest SPOF?"**
+→ Ask for edge list or description, run with `--type text`, highlight highest criticality node
+
+**"I added a fallback -- did it help?"**
+→ Get before/after descriptions, run with `--before` and `--after` flags, show drift
+
+**"6D encode this: A->B, B->C, A->C"**
+→ Run with `--type text --no-narrative` for fast vector output
+
+See [references/DRIFT.md](references/DRIFT.md) for detailed drift analysis guidance.
+See [references/SETUP.md](references/SETUP.md) if dependencies are missing.

{semanticembed-0.2.0 → semanticembed-0.2.1}/src/semanticembed/__init__.py

@@ -14,7 +14,7 @@ from .exceptions import (
 from . import extract
 from .explain import explain, ask
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 # Set this to your license key to unlock unlimited nodes:
 #   import semanticembed

{semanticembed-0.2.0 → semanticembed-0.2.1}/src/semanticembed/client.py

@@ -192,7 +192,7 @@ def encode_file(
     *,
     license_key: str | None = None,
     api_url: str | None = None,
-    timeout: float = 30.0,
+    timeout: float = 60.0,
 ) -> SemanticResult:
     """Encode a graph from a JSON file.