forktex-intelligence 0.2.3__py3-none-any.whl

forktex_intelligence/streams.py

@@ -0,0 +1,152 @@
+# 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/>.
+
+"""SSE stream consumer and event parser for the Intelligence API.
+
+Parses Server-Sent Events from the Intelligence API into typed event
+objects. Handles the tool intercept flow where the CLI must execute
+local tools and post results back.
+
+SSE event types:
+    delta              - Text chunk from the LLM
+    tool_call          - Agent called a server-side tool (informational)
+    tool_result_needed - Agent needs a LOCAL tool executed by the CLI
+    usage              - Token usage statistics
+    error              - Server-side error
+    done               - Stream complete
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any, AsyncIterator, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SSEEventType(str, Enum):
+    DELTA = "delta"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT_NEEDED = "tool_result_needed"
+    USAGE = "usage"
+    ERROR = "error"
+    DONE = "done"
+
+
+class SSEEvent(BaseModel):
+    """Parsed SSE event from the Intelligence API."""
+
+    event: SSEEventType
+    data: Dict[str, Any] = Field(default_factory=dict)
+
+    # Convenience accessors
+    @property
+    def delta_text(self) -> str:
+        """Text chunk for delta events."""
+        return self.data.get("text", "")
+
+    @property
+    def tool_name(self) -> str:
+        """Tool name for tool_call / tool_result_needed events."""
+        return self.data.get("name", "")
+
+    @property
+    def tool_call_id(self) -> str:
+        """Call ID for tool_result_needed events."""
+        return self.data.get("call_id", "")
+
+    @property
+    def tool_arguments(self) -> Dict[str, Any]:
+        """Arguments for tool_result_needed events."""
+        return self.data.get("arguments", {})
+
+    @property
+    def input_tokens(self) -> int:
+        return self.data.get("input_tokens", 0)
+
+    @property
+    def output_tokens(self) -> int:
+        return self.data.get("output_tokens", 0)
+
+    @property
+    def error_message(self) -> str:
+        return self.data.get("message", "")
+
+
+async def parse_sse_stream(raw_lines: AsyncIterator[bytes]) -> AsyncIterator[SSEEvent]:
+    """Parse raw SSE lines into typed SSEEvent objects.
+
+    Handles the standard SSE format:
+        event: <type>
+        data: <json>
+
+        (blank line separates events)
+    """
+    event_type: Optional[str] = None
+    data_lines: list[str] = []
+
+    async for raw in raw_lines:
+        line = raw.decode("utf-8") if isinstance(raw, bytes) else raw
+        line = line.rstrip("\n\r")
+
+        if not line:
+            # Blank line = end of event
+            if event_type and data_lines:
+                data_str = "\n".join(data_lines)
+                try:
+                    data = json.loads(data_str)
+                except json.JSONDecodeError:
+                    data = {"text": data_str}
+
+                try:
+                    evt_type = SSEEventType(event_type)
+                except ValueError:
+                    evt_type = SSEEventType.DELTA
+
+                yield SSEEvent(event=evt_type, data=data)
+
+            event_type = None
+            data_lines = []
+            continue
+
+        if line.startswith("event:"):
+            event_type = line[len("event:") :].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[len("data:") :].strip())
+        elif line.startswith(":"):
+            # SSE comment, ignore
+            continue
+
+    # Handle trailing event without blank line
+    if event_type and data_lines:
+        data_str = "\n".join(data_lines)
+        try:
+            data = json.loads(data_str)
+        except json.JSONDecodeError:
+            data = {"text": data_str}
+        try:
+            evt_type = SSEEventType(event_type)
+        except ValueError:
+            evt_type = SSEEventType.DELTA
+        yield SSEEvent(event=evt_type, data=data)

forktex_intelligence-0.2.3.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: forktex-intelligence
+Version: 0.2.3
+Summary: Standalone Python SDK for the ForkTex Intelligence API — chat, agent runs, embeddings, retrieval, ecosystem indexing
+License-Expression: AGPL-3.0-only
+License-File: LICENSE
+License-File: NOTICE
+Author: FORKTEX
+Author-email: info@forktex.com
+Requires-Python: >=3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx (>=0.27.0,<1.0.0)
+Requires-Dist: httpx-sse (>=0.4.0,<1.0.0)
+Requires-Dist: pydantic (>=2.11.10,<3.0.0)
+Project-URL: Bug Tracker, https://github.com/forktex/intelligence/issues
+Project-URL: Homepage, https://intelligence.forktex.com
+Project-URL: Repository, https://github.com/forktex/intelligence
+Description-Content-Type: text/markdown
+
+# forktex-intelligence
+
+[![PyPI](https://img.shields.io/pypi/v/forktex-intelligence.svg)](https://pypi.org/project/forktex-intelligence/)
+[![Python](https://img.shields.io/pypi/pyversions/forktex-intelligence.svg)](https://pypi.org/project/forktex-intelligence/)
+[![License](https://img.shields.io/pypi/l/forktex-intelligence.svg)](https://github.com/forktex/intelligence/blob/master/sdk-py/LICENSE)
+
+Standalone Python SDK for the [ForkTex Intelligence](https://intelligence.forktex.com) API.
+
+`forktex-intelligence` is the high-level Python client for the ForkTex Intelligence platform: multi-provider LLM chat (streaming + structured), embeddings, vector search, content extraction (PDF / DOCX / HTML), and image / audio generation. It backs the `forktex intelligence ask / run / scrape` CLI commands and is also usable directly from any Python application.
+
+## Install
+
+```bash
+pip install forktex-intelligence
+```
+
+**Requires Python 3.12+.** Tested on 3.12, 3.13, 3.14.
+
+## Quick Start
+
+### Single-shot prompt
+
+```python
+from forktex_intelligence import Intelligence
+
+async with Intelligence(endpoint="https://intelligence.forktex.com/api", api_key="sk-...") as ai:
+    response = await ai.chat("Summarize the ForkTex stack in one sentence.")
+    print(response.text)
+```
+
+### Structured response (Pydantic schema)
+
+```python
+from pydantic import BaseModel
+from forktex_intelligence import Intelligence
+
+class Summary(BaseModel):
+    title: str
+    bullets: list[str]
+
+async with Intelligence(endpoint="...", api_key="...") as ai:
+    result = await ai.extract_structured(
+        prompt="Summarize the ForkTex stack.",
+        schema=Summary,
+    )
+    print(result.parsed.title, result.parsed.bullets)
+```
+
+### Streaming
+
+```python
+from forktex_intelligence import Intelligence
+
+async with Intelligence(endpoint="...", api_key="...") as ai:
+    async for chunk in ai.stream("Tell me a story."):
+        print(chunk, end="", flush=True)
+```
+
+## Configuration
+
+Pass endpoint and API key explicitly:
+
+```python
+Intelligence(endpoint="https://intelligence.forktex.com/api", api_key="sk-...")
+```
+
+Or via an `IntelligenceSettings` object:
+
+```python
+from forktex_intelligence import IntelligenceSettings, Intelligence
+
+settings = IntelligenceSettings(endpoint="...", api_key="...")
+async with Intelligence(settings=settings) as ai:
+    ...
+```
+
+When used via the `forktex` CLI, settings are loaded from environment variables and `.forktex/` config files automatically.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FORKTEX_INTELLIGENCE_ENDPOINT` | Intelligence API endpoint | `https://intelligence.forktex.com/api` |
+| `FORKTEX_INTELLIGENCE_API_KEY` | Intelligence API key | *(required)* |
+
+### Local dev (point at your `make local` stack)
+
+```bash
+export FORKTEX_INTELLIGENCE_ENDPOINT=http://localhost:8001/api
+export FORKTEX_INTELLIGENCE_API_KEY=dev-key
+```
+
+Or programmatically:
+
+```python
+from forktex_intelligence import Intelligence
+intel = Intelligence(endpoint="http://localhost:8001/api", api_key="dev-key")
+```
+
+## What's in the package
+
+| Module | Purpose |
+|--------|---------|
+| `forktex_intelligence.api` | High-level `Intelligence` client (chat, structured, stream) |
+| `forktex_intelligence.client` | Low-level `ForktexIntelligenceClient` (raw HTTP, advanced use) |
+| `forktex_intelligence.client.generated` | Wire-level Pydantic models (`ChatMessage`, `ChatResponse`, …) generated from the OpenAPI spec |
+| `forktex_intelligence.streams` | SSE event types and parser |
+| `forktex_intelligence.config` | `IntelligenceSettings` — endpoint, API key |
+
+All response models come from the OpenAPI codegen pipeline — one source of truth shared between the server and every consumer.
+
+## Repository
+
+This SDK lives inside the [`forktex/intelligence`](https://github.com/forktex/intelligence) monorepo alongside the API server (`api/`). The SDK package is independently versioned and published to PyPI.
+
+## Development
+
+The [`Makefile`](Makefile) is generated by `forktex fsd makefile sync` from [`forktex.json`](forktex.json) — do not hand-edit.
+
+```bash
+make help              # list every available target
+make deps              # editable install with the dev group
+make format            # ruff format
+make lint              # ruff check
+make test              # pytest tests/
+make codegen-check     # verify the generated client imports cleanly
+make build             # python3 -m build → dist/
+make ci                # format-check + lint + license-check + audit + test + build
+make clean             # remove caches and dist/
+```
+
+`make ci` is the single command that gates a publish: format-check, lint, dual-license header check, dependency CVE audit, full test suite, and `python -m build` + `twine check`.
+
+### License headers
+
+Every source file carries the AGPL-3.0 + Commercial dual-license SPDX header, applied idempotently via:
+
+```bash
+make license-check    # CI gate — fails if any source file is missing the header
+make license-fix      # add or refresh headers across src/, tests/, scripts/
+make license-strip    # remove headers (used before license-model changes)
+```
+
+## License
+
+Dual-licensed — **AGPL-3.0-or-later** for open-source use, **commercial** for everything else (proprietary products, SaaS without source release, redistribution in closed-source form). See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for the full terms.
+
+Commercial licensing inquiries: info@forktex.com.
+
+The 1.0.0 release on PyPI remains under MIT; from **0.2.3** onwards the package ships AGPL-3.0+Commercial.
+

forktex_intelligence-0.2.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+forktex_intelligence/__init__.py,sha256=VNHIHg8baW5riWebwQfFa0XWH8nN5RVhC-Oh4oIrMfo,2973
+forktex_intelligence/api.py,sha256=yVVmQTXdLKdYRDX59hfJbF-F2cB6DtqGhgYSovkMAuo,18891
+forktex_intelligence/client/__init__.py,sha256=7ObrskJeZU3PFTP7fMyAbKj0F1JadCosYvgPmEOJqfY,1791
+forktex_intelligence/client/client.py,sha256=QXCvC-LhhAZ2fRv9-GHNF6aadG4xSUbYXKG18FAQ1Lg,13520
+forktex_intelligence/client/generated/__init__.py,sha256=7PxlOmmIJkDNiTWnWG5TkbKQ6KdIn1NPLm6n1WyIZWg,24946
+forktex_intelligence/config.py,sha256=ALmcCBV5N3eXXyjLVPGq--sesUz3HC77T9Qsio6aN1A,1592
+forktex_intelligence/streams.py,sha256=UfTTZ2Hj8P6bar4Ecf42iiaIpbUmrkJKk7o6V5-r794,4870
+forktex_intelligence-0.2.3.dist-info/METADATA,sha256=9pfrFHfMJGKkGgVmMC2ffWMyBvw7bAUUyWS9uCvY1lk,6846
+forktex_intelligence-0.2.3.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+forktex_intelligence-0.2.3.dist-info/licenses/LICENSE,sha256=GDi3ClhZX_dyu2vvf5itrkTAyXulhKwrPMfcLV6y4dw,1928
+forktex_intelligence-0.2.3.dist-info/licenses/NOTICE,sha256=quL5izPaAI8iJZvXNTPnD0gZpAZ--k_VxECDbz-enro,1051
+forktex_intelligence-0.2.3.dist-info/RECORD,,

forktex_intelligence-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any

forktex_intelligence-0.2.3.dist-info/licenses/LICENSE

@@ -0,0 +1,45 @@
+forktex-intelligence -- Dual License
+
+Copyright (C) 2026 FORKTEX S.R.L.
+
+This software is licensed under a dual-license model:
+
+============================================================================
+
+1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
+
+   You may use, modify, and redistribute this software under the terms of the
+   GNU Affero General Public License v3.0 or later, as published by the Free
+   Software Foundation. The full license text is available at:
+   https://www.gnu.org/licenses/agpl-3.0.html
+
+   Key obligations under AGPL-3.0:
+   - Any modified version MUST be released under the same AGPL-3.0 license.
+   - If you run a modified version on a server and let users interact with it
+     over a network, you MUST make the complete source code available to those
+     users under AGPL-3.0.
+   - You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
+
+============================================================================
+
+2. COMMERCIAL LICENSE
+
+   If you wish to use this software without the obligations of AGPL-3.0 --
+   for example, to keep your modifications proprietary, to embed this software
+   in a closed-source product, or to operate it as part of a commercial service
+   without releasing your source code -- you MUST obtain a commercial license
+   from FORKTEX S.R.L.
+
+   Commercial licensing includes, but is not limited to:
+   - SaaS / hosted deployments generating revenue
+   - Embedding in proprietary products or platforms
+   - Redistribution in closed-source form
+   - Use by organizations exceeding the AGPL-3.0 compliance scope
+
+   For commercial licensing inquiries, contact:
+     info@forktex.com
+
+============================================================================
+
+Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
+your use of this software is governed exclusively by the AGPL-3.0 license.

forktex_intelligence-0.2.3.dist-info/licenses/NOTICE

@@ -0,0 +1,22 @@
+forktex-intelligence
+Copyright (C) 2026 FORKTEX S.R.L.
+
+forktex-intelligence is the standalone Python SDK for the ForkTex Intelligence
+API. It provides the typed httpx-based client (sync + streaming over SSE),
+generated Pydantic models for the Intelligence OpenAPI surface, and helpers
+for chat, agent runs, embeddings, retrieval, and ecosystem indexing.
+
+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/>.
+
+For commercial licensing inquiries, contact: info@forktex.com