semanticembed 0.7.0__tar.gz → 0.7.1__tar.gz

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

@@ -2,6 +2,16 @@
 
 All notable changes to the SemanticEmbed SDK.
 
+## 0.7.1 — Async surface
+
+- New: `aencode`, `aencode_file`, `aencode_diff` — async siblings of the
+  sync versions. Same preflight node-count guard, retry-once-on-5xx, and
+  optional in-process cache.
+- Cache is **shared** across sync + async: a sync `encode(edges, cache=True)`
+  followed by `await aencode(edges, cache=True)` hits the same entry.
+- `aencode_diff` issues both encodes in parallel via `asyncio.gather`.
+- Useful for FastAPI / Celery / event-loop integrations.
+
 ## 0.7.0 — Honeycomb + Datadog live connectors
 
 - New: `semanticembed.live.from_honeycomb(dataset, api_key)` — runs a

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semanticembed
-Version: 0.7.0
+Version: 0.7.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

{semanticembed-0.7.0 → semanticembed-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "semanticembed"
-version = "0.7.0"
+version = "0.7.1"
 description = "6D structural intelligence for directed graphs. Six numbers per node. Sub-millisecond."
 readme = "README.md"
 license = {text = "Proprietary"}

{semanticembed-0.7.0 → semanticembed-0.7.1}/src/semanticembed/__init__.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
-from .client import encode, encode_file, report, drift, encode_diff, clear_encode_cache
+from .client import (
+    encode, encode_file, report, drift, encode_diff,
+    aencode, aencode_file, aencode_diff,
+    clear_encode_cache,
+)
 from .models import SemanticResult, RiskReport, RiskEntry, DIMENSION_NAMES
 from .exceptions import (
     SemanticEmbedError,
@@ -17,7 +21,7 @@ from .dedupe import dedupe_edges
 from .explain import explain, ask
 from .find_edges import find_edges
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 # Set this to your license key to unlock unlimited nodes:
 #   import semanticembed
@@ -28,6 +32,9 @@ __all__ = [
     "encode",
     "encode_file",
     "encode_diff",
+    "aencode",
+    "aencode_file",
+    "aencode_diff",
     "report",
     "drift",
     "explain",

{semanticembed-0.7.0 → semanticembed-0.7.1}/src/semanticembed/client.py

@@ -373,3 +373,170 @@ def encode_diff(
     result_after = encode(edges_after, license_key=license_key,
                           api_url=api_url, timeout=timeout)
     return drift(result_before, result_after, detail=detail)
+
+
+# ---------------------------------------------------------------------------
+# Async surface
+# ---------------------------------------------------------------------------
+#
+# `aencode` / `aencode_file` / `aencode_diff` mirror the sync versions:
+# same preflight node-count guard, same retry-once-on-5xx logic, same
+# in-process LRU cache (shared with the sync side -- a sync encode and a
+# subsequent async aencode of the same edges hit the same cache entry).
+
+
+async def _apost_with_retry(
+    url: str,
+    headers: dict[str, str],
+    payload: dict,
+    timeout: float,
+) -> httpx.Response:
+    """Async sibling of _post_with_retry. One retry on 502/503/504/ConnectError/ReadTimeout."""
+    import asyncio
+
+    last_exc: Exception | None = None
+    for attempt in range(2):
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.post(
+                    f"{url}/api/v1/encode", headers=headers, json=payload
+                )
+            if resp.status_code in _RETRYABLE_STATUS and attempt == 0:
+                await asyncio.sleep(_RETRY_BACKOFF_SECONDS)
+                continue
+            return resp
+        except (httpx.ConnectError, httpx.ReadTimeout) as e:
+            last_exc = e
+            if attempt == 0:
+                await asyncio.sleep(_RETRY_BACKOFF_SECONDS)
+                continue
+            raise SemanticConnectionError(
+                f"Could not connect to SemanticEmbed API at {url} after retry: {e}"
+            ) from e
+    if last_exc is not None:
+        raise SemanticConnectionError(
+            f"Could not connect to SemanticEmbed API at {url}: {last_exc}"
+        ) from last_exc
+    return resp  # last 5xx response
+
+
+async def aencode(
+    edges: list,
+    *,
+    license_key: str | None = None,
+    api_url: str | None = None,
+    timeout: float = 60.0,
+    cache: bool = False,
+) -> SemanticResult:
+    """Async version of :func:`encode`.
+
+    Identical semantics — preflight node guard, retry-on-5xx, optional
+    cache (shared with the sync ``encode``). Useful inside FastAPI
+    handlers, asyncio task groups, or any event-loop context.
+
+    Example::
+
+        import asyncio, semanticembed as se
+
+        async def main():
+            result = await se.aencode([("a", "b"), ("b", "c")], cache=True)
+            print(result.table)
+
+        asyncio.run(main())
+    """
+    normalized = _normalize_edges(edges)
+    if len(normalized) < 2:
+        raise ValueError("Graph must have at least 2 edges.")
+
+    if cache:
+        cache_key = _encode_cache_key(normalized)
+        hit = _cache_get(cache_key)
+        if hit is not None:
+            return hit
+
+    key = _resolve_key(license_key)
+    url = (api_url or os.environ.get("SEMANTICEMBED_API_URL") or DEFAULT_API_URL).rstrip("/")
+
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if key:
+        headers["X-API-Key"] = key
+
+    node_set: set[str] = set()
+    for e in normalized:
+        node_set.add(e[0])
+        node_set.add(e[1])
+    n_nodes = len(node_set)
+    if not key and n_nodes > FREE_TIER_LIMIT:
+        raise NodeLimitError(n_nodes, FREE_TIER_LIMIT)
+    if not key and n_nodes > FREE_TIER_LIMIT * 0.8:
+        import warnings
+        warnings.warn(
+            f"Graph has {n_nodes}/{FREE_TIER_LIMIT} free tier nodes. "
+            f"Set a license key to avoid hitting the limit.",
+            stacklevel=2,
+        )
+
+    payload = {"edges": normalized}
+    start = time.perf_counter()
+    resp = await _apost_with_retry(url, headers, payload, timeout)
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if resp.status_code == 401:
+        raise AuthenticationError(
+            "Invalid API key. Check your license key or contact jeffmurr@seas.upenn.edu"
+        )
+    if resp.status_code == 403:
+        import re as _re
+        detail = resp.text[:300]
+        match = _re.search(r"(\d+) nodes.*limit.*?(\d+)", detail)
+        if match:
+            raise NodeLimitError(int(match.group(1)), int(match.group(2)))
+        raise NodeLimitError(n_nodes, FREE_TIER_LIMIT)
+    if resp.status_code >= 400:
+        raise APIError(resp.status_code, resp.text[:200])
+
+    result = _parse_response(resp.json(), elapsed_ms)
+    if cache:
+        _cache_put(cache_key, result)
+    return result
+
+
+async def aencode_file(
+    path: str,
+    *,
+    license_key: str | None = None,
+    api_url: str | None = None,
+    timeout: float = 60.0,
+    cache: bool = False,
+) -> SemanticResult:
+    """Async version of :func:`encode_file`."""
+    import json
+
+    with open(path) as f:
+        data = json.load(f)
+    edges = data.get("edges", data) if isinstance(data, dict) else data
+    return await aencode(
+        edges, license_key=license_key, api_url=api_url, timeout=timeout, cache=cache
+    )
+
+
+async def aencode_diff(
+    edges_before: list,
+    edges_after: list,
+    *,
+    detail: bool = True,
+    license_key: str | None = None,
+    api_url: str | None = None,
+    timeout: float = 60.0,
+    cache: bool = False,
+) -> dict[str, dict[str, dict[str, float]]]:
+    """Async version of :func:`encode_diff`. Issues both encodes in parallel."""
+    import asyncio
+
+    before_t, after_t = await asyncio.gather(
+        aencode(edges_before, license_key=license_key, api_url=api_url,
+                timeout=timeout, cache=cache),
+        aencode(edges_after, license_key=license_key, api_url=api_url,
+                timeout=timeout, cache=cache),
+    )
+    return drift(before_t, after_t, detail=detail)

semanticembed-0.7.1/tests/test_aclient.py

@@ -0,0 +1,170 @@
+"""Tests for the async surface: aencode, aencode_file, aencode_diff.
+
+Mirrors the sync test cases — preflight, retry-once, cache, error paths.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+
+import semanticembed as se
+from semanticembed.client import DEFAULT_API_URL, FREE_TIER_LIMIT
+from semanticembed.exceptions import (
+    AuthenticationError,
+    NodeLimitError,
+    SemanticConnectionError,
+)
+
+
+VALID_BODY = {
+    "embeddings": {
+        "a": {"depth": 0.0, "independence": 0.5, "hierarchy": 0.5,
+              "throughput": 0.5, "criticality": 0.5, "fanout": 1.0},
+        "b": {"depth": 0.5, "independence": 0.5, "hierarchy": 0.5,
+              "throughput": 0.5, "criticality": 0.5, "fanout": 0.5},
+        "c": {"depth": 1.0, "independence": 0.5, "hierarchy": 0.5,
+              "throughput": 0.5, "criticality": 0.5, "fanout": 0.0},
+    },
+    "risks": [],
+    "fingerprint": {},
+    "metadata": {"n_nodes": 3, "n_edges": 2, "max_depth": 2},
+}
+
+SAMPLE_EDGES = [["a", "b"], ["b", "c"]]
+
+
+@pytest.fixture(autouse=True)
+def _reset(monkeypatch):
+    se.license_key = None
+    se.clear_encode_cache()
+    monkeypatch.delenv("SEMANTICEMBED_LICENSE_KEY", raising=False)
+    monkeypatch.delenv("SEMANTICEMBED_API_KEY", raising=False)
+    monkeypatch.delenv("SEMANTICEMBED_API_URL", raising=False)
+    yield
+    se.license_key = None
+    se.clear_encode_cache()
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+class TestAencodeHappyPath:
+    @respx.mock
+    def test_returns_result(self):
+        respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(200, json=VALID_BODY)
+        )
+        result = _run(se.aencode(SAMPLE_EDGES))
+        assert set(result.vectors.keys()) == {"a", "b", "c"}
+        assert result.graph_info["nodes"] == 3
+
+
+class TestAencodePreflight:
+    def test_free_tier_preflight_skips_http(self):
+        edges = [[f"n{i}", f"n{i+1}"] for i in range(59)]  # 60 nodes
+        with respx.mock:
+            route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+                return_value=httpx.Response(200, json=VALID_BODY)
+            )
+            with pytest.raises(NodeLimitError) as ei:
+                _run(se.aencode(edges))
+            assert route.call_count == 0
+        assert ei.value.n_nodes == 60
+
+
+class TestAencodeRetry:
+    @respx.mock
+    def test_retries_once_on_503(self):
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            side_effect=[
+                httpx.Response(503, text="upstream"),
+                httpx.Response(200, json=VALID_BODY),
+            ]
+        )
+        result = _run(se.aencode(SAMPLE_EDGES))
+        assert route.call_count == 2
+        assert result is not None
+
+    @respx.mock
+    def test_retries_once_on_connect_error(self):
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            side_effect=[
+                httpx.ConnectError("dns fail"),
+                httpx.Response(200, json=VALID_BODY),
+            ]
+        )
+        result = _run(se.aencode(SAMPLE_EDGES))
+        assert route.call_count == 2
+        assert result is not None
+
+    @respx.mock
+    def test_does_not_retry_on_401(self):
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(401, text="invalid")
+        )
+        with pytest.raises(AuthenticationError):
+            _run(se.aencode(SAMPLE_EDGES, license_key="bad"))
+        assert route.call_count == 1
+
+
+class TestAencodeCache:
+    @respx.mock
+    def test_cache_hit_skips_http(self):
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(200, json=VALID_BODY)
+        )
+        r1 = _run(se.aencode(SAMPLE_EDGES, cache=True))
+        r2 = _run(se.aencode(SAMPLE_EDGES, cache=True))
+        assert route.call_count == 1
+        assert r1 is r2
+
+    @respx.mock
+    def test_async_and_sync_share_cache(self):
+        # Cache hit between sync encode -> async aencode (same edges).
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(200, json=VALID_BODY)
+        )
+        r1 = se.encode(SAMPLE_EDGES, cache=True)
+        r2 = _run(se.aencode(SAMPLE_EDGES, cache=True))
+        assert route.call_count == 1
+        assert r1 is r2
+
+
+class TestAencodeFile:
+    @respx.mock
+    def test_loads_from_json_file(self, tmp_path):
+        f = tmp_path / "g.json"
+        f.write_text(json.dumps({"edges": [["a", "b"], ["b", "c"]]}))
+        respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(200, json=VALID_BODY)
+        )
+        result = _run(se.aencode_file(str(f)))
+        assert set(result.vectors.keys()) == {"a", "b", "c"}
+
+
+class TestAencodeDiff:
+    @respx.mock
+    def test_runs_two_encodes_in_parallel_and_returns_drift(self):
+        route = respx.post(f"{DEFAULT_API_URL}/api/v1/encode").mock(
+            return_value=httpx.Response(200, json=VALID_BODY)
+        )
+        result = _run(se.aencode_diff(
+            [["a", "b"], ["b", "c"]],
+            [["a", "b"], ["b", "c"], ["a", "c"]],
+        ))
+        # Both encodes were issued.
+        assert route.call_count == 2
+        # Drift returns a dict (may be empty if identical embeddings, that's fine).
+        assert isinstance(result, dict)
+
+
+class TestAencodeRequestValidation:
+    def test_too_few_edges_raises(self):
+        with pytest.raises(ValueError, match="at least 2 edges"):
+            _run(se.aencode([["a", "b"]]))