forktex-intelligence 0.2.3__py3-none-any.whl

forktex_intelligence/__init__.py

@@ -0,0 +1,97 @@
+# 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 — Standalone Python SDK for the ForkTex Intelligence API.
+
+Three pillars:
+  1. Smart API — LLM chat/structured output, proxied to best providers
+  2. Content Extraction — Upload any file, get structured text + chunks
+  3. Vector Space — Managed vector storage with semantic search
+
+Usage::
+
+    from forktex_intelligence import Intelligence
+
+    async with Intelligence(org_id="my-org-uuid") as ai:
+        # Chat
+        response = await ai.chat("Explain Python decorators")
+
+        # Extract text from a file
+        result = await ai.extract_file(pdf_bytes, "paper.pdf")
+
+        # Search across collections
+        results = await ai.search("collection-id", "quantum computing")
+"""
+
+__version__ = "0.2.3"
+
+from forktex_intelligence.api import (
+    AvailableModel,
+    Intelligence,
+    Response,
+    StructuredResponse,
+    StreamChunks,
+)
+from forktex_intelligence.config import IntelligenceSettings
+from forktex_intelligence.client.client import (
+    ForktexIntelligenceClient,
+    IntelligenceAPIError,
+)
+from forktex_intelligence.client.generated import (
+    SPEC_HASH,
+    SPEC_VERSION,
+    ChatMessage,
+    ChatResponse,
+    HealthResponse,
+    StructuredChatResponse,
+    ToolCallInfo,
+    UsageInfo,
+)
+from forktex_intelligence.streams import SSEEvent, SSEEventType
+
+__all__ = [
+    # High-level API
+    "AvailableModel",
+    "Intelligence",
+    "Response",
+    "StructuredResponse",
+    "StreamChunks",
+    # Configuration
+    "IntelligenceSettings",
+    # Low-level client (advanced)
+    "ForktexIntelligenceClient",
+    "IntelligenceAPIError",
+    # Codegen contract (wire-compatibility markers)
+    "SPEC_VERSION",
+    "SPEC_HASH",
+    # Wire-level models (advanced — prefer high-level API)
+    "ChatMessage",
+    "ChatResponse",
+    "HealthResponse",
+    "StructuredChatResponse",
+    "ToolCallInfo",
+    "UsageInfo",
+    # Streaming
+    "SSEEvent",
+    "SSEEventType",
+]

forktex_intelligence/api.py

@@ -0,0 +1,544 @@
+# 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/>.
+
+"""High-level wrapping API for the ForkTex Intelligence API.
+
+Provides a user-friendly interface for the Intelligence platform:
+  - Smart API (chat, streaming, structured output)
+  - Content Extraction (upload file → text + chunks)
+  - Vector Space (collections, documents, search)
+
+Usage::
+
+    from forktex_intelligence import Intelligence
+
+    async with Intelligence() as ai:
+        # Simple chat
+        response = await ai.chat("What is Python?")
+        print(response.text)
+
+        # Extract text from a file
+        result = await ai.extract_file(pdf_bytes, "paper.pdf")
+        print(result["text"])
+
+        # Search across collections
+        results = await ai.search("my-collection-id", "quantum computing")
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Dict, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from forktex_intelligence.config import IntelligenceSettings
+from forktex_intelligence.client.client import ForktexIntelligenceClient
+from forktex_intelligence.client.generated import (
+    ChatResponse,
+    CollectionCreateRequest,
+    CollectionListResponse,
+    CollectionResponse,
+    CrossCollectionSearchRequest,
+    DocumentListResponse,
+    DocumentResponse,
+    EmbedRequest,
+    HealthResponse,
+    OrgResponse,
+    RerankRequest,
+    SearchRequest,
+    SearchResponse,
+    StructuredChatResponse,
+    UsageAggregation,
+    UsageLogResponse,
+)
+from forktex_intelligence.streams import SSEEventType, parse_sse_stream
+
+
+class AvailableModel(BaseModel):
+    """A model available through the Intelligence API."""
+
+    id: str
+    description: str = ""
+
+    def __str__(self) -> str:
+        return self.id
+
+    def __repr__(self) -> str:
+        return f"AvailableModel({self.id!r})"
+
+
+class Response(BaseModel):
+    """Response from a chat completion."""
+
+    text: str
+    model: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    tool_calls: list[dict[str, Any]] = Field(default_factory=list)
+    raw: Dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return len(self.tool_calls) > 0
+
+    def __str__(self) -> str:
+        return self.text
+
+    def __repr__(self) -> str:
+        return f"Response(text={self.text!r}, model={self.model!r})"
+
+    @classmethod
+    def from_chat_response(cls, resp: ChatResponse) -> Response:
+        return cls(
+            text=resp.content,
+            model=resp.model,
+            input_tokens=resp.usage.input_tokens if resp.usage else 0,
+            output_tokens=resp.usage.output_tokens if resp.usage else 0,
+            tool_calls=[tc.model_dump() for tc in (resp.tool_calls or [])],
+            raw=resp.model_dump(),
+        )
+
+
+class StructuredResponse(BaseModel):
+    """Response from a structured chat completion."""
+
+    data: Dict[str, Any]
+    model: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    def __getitem__(self, key: str) -> Any:
+        return self.data[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default)
+
+    @classmethod
+    def from_structured_response(cls, resp: StructuredChatResponse) -> StructuredResponse:
+        raw = resp.content
+        if isinstance(raw, str):
+            try:
+                raw = json.loads(raw)
+            except Exception:
+                pass
+        if not isinstance(raw, dict):
+            raw = {"value": raw}
+        return cls(
+            data=raw,
+            model=resp.model,
+            input_tokens=resp.usage.input_tokens if resp.usage else 0,
+            output_tokens=resp.usage.output_tokens if resp.usage else 0,
+        )
+
+
+class StreamChunks:
+    """Async iterator wrapping raw SSE chat_stream bytes."""
+
+    def __init__(self, raw_stream: AsyncIterator[bytes]) -> None:
+        self._raw = raw_stream
+        self._iterator: Optional[AsyncIterator[str]] = None
+        self._tool_calls: list[dict[str, Any]] = []
+        self._text_parts: list[str] = []
+        self._usage: Dict[str, int] = {}
+        self._model: str = ""
+
+    def __aiter__(self) -> StreamChunks:
+        self._iterator = parse_sse_stream(self._raw)
+        return self
+
+    async def __anext__(self) -> str:
+        assert self._iterator is not None
+        async for event in self._iterator:
+            if event.event == SSEEventType.DELTA:
+                chunk = event.delta_text
+                self._text_parts.append(chunk)
+                return chunk
+            if event.event == SSEEventType.TOOL_CALL:
+                self._tool_calls.append(event.data)
+            if event.event == SSEEventType.USAGE:
+                self._usage["input_tokens"] = event.input_tokens
+                self._usage["output_tokens"] = event.output_tokens
+            if event.event == SSEEventType.DONE:
+                raise StopAsyncIteration
+        raise StopAsyncIteration
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return len(self._tool_calls) > 0
+
+    async def collect(self) -> Response:
+        async for _ in self:
+            pass
+        return Response(
+            text="".join(self._text_parts),
+            model=self._model,
+            input_tokens=self._usage.get("input_tokens", 0),
+            output_tokens=self._usage.get("output_tokens", 0),
+            tool_calls=self._tool_calls,
+        )
+
+
+class Intelligence:
+    """High-level client for the ForkTex Intelligence API.
+
+    Supports org-scoped operations and dual auth (JWT or API key). Wraps
+    ``ForktexIntelligenceClient`` (which itself inherits the generated
+    ``_GeneratedOperations`` surface from ``openapi.json``) with an
+    ergonomic facade that injects the active org_id into every org-scoped
+    call.
+
+    Usage::
+
+        async with Intelligence(org_id="my-org-uuid") as ai:
+            response = await ai.chat("Hello!")
+            results = await ai.search("coll-id", "semantic query")
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        jwt_token: Optional[str] = None,
+        org_id: Optional[str | UUID] = None,
+        timeout: float = 120.0,
+        settings: Optional[IntelligenceSettings] = None,
+        transport: Any = None,
+    ) -> None:
+        if settings is not None:
+            self._settings = settings
+        else:
+            self._settings = IntelligenceSettings(
+                endpoint=endpoint or IntelligenceSettings.model_fields["endpoint"].default,
+                api_key=api_key or "",
+            )
+
+        if not self._settings.is_configured:
+            raise RuntimeError(
+                "Intelligence API not configured. Provide endpoint and api_key "
+                "via constructor arguments or an IntelligenceSettings object."
+            )
+
+        self._client = ForktexIntelligenceClient(
+            self._settings.endpoint,
+            self._settings.api_key,
+            jwt_token=jwt_token or "",
+            org_id=org_id,
+            timeout=timeout,
+            transport=transport,
+        )
+        self._needs_org_resolve = not org_id and not self._client.org_id
+
+    @property
+    def client(self) -> ForktexIntelligenceClient:
+        return self._client
+
+    def set_org(self, org_id: str | UUID) -> None:
+        """Set the org for org-scoped requests."""
+        self._client.set_org(org_id)
+
+    async def close(self) -> None:
+        await self._client.close()
+
+    @property
+    def _org(self) -> UUID:
+        """Return active org_id as a UUID; raise if not set."""
+        if not self._client.org_id:
+            raise RuntimeError("No org_id set. Call set_org(org_id) first.")
+        return UUID(self._client.org_id)
+
+    async def _ensure_org(self) -> None:
+        """Auto-resolve org_id from API key if not set."""
+        if self._needs_org_resolve and self._client.api_key:
+            await self._client.whoami()
+            self._needs_org_resolve = False
+
+    async def __aenter__(self) -> Intelligence:
+        await self._ensure_org()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    # ── Auth ─────────────────────────────────────────────────────────
+
+    async def register(self, email: str, password: str) -> Dict[str, Any]:
+        """Register a new user. Auto-sets JWT for subsequent requests."""
+        return await self._client.register(email, password)
+
+    async def login(self, email: str, password: str) -> Dict[str, Any]:
+        """Login and get JWT. Auto-sets JWT for subsequent requests."""
+        return await self._client.login(email, password)
+
+    async def me(self) -> Any:
+        """Get current user info and orgs."""
+        return await self._client.me()
+
+    async def create_org(self, name: str, slug: str) -> OrgResponse:
+        """Create an org and auto-set it as current."""
+        return await self._client.create_org(name, slug)
+
+    # ── Smart API (Pillar 1) ─────────────────────────────────────────
+
+    async def chat(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        system: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Response:
+        """Send a chat message and get the complete response."""
+        if messages is None:
+            messages = []
+            if system:
+                messages.append({"role": "system", "content": system})
+            messages.append({"role": "user", "content": prompt})
+
+        resp = await self._client.chat(
+            self._org,
+            messages,
+            model=model,
+            system=system if messages != [] else None,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            tools=tools,
+        )
+        return Response.from_chat_response(resp)
+
+    def stream(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        system: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> StreamChunks:
+        """Send a chat message and stream the response."""
+        if messages is None:
+            messages = []
+            if system:
+                messages.append({"role": "system", "content": system})
+            messages.append({"role": "user", "content": prompt})
+
+        raw = self._client.chat_stream(
+            self._org,
+            messages,
+            model=model,
+            system=system if messages != [] else None,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            tools=tools,
+        )
+        return StreamChunks(raw)
+
+    async def extract_structured(
+        self,
+        prompt: str,
+        *,
+        schema: Dict[str, Any],
+        model: Optional[str] = None,
+        system: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+    ) -> StructuredResponse:
+        """Get a structured JSON response matching a schema."""
+        if messages is None:
+            messages = [{"role": "user", "content": prompt}]
+
+        resp = await self._client.chat_structured(
+            self._org,
+            messages,
+            model=model,
+            system=system,
+            response_schema=schema,
+        )
+        return StructuredResponse.from_structured_response(resp)
+
+    # ── Content Extraction (Pillar 2) ────────────────────────────────
+
+    async def extract_file(
+        self,
+        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 and get extracted text + chunks back (no storage)."""
+        return await self._client.extract_file(
+            self._org,
+            file_data,
+            filename,
+            content_type=content_type,
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+        )
+
+    # ── Vector Space (Pillar 3) ──────────────────────────────────────
+
+    async def list_collections(self) -> CollectionListResponse:
+        return await self._client.list_colls(self._org)
+
+    async def create_collection(
+        self,
+        name: str,
+        *,
+        embedding_model: str = "all-MiniLM-L6-v2",
+        distance_metric: str = "cosine",
+    ) -> CollectionResponse:
+        body = CollectionCreateRequest(
+            name=name,
+            embedding_model=embedding_model,
+            distance_metric=distance_metric,
+        )
+        return await self._client.create_coll(self._org, body=body)
+
+    async def get_collection(self, collection_id: str | UUID) -> CollectionResponse:
+        return await self._client.get_coll(self._org, UUID(str(collection_id)))
+
+    async def delete_collection(self, collection_id: str | UUID) -> None:
+        await self._client.delete_coll(self._org, UUID(str(collection_id)))
+
+    async def upload_document(
+        self,
+        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 vector indexing."""
+        return await self._client.upload_document(
+            self._org,
+            collection_id,
+            file_data,
+            filename,
+            content_type=content_type,
+        )
+
+    async def list_documents(self, collection_id: str | UUID) -> DocumentListResponse:
+        return await self._client.list_docs(self._org, UUID(str(collection_id)))
+
+    async def get_document(self, collection_id: str | UUID, document_id: str | UUID) -> DocumentResponse:
+        return await self._client.get_doc(self._org, UUID(str(collection_id)), UUID(str(document_id)))
+
+    async def delete_document(self, collection_id: str | UUID, document_id: str | UUID) -> None:
+        await self._client.delete_doc(self._org, UUID(str(collection_id)), UUID(str(document_id)))
+
+    async def search(
+        self,
+        collection_id: str | UUID,
+        query: str,
+        *,
+        top_k: int = 10,
+        rerank: bool = False,
+        rerank_top_k: int = 5,
+    ) -> SearchResponse:
+        """Search a single collection."""
+        body = SearchRequest(query=query, top_k=top_k, rerank=rerank, rerank_top_k=rerank_top_k)
+        return await self._client.search_single(self._org, UUID(str(collection_id)), body=body)
+
+    async def search_cross(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        collection_ids: Optional[List[str]] = None,
+        rerank: bool = False,
+        rerank_top_k: int = 5,
+    ) -> SearchResponse:
+        """Search across multiple or all org collections."""
+        body = CrossCollectionSearchRequest(
+            query=query,
+            top_k=top_k,
+            collection_ids=[UUID(c) for c in (collection_ids or [])] or None,
+            rerank=rerank,
+            rerank_top_k=rerank_top_k,
+        )
+        return await self._client.search_cross(self._org, body=body)
+
+    # ── Embeddings ───────────────────────────────────────────────────
+
+    async def embed(
+        self,
+        texts: List[str],
+        *,
+        model: str = "all-MiniLM-L6-v2",
+        normalize: bool = True,
+    ) -> List[List[float]]:
+        """Generate embeddings for a list of texts."""
+        body = EmbedRequest(input=texts, model=model, normalize=normalize)
+        result = await self._client.embed(self._org, body=body)
+        return [item.embedding for item in result.data]
+
+    async def rerank(
+        self,
+        query: str,
+        documents: List[str],
+        *,
+        model: str = "all-MiniLM-L6-v2",
+        top_k: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Rerank documents by relevance to a query."""
+        body = RerankRequest(query=query, documents=documents, model=model, top_k=top_k)
+        result = await self._client.rerank(self._org, body=body)
+        return [item.model_dump() for item in result.data]
+
+    # ── Platform ─────────────────────────────────────────────────────
+
+    async def get_usage(self, **params: Any) -> UsageAggregation:
+        return await self._client.usage_stats(self._org, **params)
+
+    async def get_usage_log(self, **params: Any) -> UsageLogResponse:
+        return await self._client.usage_log(self._org, **params)
+
+    async def models(self) -> List[AvailableModel]:
+        resp = await self._client.list_models()
+        return [AvailableModel(id=m.id, description=m.description) for m in resp.models]
+
+    async def health(self) -> HealthResponse:
+        return await self._client.health()
+
+    async def is_healthy(self) -> bool:
+        try:
+            await self._client.health()
+            return True
+        except Exception:
+            return False

forktex_intelligence/client/__init__.py

@@ -0,0 +1,56 @@
+# 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.client — HTTP client and generated models for the Intelligence API."""
+
+from forktex_intelligence.client.client import (
+    ForktexIntelligenceClient,
+    IntelligenceAPIError,
+)
+from forktex_intelligence.client.generated import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    HealthResponse,
+    ModelInfo,
+    ModelsResponse,
+    StructuredChatRequest,
+    StructuredChatResponse,
+    ToolCallInfo,
+    UsageInfo,
+)
+
+__all__ = [
+    "ForktexIntelligenceClient",
+    "IntelligenceAPIError",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "HealthResponse",
+    "ModelInfo",
+    "ModelsResponse",
+    "StructuredChatRequest",
+    "StructuredChatResponse",
+    "ToolCallInfo",
+    "UsageInfo",
+]