ragnarok-api 0.1.0__py3-none-any.whl

ragnarok_api/__init__.py

@@ -0,0 +1,223 @@
+"""ragnarok-api: the Python SDK of the RAGnarok HTTP API.
+
+Quick start::
+
+    from ragnarok_api import Client, Token
+
+    with Client("https://ragnarok.example", Token("rk_...")) as client:
+        for event in client.query.stream("What is the indication?", workspace="epar"):
+            print(event.event, event)
+
+See the package README for the four usage scenarios (streaming query, ingest a
+folder, read the graph, manage access).
+"""
+
+from __future__ import annotations
+
+from ._core import SUPPORTED_INGEST_SUFFIXES, FolderSelection, collect_folder
+from ._upload import (
+    FilesTooLarge,
+    ServerTooOldForUpload,
+    UploadInterrupted,
+    UploadItem,
+    UploadJobFinished,
+    UploadJobResult,
+    UploadProgress,
+    new_client_ref,
+    plan_batches,
+    prepare_uploads,
+    sha256_of,
+)
+from ._version import SUPPORTED_API_MAJOR, __version__
+from .accounting import (
+    ChunkCounts,
+    DocumentAccounting,
+    FigureCounts,
+    InsertedModified,
+    JobAccounting,
+    JobDocumentCounts,
+    ModelCallCounts,
+    TableCounts,
+)
+from .async_client import AsyncClient
+from .client import Client
+from .credentials import Session, Token
+from .errors import (
+    ApiVersionMismatch,
+    BadRequest,
+    ChecksumMismatch,
+    ClientRefConflict,
+    Conflict,
+    EmbeddingMismatch,
+    Forbidden,
+    ManifestMismatch,
+    NotFound,
+    PayloadTooLarge,
+    QueryFailed,
+    RagnarokError,
+    RateLimited,
+    ServerError,
+    StagedNameConflict,
+    StagingQuotaExceeded,
+    TermsRequired,
+    TransportError,
+    Unauthorized,
+    UploadIncomplete,
+)
+from .events import (
+    INGEST_UPLOAD_STEPS,
+    AnswerDeltaEvent,
+    AnswerEvent,
+    CitationMapEvent,
+    DoneEvent,
+    EntitiesEvent,
+    ErrorEvent,
+    GraphEvent,
+    HistoryError,
+    IngestDoneEvent,
+    IngestErrorEvent,
+    IngestEvent,
+    IngestJobSummary,
+    NoticesEvent,
+    QueryEvent,
+    ReferenceEntry,
+    ReferenceGroup,
+    ReferencesEvent,
+    SourcesEvent,
+    StatsEvent,
+    StatusEvent,
+    UnknownEvent,
+)
+from .models import (
+    INGEST_JOB_STATUSES,
+    WORKSPACE_ROLES,
+    EmbeddingChange,
+    EmbeddingRecord,
+    Grant,
+    GrantChange,
+    IngestDocumentResult,
+    IngestEmbedder,
+    IngestJob,
+    IngestLimits,
+    IngestNoticeDetail,
+    IngestPlan,
+    IngestRoleModel,
+    IngestSubmitted,
+    QueryResult,
+    RemovedFiles,
+    RepairFinding,
+    RepairReport,
+    StagedFile,
+    StagedFiles,
+    UserRecord,
+    WhoAmI,
+    WorkspaceGrantRow,
+    WorkspaceGrants,
+    WorkspaceMember,
+    WorkspaceMeta,
+    WorkspaceSummary,
+)
+from .paging import aiterate, iterate
+
+__all__ = [
+    "INGEST_JOB_STATUSES",
+    "INGEST_UPLOAD_STEPS",
+    "SUPPORTED_API_MAJOR",
+    "SUPPORTED_INGEST_SUFFIXES",
+    "WORKSPACE_ROLES",
+    "AnswerDeltaEvent",
+    "AnswerEvent",
+    "ApiVersionMismatch",
+    "AsyncClient",
+    "BadRequest",
+    "ChecksumMismatch",
+    "ChunkCounts",
+    "CitationMapEvent",
+    "Client",
+    "ClientRefConflict",
+    "Conflict",
+    "DocumentAccounting",
+    "DoneEvent",
+    "EmbeddingChange",
+    "EmbeddingMismatch",
+    "EmbeddingRecord",
+    "EntitiesEvent",
+    "ErrorEvent",
+    "FigureCounts",
+    "FilesTooLarge",
+    "FolderSelection",
+    "Forbidden",
+    "Grant",
+    "GrantChange",
+    "GraphEvent",
+    "HistoryError",
+    "IngestDocumentResult",
+    "IngestDoneEvent",
+    "IngestEmbedder",
+    "IngestErrorEvent",
+    "IngestEvent",
+    "IngestJob",
+    "IngestJobSummary",
+    "IngestLimits",
+    "IngestNoticeDetail",
+    "IngestPlan",
+    "IngestRoleModel",
+    "IngestSubmitted",
+    "InsertedModified",
+    "JobAccounting",
+    "JobDocumentCounts",
+    "ManifestMismatch",
+    "ModelCallCounts",
+    "NotFound",
+    "NoticesEvent",
+    "PayloadTooLarge",
+    "PostprocessRef",
+    "QueryEvent",
+    "QueryFailed",
+    "QueryResult",
+    "RagnarokError",
+    "RateLimited",
+    "ReferenceEntry",
+    "ReferenceGroup",
+    "ReferencesEvent",
+    "RemovedFiles",
+    "RepairFinding",
+    "RepairReport",
+    "ServerError",
+    "ServerTooOldForUpload",
+    "Session",
+    "SourcesEvent",
+    "StagedFile",
+    "StagedFiles",
+    "StagedNameConflict",
+    "StagingQuotaExceeded",
+    "StatsEvent",
+    "StatusEvent",
+    "TableCounts",
+    "TermsRequired",
+    "Token",
+    "TransportError",
+    "Unauthorized",
+    "UnknownEvent",
+    "UploadIncomplete",
+    "UploadInterrupted",
+    "UploadItem",
+    "UploadJobFinished",
+    "UploadJobResult",
+    "UploadProgress",
+    "UserRecord",
+    "WhoAmI",
+    "WorkspaceGrantRow",
+    "WorkspaceGrants",
+    "WorkspaceMember",
+    "WorkspaceMeta",
+    "WorkspaceSummary",
+    "__version__",
+    "aiterate",
+    "collect_folder",
+    "iterate",
+    "new_client_ref",
+    "plan_batches",
+    "prepare_uploads",
+    "sha256_of",
+]

ragnarok_api/_base.py

@@ -0,0 +1,178 @@
+"""State and pure helpers shared by :class:`Client` and :class:`AsyncClient`."""
+
+from __future__ import annotations
+
+import re
+import warnings
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._core import (
+    DEFAULT_STREAM_READ_TIMEOUT_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    Call,
+    normalize_prefix,
+)
+from ._version import SUPPORTED_API_MAJOR
+from .errors import ApiVersionMismatch, TermsRequired, Unauthorized
+from .events import (
+    AnswerDeltaEvent,
+    AnswerEvent,
+    CitationMapEvent,
+    DoneEvent,
+    EntitiesEvent,
+    ErrorEvent,
+    GraphEvent,
+    NoticesEvent,
+    QueryEvent,
+    ReferencesEvent,
+    SourcesEvent,
+    StatsEvent,
+    StatusEvent,
+    UnknownEvent,
+)
+from .models import AuthCheck, Health, QueryResult, WhoAmI
+
+STREAM_ENDED_WITHOUT_DONE = (
+    "The query stream ended before RAGnarok sent a completion event. Wait a moment and try again."
+)
+
+
+class ClientBase:
+    """Configuration shared by both clients (no I/O here)."""
+
+    _is_async = False
+
+    def __init__(
+        self,
+        base_url: str,
+        credential: Any = None,
+        *,
+        api_prefix: str = "/api/v1",
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT_SECONDS,  # #TIMEOUT : ADR-006 240 s default
+        stream_read_timeout: float = DEFAULT_STREAM_READ_TIMEOUT_SECONDS,  # #TIMEOUT : SSE liveness backstop
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        if not str(base_url or "").strip():
+            raise ValueError("base_url is required (e.g. 'https://ragnarok.example').")
+        self.base_url = str(base_url).rstrip("/")
+        self.credential = credential
+        self.api_prefix = normalize_prefix(api_prefix)
+        self._timeout = timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(float(timeout))
+        self._stream_timeout = httpx.Timeout(self._timeout.connect, read=float(stream_read_timeout),
+                                             write=self._timeout.write, pool=self._timeout.pool)
+        self._extra_headers = dict(headers or {})
+
+    def _url(self, call: Call[Any]) -> str:
+        path = call.path if call.path.startswith("/") else "/" + call.path
+        return (self.api_prefix + path) if call.versioned else path
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(base_url={self.base_url!r}, api_prefix={self.api_prefix!r}, "
+            f"credential={self.credential!r})"
+        )
+
+
+def whoami_from_check(check: AuthCheck, credential: Any) -> WhoAmI:
+    """Map ``/auth/check`` (servers before item 0166) onto :class:`WhoAmI`."""
+    if check.terms_required:
+        raise TermsRequired(
+            "The account must accept the confidentiality terms.",
+            session=credential if getattr(credential, "kind", None) == "session" else None,
+        )
+    if not check.authenticated or check.user is None:
+        raise Unauthorized("Not authenticated (auth/check reported authenticated=false).", code="not_authenticated")
+    return WhoAmI(
+        email=check.user.email,
+        account_type=check.user.account_type,
+        allowed_workspaces=list(check.user.allowed_workspaces),
+        terms_required=False,
+        terms_signed_at=check.terms_signed_at,
+        auth_kind=None,
+        source="check",
+    )
+
+
+_MAJOR_RE = re.compile(r"^\D*(\d+)")
+
+
+def api_major(api_version: str | None) -> int | None:
+    """``"1"``, ``"v1"``, ``"1.2.0"`` -> ``1``; ``None``/unparseable -> ``None``."""
+    if api_version is None:
+        return None
+    match = _MAJOR_RE.match(str(api_version).strip())
+    return int(match.group(1)) if match else None
+
+
+def check_version(health: Health, *, strict: bool) -> Health:
+    """Raise :class:`ApiVersionMismatch` when the server's API major is not the SDK's."""
+    major = api_major(health.api_version)
+    if major is None:
+        message = (
+            "The server did not report a parseable api_version on /api/health "
+            f"(got {health.api_version!r}); compatibility with API v{SUPPORTED_API_MAJOR} is unverified."
+        )
+        if strict:
+            raise ApiVersionMismatch(message, server_api_version=health.api_version,
+                                     supported_major=SUPPORTED_API_MAJOR)
+        warnings.warn(message, RuntimeWarning, stacklevel=3)
+        return health
+    if major != SUPPORTED_API_MAJOR:
+        raise ApiVersionMismatch(
+            f"Server speaks API v{major}; this SDK supports v{SUPPORTED_API_MAJOR}.",
+            server_api_version=health.api_version,
+            supported_major=SUPPORTED_API_MAJOR,
+        )
+    return health
+
+
+class QueryCollector:
+    """Fold a ``/query`` event stream into a :class:`QueryResult`."""
+
+    def __init__(self) -> None:
+        self.result = QueryResult()
+        self._draft: list[str] = []
+
+    def add(self, event: QueryEvent) -> None:
+        r = self.result
+        if isinstance(event, StatusEvent):
+            r.statuses.append(event)
+        elif isinstance(event, AnswerDeltaEvent):
+            self._draft.append(event.text)
+            r.draft = "".join(self._draft)
+        elif isinstance(event, AnswerEvent):
+            r.answer = event.text
+        elif isinstance(event, CitationMapEvent):
+            r.citation_map = dict(event.map)
+        elif isinstance(event, ReferencesEvent):
+            r.references = list(event.items)
+            r.reference_groups = list(event.groups)
+        elif isinstance(event, NoticesEvent):
+            r.notices = list(event.items)
+        elif isinstance(event, SourcesEvent):
+            r.sources = event
+        elif isinstance(event, EntitiesEvent):
+            r.entities = event
+        elif isinstance(event, GraphEvent):
+            r.graph = event
+        elif isinstance(event, StatsEvent):
+            r.stats = event
+        elif isinstance(event, ErrorEvent):
+            r.errors.append(event)
+        elif isinstance(event, DoneEvent):
+            r.success = bool(event.success) and not r.errors
+            r.history_id = event.history_id
+            r.history_error = event.history_error
+        elif isinstance(event, UnknownEvent):
+            r.unknown.append(event)
+
+
+def synthetic_end() -> list[QueryEvent]:
+    """What the web client reports when the stream ends without ``done``."""
+    return [
+        ErrorEvent(message=STREAM_ENDED_WITHOUT_DONE, code="query_network_error", client_generated=True),
+        DoneEvent(success=False, client_generated=True),
+    ]

ragnarok_api/_bridge.py

@@ -0,0 +1,63 @@
+"""Run an async httpx transport (e.g. ``httpx.ASGITransport(app=...)``) under the sync client.
+
+``httpx.Client`` only accepts sync transports, but the in-process ASGI
+transport the backend tests and ``ragnarok --local`` use is async. This
+bridge runs it on a private event loop thread (anyio blocking portal; anyio
+is already an httpx dependency). The response body is fully buffered, which
+is also what ``httpx.ASGITransport`` itself does, so SSE events arrive when
+the app finishes the stream.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from typing import Any
+
+import httpx
+
+
+class AsyncTransportBridge(httpx.BaseTransport):
+    """A sync transport that forwards every request to an async transport."""
+
+    def __init__(self, transport: httpx.AsyncBaseTransport) -> None:
+        from anyio.from_thread import start_blocking_portal
+
+        self._transport = transport
+        self._portal_cm: AbstractContextManager[Any] = start_blocking_portal()
+        self._portal = self._portal_cm.__enter__()
+        self._closed = False
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        body = request.read()
+        forwarded = httpx.Request(
+            request.method,
+            request.url,
+            headers=request.headers,
+            content=body,
+            extensions=request.extensions,
+        )
+
+        async def _send() -> httpx.Response:
+            response = await self._transport.handle_async_request(forwarded)
+            try:
+                raw = b"".join([chunk async for chunk in response.aiter_raw()])
+            finally:
+                await response.aclose()
+            return httpx.Response(
+                status_code=response.status_code,
+                headers=response.headers,
+                stream=httpx.ByteStream(raw),
+                extensions=response.extensions,
+                request=request,
+            )
+
+        return self._portal.call(_send)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._portal.call(self._transport.aclose)
+        finally:
+            self._portal_cm.__exit__(None, None, None)