confamnode 0.2.5__tar.gz → 0.3.0__tar.gz

{confamnode-0.2.5 → confamnode-0.3.0}/.gitignore

@@ -20,6 +20,7 @@ dist/
 .pytest_cache/
 
 # Test files
+live_tests/
 chat_test.py
 stream_test.py
 exchange_rate_calc.py

{confamnode-0.2.5 → confamnode-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confamnode
-Version: 0.2.5
+Version: 0.3.0
 Summary: The Nigerian AI inference gateway
 Project-URL: Repository, https://github.com/confamnodeai/confamnode
 Project-URL: Bug Tracker, https://github.com/confamnodeai/confamnode/issues
@@ -161,7 +161,7 @@ ansa.id                      # unique request ID (confam-xxxx-xxxx)
 
 # Response metadata
 ansa.raw                     # dict with id, finish_reason, usage
-ansa.raw["id"]               # provider response ID
+ansa.raw["id"]                # provider response ID
 ansa.raw["finish_reason"]    # why generation stopped
 ansa.raw["usage"]            # prompt and completion token counts
 ```
@@ -170,13 +170,82 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 ---
 
+## Embeddings
+
+Generate embeddings with `client.embed()`. The shape of what you get back mirrors the shape of what you send in: a single string returns one flat vector, a list returns a list of vectors.
+
+```python
+from confamnode import ConfamNode
+
+client = ConfamNode(api_key="confam-xxx")
+
+# Single string in → one flat vector out
+result = client.embed(
+    model="confam-embed-local",
+    input="How you dey?"
+)
+
+print(result.embeddings)       # [0.123, -0.456, ...]
+print(f"Cost: ₦{result.cost.naira:.6f}")
+print(f"Tokens: {result.usage.total_tokens}")
+
+# List in → list of vectors out, always — even with one item
+result = client.embed(
+    model="confam-embed-local",
+    input=["How you dey?", "Wetin dey happen?"]
+)
+
+print(len(result.embeddings))  # 2
+```
+
+`confam-embed-local` is currently the only available embedding model. More coming soon.
+
+### Task types
+
+Some embedding models expect a task-type hint (e.g. `"query"` vs. `"document"`) to produce better embeddings for retrieval use cases. This defaults sensibly server-side if omitted — only pass it if you need a specific one:
+
+```python
+result = client.embed(
+    model="confam-embed-local",
+    input="find me a good jollof rice recipe",
+    task_type="query"
+)
+
+print(result.task_type_applied)  # confirms what actually happened for this call
+```
+
+`task_type_applied` is `None` when the requested model doesn't use task-type hints at all — the field itself tells you whether it had any effect, no separate capability lookup needed.
+
+### The EmbeddingResult Object
+
+```python
+result = client.embed(model="confam-embed-local", input="How you dey?")
+
+result.embeddings            # vector(s) — shape matches your input shape
+result.model                 # model that served the request
+result.usage.prompt_tokens   # input tokens used
+result.usage.total_tokens    # total tokens used (embeddings have no output tokens to bill)
+result.cost.naira            # total cost in Naira
+result.cost.naira_input      # input cost in Naira
+result.is_local              # True — runs on Nigerian hardware
+result.is_ngn_data_residency # True — data never leaves Nigeria
+result.task_type_applied     # which task-type hint was actually applied, if any
+result.id                    # unique request ID
+result.raw                   # full raw response
+```
+
+### Batch limits (`confam-embed-local`)
+
+Self-hosted embedding requests to `confam-embed-local` are served in batches of up to 4 concurrent requests at a time. If you're embedding a large number of documents, being aware of this batching ceiling will give you a more predictable sense of total time than assuming unlimited concurrency.
+
+---
+
 ## Models
 
 ### Free Tier
 
 | 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 |
 
@@ -192,9 +261,18 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 | 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 |
+| `confam-health` | Local model, health information use cases — data stays in Nigeria | Image-Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+| `confam-local` | Local model, general-purpose — data stays in Nigeria | Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+
+### Embeddings
+
+| Model | Description | Where it runs |
+|---|---|---|
+| `confam-embed-local` | Self-hosted text embeddings — data stays in Nigeria | Local |
+
+More embedding models coming soon.
 
-Runs entirely on Nigerian hardware. Data never transmitted abroad.
+Local models run entirely on Nigerian hardware. Data never transmitted abroad.
 Ideal for banks, fintechs, hospitals, law firms, and government agencies.
 
 More models coming soon. Contact [hello@confamnode.com](mailto:hello@confamnode.com) for early access.
@@ -221,7 +299,7 @@ Rate limits vary by plan. Contact [hello@confamnode.com](mailto:hello@confamnode
 
 - **Free tier** — shared capacity with lower limits
 - **Paid tier** — dedicated higher limits
-- **confam-nano** — limited capacity, queue-based
+- **Local models** (`confam-health`, `confam-local`) — deployed on dedicated Nigerian hardware (Jetson AGX Orin), with a shared concurrency cap across both models. Under heavy simultaneous load, requests queue briefly rather than failing outright.
 
 ---
 
@@ -258,7 +336,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 +345,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 +354,9 @@ 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.
+
+> **Note:** a cache hit still bills the full Naira cost of the request — you're paying for inference value, not raw compute. Caching saves time, not money.
 
 ---
 
@@ -309,6 +389,18 @@ print(ansa.reasoning)   # full thinking trace
 print(ansa.text)        # final analysis
 ```
 
+### Controlling reasoning mode (`confam-local`)
+
+`confam-local` reasons in `<think>` blocks by default. To disable this per-request, pass `enable_thinking` nested under `chat_template_kwargs` via `extra_body` — this must be nested this way rather than passed as a top-level kwarg, or it will be silently ignored:
+
+```python
+result = client.gist(
+    model="confam-local",
+    messages="How you dey?",
+    extra_body={"chat_template_kwargs": {"enable_thinking": False}}
+)
+```
+
 ---
 
 ## RAG (Retrieval-Augmented Generation)
@@ -321,6 +413,8 @@ print(ansa.text)        # final analysis
 | `confam-code` | Code search, documentation RAG | 1M tokens |
 | `confam-deep-reasoning` | Complex RAG, multi-hop reasoning | 1M tokens |
 
+`confam-embed-local` pairs well with any of the above for retrieval — see [Embeddings](#embeddings).
+
 ---
 
 ## Data Residency
@@ -329,7 +423,7 @@ Nigerian businesses handling sensitive data can use local models that run entire
 
 ```python
 ansa = client.gist(
-    model="confam-nano",
+    model="confam-local",
     messages="Analyse this sensitive document..."
 )
 
@@ -338,6 +432,8 @@ print(ansa.is_ngn_data_residency)    # True — data never leaves Nigeria
 print(ansa.text)
 ```
 
+For health information use cases, `confam-health` offers the same data-residency guarantee on a model tuned for that domain.
+
 **Ideal for:**
 - Nigerian banks and fintechs
 - Healthcare companies
@@ -380,6 +476,9 @@ from confamnode import (
     ConfamAuthError,
     ConfamRateLimitError,
     ConfamModelError,
+    ConfamInsufficientBalanceError,
+    ConfamProviderError,
+    ConfamRequestError,
     ConfamNodeError
 )
 
@@ -390,14 +489,22 @@ try:
     )
 except ConfamAuthError:
     print("Check your API key")
+except ConfamInsufficientBalanceError:
+    print("Wallet balance too low. Top up to continue.")
 except ConfamRateLimitError:
     print("You don reach your limit. Contact hello@confamnode.com")
 except ConfamModelError:
     print("Invalid model name")
+except ConfamProviderError:
+    print("The AI provider is temporarily unavailable. Try again shortly.")
+except ConfamRequestError:
+    print("Request could not be processed — check your parameters")
 except ConfamNodeError as e:
     print(f"Something went wrong: {e}")
 ```
 
+All specific exceptions above are subclasses of `ConfamNodeError` — catching that alone is enough if you don't need to distinguish error types.
+
 ---
 
 ## Private AI Deployment

{confamnode-0.2.5 → confamnode-0.3.0}/README.md

@@ -137,7 +137,7 @@ ansa.id                      # unique request ID (confam-xxxx-xxxx)
 
 # Response metadata
 ansa.raw                     # dict with id, finish_reason, usage
-ansa.raw["id"]               # provider response ID
+ansa.raw["id"]                # provider response ID
 ansa.raw["finish_reason"]    # why generation stopped
 ansa.raw["usage"]            # prompt and completion token counts
 ```
@@ -146,13 +146,82 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 ---
 
+## Embeddings
+
+Generate embeddings with `client.embed()`. The shape of what you get back mirrors the shape of what you send in: a single string returns one flat vector, a list returns a list of vectors.
+
+```python
+from confamnode import ConfamNode
+
+client = ConfamNode(api_key="confam-xxx")
+
+# Single string in → one flat vector out
+result = client.embed(
+    model="confam-embed-local",
+    input="How you dey?"
+)
+
+print(result.embeddings)       # [0.123, -0.456, ...]
+print(f"Cost: ₦{result.cost.naira:.6f}")
+print(f"Tokens: {result.usage.total_tokens}")
+
+# List in → list of vectors out, always — even with one item
+result = client.embed(
+    model="confam-embed-local",
+    input=["How you dey?", "Wetin dey happen?"]
+)
+
+print(len(result.embeddings))  # 2
+```
+
+`confam-embed-local` is currently the only available embedding model. More coming soon.
+
+### Task types
+
+Some embedding models expect a task-type hint (e.g. `"query"` vs. `"document"`) to produce better embeddings for retrieval use cases. This defaults sensibly server-side if omitted — only pass it if you need a specific one:
+
+```python
+result = client.embed(
+    model="confam-embed-local",
+    input="find me a good jollof rice recipe",
+    task_type="query"
+)
+
+print(result.task_type_applied)  # confirms what actually happened for this call
+```
+
+`task_type_applied` is `None` when the requested model doesn't use task-type hints at all — the field itself tells you whether it had any effect, no separate capability lookup needed.
+
+### The EmbeddingResult Object
+
+```python
+result = client.embed(model="confam-embed-local", input="How you dey?")
+
+result.embeddings            # vector(s) — shape matches your input shape
+result.model                 # model that served the request
+result.usage.prompt_tokens   # input tokens used
+result.usage.total_tokens    # total tokens used (embeddings have no output tokens to bill)
+result.cost.naira            # total cost in Naira
+result.cost.naira_input      # input cost in Naira
+result.is_local              # True — runs on Nigerian hardware
+result.is_ngn_data_residency # True — data never leaves Nigeria
+result.task_type_applied     # which task-type hint was actually applied, if any
+result.id                    # unique request ID
+result.raw                   # full raw response
+```
+
+### Batch limits (`confam-embed-local`)
+
+Self-hosted embedding requests to `confam-embed-local` are served in batches of up to 4 concurrent requests at a time. If you're embedding a large number of documents, being aware of this batching ceiling will give you a more predictable sense of total time than assuming unlimited concurrency.
+
+---
+
 ## Models
 
 ### Free Tier
 
 | 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 |
 
@@ -168,9 +237,18 @@ ansa.raw["usage"]            # prompt and completion token counts
 
 | 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 |
+| `confam-health` | Local model, health information use cases — data stays in Nigeria | Image-Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+| `confam-local` | Local model, general-purpose — data stays in Nigeria | Text-to-Text | ₦500 | ₦1,500 | ₦0.500 | ₦1.500 |
+
+### Embeddings
+
+| Model | Description | Where it runs |
+|---|---|---|
+| `confam-embed-local` | Self-hosted text embeddings — data stays in Nigeria | Local |
+
+More embedding models coming soon.
 
-Runs entirely on Nigerian hardware. Data never transmitted abroad.
+Local models run entirely on Nigerian hardware. Data never transmitted abroad.
 Ideal for banks, fintechs, hospitals, law firms, and government agencies.
 
 More models coming soon. Contact [hello@confamnode.com](mailto:hello@confamnode.com) for early access.
@@ -197,7 +275,7 @@ Rate limits vary by plan. Contact [hello@confamnode.com](mailto:hello@confamnode
 
 - **Free tier** — shared capacity with lower limits
 - **Paid tier** — dedicated higher limits
-- **confam-nano** — limited capacity, queue-based
+- **Local models** (`confam-health`, `confam-local`) — deployed on dedicated Nigerian hardware (Jetson AGX Orin), with a shared concurrency cap across both models. Under heavy simultaneous load, requests queue briefly rather than failing outright.
 
 ---
 
@@ -234,7 +312,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 +321,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 +330,9 @@ 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.
+
+> **Note:** a cache hit still bills the full Naira cost of the request — you're paying for inference value, not raw compute. Caching saves time, not money.
 
 ---
 
@@ -285,6 +365,18 @@ print(ansa.reasoning)   # full thinking trace
 print(ansa.text)        # final analysis
 ```
 
+### Controlling reasoning mode (`confam-local`)
+
+`confam-local` reasons in `<think>` blocks by default. To disable this per-request, pass `enable_thinking` nested under `chat_template_kwargs` via `extra_body` — this must be nested this way rather than passed as a top-level kwarg, or it will be silently ignored:
+
+```python
+result = client.gist(
+    model="confam-local",
+    messages="How you dey?",
+    extra_body={"chat_template_kwargs": {"enable_thinking": False}}
+)
+```
+
 ---
 
 ## RAG (Retrieval-Augmented Generation)
@@ -297,6 +389,8 @@ print(ansa.text)        # final analysis
 | `confam-code` | Code search, documentation RAG | 1M tokens |
 | `confam-deep-reasoning` | Complex RAG, multi-hop reasoning | 1M tokens |
 
+`confam-embed-local` pairs well with any of the above for retrieval — see [Embeddings](#embeddings).
+
 ---
 
 ## Data Residency
@@ -305,7 +399,7 @@ Nigerian businesses handling sensitive data can use local models that run entire
 
 ```python
 ansa = client.gist(
-    model="confam-nano",
+    model="confam-local",
     messages="Analyse this sensitive document..."
 )
 
@@ -314,6 +408,8 @@ print(ansa.is_ngn_data_residency)    # True — data never leaves Nigeria
 print(ansa.text)
 ```
 
+For health information use cases, `confam-health` offers the same data-residency guarantee on a model tuned for that domain.
+
 **Ideal for:**
 - Nigerian banks and fintechs
 - Healthcare companies
@@ -356,6 +452,9 @@ from confamnode import (
     ConfamAuthError,
     ConfamRateLimitError,
     ConfamModelError,
+    ConfamInsufficientBalanceError,
+    ConfamProviderError,
+    ConfamRequestError,
     ConfamNodeError
 )
 
@@ -366,14 +465,22 @@ try:
     )
 except ConfamAuthError:
     print("Check your API key")
+except ConfamInsufficientBalanceError:
+    print("Wallet balance too low. Top up to continue.")
 except ConfamRateLimitError:
     print("You don reach your limit. Contact hello@confamnode.com")
 except ConfamModelError:
     print("Invalid model name")
+except ConfamProviderError:
+    print("The AI provider is temporarily unavailable. Try again shortly.")
+except ConfamRequestError:
+    print("Request could not be processed — check your parameters")
 except ConfamNodeError as e:
     print(f"Something went wrong: {e}")
 ```
 
+All specific exceptions above are subclasses of `ConfamNodeError` — catching that alone is enough if you don't need to distinguish error types.
+
 ---
 
 ## Private AI Deployment

{confamnode-0.2.5 → confamnode-0.3.0}/confamnode/__init__.py

@@ -1,25 +1,34 @@
-from confamnode.client import ConfamNode, ConfamStream
+
+from confamnode import models
 from confamnode.exceptions import (
     ConfamNodeError,
     ConfamAuthError,
-    ConfamRateLimitError,
     ConfamModelError,
+    ConfamRequestError,
+    ConfamProviderError,
+    ConfamRateLimitError,
+    ConfamInsufficientBalanceError,
 )
-from confamnode.ansa import Ansa, Usage, Cost
-from confamnode import models
+from confamnode.client import ConfamNode, ConfamStream
+from confamnode.ansa import Ansa, Usage, Cost, EmbeddingUsage, EmbeddingResult
 
-__version__ = "0.2.5"
+__version__ = "0.3.0"
 
 __all__ = [
     "ConfamNode",
     "ConfamStream",
-    "ConfamNodeError",
     "ConfamAuthError",
-    "ConfamRateLimitError",
+    "ConfamNodeError",
     "ConfamModelError",
+    "ConfamRequestError",
+    "ConfamProviderError",
+    "ConfamRateLimitError",
+    "ConfamInsufficientBalanceError",
     "Ansa",
     "Usage",
     "Cost",
+    "EmbeddingUsage",
+    "EmbeddingResult",
     "models",
     "__version__"
 ]

{confamnode-0.2.5 → confamnode-0.3.0}/confamnode/ansa.py

@@ -51,4 +51,23 @@ class StreamChoice:
 class StreamChunk:
     id: str = ""
     model: str = ""
-    choices: list = field(default_factory=list)
+    choices: list = field(default_factory=list)
+
+
+@dataclass
+class EmbeddingUsage:
+    prompt_tokens: int
+    total_tokens: int
+
+
+@dataclass
+class EmbeddingResult:
+    embeddings: list
+    model: str
+    usage: EmbeddingUsage
+    cost: Cost
+    raw: object
+    id: str = field(default_factory=lambda: f"confam-{uuid.uuid4()}")
+    is_local: bool = False
+    is_ngn_data_residency: bool = False
+    task_type_applied: str | None = None

{confamnode-0.2.5 → confamnode-0.3.0}/confamnode/client.py

@@ -4,11 +4,11 @@ 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
+from confamnode.utils import raise_for_status
 from confamnode.exceptions import ConfamAuthError, ConfamModelError
+from confamnode.ansa import Ansa, Usage, Cost, EmbeddingResult, EmbeddingUsage
 from confamnode.config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_CONNECT_TIMEOUT
 
 
@@ -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
@@ -97,11 +94,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()
-                raise Exception(f"ConfamNode error {status}: {error}")
+                try:
+                    raise_for_status(stream_response)
+                finally:
+                    stream_response.close()
+                    http_client.close()
             
             return ConfamStream(stream_response, http_client, model)
         
@@ -115,9 +112,7 @@ class ConfamNode:
             timeout=httpx.Timeout(DEFAULT_TIMEOUT, connect=DEFAULT_CONNECT_TIMEOUT)
         )
 
-        if response.status_code >= 400:
-            error = extract_error(response)
-            raise Exception(f"ConfamNode error {response.status_code}: {error}")
+        raise_for_status(response)
 
         data = response.json()
         msg = data["choices"][0]["message"]
@@ -153,6 +148,71 @@ class ConfamNode:
             is_local=confam.get("is_local", False),
             is_ngn_data_residency=confam.get("is_ngn_data_residency", False),
         )
+
+    def embed(
+        self,
+        model: str,
+        input: Union[str, List[str]],
+        task_type: str | None = None,
+        **kwargs
+    ) -> EmbeddingResult:
+        if model not in VALID_MODELS:
+            raise ConfamModelError(model)
+
+        body = {
+            "model": model,
+            "input": input,
+            **kwargs
+        }
+
+        # task_type is optional here — the API defaults to "document"
+        # server-side if omitted, so the SDK doesn't duplicate that
+        # default; only send it if the caller actually specified one.
+        if task_type is not None:
+            body["task_type"] = task_type
+
+        response = httpx.post(
+            f"{self.base_url}/embeddings",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            json=body,
+            timeout=httpx.Timeout(DEFAULT_TIMEOUT, connect=DEFAULT_CONNECT_TIMEOUT)
+        )
+
+        raise_for_status(response)
+
+        data = response.json()
+        usage_data = data.get("usage", {})
+        confam = data.get("confam", {})
+        cost_data = confam.get("cost", {})
+
+        raw_embeddings = [item["embedding"] for item in data.get("data", [])]
+
+        # Convenience unwrapping: a caller who passed a single string
+        # expects one vector back, not a one-item list. A caller who
+        # passed a list always gets a list back, even with one item —
+        # input shape determines output shape, consistently.
+        embeddings = raw_embeddings[0] if isinstance(input, str) else raw_embeddings
+
+        return EmbeddingResult(
+            id=confam.get("request_id", ""),
+            embeddings=embeddings,
+            model=data.get("model", model),
+            usage=EmbeddingUsage(
+                prompt_tokens=usage_data.get("prompt_tokens", 0),
+                total_tokens=usage_data.get("total_tokens", 0),
+            ),
+            cost=Cost(
+                naira=cost_data.get("naira", 0.0),
+                naira_input=cost_data.get("naira_input", 0.0),
+            ),
+            raw=data,
+            is_local=confam.get("is_local", False),
+            is_ngn_data_residency=confam.get("is_ngn_data_residency", False),
+            task_type_applied=confam.get("task_type_applied"),
+        )
     
 
 class ConfamStream: