inferhub-client 0.1.0__tar.gz

inferhub_client-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# ---------------------------------------------------------------------------
+# Internal build briefs — not part of the public repository. Keep them local.
+#
+# plans/CLAUDE.md is the one exception: it is the *format* rather than a brief,
+# and the root CLAUDE.md points at it, so a fresh clone that lacked it would
+# teach a reader the context does not exist rather than that it is local.
+#
+# The `/plans/*` form is required, not cosmetic — git does not descend into an
+# excluded *directory*, so `plans/` followed by a negation matches nothing.
+# ---------------------------------------------------------------------------
+/plans/*
+!/plans/CLAUDE.md
+
+# ---------------------------------------------------------------------------
+# .NET / Visual Studio
+# ---------------------------------------------------------------------------
+bin/
+obj/
+out/
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+[Bb]uild/
+[Bb]in/
+[Oo]bj/
+*.user
+*.userosscache
+*.suo
+*.sln.docstates
+.vs/
+.vscode/
+*.swp
+*~
+
+# Build results / packages
+*.dll
+*.exe
+*.pdb
+*.nupkg
+*.snupkg
+project.lock.json
+project.fragment.lock.json
+artifacts/
+nupkgs/
+
+# Test results
+[Tt]est[Rr]esult*/
+*.trx
+*.coverage
+*.coveragexml
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Rider / JetBrains
+.idea/
+*.sln.iml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local secrets / env
+*.env
+*.secrets
+
+# ---------------------------------------------------------------------------
+# Python
+# ---------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+python/dist/
+python/build/
+python/.venv/
+.venv/

inferhub_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dev Art Solutions
+
+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.

inferhub_client-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: inferhub-client
+Version: 0.1.0
+Summary: A small, typed Python client for InferHub — a self-hosted, Ollama-compatible inference mesh.
+Project-URL: Homepage, https://github.com/Dev-Art-Solutions/InferHub.Clients
+Project-URL: Repository, https://github.com/Dev-Art-Solutions/InferHub.Clients
+Project-URL: Issues, https://github.com/Dev-Art-Solutions/InferHub.Clients/issues
+Author: Dev Art Solutions
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: ruff==0.15.13; extra == 'test'
+Description-Content-Type: text/markdown
+
+# inferhub-client — the Python client
+
+[![PyPI](https://img.shields.io/pypi/v/inferhub-client.svg)](https://pypi.org/project/inferhub-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A small, typed Python client for [InferHub](https://github.com/Dev-Art-Solutions/InferHub) — a
+self-hosted, Ollama-compatible inference mesh. `v0.1.0` is the **core** surface: chat, generate
+(blocking and streaming), embeddings, model listing, status and health. Retrieval (vectors, RAG,
+ingestion, search) lands in `0.2.0`; modalities, admin and the node in `1.0.0` — see
+`plans/roadmap-polyglot-clients.md` for the shape of the rest of the track.
+
+**One dependency: `httpx`.** No pydantic — dataclasses do the job and every response type carries an
+`extra` dict for fields this version does not know about yet, the same escape hatch the C# client's
+`[JsonExtensionData]` gives it.
+
+## Install
+
+```
+pip install inferhub-client
+```
+
+## Quick start
+
+Sync:
+
+```python
+from inferhub_client import InferHubClient, ChatMessage, ChatRequest
+
+with InferHubClient("http://localhost:5080/", api_key="sk-client-token-1") as client:
+    answer = client.chat(ChatRequest(
+        model="llama3",
+        messages=[ChatMessage(role="user", content="Say hi in one word.")],
+    ))
+    print(answer.message.content)
+```
+
+Async — the same shapes, `await`ed:
+
+```python
+import asyncio
+from inferhub_client import AsyncInferHubClient, ChatMessage, ChatRequest
+
+async def main():
+    async with AsyncInferHubClient("http://localhost:5080/", api_key="sk-client-token-1") as client:
+        answer = await client.chat(ChatRequest(
+            model="llama3",
+            messages=[ChatMessage(role="user", content="Say hi in one word.")],
+        ))
+        print(answer.message.content)
+
+asyncio.run(main())
+```
+
+`InferHubClient` and `AsyncInferHubClient` are **two thin façades over the same rules**
+(`_base.py`'s header building, error mapping and NDJSON parsing) rather than one client with a
+sync-over-`asyncio.run` shim — the latter breaks the moment a sync call happens inside code that is
+already running an event loop, which is exactly where a web framework's request handler lives.
+
+## API surface (v0.1.0)
+
+| Method | Endpoint |
+|---|---|
+| `list_models()` | `GET /api/tags` |
+| `chat(request)` | `POST /api/chat` with `stream:false` |
+| `chat_stream(request)` | `POST /api/chat` with `stream:true` — an iterator/async iterator of `ChatResponse` |
+| `generate(request)` | `POST /api/generate` with `stream:false` |
+| `generate_stream(request)` | `POST /api/generate` with `stream:true` |
+| `embed(request)` | `POST /api/embed` (batch — a string or a list of strings) |
+| `embed_legacy(request)` | `POST /api/embeddings` (legacy single prompt) |
+| `get_status()` | `GET /api/status` |
+| `ping()` | `GET /health` — `True`/`False`, never raises for a non-success status |
+
+## Streaming
+
+```python
+for chunk in client.chat_stream(ChatRequest(model="llama3", messages=[...])):
+    print(chunk.message.content, end="", flush=True)
+```
+
+A terminal error chunk (`{"error": "...", "done": true}`) raises `InferHubError` out of the loop
+instead of the iterator hanging or ending quietly with a partial answer nobody was told about.
+
+## Errors
+
+Every non-success response raises `InferHubError(status_code, message, response_body,
+retry_after=...)`. `retry_after` is populated from `Retry-After` when the hub sends one — the
+refusals that carry it are the ones worth retrying rather than only reporting.
+
+```python
+from inferhub_client import InferHubError
+
+try:
+    client.embed(EmbedRequest.from_text("nomic-embed-text", "hello"))
+except InferHubError as e:
+    print(e.status_code, e.message, e.retry_after)
+```
+
+## `extra`: the fields this version does not know about yet
+
+`ChatRequest`/`GenerateRequest.extra` merges straight into the request body (Ollama's `options`,
+`format`, `keep_alive`, tool definitions — anything the hub accepts that this client has not typed);
+every response dataclass keeps unrecognized fields in its own `.extra` dict on the way back. Typing
+every Ollama option was considered and rejected, same as the C# client: the hub owns that schema and
+grows it independently of this package's release cadence.
+
+## A node as a target
+
+A solo InferHub node serves this same Ollama-dialect surface on its own address — pointing
+`InferHubClient`/`AsyncInferHubClient` at a node's URL instead of a coordinator's is the whole of
+"run it locally." `probe()` and the node-only routes (`/api/version`, the `/api/collections`
+lifecycle) land in `1.0.0`, mirroring the C# client's phase 14 (`14 D7`).
+
+## Development
+
+```
+pip install -e ".[test]"
+pytest                              # 31 pass, 9 skipped (cases outside v0.1.0's surface, see below)
+ruff check src tests examples
+ruff format --check src tests examples
+```
+
+`tests/test_conformance.py` drives the shared corpus at `../conformance/cases.json` — the same file
+the C# client's `ConformanceCorpusTests.cs` reads. A case whose `kind` this client does not cover
+yet (retrieval, the node, the OpenAI dialect) is skipped with a named reason rather than silently
+omitted; four cases (the mid-stream terminal error, `424` vs `404`, both `X-InferHub-Sources`
+shapes) pass today, unmodified, because the corpus already knew the answer.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

inferhub_client-0.1.0/README.md

@@ -0,0 +1,130 @@
+# inferhub-client — the Python client
+
+[![PyPI](https://img.shields.io/pypi/v/inferhub-client.svg)](https://pypi.org/project/inferhub-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A small, typed Python client for [InferHub](https://github.com/Dev-Art-Solutions/InferHub) — a
+self-hosted, Ollama-compatible inference mesh. `v0.1.0` is the **core** surface: chat, generate
+(blocking and streaming), embeddings, model listing, status and health. Retrieval (vectors, RAG,
+ingestion, search) lands in `0.2.0`; modalities, admin and the node in `1.0.0` — see
+`plans/roadmap-polyglot-clients.md` for the shape of the rest of the track.
+
+**One dependency: `httpx`.** No pydantic — dataclasses do the job and every response type carries an
+`extra` dict for fields this version does not know about yet, the same escape hatch the C# client's
+`[JsonExtensionData]` gives it.
+
+## Install
+
+```
+pip install inferhub-client
+```
+
+## Quick start
+
+Sync:
+
+```python
+from inferhub_client import InferHubClient, ChatMessage, ChatRequest
+
+with InferHubClient("http://localhost:5080/", api_key="sk-client-token-1") as client:
+    answer = client.chat(ChatRequest(
+        model="llama3",
+        messages=[ChatMessage(role="user", content="Say hi in one word.")],
+    ))
+    print(answer.message.content)
+```
+
+Async — the same shapes, `await`ed:
+
+```python
+import asyncio
+from inferhub_client import AsyncInferHubClient, ChatMessage, ChatRequest
+
+async def main():
+    async with AsyncInferHubClient("http://localhost:5080/", api_key="sk-client-token-1") as client:
+        answer = await client.chat(ChatRequest(
+            model="llama3",
+            messages=[ChatMessage(role="user", content="Say hi in one word.")],
+        ))
+        print(answer.message.content)
+
+asyncio.run(main())
+```
+
+`InferHubClient` and `AsyncInferHubClient` are **two thin façades over the same rules**
+(`_base.py`'s header building, error mapping and NDJSON parsing) rather than one client with a
+sync-over-`asyncio.run` shim — the latter breaks the moment a sync call happens inside code that is
+already running an event loop, which is exactly where a web framework's request handler lives.
+
+## API surface (v0.1.0)
+
+| Method | Endpoint |
+|---|---|
+| `list_models()` | `GET /api/tags` |
+| `chat(request)` | `POST /api/chat` with `stream:false` |
+| `chat_stream(request)` | `POST /api/chat` with `stream:true` — an iterator/async iterator of `ChatResponse` |
+| `generate(request)` | `POST /api/generate` with `stream:false` |
+| `generate_stream(request)` | `POST /api/generate` with `stream:true` |
+| `embed(request)` | `POST /api/embed` (batch — a string or a list of strings) |
+| `embed_legacy(request)` | `POST /api/embeddings` (legacy single prompt) |
+| `get_status()` | `GET /api/status` |
+| `ping()` | `GET /health` — `True`/`False`, never raises for a non-success status |
+
+## Streaming
+
+```python
+for chunk in client.chat_stream(ChatRequest(model="llama3", messages=[...])):
+    print(chunk.message.content, end="", flush=True)
+```
+
+A terminal error chunk (`{"error": "...", "done": true}`) raises `InferHubError` out of the loop
+instead of the iterator hanging or ending quietly with a partial answer nobody was told about.
+
+## Errors
+
+Every non-success response raises `InferHubError(status_code, message, response_body,
+retry_after=...)`. `retry_after` is populated from `Retry-After` when the hub sends one — the
+refusals that carry it are the ones worth retrying rather than only reporting.
+
+```python
+from inferhub_client import InferHubError
+
+try:
+    client.embed(EmbedRequest.from_text("nomic-embed-text", "hello"))
+except InferHubError as e:
+    print(e.status_code, e.message, e.retry_after)
+```
+
+## `extra`: the fields this version does not know about yet
+
+`ChatRequest`/`GenerateRequest.extra` merges straight into the request body (Ollama's `options`,
+`format`, `keep_alive`, tool definitions — anything the hub accepts that this client has not typed);
+every response dataclass keeps unrecognized fields in its own `.extra` dict on the way back. Typing
+every Ollama option was considered and rejected, same as the C# client: the hub owns that schema and
+grows it independently of this package's release cadence.
+
+## A node as a target
+
+A solo InferHub node serves this same Ollama-dialect surface on its own address — pointing
+`InferHubClient`/`AsyncInferHubClient` at a node's URL instead of a coordinator's is the whole of
+"run it locally." `probe()` and the node-only routes (`/api/version`, the `/api/collections`
+lifecycle) land in `1.0.0`, mirroring the C# client's phase 14 (`14 D7`).
+
+## Development
+
+```
+pip install -e ".[test]"
+pytest                              # 31 pass, 9 skipped (cases outside v0.1.0's surface, see below)
+ruff check src tests examples
+ruff format --check src tests examples
+```
+
+`tests/test_conformance.py` drives the shared corpus at `../conformance/cases.json` — the same file
+the C# client's `ConformanceCorpusTests.cs` reads. A case whose `kind` this client does not cover
+yet (retrieval, the node, the OpenAI dialect) is skipped with a named reason rather than silently
+omitted; four cases (the mid-stream terminal error, `424` vs `404`, both `X-InferHub-Sources`
+shapes) pass today, unmodified, because the corpus already knew the answer.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

inferhub_client-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "inferhub-client"
+version = "0.1.0"
+description = "A small, typed Python client for InferHub — a self-hosted, Ollama-compatible inference mesh."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Dev Art Solutions" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Dev-Art-Solutions/InferHub.Clients"
+Repository = "https://github.com/Dev-Art-Solutions/InferHub.Clients"
+Issues = "https://github.com/Dev-Art-Solutions/InferHub.Clients/issues"
+
+[project.optional-dependencies]
+# ruff pinned exactly, not >=: two different minor releases (0.15 -> 0.16) changed which lint
+# rules are on by default with nothing in this file changed, which broke CI twice in a row on an
+# unpinned version. A linter whose pass/fail depends on which version happened to install is not
+# a check, so this one is deterministic instead — bump it deliberately, in its own commit, when
+# there is a reason to.
+test = ["pytest>=7", "pytest-asyncio>=0.23", "ruff==0.15.13"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inferhub_client"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+# Pinned explicitly rather than left to ruff's default selection: 0.16 started enabling `I`
+# (isort) by default where 0.15 did not, which broke CI on an unpinned `ruff>=0.6` the moment
+# the runner picked up a newer release with nothing in this file changed. Extending the default
+# set (E4, E7, E9, F) rather than replacing it.
+extend-select = ["I"]

inferhub_client-0.1.0/src/inferhub_client/__init__.py

@@ -0,0 +1,45 @@
+"""inferhub-client — a small, typed Python client for InferHub.
+
+>>> from inferhub_client import InferHubClient, ChatMessage, ChatRequest
+>>> with InferHubClient("http://localhost:5080/", api_key="sk-...") as client:
+...     answer = client.chat(ChatRequest(model="llama3", messages=[ChatMessage("user", "hi")]))
+...     print(answer.message.content)
+"""
+
+from ._async_client import AsyncInferHubClient
+from ._client import InferHubClient
+from ._exceptions import InferHubError
+from ._models import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    EmbeddingsRequest,
+    EmbeddingsResponse,
+    EmbedRequest,
+    EmbedResponse,
+    GenerateRequest,
+    GenerateResponse,
+    ModelInfo,
+    StatusResponse,
+    TagsResponse,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "InferHubClient",
+    "AsyncInferHubClient",
+    "InferHubError",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "GenerateRequest",
+    "GenerateResponse",
+    "EmbedRequest",
+    "EmbedResponse",
+    "EmbeddingsRequest",
+    "EmbeddingsResponse",
+    "ModelInfo",
+    "TagsResponse",
+    "StatusResponse",
+]

inferhub_client-0.1.0/src/inferhub_client/_async_client.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import AsyncIterator, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_BASE_URL,
+    build_headers,
+    parse_ndjson_line,
+    raise_for_status,
+    read_served_by,
+    read_source_ids,
+)
+from ._exceptions import InferHubError
+from ._models import (
+    ChatRequest,
+    ChatResponse,
+    EmbeddingsRequest,
+    EmbeddingsResponse,
+    EmbedRequest,
+    EmbedResponse,
+    GenerateRequest,
+    GenerateResponse,
+    StatusResponse,
+    TagsResponse,
+)
+
+
+class AsyncInferHubClient:
+    """Async client for an InferHub coordinator (or a solo node — same address, same client, see
+    ``python/README.md``). Covers the Ollama-dialect core surface: chat, generate (blocking and
+    streaming), embeddings, model listing, status and health.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        *,
+        timeout: float = 100.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            base_url=base_url, headers=build_headers(api_key), timeout=timeout
+        )
+
+    async def __aenter__(self) -> "AsyncInferHubClient":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def list_models(self) -> TagsResponse:
+        """``GET /api/tags`` — models advertised by the mesh."""
+        response = await self._http.get("api/tags")
+        raise_for_status(response)
+        return TagsResponse.from_json(response.json())
+
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        """Blocking chat — ``POST /api/chat`` with ``stream:false``."""
+        request.stream = False
+        response = await self._http.post("api/chat", json=request.to_json())
+        raise_for_status(response)
+        result = ChatResponse.from_json(response.json())
+        result.served_by = read_served_by(response)
+        result.source_ids = read_source_ids(response)
+        return result
+
+    async def chat_stream(self, request: ChatRequest) -> AsyncIterator[ChatResponse]:
+        """Streaming chat — ``POST /api/chat`` with ``stream:true``. Yields one
+        :class:`ChatResponse` per NDJSON line; a terminal error chunk raises
+        :class:`InferHubError` instead of the iterator hanging or ending quietly."""
+        request.stream = True
+        async with self._http.stream(
+            "POST", "api/chat", json=request.to_json()
+        ) as response:
+            raise_for_status(response)
+            served_by = read_served_by(response)
+            source_ids = read_source_ids(response)
+            async for line in response.aiter_lines():
+                chunk = parse_ndjson_line(line)
+                if chunk is None:
+                    continue
+                result = ChatResponse.from_json(chunk)
+                result.served_by = served_by
+                result.source_ids = source_ids
+                yield result
+                if result.done:
+                    return
+
+    async def generate(self, request: GenerateRequest) -> GenerateResponse:
+        """Blocking generate — ``POST /api/generate`` with ``stream:false``."""
+        request.stream = False
+        response = await self._http.post("api/generate", json=request.to_json())
+        raise_for_status(response)
+        result = GenerateResponse.from_json(response.json())
+        result.served_by = read_served_by(response)
+        result.source_ids = read_source_ids(response)
+        return result
+
+    async def generate_stream(
+        self, request: GenerateRequest
+    ) -> AsyncIterator[GenerateResponse]:
+        """Streaming generate — ``POST /api/generate`` with ``stream:true``."""
+        request.stream = True
+        async with self._http.stream(
+            "POST", "api/generate", json=request.to_json()
+        ) as response:
+            raise_for_status(response)
+            served_by = read_served_by(response)
+            source_ids = read_source_ids(response)
+            async for line in response.aiter_lines():
+                chunk = parse_ndjson_line(line)
+                if chunk is None:
+                    continue
+                result = GenerateResponse.from_json(chunk)
+                result.served_by = served_by
+                result.source_ids = source_ids
+                yield result
+                if result.done:
+                    return
+
+    async def embed(self, request: EmbedRequest) -> EmbedResponse:
+        """``POST /api/embed`` — batch embeddings. An empty vector list on a 200 is treated as a
+        malformed response and raised, never silently returned."""
+        response = await self._http.post("api/embed", json=request.to_json())
+        raise_for_status(response)
+        result = EmbedResponse.from_json(response.json())
+        if not result.embeddings:
+            raise InferHubError(response.status_code, "embed response had no vectors")
+        return result
+
+    async def embed_legacy(self, request: EmbeddingsRequest) -> EmbeddingsResponse:
+        """``POST /api/embeddings`` — the legacy single-input endpoint. Prefer :meth:`embed`."""
+        response = await self._http.post("api/embeddings", json=request.to_json())
+        raise_for_status(response)
+        result = EmbeddingsResponse.from_json(response.json())
+        if not result.embedding:
+            raise InferHubError(
+                response.status_code, "embeddings response had no vector"
+            )
+        return result
+
+    async def get_status(self) -> StatusResponse:
+        """``GET /api/status`` — coordinator/fleet snapshot."""
+        response = await self._http.get("api/status")
+        raise_for_status(response)
+        return StatusResponse.from_json(response.json())
+
+    async def ping(self) -> bool:
+        """``GET /health`` — ``True`` on 2xx, ``False`` otherwise. Never raises for a non-success
+        status; raises only on a transport error."""
+        response = await self._http.get("health")
+        return response.is_success

inferhub_client-0.1.0/src/inferhub_client/_base.py

@@ -0,0 +1,109 @@
+"""Shared, I/O-free plumbing used by both :class:`InferHubClient` (sync) and
+:class:`AsyncInferHubClient` (async): headers, error mapping, and NDJSON chunk parsing. Kept out of
+either client so the two stay thin façades over the same rules rather than two copies that drift —
+see ``python/README.md`` on why this is two classes and not one client with a sync-over-async shim.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._exceptions import InferHubError
+
+DEFAULT_BASE_URL = "http://localhost:5080/"
+
+
+def build_headers(api_key: Optional[str]) -> Dict[str, str]:
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _extract_error_message(body: str) -> Optional[str]:
+    """The Ollama dialect answers ``{"error": "..."}"``. A non-JSON or differently-shaped body
+    falls back to the raw text, same as the C# client's ``TryExtractErrorMessage``."""
+
+    if not body.strip():
+        return None
+    try:
+        parsed = json.loads(body)
+    except (json.JSONDecodeError, ValueError):
+        return body
+    if isinstance(parsed, dict) and isinstance(parsed.get("error"), str):
+        return parsed["error"]
+    return body
+
+
+def _retry_after(response: httpx.Response) -> Optional[float]:
+    header = response.headers.get("Retry-After")
+    if not header:
+        return None
+    try:
+        return float(header)
+    except ValueError:
+        return None  # An HTTP-date form exists but the hub always writes delta-seconds.
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    body = response.text
+    message = _extract_error_message(body) or (
+        f"InferHub request failed with status {response.status_code}."
+    )
+    raise InferHubError(
+        response.status_code, message, body, retry_after=_retry_after(response)
+    )
+
+
+def parse_ndjson_line(line: str) -> Optional[Dict[str, Any]]:
+    """One line of an NDJSON stream, or ``None`` for a blank line to skip. Raises
+    :class:`InferHubError` on a terminal error chunk (``{"error": ..., "done": true}``) so a caller's
+    loop stops with a clear exception instead of hanging or silently finishing early."""
+
+    if not line.strip():
+        return None
+
+    chunk = json.loads(line)
+    error = chunk.get("error")
+    if error:
+        raise InferHubError(200, error, line)
+    return chunk
+
+
+def read_served_by(response: httpx.Response) -> Optional[str]:
+    """Which node or ``provider:<id>`` answered — surfaced, never interpreted. This client does
+    not route, retry elsewhere or prefer on it (root ``CLAUDE.md`` rule 8); reading it here is what
+    lets a caller log or display it without this library making a decision on its behalf."""
+
+    value = response.headers.get("X-InferHub-Served-By")
+    return value.strip() or None if value else None
+
+
+def read_source_ids(response: httpx.Response) -> Optional[list]:
+    """``X-InferHub-Sources`` arrives as a JSON array, but a real hub has also sent it
+    comma-separated — ``spec/README.md`` calls this the conformance corpus's first case, and both
+    shapes are parsed here even though ``v0.1.0`` has no way yet to opt into retrieval (phase 17):
+    the header is part of the core response contract, and a caller reading it manually should not
+    have to wait for this client to grow RAG headers first."""
+
+    raw = response.headers.get("X-InferHub-Sources")
+    if raw is None:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return []
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, list):
+            return [
+                str(item) for item in parsed if item is not None and str(item) != ""
+            ]
+    except (json.JSONDecodeError, ValueError):
+        pass
+    return [part.strip() for part in raw.split(",") if part.strip()]

inferhub_client-0.1.0/src/inferhub_client/_client.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from typing import Iterator, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_BASE_URL,
+    build_headers,
+    parse_ndjson_line,
+    raise_for_status,
+    read_served_by,
+    read_source_ids,
+)
+from ._exceptions import InferHubError
+from ._models import (
+    ChatRequest,
+    ChatResponse,
+    EmbeddingsRequest,
+    EmbeddingsResponse,
+    EmbedRequest,
+    EmbedResponse,
+    GenerateRequest,
+    GenerateResponse,
+    StatusResponse,
+    TagsResponse,
+)
+
+
+class InferHubClient:
+    """Sync client for an InferHub coordinator (or a solo node — same address, same client, see
+    ``python/README.md``). A thin façade over the same rules :class:`AsyncInferHubClient` uses
+    (``_base.py``), for callers not already in an event loop. Covers the Ollama-dialect core
+    surface: chat, generate (blocking and streaming), embeddings, model listing, status and health.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        *,
+        timeout: float = 100.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=base_url, headers=build_headers(api_key), timeout=timeout
+        )
+
+    def __enter__(self) -> "InferHubClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def list_models(self) -> TagsResponse:
+        """``GET /api/tags`` — models advertised by the mesh."""
+        response = self._http.get("api/tags")
+        raise_for_status(response)
+        return TagsResponse.from_json(response.json())
+
+    def chat(self, request: ChatRequest) -> ChatResponse:
+        """Blocking chat — ``POST /api/chat`` with ``stream:false``."""
+        request.stream = False
+        response = self._http.post("api/chat", json=request.to_json())
+        raise_for_status(response)
+        result = ChatResponse.from_json(response.json())
+        result.served_by = read_served_by(response)
+        result.source_ids = read_source_ids(response)
+        return result
+
+    def chat_stream(self, request: ChatRequest) -> Iterator[ChatResponse]:
+        """Streaming chat — ``POST /api/chat`` with ``stream:true``. Yields one
+        :class:`ChatResponse` per NDJSON line; a terminal error chunk raises
+        :class:`InferHubError` instead of the iterator hanging or ending quietly."""
+        request.stream = True
+        with self._http.stream("POST", "api/chat", json=request.to_json()) as response:
+            raise_for_status(response)
+            served_by = read_served_by(response)
+            source_ids = read_source_ids(response)
+            for line in response.iter_lines():
+                chunk = parse_ndjson_line(line)
+                if chunk is None:
+                    continue
+                result = ChatResponse.from_json(chunk)
+                result.served_by = served_by
+                result.source_ids = source_ids
+                yield result
+                if result.done:
+                    return
+
+    def generate(self, request: GenerateRequest) -> GenerateResponse:
+        """Blocking generate — ``POST /api/generate`` with ``stream:false``."""
+        request.stream = False
+        response = self._http.post("api/generate", json=request.to_json())
+        raise_for_status(response)
+        result = GenerateResponse.from_json(response.json())
+        result.served_by = read_served_by(response)
+        result.source_ids = read_source_ids(response)
+        return result
+
+    def generate_stream(self, request: GenerateRequest) -> Iterator[GenerateResponse]:
+        """Streaming generate — ``POST /api/generate`` with ``stream:true``."""
+        request.stream = True
+        with self._http.stream(
+            "POST", "api/generate", json=request.to_json()
+        ) as response:
+            raise_for_status(response)
+            served_by = read_served_by(response)
+            source_ids = read_source_ids(response)
+            for line in response.iter_lines():
+                chunk = parse_ndjson_line(line)
+                if chunk is None:
+                    continue
+                result = GenerateResponse.from_json(chunk)
+                result.served_by = served_by
+                result.source_ids = source_ids
+                yield result
+                if result.done:
+                    return
+
+    def embed(self, request: EmbedRequest) -> EmbedResponse:
+        """``POST /api/embed`` — batch embeddings. An empty vector list on a 200 is treated as a
+        malformed response and raised, never silently returned."""
+        response = self._http.post("api/embed", json=request.to_json())
+        raise_for_status(response)
+        result = EmbedResponse.from_json(response.json())
+        if not result.embeddings:
+            raise InferHubError(response.status_code, "embed response had no vectors")
+        return result
+
+    def embed_legacy(self, request: EmbeddingsRequest) -> EmbeddingsResponse:
+        """``POST /api/embeddings`` — the legacy single-input endpoint. Prefer :meth:`embed`."""
+        response = self._http.post("api/embeddings", json=request.to_json())
+        raise_for_status(response)
+        result = EmbeddingsResponse.from_json(response.json())
+        if not result.embedding:
+            raise InferHubError(
+                response.status_code, "embeddings response had no vector"
+            )
+        return result
+
+    def get_status(self) -> StatusResponse:
+        """``GET /api/status`` — coordinator/fleet snapshot."""
+        response = self._http.get("api/status")
+        raise_for_status(response)
+        return StatusResponse.from_json(response.json())
+
+    def ping(self) -> bool:
+        """``GET /health`` — ``True`` on 2xx, ``False`` otherwise. Never raises for a non-success
+        status; raises only on a transport error."""
+        response = self._http.get("health")
+        return response.is_success

inferhub_client-0.1.0/src/inferhub_client/_exceptions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class InferHubError(Exception):
+    """Raised when the coordinator (or a solo node) answers a non-success HTTP status.
+
+    Carries the raw status code so a caller can distinguish 404 (model or collection missing),
+    401/403 (auth), 501 (a backend that structurally cannot serve a capability) from 503 (a
+    capability an operator disabled, temporary, and worth the ``retry_after`` seconds).
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        response_body: str = "",
+        *,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.response_body = response_body
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"InferHubError(status_code={self.status_code!r}, message={self.message!r})"
+        )

inferhub_client-0.1.0/src/inferhub_client/_models.py

@@ -0,0 +1,334 @@
+"""Typed request/response shapes for the Ollama-dialect core surface.
+
+Dataclasses, not pydantic (root ``CLAUDE.md`` rule 2 / roadmap-polyglot-clients D5): the wire is
+small and stable enough that a validation library is somebody else's dependency war inherited by
+every consumer. Every response type keeps an ``extra`` dict for fields the hub sends that this
+version does not know about yet — the Python equivalent of the C# client's ``[JsonExtensionData]``
+bag — so a caller reaching for a brand-new field is never blocked on a new release of this package.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+JsonDict = Dict[str, Any]
+
+_KNOWN_MESSAGE_FIELDS = {"role", "content", "images", "tool_calls"}
+
+
+@dataclass
+class ChatMessage:
+    """One message in a chat request or response."""
+
+    role: str
+    content: str = ""
+    images: Optional[List[str]] = None
+    tool_calls: Optional[List[JsonDict]] = None
+    extra: JsonDict = field(default_factory=dict)
+
+    def to_json(self) -> JsonDict:
+        body: JsonDict = {"role": self.role, "content": self.content}
+        if self.images is not None:
+            body["images"] = self.images
+        if self.tool_calls is not None:
+            body["tool_calls"] = self.tool_calls
+        body.update(self.extra)
+        return body
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "ChatMessage":
+        return cls(
+            role=data.get("role", ""),
+            content=data.get("content", ""),
+            images=data.get("images"),
+            tool_calls=data.get("tool_calls"),
+            extra={k: v for k, v in data.items() if k not in _KNOWN_MESSAGE_FIELDS},
+        )
+
+
+@dataclass
+class ChatRequest:
+    """``POST /api/chat``. ``extra`` merges straight into the top-level body, untouched — the
+    passthrough that keeps every Ollama option (``options``, ``format``, ``keep_alive``, tool
+    definitions) reachable without this client typing each one (roadmap-polyglot-clients,
+    "typed request builders for every option" is a rejected non-goal, same as the C# client)."""
+
+    model: str
+    messages: List[ChatMessage] = field(default_factory=list)
+    stream: bool = False
+    options: Optional[JsonDict] = None
+    format: Optional[Union[str, JsonDict]] = None
+    keep_alive: Optional[str] = None
+    extra: JsonDict = field(default_factory=dict)
+
+    def to_json(self) -> JsonDict:
+        body: JsonDict = {
+            "model": self.model,
+            "messages": [m.to_json() for m in self.messages],
+            "stream": self.stream,
+        }
+        if self.options is not None:
+            body["options"] = self.options
+        if self.format is not None:
+            body["format"] = self.format
+        if self.keep_alive is not None:
+            body["keep_alive"] = self.keep_alive
+        body.update(self.extra)
+        return body
+
+
+_KNOWN_CHAT_RESPONSE_FIELDS = {
+    "model",
+    "created_at",
+    "message",
+    "done",
+    "done_reason",
+    "total_duration",
+    "load_duration",
+    "prompt_eval_count",
+    "prompt_eval_duration",
+    "eval_count",
+    "eval_duration",
+    "error",
+}
+
+
+@dataclass
+class ChatResponse:
+    """A blocking answer, or one NDJSON chunk of a streamed one."""
+
+    model: str = ""
+    created_at: Optional[str] = None
+    message: Optional[ChatMessage] = None
+    done: Optional[bool] = None
+    done_reason: Optional[str] = None
+    total_duration: Optional[int] = None
+    load_duration: Optional[int] = None
+    prompt_eval_count: Optional[int] = None
+    prompt_eval_duration: Optional[int] = None
+    eval_count: Optional[int] = None
+    eval_duration: Optional[int] = None
+    error: Optional[str] = None
+    extra: JsonDict = field(default_factory=dict)
+    # Set from response headers, not the body — never part of round-tripping the JSON.
+    served_by: Optional[str] = None
+    source_ids: Optional[List[str]] = None
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "ChatResponse":
+        message = data.get("message")
+        return cls(
+            model=data.get("model", ""),
+            created_at=data.get("created_at"),
+            message=ChatMessage.from_json(message) if message is not None else None,
+            done=data.get("done"),
+            done_reason=data.get("done_reason"),
+            total_duration=data.get("total_duration"),
+            load_duration=data.get("load_duration"),
+            prompt_eval_count=data.get("prompt_eval_count"),
+            prompt_eval_duration=data.get("prompt_eval_duration"),
+            eval_count=data.get("eval_count"),
+            eval_duration=data.get("eval_duration"),
+            error=data.get("error"),
+            extra={
+                k: v for k, v in data.items() if k not in _KNOWN_CHAT_RESPONSE_FIELDS
+            },
+        )
+
+
+@dataclass
+class GenerateRequest:
+    """``POST /api/generate``. Same extension-bag contract as :class:`ChatRequest`."""
+
+    model: str
+    prompt: str = ""
+    stream: bool = False
+    options: Optional[JsonDict] = None
+    format: Optional[Union[str, JsonDict]] = None
+    keep_alive: Optional[str] = None
+    extra: JsonDict = field(default_factory=dict)
+
+    def to_json(self) -> JsonDict:
+        body: JsonDict = {
+            "model": self.model,
+            "prompt": self.prompt,
+            "stream": self.stream,
+        }
+        if self.options is not None:
+            body["options"] = self.options
+        if self.format is not None:
+            body["format"] = self.format
+        if self.keep_alive is not None:
+            body["keep_alive"] = self.keep_alive
+        body.update(self.extra)
+        return body
+
+
+_KNOWN_GENERATE_RESPONSE_FIELDS = {
+    "model",
+    "created_at",
+    "response",
+    "done",
+    "done_reason",
+    "context",
+    "total_duration",
+    "load_duration",
+    "prompt_eval_count",
+    "prompt_eval_duration",
+    "eval_count",
+    "eval_duration",
+    "error",
+}
+
+
+@dataclass
+class GenerateResponse:
+    model: str = ""
+    created_at: Optional[str] = None
+    response: str = ""
+    done: Optional[bool] = None
+    done_reason: Optional[str] = None
+    context: Optional[List[int]] = None
+    total_duration: Optional[int] = None
+    load_duration: Optional[int] = None
+    prompt_eval_count: Optional[int] = None
+    prompt_eval_duration: Optional[int] = None
+    eval_count: Optional[int] = None
+    eval_duration: Optional[int] = None
+    error: Optional[str] = None
+    extra: JsonDict = field(default_factory=dict)
+    served_by: Optional[str] = None
+    source_ids: Optional[List[str]] = None
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "GenerateResponse":
+        return cls(
+            model=data.get("model", ""),
+            created_at=data.get("created_at"),
+            response=data.get("response", ""),
+            done=data.get("done"),
+            done_reason=data.get("done_reason"),
+            context=data.get("context"),
+            total_duration=data.get("total_duration"),
+            load_duration=data.get("load_duration"),
+            prompt_eval_count=data.get("prompt_eval_count"),
+            prompt_eval_duration=data.get("prompt_eval_duration"),
+            eval_count=data.get("eval_count"),
+            eval_duration=data.get("eval_duration"),
+            error=data.get("error"),
+            extra={
+                k: v
+                for k, v in data.items()
+                if k not in _KNOWN_GENERATE_RESPONSE_FIELDS
+            },
+        )
+
+
+@dataclass
+class EmbedRequest:
+    """``POST /api/embed`` — the modern batch endpoint. ``input`` is a single string or a list."""
+
+    model: str
+    input: Union[str, List[str]]
+
+    def to_json(self) -> JsonDict:
+        return {"model": self.model, "input": self.input}
+
+    @classmethod
+    def from_text(cls, model: str, text: str) -> "EmbedRequest":
+        return cls(model=model, input=text)
+
+    @classmethod
+    def from_texts(cls, model: str, texts: List[str]) -> "EmbedRequest":
+        return cls(model=model, input=list(texts))
+
+
+@dataclass
+class EmbedResponse:
+    model: str = ""
+    embeddings: List[List[float]] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "EmbedResponse":
+        return cls(model=data.get("model", ""), embeddings=data.get("embeddings") or [])
+
+
+@dataclass
+class EmbeddingsRequest:
+    """``POST /api/embeddings`` — the legacy single-input endpoint. Prefer :class:`EmbedRequest`."""
+
+    model: str
+    prompt: str
+
+    def to_json(self) -> JsonDict:
+        return {"model": self.model, "prompt": self.prompt}
+
+
+@dataclass
+class EmbeddingsResponse:
+    embedding: List[float] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "EmbeddingsResponse":
+        return cls(embedding=data.get("embedding") or [])
+
+
+@dataclass
+class ModelInfo:
+    name: str
+    digest: Optional[str] = None
+    size: Optional[int] = None
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "ModelInfo":
+        return cls(
+            name=data.get("name", ""), digest=data.get("digest"), size=data.get("size")
+        )
+
+
+@dataclass
+class TagsResponse:
+    models: List[ModelInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "TagsResponse":
+        return cls(models=[ModelInfo.from_json(m) for m in data.get("models") or []])
+
+
+_KNOWN_STATUS_FIELDS = {
+    "coordinatorVersion",
+    "nowUtc",
+    "uptimeSeconds",
+    "nodes",
+    "models",
+    "metrics",
+    "vector",
+}
+
+
+@dataclass
+class StatusResponse:
+    """``GET /api/status`` on a coordinator. See :mod:`inferhub_client.probe` for the solo-node shape
+    (added in a later phase) and how a caller tells the two apart."""
+
+    coordinator_version: Optional[str] = None
+    now_utc: Optional[str] = None
+    uptime_seconds: Optional[float] = None
+    nodes: Optional[List[JsonDict]] = None
+    models: Optional[List[ModelInfo]] = None
+    extra: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "StatusResponse":
+        models = data.get("models")
+        return cls(
+            coordinator_version=data.get("coordinatorVersion"),
+            now_utc=data.get("nowUtc"),
+            uptime_seconds=data.get("uptimeSeconds"),
+            nodes=data.get("nodes"),
+            models=[ModelInfo.from_json(m) for m in models]
+            if models is not None
+            else None,
+            extra={k: v for k, v in data.items() if k not in _KNOWN_STATUS_FIELDS},
+        )

inferhub_client-0.1.0/src/inferhub_client/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"