docforge-sdk 0.1.0__tar.gz

docforge_sdk-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# ── Python ────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# ── Virtual environments ───────────────────────────────────
+.venv/
+venv/
+env/
+ENV/
+
+# ── uv ────────────────────────────────────────────────────
+.uv/
+
+# ── Secrets / credentials ─────────────────────────────────
+services/**/.env
+*.env
+!services/**/.env.example
+!.env.example
+# SeaweedFS S3 identity (real secret) — track only the placeholder template.
+services/**/s3_config.json
+!services/**/s3_config.json.example
+
+# ── Logs ──────────────────────────────────────────────────
+logs/
+*.log
+
+# ── Node / frontend build artifacts (location-independent) ──
+# Globbed so they match wherever the frontend lives (now src/docforge-rework/app/frontend/).
+**/node_modules/
+**/frontend/dist/
+# Stale .js outputs that shadow .tsx/.ts source — Vite resolves them with priority
+# and serves an old bundle.  We're TS-only (tsconfig has noEmit); any .js under a
+# frontend src/ is build artefact noise.
+**/frontend/src/**/*.js
+**/frontend/src/**/*.js.map
+# NOTE: src/api/generated.ts is NOW committed (tracked) so the build is reproducible
+# without a live backend — regenerate it with `npm run gen:types` after schema changes.
+
+# ── IDE / OS ──────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ── Claude Code / AI dev tooling (kept LOCAL, never published) ──
+# The whole .claude/ tree (agents, rules, commands, agent-memory, session data, knowledge graph)
+# and the MCP client config are internal AI-assisted-workflow tooling — not part of the public repo.
+.claude/
+.mcp.json
+
+# ── Alembic / migrations (keep structure, not generated) ──
+# src/docforge-rework/migrations/versions/*.py  # comment in to exclude
+
+# ── Test artifacts ────────────────────────────────────────
+.pytest_cache/
+.coverage
+htmlcov/
+# Note: the synthetic test corpus under src/docforge-rework/tests/corpus/documents/<ext>/ IS committed
+# (deterministic, loaded at test time); it is regenerated via tests/corpus/generation/ when builders change.
+
+# Vite dependency pre-bundling cache (regenerated by the dev server)
+**/.vite/
+
+# Playwright MCP session artifacts (snapshots / console logs from browser-driven checks)
+.playwright-mcp/
+
+# The pipeline BUILD module (blob models + PipelineBuilder) is SOURCE, not a build
+# artifact - re-include it from the global build/ rule above.
+!src/docforge-rework/shared/libs/pipelines/build/
+!src/docforge-rework/shared/libs/pipelines/build/**
+
+# The build/ unit-test package mirrors that source module - also SOURCE, not an artifact.
+!src/docforge-rework/tests/units/build/
+!src/docforge-rework/tests/units/build/**
+src/docforge-rework/app/frontend/scripts/node_modules/

docforge_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

docforge_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Barré
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docforge_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: docforge-sdk
+Version: 0.1.0
+Summary: Typed async + sync Python client for the DocForge REST API (standalone, zero server deps).
+Project-URL: Homepage, https://github.com/Florian-BARRE/docforge
+Project-URL: Repository, https://github.com/Florian-BARRE/docforge
+Project-URL: Issues, https://github.com/Florian-BARRE/docforge/issues
+Author: Florian Barré
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,async,client,docforge,document-intelligence,rag,retrieval,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# docforge-sdk
+
+A typed Python client for the [DocForge](https://github.com/Florian-BARRE/docforge) REST API. It
+ships **both** an asynchronous and a synchronous client with an identical surface, is fully
+type-hinted (`py.typed`), and has **zero dependency on the DocForge server tree** — it is a
+clean-room client that talks to the API over HTTP only (`httpx` + `pydantic` + hand-written models
+that mirror the public REST contract), so it can be vendored or published independently.
+
+## Install
+
+```bash
+pip install docforge-sdk
+```
+
+## Async usage
+
+```python
+import asyncio
+
+from docforge_sdk import AsyncClient, SearchRequest
+
+
+async def main() -> None:
+    async with AsyncClient("http://localhost:10040", api_token="df_root_...") as client:
+        collections = await client.collections.list()
+        for collection in collections:
+            print(collection.id, collection.name)
+
+        hits = await client.search.search(
+            collections[0].id,
+            SearchRequest(query="quarterly revenue", limit=5),
+        )
+        for hit in hits.hits:
+            print(hit.score, hit.text)
+
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+```python
+from docforge_sdk import Client, SearchRequest
+
+with Client("http://localhost:10040", api_token="df_root_...") as client:
+    collections = client.collections.list()
+    hits = client.search.search(
+        collections[0].id,
+        SearchRequest(query="quarterly revenue", limit=5),
+    )
+    for hit in hits.hits:
+        print(hit.score, hit.text)
+```
+
+The two clients expose the same resources and method signatures; the sync methods are the async ones
+without `await`. Available resource groups: `auth`, `health`, `collections`, `documents`, `explorer`,
+`search`, `jobs`, `blobs`, `pipelines`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). This SDK is deliberately licensed **MIT even though the parent DocForge
+repository is GPLv3**: it is a standalone, clean-room client (HTTP models only, no server code), so a
+permissive per-directory license is intentional and lets any project depend on it freely.
+
+## Publishing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing (OIDC)** — there is no API token stored in the
+repo. To cut a release, tag a commit with the `sdk-v<version>` prefix (the version must match
+`docforge_sdk/_version.py`) and push the tag:
+
+```bash
+git tag sdk-v0.1.0
+git push origin sdk-v0.1.0
+```
+
+The `.github/workflows/release-sdk.yml` workflow then builds and uploads the sdist + wheel.
+
+**One-time PyPI setup** (done once by the maintainer, before the first release):
+
+1. Reserve the project name `docforge-sdk` on PyPI.
+2. Under the project's *Publishing* settings, add a **GitHub trusted publisher** with:
+   - Owner: `Florian-BARRE`
+   - Repository: `docforge`
+   - Workflow name: `release-sdk.yml`
+   - Environment: `pypi`

docforge_sdk-0.1.0/README.md

@@ -0,0 +1,85 @@
+# docforge-sdk
+
+A typed Python client for the [DocForge](https://github.com/Florian-BARRE/docforge) REST API. It
+ships **both** an asynchronous and a synchronous client with an identical surface, is fully
+type-hinted (`py.typed`), and has **zero dependency on the DocForge server tree** — it is a
+clean-room client that talks to the API over HTTP only (`httpx` + `pydantic` + hand-written models
+that mirror the public REST contract), so it can be vendored or published independently.
+
+## Install
+
+```bash
+pip install docforge-sdk
+```
+
+## Async usage
+
+```python
+import asyncio
+
+from docforge_sdk import AsyncClient, SearchRequest
+
+
+async def main() -> None:
+    async with AsyncClient("http://localhost:10040", api_token="df_root_...") as client:
+        collections = await client.collections.list()
+        for collection in collections:
+            print(collection.id, collection.name)
+
+        hits = await client.search.search(
+            collections[0].id,
+            SearchRequest(query="quarterly revenue", limit=5),
+        )
+        for hit in hits.hits:
+            print(hit.score, hit.text)
+
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+```python
+from docforge_sdk import Client, SearchRequest
+
+with Client("http://localhost:10040", api_token="df_root_...") as client:
+    collections = client.collections.list()
+    hits = client.search.search(
+        collections[0].id,
+        SearchRequest(query="quarterly revenue", limit=5),
+    )
+    for hit in hits.hits:
+        print(hit.score, hit.text)
+```
+
+The two clients expose the same resources and method signatures; the sync methods are the async ones
+without `await`. Available resource groups: `auth`, `health`, `collections`, `documents`, `explorer`,
+`search`, `jobs`, `blobs`, `pipelines`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). This SDK is deliberately licensed **MIT even though the parent DocForge
+repository is GPLv3**: it is a standalone, clean-room client (HTTP models only, no server code), so a
+permissive per-directory license is intentional and lets any project depend on it freely.
+
+## Publishing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing (OIDC)** — there is no API token stored in the
+repo. To cut a release, tag a commit with the `sdk-v<version>` prefix (the version must match
+`docforge_sdk/_version.py`) and push the tag:
+
+```bash
+git tag sdk-v0.1.0
+git push origin sdk-v0.1.0
+```
+
+The `.github/workflows/release-sdk.yml` workflow then builds and uploads the sdist + wheel.
+
+**One-time PyPI setup** (done once by the maintainer, before the first release):
+
+1. Reserve the project name `docforge-sdk` on PyPI.
+2. Under the project's *Publishing* settings, add a **GitHub trusted publisher** with:
+   - Owner: `Florian-BARRE`
+   - Repository: `docforge`
+   - Workflow name: `release-sdk.yml`
+   - Environment: `pypi`

docforge_sdk-0.1.0/docforge_sdk/__init__.py

@@ -0,0 +1,161 @@
+# ------------------- Exceptions ------------------- #
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthError,
+    ConflictError,
+    DocForgeError,
+    NotFoundError,
+    UnprocessableError,
+)
+from ._version import __version__
+
+# ------------------- Clients ------------------- #
+from .client import AsyncClient, Client
+
+# ------------------- Shared vocabulary ------------------- #
+from .models._shared import (
+    Capability,
+    DocumentStatus,
+    EnrichmentKind,
+    EnrichmentStatus,
+    FieldOrigin,
+    FieldScope,
+    FieldType,
+    KeyPermissions,
+    SourceKind,
+)
+
+# ------------------- Auth models ------------------- #
+from .models.auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest
+
+# ------------------- Blobs models ------------------- #
+from .models.blobs import BlobContent
+
+# ------------------- Collections models ------------------- #
+from .models.collections import (
+    CollectionModel,
+    CreateCollectionRequest,
+    FieldSpec,
+    UpdateCollectionRequest,
+)
+
+# ------------------- Documents models ------------------- #
+from .models.documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+
+# ------------------- Explorer models ------------------- #
+from .models.explorer import (
+    BulkChunkEnabledPatch,
+    BulkChunkEnabledResponse,
+    ChunkEnabledPatch,
+    ChunkEnabledResult,
+    ChunkInfo,
+    DocumentDetail,
+    DocumentListItem,
+    MetadataValue,
+    PageInfo,
+)
+
+# ------------------- Health models ------------------- #
+from .models.health import HealthStatus
+
+# ------------------- IR models ------------------- #
+from .models.ir import DocumentIRModel, IRBlock, IREnrichment, IRFigure, IRTable
+
+# ------------------- Jobs models ------------------- #
+from .models.jobs import JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
+
+# ------------------- Pipelines models ------------------- #
+from .models.pipelines import (
+    EditResponse,
+    InspectResponse,
+    PipelineDesignResponse,
+    PipelineIndexResponse,
+    PipelineSurface,
+    StageApplyResponse,
+    StageViewResponse,
+)
+
+# ------------------- Search models ------------------- #
+from .models.search import SearchHit, SearchRequest, SearchResponse, SearchTarget
+
+# ------------------- Public API ------------------- #
+__all__ = [
+    "__version__",
+    # Clients
+    "AsyncClient",
+    "Client",
+    # Shared vocabulary
+    "Capability",
+    "KeyPermissions",
+    "FieldType",
+    "FieldOrigin",
+    "FieldScope",
+    "SourceKind",
+    "DocumentStatus",
+    "EnrichmentKind",
+    "EnrichmentStatus",
+    # Auth
+    "CreateKeyRequest",
+    "RotateKeyRequest",
+    "CreatedKey",
+    "KeyInfo",
+    # Health
+    "HealthStatus",
+    # Collections
+    "FieldSpec",
+    "CollectionModel",
+    "CreateCollectionRequest",
+    "UpdateCollectionRequest",
+    # Documents
+    "UploadAccepted",
+    "EnabledPatch",
+    "DocumentEnabledResponse",
+    # Explorer
+    "MetadataValue",
+    "DocumentListItem",
+    "DocumentDetail",
+    "PageInfo",
+    "ChunkInfo",
+    "ChunkEnabledPatch",
+    "BulkChunkEnabledPatch",
+    "ChunkEnabledResult",
+    "BulkChunkEnabledResponse",
+    # IR
+    "IRBlock",
+    "IRTable",
+    "IRFigure",
+    "IREnrichment",
+    "DocumentIRModel",
+    # Search
+    "SearchTarget",
+    "SearchRequest",
+    "SearchHit",
+    "SearchResponse",
+    # Jobs
+    "JobStatus",
+    "JobEvent",
+    "JobTrace",
+    "WorkerActivity",
+    "WorkersLive",
+    # Blobs
+    "BlobContent",
+    # Pipelines
+    "PipelineSurface",
+    "PipelineIndexResponse",
+    "PipelineDesignResponse",
+    "InspectResponse",
+    "EditResponse",
+    "StageViewResponse",
+    "StageApplyResponse",
+    # Exceptions
+    "DocForgeError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableError",
+]

docforge_sdk-0.1.0/docforge_sdk/_exceptions.py

@@ -0,0 +1,108 @@
+# ====== Code Summary ======
+# The public exception hierarchy for the SDK. Every failure a caller can catch descends from
+# ``DocForgeError``. Transport-level failures (no connection, timeout) and HTTP error statuses map to
+# dedicated subclasses so callers can branch on failure kind without inspecting raw httpx objects.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+import httpx
+
+
+class DocForgeError(Exception):
+    """Base class for every error raised by the DocForge SDK."""
+
+
+class APIConnectionError(DocForgeError):
+    """Raised when the API could not be reached (DNS, refused connection, network drop)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """Raised when a request exceeded the configured timeout before a response arrived."""
+
+
+class APIStatusError(DocForgeError):
+    """
+    Raised when the API returned a 4xx/5xx HTTP status.
+
+    Attributes:
+        status_code (int): The HTTP status code returned by the API.
+        body (Any): The parsed response body (JSON when decodable, else raw text) — an opaque,
+            server-shaped error payload.
+    """
+
+    def __init__(self, message: str, *, status_code: int, body: Any) -> None:
+        """
+        Initialize the status error with the failing code and response body.
+
+        Args:
+            message (str): Human-readable summary of the failure.
+            status_code (int): The HTTP status code returned by the API.
+            body (Any): The parsed response body (opaque server error payload).
+        """
+        super().__init__(message)
+        self.status_code: int = status_code
+        self.body: Any = body
+
+
+class AuthError(APIStatusError):
+    """Raised on 401 (unauthenticated) or 403 (unauthorized) responses."""
+
+
+class NotFoundError(APIStatusError):
+    """Raised on 404 responses (the target resource does not exist)."""
+
+
+class ConflictError(APIStatusError):
+    """Raised on 409 responses (the request conflicts with the resource's current state)."""
+
+
+class UnprocessableError(APIStatusError):
+    """Raised on 422 responses (the request body failed server-side validation)."""
+
+
+# Maps an HTTP status code to the most specific exception class for it.
+_STATUS_TO_EXCEPTION: dict[int, type[APIStatusError]] = {
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableError,
+}
+
+
+def exception_from_response(response: httpx.Response) -> APIStatusError:
+    """
+    Build the most specific ``APIStatusError`` for an errored HTTP response.
+
+    Args:
+        response (httpx.Response): The response whose status is 4xx/5xx.
+
+    Returns:
+        APIStatusError: A ``NotFoundError`` / ``AuthError`` / ``ConflictError`` /
+        ``UnprocessableError`` when the status is recognised, else a plain ``APIStatusError``.
+    """
+    # 1. Decode the body as JSON when possible; fall back to raw text for non-JSON errors.
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = response.text
+
+    # 2. Pick the dedicated subclass for this status, defaulting to the generic status error.
+    exception_class = _STATUS_TO_EXCEPTION.get(response.status_code, APIStatusError)
+    message = f"API request failed with status {response.status_code}"
+    return exception_class(message, status_code=response.status_code, body=body)
+
+
+__all__ = [
+    "DocForgeError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableError",
+    "exception_from_response",
+]

docforge_sdk-0.1.0/docforge_sdk/_requestspec.py

@@ -0,0 +1,34 @@
+# ====== Code Summary ======
+# The immutable description of a single HTTP call. A RequestSpec is pure data — it carries the method,
+# API-relative path and payload, and performs no I/O. Resource classes build specs; transports execute
+# them. Centralising URL/body shape here keeps it out of the async/sync transport bodies.
+
+# ====== Standard Library Imports ======
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RequestSpec:
+    """
+    An immutable, I/O-free description of one API request.
+
+    The ``json`` and ``files`` payloads are typed ``Any`` because they are opaque, endpoint-shaped
+    bodies already serialised by the calling resource (a model dump or an httpx multipart mapping).
+
+    Attributes:
+        method (str): The HTTP method (e.g. ``"GET"``, ``"POST"``, ``"DELETE"``).
+        path (str): The path relative to the API root (e.g. ``"/auth/keys"``).
+        params (dict[str, Any] | None): Query parameters; ``None`` values are dropped at execution.
+        json (Any): The JSON request body, or ``None`` for bodyless requests.
+        files (Any): The multipart file mapping for uploads, or ``None``.
+    """
+
+    method: str
+    path: str
+    params: dict[str, Any] | None = None
+    json: Any = None
+    files: Any = None
+
+
+__all__ = ["RequestSpec"]