confamnode 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confamnode
-Version: 0.2.2
+Version: 0.2.4
 Summary: The Nigerian AI inference gateway
 Project-URL: Repository, https://github.com/confamnodeai/confamnode
 Project-URL: Bug Tracker, https://github.com/confamnodeai/confamnode/issues
@@ -174,25 +174,25 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 ### Free Tier
 
-| Model | Description | Price |
-|---|---|---|
-| `confam-lite` | Light text and general chat | Free |
-| `confam-speed` | Fast, high quality responses | Free |
-| `confam-reasoning` | Standard reasoning and analysis | Free |
+| Model | Description | Modality | Price |
+|---|---|---|---|
+| `confam-lite` | Light text and general chat | Text-to-Text | Free |
+| `confam-speed` | Fast, high quality responses | Image-Text-to-Text | Free |
+| `confam-reasoning` | Standard reasoning and analysis | Text-to-Text | Free |
 
 ### Paid Tier
 
-| Model | Description | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
-|---|---|---|---|---|---|
-| `confam-intelligence` | General smart tasks, 1M context | ₦596 | ₦3,571 | ₦0.596 | ₦3.571 |
-| `confam-deep-reasoning` | Complex thinking, multi-step analysis | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
-| `confam-code` | Coding assistance, 1M context | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
+| Model | Description | Modality | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
+|---|---|---|---|---|---|---|
+| `confam-intelligence` | General smart tasks, 1M context | Image-Text-to-Text | ₦596 | ₦3,571 | ₦0.596 | ₦3.571 |
+| `confam-deep-reasoning` | Complex thinking, multi-step analysis | Image-Text-to-Text | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
+| `confam-code` | Coding assistance, 1M context | Image-Text-to-Text | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
 
 ### Local Models — Nigerian Data Residency
 
-| Model | Description | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
-|---|---|---|---|---|---|
-| `confam-nano` | Local model — data stays in Nigeria | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+| Model | Description | Modality | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
+|---|---|---|---|---|---|---|
+| `confam-nano` | Local model — data stays in Nigeria | Image-Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
 
 Runs entirely on Nigerian hardware. Data never transmitted abroad.
 Ideal for banks, fintechs, hospitals, law firms, and government agencies.
@@ -254,6 +254,32 @@ ansa = client.gist(
 
 ---
 
+## Caching
+
+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:
+
+```python
+# Default — caching off, fresh response every call
+ansa = client.gist(
+    model="confam-speed",
+    messages="How you dey?"
+)
+
+# Enable caching — use a stored response when the request matches,
+# and store this response for next time
+ansa = client.gist(
+    model="confam-speed",
+    messages="How you dey?",
+    cache=True
+)
+```
+
+A cache hit is typically returned near-instantly and at little or no token cost — a quick way to confirm caching is active.
+
+---
+
 ## Reasoning Models
 
 Enable extended thinking for complex problems:
@@ -404,4 +430,4 @@ Contact: [hello@confamnode.com](mailto:hello@confamnode.com)
 
 Apache 2.0
 
----
+---

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

@@ -150,25 +150,25 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 ### Free Tier
 
-| Model | Description | Price |
-|---|---|---|
-| `confam-lite` | Light text and general chat | Free |
-| `confam-speed` | Fast, high quality responses | Free |
-| `confam-reasoning` | Standard reasoning and analysis | Free |
+| Model | Description | Modality | Price |
+|---|---|---|---|
+| `confam-lite` | Light text and general chat | Text-to-Text | Free |
+| `confam-speed` | Fast, high quality responses | Image-Text-to-Text | Free |
+| `confam-reasoning` | Standard reasoning and analysis | Text-to-Text | Free |
 
 ### Paid Tier
 
-| Model | Description | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
-|---|---|---|---|---|---|
-| `confam-intelligence` | General smart tasks, 1M context | ₦596 | ₦3,571 | ₦0.596 | ₦3.571 |
-| `confam-deep-reasoning` | Complex thinking, multi-step analysis | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
-| `confam-code` | Coding assistance, 1M context | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
+| Model | Description | Modality | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
+|---|---|---|---|---|---|---|
+| `confam-intelligence` | General smart tasks, 1M context | Image-Text-to-Text | ₦596 | ₦3,571 | ₦0.596 | ₦3.571 |
+| `confam-deep-reasoning` | Complex thinking, multi-step analysis | Image-Text-to-Text | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
+| `confam-code` | Coding assistance, 1M context | Image-Text-to-Text | ₦234 | ₦468 | ₦0.234 | ₦0.468 |
 
 ### Local Models — Nigerian Data Residency
 
-| Model | Description | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
-|---|---|---|---|---|---|
-| `confam-nano` | Local model — data stays in Nigeria | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+| Model | Description | Modality | Input ₦/1M | Output ₦/1M | Input ₦/1K | Output ₦/1K |
+|---|---|---|---|---|---|---|
+| `confam-nano` | Local model — data stays in Nigeria | Image-Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
 
 Runs entirely on Nigerian hardware. Data never transmitted abroad.
 Ideal for banks, fintechs, hospitals, law firms, and government agencies.
@@ -230,6 +230,32 @@ ansa = client.gist(
 
 ---
 
+## Caching
+
+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:
+
+```python
+# Default — caching off, fresh response every call
+ansa = client.gist(
+    model="confam-speed",
+    messages="How you dey?"
+)
+
+# Enable caching — use a stored response when the request matches,
+# and store this response for next time
+ansa = client.gist(
+    model="confam-speed",
+    messages="How you dey?",
+    cache=True
+)
+```
+
+A cache hit is typically returned near-instantly and at little or no token cost — a quick way to confirm caching is active.
+
+---
+
 ## Reasoning Models
 
 Enable extended thinking for complex problems:
@@ -380,4 +406,4 @@ Contact: [hello@confamnode.com](mailto:hello@confamnode.com)
 
 Apache 2.0
 
----
+---

{confamnode-0.2.2 → confamnode-0.2.4}/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.2"
+__version__ = "0.2.4"
 
 __all__ = [
     "ConfamNode",

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

@@ -4,6 +4,7 @@ import httpx
 
 from typing import Union, List, Dict
 
+from confamnode.utils import extract_error
 from confamnode.builders import parse_chunk
 from confamnode.ansa import Ansa, Usage, Cost
 from confamnode.registry import VALID_MODELS
@@ -34,6 +35,7 @@ class ConfamNode:
         model: str,
         messages: Union[str, List[Dict[str, str]]],
         system: str | None = "default",
+        cache: bool = False,
         **kwargs
     ) -> "Ansa | ConfamStream":
         if model not in VALID_MODELS:
@@ -59,6 +61,25 @@ 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
+        # 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).
+        #
+        # 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:
+            body["cache"] = {
+                "no-cache": True, # Skip cache check, get fresh response
+                "no-store": True # Don't cache this response
+            }
+
         if kwargs.get("stream", False):
             http_client = httpx.Client(
                 timeout=httpx.Timeout(DEFAULT_TIMEOUT, connect=DEFAULT_CONNECT_TIMEOUT)
@@ -76,10 +97,11 @@ class ConfamNode:
 
             if stream_response.status_code >= 400:
                 stream_response.read()
+                status = stream_response.status_code
+                error = extract_error(stream_response)
                 stream_response.close()
                 http_client.close()
-                error = stream_response.json().get("detail", "Requeest failed")
-                raise Exception(f"ConfamNode error {stream_response.status_code}: {error}")
+                raise Exception(f"ConfamNode error {status}: {error}")
             
             return ConfamStream(stream_response, http_client, model)
         
@@ -94,7 +116,7 @@ class ConfamNode:
         )
 
         if response.status_code >= 400:
-            error = response.json().get("detail", "Request failed")
+            error = extract_error(response)
             raise Exception(f"ConfamNode error {response.status_code}: {error}")
 
         data = response.json()

confamnode-0.2.4/confamnode/utils.py

@@ -0,0 +1,26 @@
+"""
+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"

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

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

confamnode-0.2.4/tests/test_cache_flag.py

@@ -0,0 +1,74 @@
+"""
+Tests for the per-request cache flag on ConfamNode.gist().
+
+Caching is opt-OUT by default: identical requests must each return a fresh
+response (critical for data-generation loops). cache=True flips the request
+to read-from + write-to the cache. These tests pin down the exact payload
+sent in each case so a future refactor can't silently flip the default.
+
+No network: httpx.post is monkeypatched to capture the request body.
+"""
+import httpx
+import pytest
+
+from confamnode.client import ConfamNode
+from confamnode.registry import VALID_MODELS
+
+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
+def captured_body(monkeypatch):
+    """Patch httpx.post to record the JSON body and return a valid 200."""
+    box = {}
+
+    def fake_post(url, headers=None, json=None, timeout=None):
+        box["body"] = json
+
+        class _Resp:
+            status_code = 200
+            text = ""
+
+            def json(self):
+                return {
+                    "choices": [{"message": {"content": "hi"}, "finish_reason": "stop"}],
+                    "usage": {},
+                    "confam": {"cost": {"naira": 0.0}},
+                }
+
+        return _Resp()
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+    return box
+
+
+def _gist(**kwargs):
+    ConfamNode(api_key=API_KEY).gist(model=MODEL, messages="x", **kwargs)
+
+
+def test_cache_off_by_default(captured_body):
+    _gist()
+    assert captured_body["body"]["cache"] == CACHE_OFF
+
+
+def test_cache_true_uses_and_stores(captured_body):
+    _gist(cache=True)
+    assert captured_body["body"]["cache"] == CACHE_ON
+
+
+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"]

confamnode-0.2.4/tests/test_client_errors.py

@@ -0,0 +1,82 @@
+"""
+Tests for ConfamNode.gist() error handling.
+
+The original bug: a non-2xx response with an empty / non-JSON body made the
+SDK call response.json() in its error branch, which raised JSONDecodeError
+and hid the HTTP status. These tests pin down that:
+  - an empty error body raises a clean "ConfamNode error <status>: ..." with
+    the status code intact (NOT a JSONDecodeError), and
+  - the normal success path still works after the refactor.
+
+No network: httpx.post is monkeypatched to return a fake response.
+"""
+import httpx
+import pytest
+
+from confamnode.client import ConfamNode
+from confamnode.registry import VALID_MODELS
+
+API_KEY = "confam-test"
+MODEL = next(iter(VALID_MODELS))   # any valid model; we never really call out
+
+
+class FakeResponse:
+    def __init__(self, status_code, payload=None, *, json_raises=False, text=""):
+        self.status_code = status_code
+        self._payload = payload
+        self._json_raises = json_raises
+        self.text = text
+
+    def json(self):
+        if self._json_raises:
+            raise ValueError("Expecting value: line 1 column 1 (char 0)")
+        return self._payload
+
+
+def _patch_post(monkeypatch, response):
+    monkeypatch.setattr(httpx, "post", lambda *a, **k: response)
+
+
+def test_empty_error_body_raises_with_status_not_jsondecodeerror(monkeypatch):
+    # The reproduction of the reported crash: 429, empty body.
+    _patch_post(monkeypatch, FakeResponse(429, json_raises=True, text=""))
+    client = ConfamNode(api_key=API_KEY)
+    with pytest.raises(Exception) as exc:
+        client.gist(model=MODEL, messages="hi")
+    msg = str(exc.value)
+    assert "429" in msg
+    assert "no response body" in msg
+    assert "JSONDecode" not in type(exc.value).__name__
+
+
+def test_json_detail_error_surfaces_detail(monkeypatch):
+    _patch_post(monkeypatch, FakeResponse(400, payload={"detail": "invalid model"}))
+    client = ConfamNode(api_key=API_KEY)
+    with pytest.raises(Exception) as exc:
+        client.gist(model=MODEL, messages="hi")
+    assert "400" in str(exc.value)
+    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>"))
+    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)
+
+
+def test_success_path_still_returns_ansa(monkeypatch):
+    payload = {
+        "id": "abc",
+        "choices": [{"message": {"content": "hello"}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": 1, "completion_tokens": 2, "total_tokens": 3},
+        "confam": {"request_id": "r1", "cost": {"naira": 0.0}},
+    }
+    _patch_post(monkeypatch, FakeResponse(200, payload=payload))
+    client = ConfamNode(api_key=API_KEY)
+    ansa = client.gist(model=MODEL, messages="hi")
+    assert ansa.text == "hello"
+    assert ansa.cost.naira == 0.0

confamnode-0.2.4/tests/test_utils.py

@@ -0,0 +1,46 @@
+"""
+Unit tests for confamnode.utils.extract_error.
+
+Pure function, no network: just feed it fake responses and assert it never
+raises and always produces a usable message.
+"""
+from confamnode.utils import extract_error
+
+
+class _Resp:
+    """Minimal stand-in for an httpx.Response."""
+    def __init__(self, payload=None, *, json_raises=False, text=""):
+        self._payload = payload
+        self._json_raises = json_raises
+        self.text = text
+
+    def json(self):
+        if self._json_raises:
+            raise ValueError("Expecting value: line 1 column 1 (char 0)")
+        return self._payload
+
+
+def test_empty_body_returns_placeholder():
+    # The exact case that crashed the SDK: empty 429 body.
+    assert extract_error(_Resp(json_raises=True, text="")) == "no response body"
+
+
+def test_non_json_text_body_is_returned_stripped():
+    assert extract_error(_Resp(json_raises=True, text="  upstream timeout  ")) == "upstream timeout"
+
+
+def test_detail_key_is_preferred():
+    assert extract_error(_Resp(payload={"detail": "invalid model"})) == "invalid model"
+
+
+def test_error_key_fallback():
+    assert extract_error(_Resp(payload={"error": "nope"})) == "nope"
+
+
+def test_message_key_fallback():
+    assert extract_error(_Resp(payload={"message": "hmm"})) == "hmm"
+
+
+def test_non_dict_json_falls_back_to_text():
+    # A JSON array (not a dict) shouldn't blow up; fall back to text.
+    assert extract_error(_Resp(payload=["a", "b"], text="listy")) == "listy"

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

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