ragfabric-sdk 0.3.1__tar.gz

ragfabric_sdk-0.3.1/.gitignore

@@ -0,0 +1,49 @@
+# Environment
+.env
+.env.*
+!.env.example
+
+# local configuration (copy of ragfabric.example.yaml)
+ragfabric.yaml
+
+# OS
+.DS_Store
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+
+# Local data / databases
+*.db
+backend/data/uploads/
+
+# Node / Angular
+node_modules/
+dist/
+.angular/
+npm-debug.log*
+
+# Editors
+.idea/
+.vscode/
+
+# Frontend test artifacts
+coverage/
+out-tsc/
+
+# Local planning notes and scratch (never committed)
+MEMORY*.md
+*.local.md
+.notes/
+.scratch/
+
+# Secrets and keys (belt and braces; .env already excluded above)
+*.pem
+*.key
+*.p12
+secrets/

ragfabric_sdk-0.3.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.5
+Name: ragfabric-sdk
+Version: 0.3.1
+Summary: Python client for a RagFabric server.
+Project-URL: Homepage, https://github.com/ranjan-del/ragfabric
+Project-URL: Repository, https://github.com/ranjan-del/ragfabric
+Project-URL: Documentation, https://github.com/ranjan-del/ragfabric/tree/main/docs
+Project-URL: Changelog, https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ranjan-del/ragfabric/issues
+Author-email: Ranjan G <ranjan.g@ispf.ngo>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.13
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.13
+Description-Content-Type: text/markdown
+
+# ragfabric-sdk
+
+Python client for a RagFabric server, talking HTTP only.
+
+```python
+from ragfabric_sdk import Client
+
+client = Client("http://localhost:8000", token="a-jwt-or-api-key")
+answer = client.ask("What is the refund policy?")
+print(answer.answer, answer.citations)
+```

ragfabric_sdk-0.3.1/README.md

@@ -0,0 +1,11 @@
+# ragfabric-sdk
+
+Python client for a RagFabric server, talking HTTP only.
+
+```python
+from ragfabric_sdk import Client
+
+client = Client("http://localhost:8000", token="a-jwt-or-api-key")
+answer = client.ask("What is the refund policy?")
+print(answer.answer, answer.citations)
+```

ragfabric_sdk-0.3.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ragfabric-sdk"
+version = "0.3.1"
+description = "Python client for a RagFabric server."
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+license = "Apache-2.0"
+authors = [{ name = "Ranjan G", email = "ranjan.g@ispf.ngo" }]
+dependencies = ["httpx>=0.28", "pydantic>=2.13"]
+
+[project.urls]
+Homepage = "https://github.com/ranjan-del/ragfabric"
+Repository = "https://github.com/ranjan-del/ragfabric"
+Documentation = "https://github.com/ranjan-del/ragfabric/tree/main/docs"
+Changelog = "https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ranjan-del/ragfabric/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragfabric_sdk"]

ragfabric_sdk-0.3.1/src/ragfabric_sdk/__init__.py

@@ -0,0 +1,46 @@
+"""ragfabric_sdk: a typed HTTP client for a RagFabric server.
+
+Talks HTTP only and never imports ragfabric_core, ragfabric_server or
+ragfabric_cli; see client.py for why.
+"""
+
+from __future__ import annotations
+
+from ragfabric_sdk.client import Client
+from ragfabric_sdk.errors import AuthError, NotFoundError, RagFabricError, RateLimitError
+from ragfabric_sdk.models import (
+    Answer,
+    AskEvent,
+    Citation,
+    Document,
+    GraphEdge,
+    GraphNode,
+    Highlight,
+    Run,
+    SearchResult,
+    Source,
+    SourceDocument,
+    Span,
+    Subgraph,
+)
+
+__all__ = [
+    "Client",
+    "RagFabricError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "Answer",
+    "AskEvent",
+    "Citation",
+    "Document",
+    "GraphEdge",
+    "GraphNode",
+    "Highlight",
+    "Run",
+    "SearchResult",
+    "Source",
+    "SourceDocument",
+    "Span",
+    "Subgraph",
+]

ragfabric_sdk-0.3.1/src/ragfabric_sdk/client.py

@@ -0,0 +1,210 @@
+"""HTTP client for a RagFabric server.
+
+Talks HTTP only and never imports ragfabric_core, ragfabric_server or
+ragfabric_cli: an adopter installs this on a laptop or in a serverless
+function to call a RagFabric server someone else runs. If it imported core
+it would drag SQLAlchemy, pgvector, chromadb and the migrations into that
+environment, and a version skew between the client's core and the server's
+core would produce failures that look like API bugs. The rule is enforced
+by an import linter contract, not by convention.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from pathlib import Path
+
+import httpx
+
+from ragfabric_sdk.errors import raise_for_status
+from ragfabric_sdk.models import Answer, AskEvent, Document, Run, SearchResult
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class Client:
+    """A RagFabric API client.
+
+    Args:
+        base_url: e.g. "http://localhost:8000".
+        token: a JWT from POST /api/auth/login; sent as Authorization: Bearer.
+        api_key: an rf_ key; sent as X-API-Key. If both are given, the API
+            key wins and the bearer header is not sent.
+        timeout: seconds.
+        transport: a testing seam only, not a public feature. Pass an
+            ``httpx`` transport (for example ``httpx.MockTransport``) to
+            exercise this client against a fake server, so tests never touch
+            the network.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        elif token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def ask(self, query: str, strategy: str = "traditional", **params) -> Answer:
+        """POST /api/ask with stream=False and return the finished, cited answer.
+
+        ``strategy`` names the retrieval strategy: ``"traditional"`` (embed the
+        question, search the vector index), ``"vectorless"`` (BM25 fused with
+        ts_rank_cd, no embedding call at all), ``"agentic"`` (decompose the
+        question, retrieve per part, repair or abandon the parts that fail) or
+        ``"graph"`` (see below).
+        It is spelled out as a named parameter rather than left to ``**params``
+        because it changes what the server does, and a caller should be able to
+        find it in the signature. The server rejects any other name with a 422.
+
+        With ``"agentic"``, the answer also carries ``sub_questions`` (what was
+        and was not answered, and why), ``dropped_claims`` (claims the citation
+        contract refused, removed rather than retried), ``dated_sources`` and
+        the agent's ``trace``. Every one of them is empty for the other
+        strategies, which have no parts to report.
+
+        With ``"graph"`` (walk the knowledge graph from the entities the
+        question names), the answer carries ``subgraph`` (the nodes and edges
+        walked, whether the walk was truncated, and why it was empty if it
+        was) and ``dropped_relationship_claims`` (relationship claims the graph
+        citation contract removed, each with its reason). ``subgraph`` is None
+        for every other strategy. A graph request with ``document_id`` or
+        ``format`` is refused with a 422, since the walk cannot apply them.
+        """
+        res = self._http.post(
+            "/api/ask",
+            json={"query": query, "stream": False, "strategy": strategy, **params},
+        )
+        raise_for_status(res)
+        return Answer.model_validate(res.json())
+
+    def ask_stream(self, query: str, strategy: str = "traditional", **params) -> Iterator[AskEvent]:
+        """POST /api/ask with stream=True and yield each server-sent event.
+
+        Events arrive in this order: ``retrieval``, one or more ``token``,
+        optionally ``superseded``, ``citations``, then ``done`` (carrying
+        ``run_id`` and ``latency_ms``).
+
+        ``superseded`` is not a failure: it fires when the streamed text
+        already rendered to the caller turns out to violate the citation
+        contract. The server cannot retake back the tokens it already sent,
+        so instead of silently recording a different answer than what was
+        shown, it repairs the answer and announces the repair. A caller
+        handling this event should REPLACE whatever it has drawn from the
+        preceding ``token`` events with ``event.data["text"]``, the same way
+        the ``ragfabric ask`` command does.
+
+        Per the SSE wire format, a ``data:`` line with no preceding
+        ``event:`` line for that block defaults to the event name
+        ``"message"``. The RagFabric server always sends an explicit
+        ``event:`` line today, but a client library follows the spec rather
+        than only the one server it was written against, so a bare
+        ``data:`` line is still yielded rather than silently dropped.
+        """
+        with self._http.stream(
+            "POST",
+            "/api/ask",
+            json={"query": query, "stream": True, "strategy": strategy, **params},
+        ) as res:
+            if res.status_code >= 400:
+                res.read()
+                raise_for_status(res)
+            name: str | None = None
+            for line in res.iter_lines():
+                if line.startswith("event:"):
+                    name = line.split(":", 1)[1].strip()
+                elif line.startswith("data:"):
+                    yield AskEvent(
+                        event=name if name is not None else "message",
+                        data=json.loads(line.split(":", 1)[1].strip()),
+                    )
+                    name = None
+
+    def search(
+        self,
+        query: str,
+        mode: str = "semantic",
+        strategy: str = "traditional",
+        **params,
+    ) -> list[SearchResult]:
+        """POST /api/search/semantic or /api/search/hybrid and return the ranked chunks.
+
+        ``strategy`` selects the retrieval strategy, as on ``ask``. Note that
+        ``mode="hybrid"`` fuses one vector ranking with one lexical ranking, so
+        the server refuses any strategy that does not provide that pair with a
+        422; use the default ``mode="semantic"`` to search with
+        ``strategy="vectorless"``, ``strategy="agentic"`` or ``strategy="graph"``.
+        """
+        path = "/api/search/hybrid" if mode == "hybrid" else "/api/search/semantic"
+        res = self._http.post(
+            path, json={"query": query, "mode": mode, "strategy": strategy, **params}
+        )
+        raise_for_status(res)
+        return [SearchResult.model_validate(r) for r in res.json()["results"]]
+
+    def ingest(
+        self,
+        path: str | Path,
+        collection: int | None = None,
+        chunk_size: int | None = None,
+        chunk_overlap: int | None = None,
+    ) -> Document:
+        """POST /api/documents/upload and return the ingested document.
+
+        ``collection`` maps to the upload form's ``collection_id`` field.
+        ``chunk_size``/``chunk_overlap`` are the optional per-upload chunking
+        overrides the route accepts; left unset, the document is chunked
+        with the server's configured defaults.
+        """
+        file_path = Path(path)
+        data: dict[str, str] = {}
+        if collection is not None:
+            data["collection_id"] = str(collection)
+        if chunk_size is not None:
+            data["chunk_size"] = str(chunk_size)
+        if chunk_overlap is not None:
+            data["chunk_overlap"] = str(chunk_overlap)
+        with file_path.open("rb") as handle:
+            res = self._http.post(
+                "/api/documents/upload",
+                files={"file": (file_path.name, handle)},
+                data=data or None,
+            )
+        raise_for_status(res)
+        return Document.model_validate(res.json())
+
+    def documents(self) -> list[Document]:
+        """GET /api/documents. The route always returns the {"items": [...],
+        "total": N} envelope (schemas.document.DocumentList), never a bare
+        list, so that is the only shape parsed here."""
+        res = self._http.get("/api/documents")
+        raise_for_status(res)
+        return [Document.model_validate(r) for r in res.json()["items"]]
+
+    def run(self, run_id: int) -> Run:
+        """GET /api/runs/{id}."""
+        res = self._http.get(f"/api/runs/{run_id}")
+        raise_for_status(res)
+        return Run.model_validate(res.json())

ragfabric_sdk-0.3.1/src/ragfabric_sdk/errors.py

@@ -0,0 +1,50 @@
+"""Exception types, mapped from HTTP status codes in one place.
+
+Every client method funnels through ``raise_for_status`` so a caller can
+catch one hierarchy (``RagFabricError``) or one specific cause
+(``AuthError``, ``NotFoundError``, ``RateLimitError``) regardless of which
+endpoint raised it.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class RagFabricError(Exception):
+    """Base error for anything the server rejected. Carries the HTTP status
+    code and the response body's ``detail`` as the message."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(RagFabricError):
+    """401 (not authenticated) or 403 (authenticated but not permitted)."""
+
+
+class NotFoundError(RagFabricError):
+    """404: no such resource."""
+
+
+class RateLimitError(RagFabricError):
+    """429: an API key went over its rate limit."""
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise the mapped error for a 4xx/5xx response; do nothing otherwise."""
+    if response.status_code < 400:
+        return
+    try:
+        detail = response.json().get("detail", response.text)
+    except ValueError:
+        detail = response.text
+    code = response.status_code
+    if code in (401, 403):
+        raise AuthError(str(detail), code)
+    if code == 404:
+        raise NotFoundError(str(detail), code)
+    if code == 429:
+        raise RateLimitError(str(detail), code)
+    raise RagFabricError(str(detail), code)

ragfabric_sdk-0.3.1/src/ragfabric_sdk/models.py

@@ -0,0 +1,281 @@
+"""Pydantic mirrors of the server's response schemas.
+
+Each class here shadows one schema in
+``packages/server/src/ragfabric_server/schemas/``. Field names and types are
+copied from the real schema modules, not from the plan that first described
+this client, because the schemas are the source of truth and drift between
+the two is exactly what these models exist to catch early (a validation
+error at parse time, not a confusing ``KeyError`` deep in caller code).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class Highlight(BaseModel):
+    """A query-term span, in ``schemas/search.py``."""
+
+    term: str
+    start: int
+    end: int
+
+
+class Span(BaseModel):
+    """A character range plus the text it covers, in ``schemas/search.py``."""
+
+    text: str
+    start: int
+    end: int
+
+
+class Citation(BaseModel):
+    """Mirrors ``schemas.search.Citation``."""
+
+    marker: str
+    chunk_id: int | None = None
+    document_id: int | None = None
+    filename: str | None = None
+    page: int | None = None
+    # None for the graph strategy, whose chunks come from a traversal and
+    # carry no similarity score.
+    score: float | None = None
+    snippet: str
+    used: bool = False
+    highlights: list[Highlight] = Field(default_factory=list)
+    supporting_span: Span | None = None
+
+
+class SourceDocument(BaseModel):
+    """Mirrors ``schemas.search.SourceDocument``."""
+
+    document_id: int | None = None
+    filename: str | None = None
+    page: int | None = None
+    collection_id: int | None = None
+
+
+class Usage(BaseModel):
+    """Mirrors ``schemas.search.Usage``: what the request actually cost.
+
+    ``embedding_calls`` is zero for the vectorless strategy, which makes none,
+    and one for the traditional strategy, which embeds the query exactly once.
+    """
+
+    embedding_calls: int = 0
+    llm_calls: int = 0
+    retrieval_calls: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class SubQuestionReport(BaseModel):
+    """Mirrors ``schemas.search.SubQuestionReportOut``.
+
+    Only the agentic strategy fills this in. ``status`` is ``answered``,
+    ``abandoned`` or ``open``, where ``open`` means the run stopped with this
+    part of the question unanswered, and ``reason`` says what stopped it. It
+    replaces what a single "this answer is partial" flag could not express:
+    which part failed, and why.
+    """
+
+    text: str
+    status: str
+    reason: str | None = None
+    chunk_ids: list[int] = Field(default_factory=list)
+
+
+class DroppedClaim(BaseModel):
+    """Mirrors ``schemas.search.DroppedClaimOut``: a claim the contract refused.
+
+    The agent removes an unsupported claim rather than retrying retrieval for
+    it, and reports the removal here so the caller can see what was cut.
+    """
+
+    text: str
+    reason: str
+
+
+class DatedSource(BaseModel):
+    """Mirrors ``schemas.search.DatedSourceOut``."""
+
+    marker: int
+    chunk_id: int
+    document_id: int
+    effective_date: str
+
+
+class DatedSubQuestion(BaseModel):
+    """Mirrors ``schemas.search.DatedSubQuestionOut``.
+
+    Sources for one part of the question carrying different effective dates.
+    This is metadata: nothing here says they disagree in meaning.
+    """
+
+    sub_question: str
+    sources: list[DatedSource] = Field(default_factory=list)
+
+
+class GraphNode(BaseModel):
+    """Mirrors ``schemas.search.GraphNodeOut``: an entity the graph walk reached.
+
+    Names and types only; the server never sends a stored description.
+    ``entity_type`` stays a plain string so a type added on the server does not
+    make this client reject the response.
+    """
+
+    id: int
+    name: str
+    entity_type: str
+    depth: int
+
+
+class GraphEdge(BaseModel):
+    """Mirrors ``schemas.search.GraphEdgeOut``: an edge the walk kept.
+
+    ``walked_as`` is the relation as walked (the inverse name when
+    ``reversed``). ``confidence`` is None when nothing measured it.
+    """
+
+    id: int
+    source_id: int
+    target_id: int
+    relation_type: str
+    walked_as: str
+    reversed: bool
+    confidence: float | None = None
+    source_chunk_ids: list[int] = Field(default_factory=list)
+
+
+class Subgraph(BaseModel):
+    """Mirrors ``schemas.search.SubgraphOut``: what the graph strategy walked.
+
+    ``empty_reason`` is ``no_graph_coverage``, ``no_entity_matched`` or
+    ``no_walkable_edges`` when nothing was walked, and None otherwise.
+    ``truncated`` is True when the server's node budget cut the walk.
+    """
+
+    nodes: list[GraphNode] = Field(default_factory=list)
+    edges: list[GraphEdge] = Field(default_factory=list)
+    truncated: bool = False
+    empty_reason: str | None = None
+
+
+class Answer(BaseModel):
+    """Mirrors ``schemas.search.AnswerResponse``, returned by both
+    ``POST /api/ask`` (non streaming) and ``POST /api/search/query``."""
+
+    question: str
+    answer: str
+    confidence: float
+    citations: list[Citation]
+    highlights: list[Highlight]
+    source_document: SourceDocument | None = None
+    # Optional so this client still parses a response from a server older
+    # than Phase 4, which has no usage block to report.
+    usage: Usage | None = None
+    # Empty unless the agentic strategy served the request, and empty rather
+    # than optional so a server older than Phase 5 parses without special
+    # cases. ``trace`` stays a list of plain dicts for the same reason
+    # ``Run.trace`` does: a span's attributes differ per node and typing them
+    # would make the client reject a span shape it simply has not seen.
+    sub_questions: list[SubQuestionReport] = Field(default_factory=list)
+    dropped_claims: list[DroppedClaim] = Field(default_factory=list)
+    dated_sources: list[DatedSubQuestion] = Field(default_factory=list)
+    trace: list[dict] = Field(default_factory=list)
+    # Only the graph strategy fills these in; optional and empty by default so
+    # a server older than Phase 6 parses unchanged. ``dropped_relationship_claims``
+    # are relationship claims the graph citation contract removed, with the
+    # rule that removed each one as ``reason``.
+    subgraph: Subgraph | None = None
+    dropped_relationship_claims: list[DroppedClaim] = Field(default_factory=list)
+
+
+class SearchResult(BaseModel):
+    """Mirrors ``schemas.search.SearchResultItem``."""
+
+    chunk_id: int | None = None
+    document_id: int | None = None
+    filename: str | None = None
+    format: str | None = None
+    page: int | None = None
+    chunk_index: int | None = None
+    score: float
+    lexical_score: float | None = None
+    hybrid_score: float | None = None
+    text: str
+
+
+class Document(BaseModel):
+    """Mirrors ``schemas.document.DocumentOut``, returned by
+    ``POST /api/documents/upload``, ``GET /api/documents`` and
+    ``GET /api/documents/{id}``."""
+
+    id: int
+    filename: str
+    format: str
+    document_type: str = ""
+    storage_path: str | None = None
+    content_type: str
+    status: str
+    collection_id: int | None = None
+    owner_id: int | None = None
+    version: int
+    num_chunks: int
+    error: str
+    created_at: datetime
+
+
+class Source(BaseModel):
+    """Mirrors ``schemas.runs.SourceOut``, one row of ``Run.sources``."""
+
+    rank: int
+    chunk_id: int | None = None
+    document_id: int | None = None
+    score: float | None = None
+    cited: bool
+    page: int | None = None
+
+
+class Run(BaseModel):
+    """Mirrors ``schemas.runs.RunOut``, returned by ``GET /api/runs/{id}``."""
+
+    id: int
+    question: str
+    mode: str
+    requested_strategy: str | None = None
+    selected_strategy: str
+    fallback_from: str | None = None
+    answer: str | None = None
+    latency_ms: int
+    retrieval_latency_ms: int
+    generation_latency_ms: int
+    llm_calls: int
+    retrieval_calls: int
+    input_tokens: int
+    output_tokens: int
+    estimated_cost_usd: float | None = None
+    llm_model: str | None = None
+    embedding_model: str | None = None
+    trace: list[dict] = Field(default_factory=list)
+    created_at: datetime
+    sources: list[Source] = Field(default_factory=list)
+
+
+class AskEvent(BaseModel):
+    """One SSE event from ``POST /api/ask`` with ``stream: true``.
+
+    ``event`` is one of ``retrieval``, ``token``, ``superseded``,
+    ``citations`` or ``done``, in that order (``superseded`` only appears
+    when the streamed answer failed the citation contract). With the graph
+    strategy, ``retrieval`` carries ``subgraph`` (a ``Subgraph`` as a dict),
+    and ``superseded`` carries ``dropped_claims`` and
+    ``dropped_relationship_claims`` alongside the repaired ``text``. ``data`` is the
+    event's raw JSON payload, kept untyped because each event name carries a
+    different shape and this class is a thin parsing result, not a schema.
+    """
+
+    event: str
+    data: dict

ragfabric_sdk-0.3.1/tests/test_client.py

@@ -0,0 +1,547 @@
+"""Tests for the ragfabric_sdk client, against httpx.MockTransport only.
+
+No test here talks to a network or a running server: every handler below
+builds the response by hand, shaped exactly like the real server's routes in
+packages/server/src/ragfabric_server/api/routes/ and schemas in
+packages/server/src/ragfabric_server/schemas/.
+"""
+
+import email
+import json
+
+import httpx
+import pytest
+
+from ragfabric_sdk import Client
+from ragfabric_sdk.errors import AuthError, NotFoundError, RateLimitError
+from ragfabric_sdk.models import Document
+
+
+def transport(handler):
+    return httpx.MockTransport(handler)
+
+
+def client_with(handler, **kwargs):
+    return Client("http://server", token="t", transport=transport(handler), **kwargs)
+
+
+def parse_multipart(request: httpx.Request) -> dict[str, str | bytes]:
+    """Decode a MockTransport-captured multipart/form-data request into a
+    {field name: value} dict, keyed exactly by the field's ``name`` so
+    "collection" and "collection_id" are never confused with one another.
+
+    Uses the standard library's ``email`` parser rather than substring
+    matching on the raw bytes, since a substring check for ``name="x"``
+    would also match inside ``name="x_id"``.
+    """
+    content_type = request.headers["content-type"]
+    raw = b"Content-Type: " + content_type.encode() + b"\r\n\r\n" + request.content
+    message = email.message_from_bytes(raw)
+    fields: dict[str, str | bytes] = {}
+    for part in message.get_payload():
+        name = part.get_param("name", header="Content-Disposition")
+        payload = part.get_payload(decode=True)
+        fields[name] = payload if part.get_filename() else payload.decode()
+    return fields
+
+
+_DOCUMENT_RESPONSE = {
+    "id": 1,
+    "filename": "doc.txt",
+    "format": "txt",
+    "document_type": "",
+    "storage_path": None,
+    "content_type": "text/plain",
+    "status": "ready",
+    "collection_id": 42,
+    "owner_id": 1,
+    "version": 1,
+    "num_chunks": 2,
+    "error": "",
+    "created_at": "2026-09-18T00:00:00",
+}
+
+
+def test_ask_returns_a_typed_answer():
+    def handler(request):
+        assert request.url.path == "/api/ask"
+        assert json.loads(request.content)["stream"] is False
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "a [1]",
+                "confidence": 0.8,
+                "citations": [
+                    {"marker": "[1]", "chunk_id": 3, "document_id": 1, "score": 0.9, "snippet": "s"}
+                ],
+                "highlights": [],
+            },
+        )
+
+    answer = client_with(handler).ask("q")
+    assert answer.answer == "a [1]"
+    assert answer.citations[0].chunk_id == 3
+    assert answer.confidence == pytest.approx(0.8)
+    # Fields absent from the response body fall back to the schema's
+    # defaults rather than raising.
+    assert answer.citations[0].used is False
+    assert answer.citations[0].filename is None
+    assert answer.source_document is None
+
+
+def test_the_bearer_token_is_sent():
+    def handler(request):
+        assert request.headers["authorization"] == "Bearer t"
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "",
+                "confidence": 0.0,
+                "citations": [],
+                "highlights": [],
+            },
+        )
+
+    client_with(handler).ask("q")
+
+
+def test_an_api_key_is_sent_in_the_x_api_key_header():
+    def handler(request):
+        assert request.headers["x-api-key"] == "rf_abc"
+        assert "authorization" not in request.headers
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "",
+                "confidence": 0.0,
+                "citations": [],
+                "highlights": [],
+            },
+        )
+
+    Client("http://server", api_key="rf_abc", transport=transport(handler)).ask("q")
+
+
+def test_an_api_key_wins_when_both_are_given():
+    """The class docstring documents this precedence; pin it with a test."""
+
+    def handler(request):
+        assert request.headers["x-api-key"] == "rf_abc"
+        assert "authorization" not in request.headers
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "",
+                "confidence": 0.0,
+                "citations": [],
+                "highlights": [],
+            },
+        )
+
+    Client("http://server", token="t", api_key="rf_abc", transport=transport(handler)).ask("q")
+
+
+def test_ask_stream_yields_parsed_events():
+    body = (
+        'event: retrieval\ndata: {"chunks": 2}\n\n'
+        'event: token\ndata: {"text": "hello "}\n\n'
+        'event: token\ndata: {"text": "world"}\n\n'
+        'event: citations\ndata: {"citations": []}\n\n'
+        'event: done\ndata: {"run_id": 7, "latency_ms": 12}\n\n'
+    )
+
+    def handler(request):
+        return httpx.Response(200, text=body, headers={"content-type": "text/event-stream"})
+
+    events = list(client_with(handler).ask_stream("q"))
+    assert [e.event for e in events] == ["retrieval", "token", "token", "citations", "done"]
+    assert "".join(e.data["text"] for e in events if e.event == "token") == "hello world"
+    assert events[-1].data["run_id"] == 7
+
+
+def test_ask_stream_surfaces_a_superseded_event():
+    """A citation contract violation on the streamed text is reported as a
+    superseded event carrying the corrected text, not silently swallowed and
+    not raised as an error: the SDK must pass it through so a caller can
+    replace what it already rendered."""
+    body = (
+        'event: retrieval\ndata: {"chunks": 1}\n\n'
+        'event: token\ndata: {"text": "unverified claim"}\n\n'
+        'event: superseded\ndata: {"text": "corrected [1] answer", "reason": "citation contract"}\n\n'
+        'event: citations\ndata: {"citations": []}\n\n'
+        'event: done\ndata: {"run_id": 9, "latency_ms": 40}\n\n'
+    )
+
+    def handler(request):
+        return httpx.Response(200, text=body, headers={"content-type": "text/event-stream"})
+
+    events = list(client_with(handler).ask_stream("q"))
+    assert [e.event for e in events] == ["retrieval", "token", "superseded", "citations", "done"]
+    superseded = events[2]
+    assert superseded.data["text"] == "corrected [1] answer"
+    assert superseded.data["reason"] == "citation contract"
+
+
+def test_ask_stream_defaults_a_bare_data_line_to_the_message_event():
+    """Per the SSE wire format, a data: line with no preceding event: line
+    defaults to the event name "message". The real server always sends an
+    explicit event: line today, but the parser should follow the spec, not
+    just the one server it was written against."""
+    body = 'data: {"chunks": 2}\n\n'
+
+    def handler(request):
+        return httpx.Response(200, text=body, headers={"content-type": "text/event-stream"})
+
+    events = list(client_with(handler).ask_stream("q"))
+    assert len(events) == 1
+    assert events[0].event == "message"
+    assert events[0].data == {"chunks": 2}
+
+
+def test_a_401_becomes_an_auth_error():
+    def handler(request):
+        return httpx.Response(401, json={"detail": "not authenticated"})
+
+    with pytest.raises(AuthError):
+        client_with(handler).ask("q")
+
+
+def test_a_403_also_becomes_an_auth_error():
+    def handler(request):
+        return httpx.Response(403, json={"detail": "insufficient permissions"})
+
+    with pytest.raises(AuthError) as exc_info:
+        client_with(handler).ask("q")
+    assert "insufficient permissions" in str(exc_info.value)
+
+
+def test_a_429_becomes_a_rate_limit_error():
+    def handler(request):
+        return httpx.Response(429, json={"detail": "too many"})
+
+    with pytest.raises(RateLimitError):
+        client_with(handler).ask("q")
+
+
+def test_a_404_becomes_a_not_found_error():
+    def handler(request):
+        return httpx.Response(404, json={"detail": "no such run"})
+
+    with pytest.raises(NotFoundError):
+        client_with(handler).run(99)
+
+
+def test_search_returns_typed_results():
+    def handler(request):
+        assert request.url.path == "/api/search/semantic"
+        return httpx.Response(
+            200,
+            json={
+                "query": "q",
+                "mode": "semantic",
+                "results": [{"chunk_id": 1, "document_id": 2, "score": 0.5, "text": "t"}],
+            },
+        )
+
+    results = client_with(handler).search("q")
+    assert results[0].score == pytest.approx(0.5)
+    assert results[0].text == "t"
+
+
+def test_search_hybrid_uses_the_hybrid_path():
+    def handler(request):
+        assert request.url.path == "/api/search/hybrid"
+        return httpx.Response(
+            200,
+            json={"query": "q", "mode": "hybrid", "results": []},
+        )
+
+    client_with(handler).search("q", mode="hybrid")
+
+
+def test_ingest_sends_the_real_multipart_shape(tmp_path):
+    """The plan's reference sent the collection as a form field named
+    "collection"; the real upload route (api/routes/documents.py) reads
+    "collection_id", "chunk_size" and "chunk_overlap" as Form fields. This
+    test inspects the outgoing request rather than only the parsed response,
+    so a regression back to the wrong field name would be caught here."""
+    file_path = tmp_path / "doc.txt"
+    file_path.write_text("hello world")
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request):
+        assert request.url.path == "/api/documents/upload"
+        captured["request"] = request
+        return httpx.Response(201, json=_DOCUMENT_RESPONSE)
+
+    doc = client_with(handler).ingest(file_path, collection=42, chunk_size=500)
+
+    fields = parse_multipart(captured["request"])
+    assert fields["file"] == b"hello world"
+    assert fields["collection_id"] == "42"
+    assert "collection" not in fields
+    assert fields["chunk_size"] == "500"
+    # chunk_overlap was never supplied: the server treats an absent field as
+    # "use the configured value", which is a different thing from a form
+    # field carrying an empty string or the literal text "None".
+    assert "chunk_overlap" not in fields
+    assert isinstance(doc, Document)
+    assert doc.filename == "doc.txt"
+
+
+def test_ingest_omits_every_optional_field_when_none_are_given(tmp_path):
+    """With no collection/chunk_size/chunk_overlap supplied, the client must
+    send only the file: it must not stringify None into any of these form
+    fields."""
+    file_path = tmp_path / "doc.txt"
+    file_path.write_text("hello world")
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request):
+        captured["request"] = request
+        return httpx.Response(201, json=_DOCUMENT_RESPONSE)
+
+    client_with(handler).ingest(file_path)
+
+    fields = parse_multipart(captured["request"])
+    assert set(fields) == {"file"}
+
+
+def test_documents_parses_the_items_envelope():
+    """GET /api/documents always returns {"items": [...], "total": N}
+    (schemas.document.DocumentList); there is no bare-list shape to
+    tolerate."""
+
+    def handler(request):
+        assert request.url.path == "/api/documents"
+        return httpx.Response(
+            200,
+            json={
+                "items": [
+                    {
+                        "id": 1,
+                        "filename": "a.pdf",
+                        "format": "pdf",
+                        "document_type": "",
+                        "storage_path": None,
+                        "content_type": "application/pdf",
+                        "status": "ready",
+                        "collection_id": None,
+                        "owner_id": 1,
+                        "version": 1,
+                        "num_chunks": 3,
+                        "error": "",
+                        "created_at": "2026-09-18T00:00:00",
+                    }
+                ],
+                "total": 1,
+            },
+        )
+
+    docs = client_with(handler).documents()
+    assert len(docs) == 1
+    assert docs[0].filename == "a.pdf"
+    assert docs[0].num_chunks == 3
+
+
+def test_run_returns_a_typed_run_with_sources():
+    def handler(request):
+        assert request.url.path == "/api/runs/7"
+        return httpx.Response(
+            200,
+            json={
+                "id": 7,
+                "question": "q",
+                "mode": "manual",
+                "requested_strategy": "traditional",
+                "selected_strategy": "traditional",
+                "fallback_from": None,
+                "answer": "a",
+                "latency_ms": 100,
+                "retrieval_latency_ms": 40,
+                "generation_latency_ms": 60,
+                "llm_calls": 1,
+                "retrieval_calls": 1,
+                "input_tokens": 10,
+                "output_tokens": 20,
+                "estimated_cost_usd": 0.0,
+                "llm_model": None,
+                "embedding_model": "hashing",
+                "trace": [],
+                "created_at": "2026-09-18T00:00:00",
+                "sources": [
+                    {
+                        "rank": 1,
+                        "chunk_id": 3,
+                        "document_id": 1,
+                        "score": 0.9,
+                        "cited": True,
+                        "page": None,
+                    }
+                ],
+            },
+        )
+
+    run = client_with(handler).run(7)
+    assert run.id == 7
+    assert run.sources[0].chunk_id == 3
+    assert run.sources[0].cited is True
+
+
+def test_ask_sends_the_agentic_strategy_and_parses_the_sub_question_report():
+    """The agent's partial answers are structured, so the client types them."""
+
+    def handler(request):
+        assert json.loads(request.content)["strategy"] == "agentic"
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "a [1]",
+                "confidence": 0.8,
+                "citations": [],
+                "highlights": [],
+                "sub_questions": [
+                    {
+                        "text": "what is the retry limit",
+                        "status": "answered",
+                        "reason": None,
+                        "chunk_ids": [3],
+                    },
+                    {
+                        "text": "who signs it off",
+                        "status": "open",
+                        "reason": "no evidence was retrieved for this sub-question",
+                        "chunk_ids": [],
+                    },
+                ],
+                "dropped_claims": [{"text": "the board approved it", "reason": "uncited answer"}],
+                "dated_sources": [
+                    {
+                        "sub_question": "what is the retry limit",
+                        "sources": [
+                            {
+                                "marker": 1,
+                                "chunk_id": 3,
+                                "document_id": 7,
+                                "effective_date": "2025-06-01",
+                            }
+                        ],
+                    }
+                ],
+                "trace": [{"name": "plan", "started_ms": 0, "duration_ms": 2, "attributes": {}}],
+            },
+        )
+
+    answer = client_with(handler).ask("q", strategy="agentic")
+
+    assert [report.status for report in answer.sub_questions] == ["answered", "open"]
+    assert answer.sub_questions[1].reason
+    assert answer.dropped_claims[0].reason == "uncited answer"
+    assert answer.dated_sources[0].sources[0].effective_date == "2025-06-01"
+    assert answer.trace[0]["name"] == "plan"
+
+
+def test_an_answer_from_a_server_without_the_agent_fields_still_parses():
+    """Every field this task adds is optional, so an older server is readable."""
+
+    def handler(request):
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "a [1]",
+                "confidence": 0.8,
+                "citations": [],
+                "highlights": [],
+            },
+        )
+
+    answer = client_with(handler).ask("q")
+
+    assert answer.sub_questions == []
+    assert answer.dropped_claims == []
+    assert answer.dated_sources == []
+    assert answer.trace == []
+    assert answer.subgraph is None
+    assert answer.dropped_relationship_claims == []
+
+
+def test_ask_sends_the_graph_strategy_and_parses_the_subgraph():
+    def handler(request):
+        assert json.loads(request.content)["strategy"] == "graph"
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "The Platform Team is a member of Engineering [E 1] [1].",
+                "confidence": 0.8,
+                "citations": [],
+                "highlights": [],
+                "subgraph": {
+                    "nodes": [
+                        {"id": 1, "name": "Platform Team", "entity_type": "team", "depth": 0},
+                        {"id": 2, "name": "Engineering", "entity_type": "organisation", "depth": 1},
+                    ],
+                    "edges": [
+                        {
+                            "id": 5,
+                            "source_id": 1,
+                            "target_id": 2,
+                            "relation_type": "MEMBER_OF",
+                            "walked_as": "MEMBER_OF",
+                            "reversed": False,
+                            "confidence": None,
+                            "source_chunk_ids": [9],
+                        }
+                    ],
+                    "truncated": True,
+                    "empty_reason": None,
+                },
+                "dropped_relationship_claims": [
+                    {
+                        "text": "Engineering reports to the Board [E 99] [1].",
+                        "reason": "edge_not_in_subgraph",
+                    }
+                ],
+            },
+        )
+
+    answer = client_with(handler).ask("q", strategy="graph")
+
+    assert [node.name for node in answer.subgraph.nodes] == ["Platform Team", "Engineering"]
+    assert answer.subgraph.nodes[1].depth == 1
+    [edge] = answer.subgraph.edges
+    assert (edge.walked_as, edge.reversed, edge.confidence) == ("MEMBER_OF", False, None)
+    assert edge.source_chunk_ids == [9]
+    assert answer.subgraph.truncated is True
+    assert answer.subgraph.empty_reason is None
+    assert answer.dropped_relationship_claims[0].reason == "edge_not_in_subgraph"
+
+
+def test_an_empty_subgraph_reports_why():
+    def handler(request):
+        return httpx.Response(
+            200,
+            json={
+                "question": "q",
+                "answer": "I could not find an answer to that in the documents provided.",
+                "confidence": 0.0,
+                "citations": [],
+                "highlights": [],
+                "subgraph": {
+                    "nodes": [],
+                    "edges": [],
+                    "truncated": False,
+                    "empty_reason": "no_graph_coverage",
+                },
+            },
+        )
+
+    answer = client_with(handler).ask("q", strategy="graph")
+
+    assert answer.subgraph.empty_reason == "no_graph_coverage"