confamnode 0.2.4__tar.gz → 0.2.6__tar.gz

{confamnode-0.2.4 → confamnode-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confamnode
-Version: 0.2.4
+Version: 0.2.6
 Summary: The Nigerian AI inference gateway
 Project-URL: Repository, https://github.com/confamnodeai/confamnode
 Project-URL: Bug Tracker, https://github.com/confamnodeai/confamnode/issues
@@ -258,7 +258,7 @@ ansa = client.gist(
 
 Caching is controlled **per request** and is **off by default** — every call returns a fresh response, even when the request is identical. This keeps data-generation loops and any workflow that resends the same prompt from getting the same cached answer back each time.
 
-Pass `cache=True` to read from and write to the cache — useful for idempotent lookups or to save cost on repeated queries:
+Pass `cache=True` to let the gateway serve and store a cached response — useful for idempotent lookups:
 
 ```python
 # Default — caching off, fresh response every call
@@ -267,8 +267,8 @@ ansa = client.gist(
     messages="How you dey?"
 )
 
-# Enable caching — use a stored response when the request matches,
-# and store this response for next time
+# Enable caching — the gateway may return a stored response for a
+# matching request, and store this one for next time
 ansa = client.gist(
     model="confam-speed",
     messages="How you dey?",
@@ -276,7 +276,7 @@ ansa = client.gist(
 )
 ```
 
-A cache hit is typically returned near-instantly and at little or no token cost — a quick way to confirm caching is active.
+Caching must be enabled for your account for `cache=True` to take effect. A cache hit returns near-instantly — the quickest way to see it is to send the **same** request twice with `cache=True`: the first call populates the cache, the second is served from it.
 
 ---
 

{confamnode-0.2.4 → confamnode-0.2.6}/README.md

@@ -234,7 +234,7 @@ ansa = client.gist(
 
 Caching is controlled **per request** and is **off by default** — every call returns a fresh response, even when the request is identical. This keeps data-generation loops and any workflow that resends the same prompt from getting the same cached answer back each time.
 
-Pass `cache=True` to read from and write to the cache — useful for idempotent lookups or to save cost on repeated queries:
+Pass `cache=True` to let the gateway serve and store a cached response — useful for idempotent lookups:
 
 ```python
 # Default — caching off, fresh response every call
@@ -243,8 +243,8 @@ ansa = client.gist(
     messages="How you dey?"
 )
 
-# Enable caching — use a stored response when the request matches,
-# and store this response for next time
+# Enable caching — the gateway may return a stored response for a
+# matching request, and store this one for next time
 ansa = client.gist(
     model="confam-speed",
     messages="How you dey?",
@@ -252,7 +252,7 @@ ansa = client.gist(
 )
 ```
 
-A cache hit is typically returned near-instantly and at little or no token cost — a quick way to confirm caching is active.
+Caching must be enabled for your account for `cache=True` to take effect. A cache hit returns near-instantly — the quickest way to see it is to send the **same** request twice with `cache=True`: the first call populates the cache, the second is served from it.
 
 ---
 

{confamnode-0.2.4 → confamnode-0.2.6}/confamnode/__init__.py

@@ -8,7 +8,7 @@ from confamnode.exceptions import (
 from confamnode.ansa import Ansa, Usage, Cost
 from confamnode import models
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 
 __all__ = [
     "ConfamNode",

{confamnode-0.2.4 → confamnode-0.2.6}/confamnode/client.py

@@ -61,20 +61,17 @@ class ConfamNode:
             else:
                 body["system"] = system # None or custom string
 
-        # Caching is controlled per request. By default the SDK opts OUT, so
-        # identical requests (same model + messages + system) each return a
+        # Caching is opt-in. By default the SDK sends an explicit cache-bypass,
+        # so identical requests (same model + messages + system) each return a
         # FRESH response -- important for data-generation loops that resend the
-        # same prompt expecting varied output. Pass cache=True to read from and
-        # write to the cache (idempotent lookups, cost savings on repeats).
+        # same prompt expecting varied output.
         #
-        # These flags only tell the gateway whether to use a cache for THIS
-        # request; whether one exists at all is a gateway-side capability.
-        if cache:
-            body["cache"] = {
-                "no-cache": False, # Cache the response
-                "no-store": False # Store the response
-            }
-        else:
+        # With cache=True we send NO cache field at all, letting the gateway
+        # apply its normal caching. That absent-field shape is exactly what
+        # produced cached responses before this flag existed, so it's the
+        # request form known to engage the cache -- more reliable than sending
+        # explicit "false" flags the gateway may not interpret identically.
+        if not cache:
             body["cache"] = {
                 "no-cache": True, # Skip cache check, get fresh response
                 "no-store": True # Don't cache this response

confamnode-0.2.6/confamnode/utils.py

@@ -0,0 +1,48 @@
+"""
+Small internal helpers shared across the confamnode client.
+"""
+
+
+import re
+
+
+def extract_error(response) -> str:
+    """
+    Best-effort error detail from a non-2xx response, WITHOUT raising.
+ 
+    The server's normal error shape is {"detail": "..."}, but gateway-level
+    errors (e.g. a 429 throttle, a 502/504 from a proxy, a 524 origin timeout)
+    often return an empty or non-JSON body. Calling response.json() directly on
+    those bodies raises JSONDecodeError and swallows the status code -- the one
+    thing the caller actually needs. So we parse defensively and always fall
+    back to something readable.
+ 
+    HTML error pages (Cloudflare, nginx, ...) are summarised to their <title>
+    rather than dumped in full, so error messages and logs stay readable.
+    """
+    # 1. Normal JSON error shape.
+    try:
+        payload = response.json()
+        if isinstance(payload, dict):
+            detail = payload.get("detail") or payload.get("error") or payload.get("message")
+            if detail:
+                return str(detail)
+    except Exception:
+        pass
+
+    text = (getattr(response, "text", "") or "").strip()
+    if not text:
+        return  "no response body"
+    
+    # 2. HTML error page: the full page is noise. Pull the <title>, which
+    #    carries the human-readable status (e.g. "524: A timeout occurred").
+    if "<html" in text[:200].lower() or "<!doctype html" in text[:200].lower():
+        m = re.search(r"<title[^>]*>(.*?)</title>", text, re.IGNORECASE | re.DOTALL)
+        if m:
+            title = re.sub(r"\s+", " ", m.group(1)).strip()
+            if title:
+                return title
+        return "HTML error page (no title)"
+    
+    # 3. Plain-text body: return it, truncated so we never dump a wall.
+    return text if len(text) <= 300 else text[:297] + "..."

{confamnode-0.2.4 → confamnode-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "confamnode"
-version = "0.2.4"
+version = "0.2.6"
 description = "The Nigerian AI inference gateway"
 readme = "README.md"
 requires-python = ">=3.10"

{confamnode-0.2.4 → confamnode-0.2.6}/tests/test_cache_flag.py

@@ -18,7 +18,6 @@ API_KEY = "confam-test"
 MODEL = next(iter(VALID_MODELS))
 
 CACHE_OFF = {"no-cache": True, "no-store": True}    # skip read + skip store
-CACHE_ON = {"no-cache": False, "no-store": False}   # use + store
 
 
 @pytest.fixture
@@ -55,20 +54,13 @@ def test_cache_off_by_default(captured_body):
     assert captured_body["body"]["cache"] == CACHE_OFF
 
 
-def test_cache_true_uses_and_stores(captured_body):
+def test_cache_true_omits_field(captured_body):
+    # cache=True lets the gateway apply its normal caching by sending NO cache
+    # field -- the request shape proven to engage the cache.
     _gist(cache=True)
-    assert captured_body["body"]["cache"] == CACHE_ON
+    assert "cache" not in captured_body["body"]
 
 
 def test_cache_false_is_explicit_off(captured_body):
     _gist(cache=False)
-    assert captured_body["body"]["cache"] == CACHE_OFF
-
-
-def test_cache_field_always_present(captured_body):
-    # The request should always state its caching intent in both directions,
-    # never leave it implied by omission.
-    _gist()
-    assert "cache" in captured_body["body"]
-    _gist(cache=True)
-    assert "cache" in captured_body["body"]
+    assert captured_body["body"]["cache"] == CACHE_OFF

{confamnode-0.2.4 → confamnode-0.2.6}/tests/test_client_errors.py

@@ -58,14 +58,20 @@ def test_json_detail_error_surfaces_detail(monkeypatch):
     assert "invalid model" in str(exc.value)
 
 
-def test_html_gateway_error_surfaces_text(monkeypatch):
-    _patch_post(monkeypatch, FakeResponse(502, json_raises=True,
-                                          text="<html>502 Bad Gateway</html>"))
+def test_html_gateway_error_surfaces_title(monkeypatch):
+    html = (
+        "<!DOCTYPE html><html><head>"
+        "<title>confamnode.com | 524: A timeout occurred</title>"
+        "</head><body>...</body></html>"
+    )
+    _patch_post(monkeypatch, FakeResponse(524, json_raises=True, text=html))
     client = ConfamNode(api_key=API_KEY)
     with pytest.raises(Exception) as exc:
         client.gist(model=MODEL, messages="hi")
-    assert "502" in str(exc.value)
-    assert "Bad Gateway" in str(exc.value)
+    msg = str(exc.value)
+    assert "524" in msg
+    assert "A timeout occurred" in msg
+    assert "<html" not in msg   # the page itself must NOT be dumped into the error
 
 
 def test_success_path_still_returns_ansa(monkeypatch):

{confamnode-0.2.4 → confamnode-0.2.6}/tests/test_utils.py

@@ -29,6 +29,27 @@ def test_non_json_text_body_is_returned_stripped():
     assert extract_error(_Resp(json_raises=True, text="  upstream timeout  ")) == "upstream timeout"
 
 
+def test_html_error_page_summarised_to_title():
+    # A Cloudflare 524 page: don't dump the whole page, surface the <title>.
+    html = (
+        "<!DOCTYPE html><html><head>"
+        "<title>confamnode.com | 524: A timeout occurred</title>"
+        "</head><body>...lots of markup...</body></html>"
+    )
+    assert extract_error(_Resp(json_raises=True, text=html)) == "confamnode.com | 524: A timeout occurred"
+
+
+def test_html_without_title_falls_back():
+    html = "<html><body>502 Bad Gateway</body></html>"
+    assert extract_error(_Resp(json_raises=True, text=html)) == "HTML error page (no title)"
+
+
+def test_long_plain_text_is_truncated():
+    body = "x" * 500
+    out = extract_error(_Resp(json_raises=True, text=body))
+    assert len(out) == 300 and out.endswith("...")
+
+
 def test_detail_key_is_preferred():
     assert extract_error(_Resp(payload={"detail": "invalid model"})) == "invalid model"
 

{confamnode-0.2.4 → confamnode-0.2.6}/uv.lock

@@ -40,7 +40,7 @@ wheels = [
 
 [[package]]
 name = "confamnode"
-version = "0.2.3"
+version = "0.2.6"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

confamnode-0.2.4/confamnode/utils.py

@@ -1,26 +0,0 @@
-"""
-Small internal helpers shared across the confamnode client.
-"""
-
-
-def extract_error(response) -> str:
-    """
-    Best-effort error detail from a non-2xx response, WITHOUT raising.
- 
-    The server's normal error shape is {"detail": "..."}, but gateway-level
-    errors (e.g. a 429 throttle, a 502/504 from a proxy) often return an
-    empty or non-JSON body. Calling response.json() directly on those bodies
-    raises JSONDecodeError and swallows the status code -- the one thing the
-    caller actually needs. So we parse defensively and always fall back to
-    the raw text, then to a status-only message.
-    """
-    try:
-        payload = response.json()
-        if isinstance(payload, dict):
-            detail = payload.get("detail") or payload.get("error") or payload.get("message")
-            if detail:
-                return str(detail)
-    except Exception:
-        pass
-    text = (getattr(response, "text", "") or "").strip()
-    return text or "no response body"