forktex-intelligence 0.2.3__py3-none-any.whl

forktex_intelligence/client/client.py

@@ -0,0 +1,360 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of forktex-intelligence.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""ForkTex Intelligence async client.
+
+Combines a generated method-per-operation surface (``_GeneratedOperations``,
+emitted from ``openapi.json``) with a handwritten patch layer providing
+session lifecycle, auth header management (dual JWT / X-API-Key), error
+normalization, and wrappers for the request shapes the generator cannot
+express verbatim: SSE streaming and ``multipart/form-data`` uploads.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict
+from uuid import UUID
+
+import httpx
+
+from forktex_intelligence.config import IntelligenceSettings
+from forktex_intelligence.client.generated import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    LoginRequest,
+    OrgCreateRequest,
+    OrgResponse,
+    RegisterRequest,
+    StructuredChatRequest,
+    StructuredChatResponse,
+    _GeneratedOperations,
+)
+
+
+class IntelligenceAPIError(Exception):
+    """Raised when the Intelligence API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class ForktexIntelligenceClient(_GeneratedOperations):
+    """Async client for the ForkTex Intelligence API.
+
+    Public surface is the union of:
+
+    * ~20 generated async methods inherited from ``_GeneratedOperations``
+      (``health``, ``list_models``, ``list_colls``, ``search_single`` …).
+    * The handwritten wrappers on this class for flows the generator does
+      not express: SSE chat streaming, multipart upload, JWT capture on
+      login/register, org-id capture on whoami / create_org.
+
+    Dual auth is supported:
+
+    * ``X-API-Key`` — org-scoped, no JWT needed (machine-to-machine).
+    * ``Authorization: Bearer <JWT>`` — user-level + org-scoped.
+
+    Org-scoped generated ops take ``org_id: UUID`` as the first argument;
+    the caller is expected to pass the currently-active org. This class
+    tracks one in ``self._org_id`` as a convenience for facade callers.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str = "",
+        *,
+        jwt_token: str = "",
+        org_id: str | UUID | None = None,
+        timeout: float = 120.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Construct a client.
+
+        ``transport`` is an optional custom httpx transport. Pass an
+        ``httpx.ASGITransport(app=fastapi_app)`` to drive an in-process
+        FastAPI instance — used by contract tests to exercise the SDK
+        against a live ASGI app without a network hop.
+        """
+        # Generated operations emit absolute paths including ``/api/...``, so
+        # the httpx base_url must be the origin only. Strip a trailing
+        # ``/api`` from a configured endpoint for backwards compatibility.
+        trimmed = base_url.rstrip("/")
+        if trimmed.endswith("/api"):
+            trimmed = trimmed[: -len("/api")]
+        self._base_url = trimmed
+        self._api_key = api_key
+        self._jwt_token = jwt_token
+        self._org_id = str(org_id) if org_id else ""
+
+        headers: Dict[str, str] = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if jwt_token:
+            headers["Authorization"] = f"Bearer {jwt_token}"
+
+        client_kwargs: Dict[str, Any] = dict(
+            base_url=self._base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+        if transport is not None:
+            client_kwargs["transport"] = transport
+
+        self._client = httpx.AsyncClient(**client_kwargs)
+
+    @classmethod
+    def from_settings(cls, settings: IntelligenceSettings, **kwargs: Any) -> ForktexIntelligenceClient:
+        """Create a client from IntelligenceSettings."""
+        if not settings.is_configured:
+            raise RuntimeError("Intelligence API not configured. Run: forktex intelligence init")
+        return cls(settings.endpoint, settings.api_key, **kwargs)
+
+    def set_org(self, org_id: str | UUID) -> None:
+        """Set the org for org-scoped requests."""
+        self._org_id = str(org_id)
+
+    @property
+    def org_id(self) -> str:
+        """Currently-set org id, or empty string if not yet resolved."""
+        return self._org_id
+
+    @property
+    def api_key(self) -> str:
+        """Currently-configured API key (X-API-Key auth)."""
+        return self._api_key
+
+    @property
+    def base_url(self) -> str:
+        """Configured API base URL (no trailing slash, origin only)."""
+        return self._base_url
+
+    def set_jwt(self, token: str) -> None:
+        """Set JWT token for user-level auth."""
+        self._jwt_token = token
+        self._client.headers["Authorization"] = f"Bearer {token}"
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> ForktexIntelligenceClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    # ── Request infrastructure ────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        resp = await self._client.request(method, path, json=json, params=params)
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise IntelligenceAPIError(resp.status_code, str(detail))
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    # ── JWT / org capture overrides ──────────────────────────────────
+
+    async def login(self, email: str, password: str) -> Dict[str, Any]:  # type: ignore[override]
+        """Login with email/password; captures the returned JWT token."""
+        data = await self._request(
+            "POST",
+            "/api/auth/login",
+            json=LoginRequest(email=email, password=password).model_dump(mode="json", exclude_unset=True),
+        )
+        if isinstance(data, dict) and "access_token" in data:
+            self.set_jwt(data["access_token"])
+        return data or {}
+
+    async def register(self, email: str, password: str) -> Dict[str, Any]:  # type: ignore[override]
+        """Register a new user; captures the returned JWT token."""
+        data = await self._request(
+            "POST",
+            "/api/auth/register",
+            json=RegisterRequest(email=email, password=password).model_dump(mode="json", exclude_unset=True),
+        )
+        if isinstance(data, dict) and "access_token" in data:
+            self.set_jwt(data["access_token"])
+        return data or {}
+
+    async def whoami(self) -> Dict[str, Any]:  # type: ignore[override]
+        """Resolve API key → org_id. Auto-sets org on this client."""
+        data = await self._request("GET", "/api/whoami")
+        if isinstance(data, dict) and "org_id" in data:
+            self.set_org(data["org_id"])
+        return data or {}
+
+    async def create_org(self, name: str, slug: str) -> OrgResponse:
+        """Create an org; captures the returned id as the active org."""
+        req = OrgCreateRequest(name=name, slug=slug)
+        data = await self._request("POST", "/api/orgs", json=req.model_dump(mode="json", exclude_unset=True))
+        if isinstance(data, dict) and "id" in data:
+            self.set_org(data["id"])
+        return OrgResponse.model_validate(data)
+
+    # ── Streaming / multipart — not expressible by the generator ─────
+
+    async def chat_stream(
+        self,
+        org_id: str | UUID,
+        messages: list[Dict[str, str]],
+        *,
+        model: str | None = None,
+        system: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        tools: list[Dict[str, Any]] | None = None,
+    ) -> AsyncIterator[bytes]:
+        """SSE chat streaming. ``model``, ``system``, etc. forwarded verbatim."""
+        req = ChatRequest(
+            messages=[ChatMessage(**m) for m in messages],
+            model=model,
+            system=system,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+            tools=tools,
+        )
+        lines: list[bytes] = []
+        async with self._client.stream(
+            "POST",
+            f"/api/org/{org_id}/chat",
+            content=req.model_dump_json(exclude_none=True),
+            headers={
+                "Accept": "text/event-stream",
+                "Content-Type": "application/json",
+            },
+        ) as resp:
+            if resp.status_code >= 400:
+                raise IntelligenceAPIError(resp.status_code, await resp.aread())
+            async for line in resp.aiter_lines():
+                lines.append(line.encode())
+        for line in lines:
+            yield line
+
+    async def extract_file(
+        self,
+        org_id: str | UUID,
+        file_data: bytes,
+        filename: str,
+        *,
+        content_type: str = "application/octet-stream",
+        chunk_size: int = 256,
+        chunk_overlap: int = 32,
+    ) -> Dict[str, Any]:
+        """Upload a file for text extraction (stateless, no storage)."""
+        files = {"file": (filename, file_data, content_type)}
+        data = {
+            "chunk_size": str(chunk_size),
+            "chunk_overlap": str(chunk_overlap),
+        }
+        resp = await self._client.post(f"/api/org/{org_id}/extract", files=files, data=data)
+        if resp.status_code >= 400:
+            raise IntelligenceAPIError(resp.status_code, resp.text)
+        return resp.json()
+
+    async def upload_document(
+        self,
+        org_id: str | UUID,
+        collection_id: str | UUID,
+        file_data: bytes,
+        filename: str,
+        *,
+        content_type: str = "application/octet-stream",
+    ) -> Dict[str, Any]:
+        """Upload a document into a collection for ingestion (multipart)."""
+        files = {"file": (filename, file_data, content_type)}
+        resp = await self._client.post(f"/api/org/{org_id}/collections/{collection_id}/documents", files=files)
+        if resp.status_code >= 400:
+            raise IntelligenceAPIError(resp.status_code, resp.text)
+        return resp.json()
+
+    # ── Chat (handwritten — request shape dual-purposed across stream/non-stream) ─
+
+    async def chat(  # type: ignore[override]
+        self,
+        org_id: str | UUID,
+        messages: list[Dict[str, str]],
+        *,
+        model: str | None = None,
+        system: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        tools: list[Dict[str, Any]] | None = None,
+    ) -> ChatResponse:
+        """Non-streaming chat. Generator emits a body-only variant; this
+        convenience form accepts loose message dicts and constructs the
+        Pydantic request so ``chat`` and ``chat_stream`` share a call shape.
+        """
+        req = ChatRequest(
+            messages=[ChatMessage(**m) for m in messages],
+            model=model,
+            system=system,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=False,
+            tools=tools,
+        )
+        data = await self._request(
+            "POST",
+            f"/api/org/{org_id}/chat",
+            json=req.model_dump(mode="json", exclude_none=True),
+        )
+        return ChatResponse.model_validate(data)
+
+    async def chat_structured(  # type: ignore[override]
+        self,
+        org_id: str | UUID,
+        messages: list[Dict[str, str]],
+        *,
+        model: str | None = None,
+        system: str | None = None,
+        response_schema: Dict[str, Any] | None = None,
+    ) -> StructuredChatResponse:
+        """Structured chat with a JSON schema."""
+        req = StructuredChatRequest(
+            messages=[ChatMessage(**m) for m in messages],
+            model=model,
+            system=system,
+            response_schema=response_schema,
+        )
+        data = await self._request(
+            "POST",
+            f"/api/org/{org_id}/chat/structured",
+            json=req.model_dump(mode="json", exclude_none=True),
+        )
+        return StructuredChatResponse.model_validate(data)