docforge-sdk 0.1.0__py3-none-any.whl

docforge_sdk/resources/pipelines.py

@@ -0,0 +1,291 @@
+# ====== Code Summary ======
+# The pipelines resource — discovery + design of the pipeline graph surfaces. The graph JSON is OPAQUE
+# to the SDK: blob/operations/action pass through as plain dicts, only the typed ENVELOPE comes back.
+# All URL/body logic lives once in the pure _PipelinesSpecs mixin so the async/sync shells differ ONLY
+# by ``await``.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.pipelines import (
+    EditResponse,
+    InspectResponse,
+    PipelineDesignResponse,
+    PipelineIndexResponse,
+    StageApplyResponse,
+    StageViewResponse,
+)
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _PipelinesSpecs(_ResourceMixin):
+    """Pure ``RequestSpec`` builders for the pipeline endpoints — the single source of URL/body logic."""
+
+    _PIPELINES_PATH = "/pipelines"
+
+    def _list_surfaces_spec(self) -> RequestSpec:
+        """
+        Build the spec for discovering the available pipeline surfaces.
+
+        Returns:
+            RequestSpec: A GET on the pipelines index.
+        """
+        return RequestSpec("GET", self._PIPELINES_PATH)
+
+    def _get_design_spec(self, key: str, full: bool) -> RequestSpec:
+        """
+        Build the spec for opening a pipeline's design payload.
+
+        Args:
+            key (str): The pipeline key (e.g. ``"ingest"``).
+            full (bool): Whether to include the advanced palette blocks.
+
+        Returns:
+            RequestSpec: A GET on the pipeline resource, carrying the ``full`` query flag.
+        """
+        return RequestSpec("GET", f"{self._PIPELINES_PATH}/{key}", params={"full": full})
+
+    def _inspect_spec(self, key: str, blob: dict[str, Any]) -> RequestSpec:
+        """
+        Build the spec for inspecting an edited pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to inspect.
+
+        Returns:
+            RequestSpec: A POST to the pipeline's ``/inspect`` route.
+        """
+        return RequestSpec("POST", f"{self._PIPELINES_PATH}/{key}/inspect", json={"blob": blob})
+
+    def _edit_spec(
+        self, key: str, blob: dict[str, Any], operations: list[dict[str, Any]]
+    ) -> RequestSpec:
+        """
+        Build the spec for applying graph operations to a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the operations start from.
+            operations (list[dict[str, Any]]): The ordered, opaque edit operations.
+
+        Returns:
+            RequestSpec: A POST to the pipeline's ``/edit`` route.
+        """
+        return RequestSpec(
+            "POST",
+            f"{self._PIPELINES_PATH}/{key}/edit",
+            json={"blob": blob, "operations": operations},
+        )
+
+    def _view_stages_spec(self, key: str, blob: dict[str, Any]) -> RequestSpec:
+        """
+        Build the spec for deriving the stage view of a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to view as stages.
+
+        Returns:
+            RequestSpec: A POST to the pipeline's ``/stages/view`` route.
+        """
+        return RequestSpec("POST", f"{self._PIPELINES_PATH}/{key}/stages/view", json={"blob": blob})
+
+    def _apply_stage_spec(
+        self, key: str, blob: dict[str, Any], action: dict[str, Any]
+    ) -> RequestSpec:
+        """
+        Build the spec for compiling a stage action into a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the action starts from.
+            action (dict[str, Any]): The opaque stage action to apply.
+
+        Returns:
+            RequestSpec: A POST to the pipeline's ``/stages/apply`` route.
+        """
+        return RequestSpec(
+            "POST",
+            f"{self._PIPELINES_PATH}/{key}/stages/apply",
+            json={"blob": blob, "action": action},
+        )
+
+
+class AsyncPipelines(AsyncResource, _PipelinesSpecs):
+    """Asynchronous pipeline discovery + design surface."""
+
+    async def list_surfaces(self) -> PipelineIndexResponse:
+        """
+        Discover the pipeline design surfaces the backend serves.
+
+        Returns:
+            PipelineIndexResponse: One entry per available surface.
+        """
+        return await self._transport.request(self._list_surfaces_spec(), PipelineIndexResponse)
+
+    async def get_design(self, key: str, full: bool = True) -> PipelineDesignResponse:
+        """
+        Open a pipeline's design payload (palette + blob + issues).
+
+        Args:
+            key (str): The pipeline key (e.g. ``"ingest"``).
+            full (bool): Include the advanced palette blocks.
+
+        Returns:
+            PipelineDesignResponse: The design payload.
+        """
+        return await self._transport.request(
+            self._get_design_spec(key, full), PipelineDesignResponse
+        )
+
+    async def inspect(self, key: str, blob: dict[str, Any]) -> InspectResponse:
+        """
+        Inspect an edited pipeline blob (validity + issues + described tree).
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to inspect.
+
+        Returns:
+            InspectResponse: The described mirror of the blob.
+        """
+        return await self._transport.request(self._inspect_spec(key, blob), InspectResponse)
+
+    async def edit(
+        self, key: str, blob: dict[str, Any], operations: list[dict[str, Any]]
+    ) -> EditResponse:
+        """
+        Apply ordered graph operations to a pipeline blob, server-side.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the operations start from.
+            operations (list[dict[str, Any]]): The ordered, opaque edit operations.
+
+        Returns:
+            EditResponse: The edited blob plus validity + issues + described tree.
+        """
+        return await self._transport.request(self._edit_spec(key, blob, operations), EditResponse)
+
+    async def view_stages(self, key: str, blob: dict[str, Any]) -> StageViewResponse:
+        """
+        Derive the stage view of a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to view as stages.
+
+        Returns:
+            StageViewResponse: The ordered stages plus the validity verdict.
+        """
+        return await self._transport.request(self._view_stages_spec(key, blob), StageViewResponse)
+
+    async def apply_stage(
+        self, key: str, blob: dict[str, Any], action: dict[str, Any]
+    ) -> StageApplyResponse:
+        """
+        Compile a stage action into a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the action starts from.
+            action (dict[str, Any]): The opaque stage action to apply.
+
+        Returns:
+            StageApplyResponse: The recompiled blob plus its stage view, validity and notices.
+        """
+        return await self._transport.request(
+            self._apply_stage_spec(key, blob, action), StageApplyResponse
+        )
+
+
+class SyncPipelines(SyncResource, _PipelinesSpecs):
+    """Synchronous pipeline discovery + design surface."""
+
+    def list_surfaces(self) -> PipelineIndexResponse:
+        """
+        Discover the pipeline design surfaces the backend serves.
+
+        Returns:
+            PipelineIndexResponse: One entry per available surface.
+        """
+        return self._transport.request(self._list_surfaces_spec(), PipelineIndexResponse)
+
+    def get_design(self, key: str, full: bool = True) -> PipelineDesignResponse:
+        """
+        Open a pipeline's design payload (palette + blob + issues).
+
+        Args:
+            key (str): The pipeline key (e.g. ``"ingest"``).
+            full (bool): Include the advanced palette blocks.
+
+        Returns:
+            PipelineDesignResponse: The design payload.
+        """
+        return self._transport.request(self._get_design_spec(key, full), PipelineDesignResponse)
+
+    def inspect(self, key: str, blob: dict[str, Any]) -> InspectResponse:
+        """
+        Inspect an edited pipeline blob (validity + issues + described tree).
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to inspect.
+
+        Returns:
+            InspectResponse: The described mirror of the blob.
+        """
+        return self._transport.request(self._inspect_spec(key, blob), InspectResponse)
+
+    def edit(
+        self, key: str, blob: dict[str, Any], operations: list[dict[str, Any]]
+    ) -> EditResponse:
+        """
+        Apply ordered graph operations to a pipeline blob, server-side.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the operations start from.
+            operations (list[dict[str, Any]]): The ordered, opaque edit operations.
+
+        Returns:
+            EditResponse: The edited blob plus validity + issues + described tree.
+        """
+        return self._transport.request(self._edit_spec(key, blob, operations), EditResponse)
+
+    def view_stages(self, key: str, blob: dict[str, Any]) -> StageViewResponse:
+        """
+        Derive the stage view of a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob to view as stages.
+
+        Returns:
+            StageViewResponse: The ordered stages plus the validity verdict.
+        """
+        return self._transport.request(self._view_stages_spec(key, blob), StageViewResponse)
+
+    def apply_stage(
+        self, key: str, blob: dict[str, Any], action: dict[str, Any]
+    ) -> StageApplyResponse:
+        """
+        Compile a stage action into a pipeline blob.
+
+        Args:
+            key (str): The pipeline key.
+            blob (dict[str, Any]): The opaque graph blob the action starts from.
+            action (dict[str, Any]): The opaque stage action to apply.
+
+        Returns:
+            StageApplyResponse: The recompiled blob plus its stage view, validity and notices.
+        """
+        return self._transport.request(
+            self._apply_stage_spec(key, blob, action), StageApplyResponse
+        )
+
+
+__all__ = ["AsyncPipelines", "SyncPipelines"]

docforge_sdk/resources/search.py

@@ -0,0 +1,70 @@
+# ====== Code Summary ======
+# The search resource — a hybrid search over one collection's chunks. All URL/body logic lives once in
+# the pure _SearchSpecs mixin so AsyncSearch and SyncSearch differ ONLY by ``await``.
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.search import SearchRequest, SearchResponse
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _SearchSpecs(_ResourceMixin):
+    """Pure ``RequestSpec`` builders for the search endpoint — the single source of URL/body logic."""
+
+    _COLLECTIONS_PATH = "/collections"
+
+    def _search_spec(self, collection_id: str, request: SearchRequest) -> RequestSpec:
+        """
+        Build the spec for searching a collection.
+
+        Args:
+            collection_id (str): The collection to search.
+            request (SearchRequest): The query, filters and target modalities.
+
+        Returns:
+            RequestSpec: A POST to the collection's ``/search`` route carrying the query body.
+        """
+        return RequestSpec(
+            "POST",
+            f"{self._COLLECTIONS_PATH}/{collection_id}/search",
+            json=request.model_dump(mode="json"),
+        )
+
+
+class AsyncSearch(AsyncResource, _SearchSpecs):
+    """Asynchronous hybrid search."""
+
+    async def search(self, collection_id: str, request: SearchRequest) -> SearchResponse:
+        """
+        Run a hybrid search over a collection and return ranked, hydrated chunk hits.
+
+        Args:
+            collection_id (str): The collection to search.
+            request (SearchRequest): The query, filters and target modalities.
+
+        Returns:
+            SearchResponse: The echoed query and its hits, best first.
+        """
+        return await self._transport.request(
+            self._search_spec(collection_id, request), SearchResponse
+        )
+
+
+class SyncSearch(SyncResource, _SearchSpecs):
+    """Synchronous hybrid search."""
+
+    def search(self, collection_id: str, request: SearchRequest) -> SearchResponse:
+        """
+        Run a hybrid search over a collection and return ranked, hydrated chunk hits.
+
+        Args:
+            collection_id (str): The collection to search.
+            request (SearchRequest): The query, filters and target modalities.
+
+        Returns:
+            SearchResponse: The echoed query and its hits, best first.
+        """
+        return self._transport.request(self._search_spec(collection_id, request), SearchResponse)
+
+
+__all__ = ["AsyncSearch", "SyncSearch"]

docforge_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,36 @@
+docforge_sdk/__init__.py,sha256=XS61Q-rfIdy3TvxfSjw6zViGfUsUB9Y4ZKkjV_ltUZU,3876
+docforge_sdk/_exceptions.py,sha256=BrfgSn2Yq6dKSFg_i9FHDdWrb9N1HwwwbVKH4nAadmQ,3592
+docforge_sdk/_requestspec.py,sha256=HuRnpPA4O_lwXgByYekgJtpGNFss_fqZ6d_6ucSpfaY,1331
+docforge_sdk/_transport_async.py,sha256=bYfuah01yxKMzRlsMhyABzkTIxr8huyAbSOfp1hwVEo,6129
+docforge_sdk/_transport_base.py,sha256=120RPWiuhSD30TOKCqVC519nOgrOHIAMq5y8vkFhP_0,5317
+docforge_sdk/_transport_sync.py,sha256=OVTjKtvshj13K_AmRrTtLkCyahHXHtfKhT4ufSd4Wx4,6022
+docforge_sdk/_version.py,sha256=0LO1fk-0zhM_r0SLBJ2pX3jrF69BB9BM1EQETn22bDI,239
+docforge_sdk/client.py,sha256=vaKECQr8AgjUI-UmXoZEBeKgyMX2PgQ4wPTc0aF4uQw,5301
+docforge_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docforge_sdk/models/__init__.py,sha256=s9pkJbyoRWTz_5NHZ092RQg5WAUGi8KqE3N5udBGqf8,3166
+docforge_sdk/models/_shared.py,sha256=CmV2kKzJBVUj1Pkr0iq78fN51cNg7gEW-pMLM9D837c,3292
+docforge_sdk/models/auth.py,sha256=gTqJOz3l4k_aGzVA4Y8dMFIEgWiRTguYE4y4UCzSCTA,5635
+docforge_sdk/models/blobs.py,sha256=9e_xJiM6bc8F5gG97Bw7N0W2I2RjYyCxtvhDnooPZPc,888
+docforge_sdk/models/collections.py,sha256=qKJK8tt2jYWP87ScTUL3vTLzk8xpMzqfw8zsz96PCKE,6525
+docforge_sdk/models/documents.py,sha256=dJk5aC0uUy6Gda25yP3jpsrGs1XS8Lo1dWMz7McscNo,1809
+docforge_sdk/models/explorer.py,sha256=hqWYNY-dJSYJlUNcRxv4njwoKvM8kzBfIZ4ShS9Y5OQ,10761
+docforge_sdk/models/health.py,sha256=SSWeFtEh2R_eRBuIi2QXFEuy6lPDL03I9uaYC3ESNNk,602
+docforge_sdk/models/ir.py,sha256=2LClyD6_XuJQllc5WUeA32UqM1z30kDNC87IQAo-8us,6269
+docforge_sdk/models/jobs.py,sha256=I22srI1YGUdw1wwL5mOFe_43CMpplgpfXfOtmkFyQeM,3984
+docforge_sdk/models/pipelines.py,sha256=tf5aggvfetPsODEMP-UN77zbiGNmgWqpmXeT5uk5W1k,8054
+docforge_sdk/models/search.py,sha256=VKbO8JrgSiPN7yQt2vy9wxVu51JrYLtCWMz589l6QFU,4544
+docforge_sdk/resources/__init__.py,sha256=kGQed_gnpoo7LE6ViDH7GPm56po6oX7AsLiwqbITV4E,1534
+docforge_sdk/resources/_base.py,sha256=NoDy86ccGsyAZJEU2KjW3NYYJlsypvjmEkQtAdhaS04,1499
+docforge_sdk/resources/auth.py,sha256=a_6tIAX13BXasMN3TDeX7STSdbjZ7QiGMNX62q9y2mo,10042
+docforge_sdk/resources/blobs.py,sha256=SGAEF8XGytf72TQDOFaDEd89_Tj_w88JOOhxO0vrIBs,2182
+docforge_sdk/resources/collections.py,sha256=4yfkQwCcbH5Gj4rkStQeEiTxgzRPl1B8u09KMWe-cTA,6949
+docforge_sdk/resources/documents.py,sha256=p5hrYBwJeLn5Ay7TOfWAmc085h2F32KqbUgN8naHzBY,6114
+docforge_sdk/resources/explorer.py,sha256=BoDY-45Mp-7r097VNpzQOV974kfc_tmLH-ebWNsSDxM,11429
+docforge_sdk/resources/health.py,sha256=WL7_iTwu533R8s7yG8qhB_RUJV4eB6ytKXRDXcB3ILg,1723
+docforge_sdk/resources/jobs.py,sha256=gI679qu26o6RbayUcEsYxOGvwc_atYp40LD1JQkfdpM,5062
+docforge_sdk/resources/pipelines.py,sha256=2A4PY5-wt3nrl5e8vKpl59gE9ws4qXELs2SJci-2Z34,10474
+docforge_sdk/resources/search.py,sha256=b9H5gaRHxSWUukxbNvYMRfxA4CKo_Y-6Es6FVKMlJ4s,2522
+docforge_sdk-0.1.0.dist-info/METADATA,sha256=39g7orUkcmCPSB9YgQ2_zc6wmcdustB41Jlhr9K3Yko,3779
+docforge_sdk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+docforge_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=tyuGDFWUibVB0DmTCdzAPFQPBobDYEuQr1pDHxNLTHU,1071
+docforge_sdk-0.1.0.dist-info/RECORD,,

docforge_sdk-0.1.0.dist-info/WHEEL

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

docforge_sdk-0.1.0.dist-info/licenses/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.