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`
