thinchat 0.1.0__py3-none-any.whl

thinchat/__init__.py

@@ -0,0 +1,51 @@
+"""thinchat: a tiny, unified client for four LLM providers -- claude, openai, gemini, ollama.
+
+Name a provider, then call it. Each client offers completion (whole, streamed, or
+JSON-structured) and, where the provider has one, embeddings -- with an async twin for each.
+
+    from thinchat import make_client
+
+    llm = make_client("claude")                 # key from CLAUDE_API_KEY
+    print(llm.complete("Say hi in one word."))
+    verdict = llm.parse("Is this an ad? 'Buy now, 50% off'",
+                        schema={"type": "object",
+                                "properties": {"is_ad": {"type": "boolean"}},
+                                "required": ["is_ad"]})
+
+Installing thinchat brings both provider SDKs (openai and anthropic), so every provider
+works out of the box; each SDK is imported lazily when you first construct its client.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from thinchat.claude_client import ClaudeClient
+from thinchat.client import Capability, Client, Provider
+from thinchat.errors import (
+    LLMError,
+    ProviderUnavailableError,
+    ThinchatError,
+    UnknownProviderError,
+    UnsupportedError,
+)
+from thinchat.openai_client import OpenAICompatibleClient
+from thinchat.providers import PROVIDERS, make_client
+
+__all__ = [
+    "PROVIDERS",
+    "Capability",
+    "ClaudeClient",
+    "Client",
+    "LLMError",
+    "OpenAICompatibleClient",
+    "Provider",
+    "ProviderUnavailableError",
+    "ThinchatError",
+    "UnknownProviderError",
+    "UnsupportedError",
+    "make_client",
+]
+
+try:
+    __version__ = version("thinchat")   # single source of truth: the installed metadata
+except PackageNotFoundError:            # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"

thinchat/claude_client.py

@@ -0,0 +1,139 @@
+"""The Claude client, over Anthropic's native SDK.
+
+Claude is the one client not reached through the OpenAI-compatible path: Anthropic's API
+takes ``system`` as its own argument rather than a message, and Anthropic has no
+first-party embeddings API, so this client has completion, streaming, and structured
+output but refuses ``embed`` (the base's default). ``max_tokens`` is required by this API
+(unlike OpenAI's), so it is a constructor knob with a generous default.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+import thinchat.keys as keys
+from thinchat.client import Capability, _BaseClient
+from thinchat.errors import LLMError, ProviderUnavailableError
+
+__all__ = ["ClaudeClient"]
+
+_CLAUDE_DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+
+# No "embeddings": Anthropic has no first-party embeddings API, so embed stays the base's
+# refusing default and a caller reads `supports("embeddings")` as False.
+_CAPABILITIES: frozenset[Capability] = frozenset({"completion", "streaming", "structured_output"})
+
+# Anthropic requires max_tokens (unlike OpenAI, where it is optional). 4096 is a generous
+# default that stays within every current Claude model's output limit; a caller wanting a
+# different cap passes max_tokens= to make_client.
+_CLAUDE_DEFAULT_MAX_TOKENS = 4096
+
+
+class ClaudeClient(_BaseClient):
+    """A client over Anthropic's ``anthropic`` SDK. Holds a sync client and lazily builds a
+    reusable async client on first async use, plus the model id. ``max_tokens`` bounds every
+    reply (the API requires it)."""
+
+    _sdk_error:     type[Exception]
+    _stream_errors: tuple[type[Exception], ...]
+
+    def __init__(self, *, api_key: str, model: str, max_tokens: int = _CLAUDE_DEFAULT_MAX_TOKENS) -> None:
+        try:
+            import httpx
+            from anthropic import Anthropic, AnthropicError
+        except ImportError as err:
+            raise ProviderUnavailableError(
+                "the anthropic package is required but could not be imported; reinstall thinchat"
+            ) from err
+        self.model          = model
+        self.capabilities   = _CAPABILITIES
+        self._api_key       = api_key
+        self._max_tokens    = max_tokens
+        # Catch only Anthropic's own error family (so our bugs surface as themselves); the
+        # streaming path also raises raw httpx on a mid-stream transport drop.
+        self._sdk_error     = AnthropicError
+        self._stream_errors = (AnthropicError, httpx.HTTPError)
+        self._client        = Anthropic(api_key=api_key)
+        self._aclient       = None   # built on first async use (see _make_aclient)
+
+    def _make_aclient(self) -> Any:
+        from anthropic import AsyncAnthropic  # the sync import above already proved it installed
+        return AsyncAnthropic(api_key=self._api_key)
+
+    def complete(self, prompt: str, *, system: str | None = None) -> str:
+        try:
+            response = self._client.messages.create(**self._make_request(prompt, system))
+        except self._sdk_error as err:
+            raise LLMError(f"claude completion failed: {err}") from err
+        return _extract_message_text(response)
+
+    async def acomplete(self, prompt: str, *, system: str | None = None) -> str:
+        try:
+            response = await self._get_aclient().messages.create(**self._make_request(prompt, system))
+        except self._sdk_error as err:
+            raise LLMError(f"claude completion failed: {err}") from err
+        return _extract_message_text(response)
+
+    def stream(self, prompt: str, *, system: str | None = None) -> Iterator[str]:
+        try:
+            with self._client.messages.stream(**self._make_request(prompt, system)) as events:
+                yield from events.text_stream
+        except self._stream_errors as err:
+            raise LLMError(f"claude stream failed: {err}") from err
+
+    async def astream(self, prompt: str, *, system: str | None = None) -> AsyncIterator[str]:
+        try:
+            async with self._get_aclient().messages.stream(**self._make_request(prompt, system)) as events:
+                async for chunk in events.text_stream:
+                    yield chunk
+        except self._stream_errors as err:
+            raise LLMError(f"claude stream failed: {err}") from err
+
+    def _make_request(self, prompt: str, system: str | None) -> dict[str, object]:
+        request: dict[str, object] = {
+            "model":      self.model,
+            "max_tokens": self._max_tokens,
+            "messages":   [{"role": "user", "content": prompt}],
+        }
+        if system is not None:
+            request["system"] = system   # Anthropic takes system as its own field, not a message
+        return request
+
+
+def _make_claude_client(
+    *, model: str | None = None, api_key: str | None = None, max_tokens: int | None = None,
+) -> ClaudeClient:
+    """Construct the Claude client. ``max_tokens`` caps the reply; when None the default
+    (Anthropic requires the field) is used.
+
+    Raises:
+        ProviderUnavailableError: the anthropic SDK is not installed, or no API key is set
+            (or passed).
+    """
+    key = api_key if api_key is not None else keys.get_api_key("claude")
+    if not key:
+        raise ProviderUnavailableError(
+            f"no API key for claude: set {keys.ENV_BY_PROVIDER['claude']} or pass api_key="
+        )
+    return ClaudeClient(
+        api_key    = key,
+        model      = model or _CLAUDE_DEFAULT_MODEL,
+        max_tokens = max_tokens if max_tokens is not None else _CLAUDE_DEFAULT_MAX_TOKENS,
+    )
+
+
+def _extract_message_text(response: object) -> str:
+    """The concatenated text blocks of a Messages response. Raises ``LLMError`` when the
+    reply is empty, or carries content but no text block (e.g. a non-text block only)."""
+    content = getattr(response, "content", None)
+    if not isinstance(content, list) or not content:
+        raise LLMError("claude completion returned an empty reply")
+    parts = [
+        block.text for block in content
+        if getattr(block, "type", None) == "text" and isinstance(getattr(block, "text", None), str)
+    ]
+    text = "".join(parts).strip()
+    if not text:
+        raise LLMError("claude reply carried no text block")
+    return text

thinchat/client.py

@@ -0,0 +1,225 @@
+"""The client contract and the behaviour every client shares.
+
+``Client`` is the structural type a caller depends on -- four verbs, each with an async
+twin, plus a capability probe. ``_BaseClient`` supplies the parts that do not vary by
+provider: structured output steered through the prompt (overridden by a client with native
+support), embeddings that refuse by default (Claude has no embeddings API), the ``supports``
+probe, and closing the underlying HTTP pools. A concrete client implements only the four
+primitives -- ``complete``, ``acomplete``, ``stream``, ``astream`` -- and declares its
+``capabilities``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any, Literal, Protocol, Self, runtime_checkable
+
+from thinchat.errors import UnsupportedError
+from thinchat.structured_output import make_json_instruction, parse_json
+
+__all__ = ["Capability", "Client", "Provider"]
+
+# The four providers thinchat speaks to, as a closed type. The public boundary
+# (``make_client``) still takes a runtime ``str`` (a config value is not a Literal) and
+# validates it; the internal surfaces carry ``Provider`` so a typo is a static error.
+Provider = Literal["claude", "openai", "gemini", "ollama"]
+
+# What a client can do. A caller reads ``supports`` (or catches ``UnsupportedError``)
+# rather than assuming: Claude, for one, has completion and streaming but no embeddings.
+Capability = Literal["completion", "streaming", "structured_output", "embeddings"]
+
+
+@runtime_checkable
+class Client(Protocol):
+    """One LLM client. ``model`` is the chat model it calls; the verbs turn a prompt into
+    a completion (whole, streamed, or JSON) and texts into embeddings. Each has an async
+    twin for a caller inside an event loop.
+
+    Raises:
+        LLMError: a failed API call, or an empty / malformed reply -- for the
+            non-streaming verbs (complete/acomplete/parse/aparse/embed/aembed). For
+            stream/astream the error surfaces *while iterating*, not at the call, and an
+            empty stream is not itself an error.
+        UnsupportedError: embed / aembed on a provider with no embeddings API (Claude);
+            check ``supports("embeddings")`` first."""
+
+    model: str
+    capabilities: frozenset[Capability]
+
+    def supports(self, capability: Capability) -> bool: ...
+
+    def complete(self, prompt: str, *, system: str | None = None) -> str: ...
+    async def acomplete(self, prompt: str, *, system: str | None = None) -> str: ...
+
+    def stream(self, prompt: str, *, system: str | None = None) -> Iterator[str]: ...
+    def astream(self, prompt: str, *, system: str | None = None) -> AsyncIterator[str]: ...
+
+    def parse(
+        self, prompt: str, schema: dict[str, object], *, system: str | None = None
+    ) -> dict[str, object]: ...
+    async def aparse(
+        self, prompt: str, schema: dict[str, object], *, system: str | None = None
+    ) -> dict[str, object]: ...
+
+    def embed(self, texts: Sequence[str], *, model: str | None = None) -> list[list[float]]: ...
+    async def aembed(
+        self, texts: Sequence[str], *, model: str | None = None
+    ) -> list[list[float]]: ...
+
+    def close(self) -> None: ...
+    async def aclose(self) -> None: ...
+
+    def __enter__(self) -> Self: ...
+    def __exit__(self, *exc: object) -> None: ...
+    async def __aenter__(self) -> Self: ...
+    async def __aexit__(self, *exc: object) -> None: ...
+
+
+class _BaseClient(ABC):
+    """Shared behaviour behind the concrete clients. Subclasses implement the four
+    primitives and ``_make_aclient`` (which builds the vendor's async SDK client), set
+    ``model`` / ``capabilities``, assign ``_client`` (the sync SDK client), and set
+    ``_aclient`` to None (the async client is built lazily on first async use); everything
+    else is derived here."""
+
+    model:        str
+    capabilities: frozenset[Capability]
+    _client:      Any   # the vendor's sync SDK client (owns an HTTP connection pool)
+    _aclient:     Any   # the vendor's async SDK client, or None until first async use
+
+    def supports(self, capability: Capability) -> bool:
+        """Whether this client offers ``capability`` -- the check to make before calling
+        a verb that might raise ``UnsupportedError`` (e.g. ``embed`` on Claude)."""
+        return capability in self.capabilities
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(model={self.model!r})"
+
+    # --- primitives each client implements natively -------------------------------
+
+    @abstractmethod
+    def complete(self, prompt: str, *, system: str | None = None) -> str: ...
+
+    @abstractmethod
+    async def acomplete(self, prompt: str, *, system: str | None = None) -> str: ...
+
+    @abstractmethod
+    def stream(self, prompt: str, *, system: str | None = None) -> Iterator[str]: ...
+
+    @abstractmethod
+    def astream(self, prompt: str, *, system: str | None = None) -> AsyncIterator[str]: ...
+
+    # --- async SDK client: built on first async use --------------------------------
+    # The async verbs go through _get_aclient() rather than touching _aclient, so a
+    # sync-only caller never constructs an async pool it then cannot release (close() and
+    # __exit__ are sync and reach only _client). A subclass makes its vendor async client
+    # in _make_aclient; this caches it after the first async call. (Not synchronised: two
+    # threads first-touching an async verb at once could build two -- fine for a client
+    # driven from a single event loop, the normal case.)
+
+    @abstractmethod
+    def _make_aclient(self) -> Any: ...
+
+    def _get_aclient(self) -> Any:
+        if self._aclient is None:
+            self._aclient = self._make_aclient()
+        return self._aclient
+
+    # --- structured output: default steers through the prompt ----------------------
+    # A client with native constrained output (OpenAI's response_format) overrides the
+    # ``_text_for_parse`` hooks; the default appends the schema to the system prompt and
+    # parses the reply, which works on any client that can follow an instruction.
+
+    def parse(
+        self, prompt: str, schema: dict[str, object], *, system: str | None = None
+    ) -> dict[str, object]:
+        """Return the reply parsed into a JSON object. ``schema`` is supplied to guide (or
+        natively constrain) generation; it is not validated locally, so a caller that needs
+        strict conformance checks the returned object itself. Raises ``LLMError`` if the
+        reply is not a JSON object."""
+        return parse_json(self._text_for_parse(prompt, _with_schema(system, schema)))
+
+    async def aparse(
+        self, prompt: str, schema: dict[str, object], *, system: str | None = None
+    ) -> dict[str, object]:
+        """Async twin of ``parse``."""
+        return parse_json(await self._atext_for_parse(prompt, _with_schema(system, schema)))
+
+    def _text_for_parse(self, prompt: str, system: str) -> str:
+        """How ``parse`` gets its raw text. The default just completes with the schema
+        folded into the system prompt; a client with native JSON mode overrides this to
+        constrain the reply at the API as well."""
+        return self.complete(prompt, system=system)
+
+    async def _atext_for_parse(self, prompt: str, system: str) -> str:
+        """Async twin of ``_text_for_parse``."""
+        return await self.acomplete(prompt, system=system)
+
+    # --- embeddings: refused unless a client overrides ----------------------------
+
+    def embed(self, texts: Sequence[str], *, model: str | None = None) -> list[list[float]]:
+        """Return one embedding vector per input text. Raises ``UnsupportedError`` on a
+        client without an embeddings API (Claude)."""
+        raise UnsupportedError(f"{type(self).__name__} does not support embeddings")
+
+    async def aembed(
+        self, texts: Sequence[str], *, model: str | None = None
+    ) -> list[list[float]]:
+        """Async twin of ``embed``."""
+        raise UnsupportedError(f"{type(self).__name__} does not support embeddings")
+
+    # --- lifecycle: release the underlying HTTP connection pools -------------------
+
+    def close(self) -> None:
+        """Close the sync SDK client's connection pool. Use ``with make_client(...) as c:``
+        or call this when done, so a server building a client per request does not leak
+        connections. If you drove async verbs (``acomplete`` / ``astream`` / ...), release
+        with ``aclose()`` or ``async with`` instead -- that also closes the async pool,
+        which this sync close cannot."""
+        _close(self._client)
+
+    async def aclose(self) -> None:
+        """Close both the async and sync SDK clients' pools. The async pool exists only if
+        an async verb was used (it is built lazily); the sync pool is always released, even
+        if closing the async one raises."""
+        try:
+            aclient = self._aclient
+            if aclient is not None:
+                # The async SDK client's close is a coroutine named ``close``
+                # (openai/anthropic), occasionally ``aclose`` elsewhere; accept either and
+                # await it if it is one.
+                aclose = getattr(aclient, "aclose", None) or getattr(aclient, "close", None)
+                if callable(aclose):
+                    result = aclose()
+                    if inspect.isawaitable(result):
+                        await result
+        finally:
+            _close(self._client)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+def _with_schema(system: str | None, schema: dict[str, object]) -> str:
+    """Fold the JSON-schema instruction into the system prompt: appended when a system
+    prompt is given, else it stands alone as the system prompt."""
+    instruction = make_json_instruction(schema)
+    return f"{system}\n\n{instruction}" if system else instruction
+
+
+def _close(client: object) -> None:
+    """Call an SDK client's ``close`` if it has one (the fakes and some SDKs do not)."""
+    close = getattr(client, "close", None)
+    if callable(close):
+        close()

thinchat/errors.py

@@ -0,0 +1,45 @@
+"""Domain exception hierarchy for thinchat.
+
+Every error thinchat raises on purpose derives from ``ThinchatError``, so a caller can
+handle this package's failures with one ``except`` without catching unrelated bugs. The
+tree separates the four ways a call can fail: the client could not be built
+(``ProviderUnavailableError``), the name is not one we know (``UnknownProviderError``), the
+client does not offer the requested capability (``UnsupportedError``), or the API call
+itself failed (``LLMError``).
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ThinchatError",
+    "ProviderUnavailableError",
+    "LLMError",
+    "UnknownProviderError",
+    "UnsupportedError",
+]
+
+
+class ThinchatError(Exception):
+    """Base for every error thinchat raises deliberately."""
+
+
+class UnknownProviderError(ThinchatError):
+    """The requested client name is not one of the four thinchat supports. Permanent --
+    a typo or an unsupported provider -- so the caller fixes the name rather than retries."""
+
+
+class ProviderUnavailableError(ThinchatError):
+    """A client could not be constructed: its SDK is not installed (install the matching
+    extra) or no API key is available for it. Distinct from ``LLMError`` because nothing
+    was sent -- the failure is local setup, not the remote service."""
+
+
+class UnsupportedError(ThinchatError):
+    """The client does not offer the requested capability -- asking Claude for embeddings,
+    which Anthropic has no first-party API for. Permanent for that client, so ``supports``
+    lets a caller check before calling."""
+
+
+class LLMError(ThinchatError):
+    """The API call was made but failed: the service returned an error, or the reply was
+    empty or not the requested shape. Its message carries the underlying cause."""

thinchat/keys.py

@@ -0,0 +1,30 @@
+"""Resolve a client's API key from the environment.
+
+thinchat is a library, not an application, so it reads keys from the environment (or an
+explicit ``api_key=`` a caller passes) and never imposes a file location of its own --
+where keys live on disk is the calling program's decision. Each name follows the provider
+handle you pass to ``make_client`` -- ``<PROVIDER>_API_KEY`` -- so ``make_client("claude")``
+pairs with ``CLAUDE_API_KEY``, matching the roster rather than each vendor SDK's own default.
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["ENV_BY_PROVIDER", "get_api_key"]
+
+# The environment variable each provider's key is read from. ollama is absent on purpose:
+# a local server needs no key, so its client passes a dummy the SDK accepts.
+ENV_BY_PROVIDER: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "claude": "CLAUDE_API_KEY",
+}
+
+
+def get_api_key(provider: str) -> str | None:
+    """Return the API key for ``provider`` from its environment variable, or ``None`` when
+    it is unset (so a client can phrase its own "no key" error) or the provider needs
+    none (ollama). A ``provider`` outside the roster simply reads as "no env"."""
+    name = ENV_BY_PROVIDER.get(provider)
+    return os.environ.get(name) if name is not None else None

thinchat/openai_client.py

@@ -0,0 +1,283 @@
+"""The three clients that speak the OpenAI-compatible API: openai, gemini, ollama.
+
+OpenAI, Gemini, and Ollama all expose the same ``/chat/completions`` and ``/embeddings``
+shapes, so one client over the ``openai`` SDK serves all three -- they differ only in
+data: the base URL, the key, the default models, and whether the endpoint honours a
+native JSON mode. Gemini and Ollama are reached by pointing the SDK's ``base_url`` at
+their compatible endpoints; only the provider rows below change.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import thinchat.keys as keys
+from thinchat.client import Capability, _BaseClient
+from thinchat.errors import LLMError, ProviderUnavailableError, UnknownProviderError
+
+__all__ = ["OpenAICompatibleClient"]
+
+# An OpenAI-compatible client does everything; only Claude drops a capability.
+_CAPABILITIES: frozenset[Capability] = frozenset(
+    {"completion", "streaming", "structured_output", "embeddings"}
+)
+
+
+@dataclass(frozen=True, kw_only=True)
+class _ProviderSpec:
+    """The data that distinguishes one OpenAI-compatible provider from another. ``is_local``
+    is True for Ollama -- a local server that authenticates nothing and whose ``base_url``
+    is resolved from ``OLLAMA_HOST`` at construction (so the ``base_url`` field is ignored).
+    ``has_native_json`` marks an endpoint that honours ``response_format`` -- OpenAI and
+    Gemini do; Ollama's compat layer does not, so it falls back to prompt-steered JSON.
+    Keyword-only so two same-typed model ids cannot be transposed by position."""
+
+    base_url:        str | None
+    chat_model:      str
+    embed_model:     str
+    has_native_json: bool
+    needs_key:       bool
+    is_local:        bool
+
+
+# The three providers, as data. A `-latest` alias for Gemini, not a pinned name: Google
+# gates pinned model ids (e.g. gemini-2.5-flash-lite) to 404 for newly created API keys,
+# while the alias tracks the current model and stays on the free tier. Private: reached
+# only through _make_openai_client, not exported.
+_SPEC_BY_PROVIDER: dict[str, _ProviderSpec] = {
+    "openai": _ProviderSpec(
+        base_url=None, chat_model="gpt-4o-mini", embed_model="text-embedding-3-small",
+        has_native_json=True, needs_key=True, is_local=False),
+    "gemini": _ProviderSpec(
+        base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+        chat_model="gemini-flash-lite-latest", embed_model="text-embedding-004",
+        has_native_json=True, needs_key=True, is_local=False),
+    "ollama": _ProviderSpec(
+        base_url=None, chat_model="llama3.1", embed_model="nomic-embed-text",
+        has_native_json=False, needs_key=False, is_local=True),
+}
+
+
+class OpenAICompatibleClient(_BaseClient):
+    """A client over the ``openai`` SDK, pointed at any OpenAI-compatible endpoint. Holds a
+    sync client and lazily builds a reusable async client on first async use, plus the chat
+    and embedding model ids, so the same class serves OpenAI, Gemini, and Ollama."""
+
+    _sdk_error:     type[Exception]
+    _stream_errors: tuple[type[Exception], ...]
+
+    def __init__(
+        self, *, provider: str, base_url: str | None, api_key: str, model: str,
+        embed_model: str, has_native_json: bool, max_tokens: int | None = None,
+    ) -> None:
+        try:
+            import httpx
+            from openai import OpenAI, OpenAIError
+        except ImportError as err:
+            raise ProviderUnavailableError(
+                "the openai package is required but could not be imported; reinstall thinchat"
+            ) from err
+        self.model            = model
+        self.capabilities     = _CAPABILITIES
+        self._provider        = provider
+        self._base_url        = base_url
+        self._api_key         = api_key
+        self._embed_model     = embed_model
+        self._has_native_json = has_native_json
+        self._max_tokens      = max_tokens   # None -> omit (OpenAI-compatible; the model decides)
+        # Catch only the SDK's own error family so a bug in our code surfaces as itself.
+        self._sdk_error       = OpenAIError
+        # The streaming iteration path does NOT wrap transport failures in OpenAIError, so
+        # a mid-stream disconnect raises a raw httpx error; catch that base there too.
+        self._stream_errors   = (OpenAIError, httpx.HTTPError)
+        self._client          = OpenAI(base_url=base_url, api_key=api_key)
+        self._aclient         = None   # built on first async use (see _make_aclient)
+
+    def _make_aclient(self) -> Any:
+        from openai import AsyncOpenAI  # the sync import above already proved it installed
+        return AsyncOpenAI(base_url=self._base_url, api_key=self._api_key)
+
+    def __repr__(self) -> str:   # one class serves three providers; show which
+        return f"OpenAICompatibleClient(provider={self._provider!r}, model={self.model!r})"
+
+    def complete(self, prompt: str, *, system: str | None = None) -> str:
+        return self._chat(self._make_messages(prompt, system))
+
+    async def acomplete(self, prompt: str, *, system: str | None = None) -> str:
+        return await self._achat(self._make_messages(prompt, system))
+
+    def stream(self, prompt: str, *, system: str | None = None) -> Iterator[str]:
+        request = self._make_request(self._make_messages(prompt, system), json_mode=False)
+        request["stream"] = True
+        try:
+            # The SDK stream owns the HTTP connection and is a context manager; `with`
+            # releases it on an early break or a consumer exception. `Any`: the streamed
+            # type is hidden behind **request, so chunks are read defensively via
+            # _extract_stream_text.
+            sdk_stream: Any = self._client.chat.completions.create(**request)
+            with sdk_stream as events:
+                for chunk in events:
+                    delta = _extract_stream_text(chunk)
+                    if delta:
+                        yield delta
+        except self._stream_errors as err:
+            raise LLMError(f"{self._provider} stream failed: {err}") from err
+
+    async def astream(self, prompt: str, *, system: str | None = None) -> AsyncIterator[str]:
+        request = self._make_request(self._make_messages(prompt, system), json_mode=False)
+        request["stream"] = True
+        try:
+            sdk_stream: Any = await self._get_aclient().chat.completions.create(**request)
+            async with sdk_stream as events:
+                async for chunk in events:
+                    delta = _extract_stream_text(chunk)
+                    if delta:
+                        yield delta
+        except self._stream_errors as err:
+            raise LLMError(f"{self._provider} stream failed: {err}") from err
+
+    def embed(self, texts: Sequence[str], *, model: str | None = None) -> list[list[float]]:
+        """Return one embedding vector per input text (empty input -> empty list, no call).
+        Raises ``LLMError`` if the API call fails or a reply carries no vector."""
+        text_list = list(texts)
+        if not text_list:
+            return []   # one vector per input; zero inputs -> zero vectors, not an error
+        try:
+            response = self._client.embeddings.create(model=model or self._embed_model, input=text_list)
+        except self._sdk_error as err:
+            raise LLMError(f"{self._provider} embedding failed: {err}") from err
+        return _extract_embedding_vectors(response)
+
+    async def aembed(self, texts: Sequence[str], *, model: str | None = None) -> list[list[float]]:
+        """Async twin of ``embed``."""
+        text_list = list(texts)
+        if not text_list:
+            return []
+        try:
+            response = await self._get_aclient().embeddings.create(model=model or self._embed_model, input=text_list)
+        except self._sdk_error as err:
+            raise LLMError(f"{self._provider} embedding failed: {err}") from err
+        return _extract_embedding_vectors(response)
+
+    # Native JSON mode where the endpoint honours it, else the base's prompt-steered path.
+    def _text_for_parse(self, prompt: str, system: str) -> str:
+        return self._chat(self._make_messages(prompt, system), json_mode=self._has_native_json)
+
+    async def _atext_for_parse(self, prompt: str, system: str) -> str:
+        return await self._achat(self._make_messages(prompt, system), json_mode=self._has_native_json)
+
+    def _chat(self, messages: list[dict[str, str]], *, json_mode: bool = False) -> str:
+        try:
+            response = self._client.chat.completions.create(**self._make_request(messages, json_mode=json_mode))
+        except self._sdk_error as err:
+            raise LLMError(f"{self._provider} completion failed: {err}") from err
+        return _extract_chat_text(response)
+
+    async def _achat(self, messages: list[dict[str, str]], *, json_mode: bool = False) -> str:
+        try:
+            response = await self._get_aclient().chat.completions.create(**self._make_request(messages, json_mode=json_mode))
+        except self._sdk_error as err:
+            raise LLMError(f"{self._provider} completion failed: {err}") from err
+        return _extract_chat_text(response)
+
+    def _make_request(self, messages: list[dict[str, str]], *, json_mode: bool) -> dict[str, object]:
+        request: dict[str, object] = {"model": self.model, "messages": messages}
+        if self._max_tokens is not None:   # optional here, so send it only when set
+            request["max_tokens"] = self._max_tokens
+        if json_mode:
+            request["response_format"] = {"type": "json_object"}
+        return request
+
+    def _make_messages(self, prompt: str, system: str | None) -> list[dict[str, str]]:
+        messages: list[dict[str, str]] = []
+        if system is not None:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return messages
+
+
+def _make_openai_client(
+    provider: str, *, model: str | None = None, api_key: str | None = None,
+    max_tokens: int | None = None,
+) -> OpenAICompatibleClient:
+    """Construct one of the OpenAI-compatible clients (openai / gemini / ollama) by name.
+    ``max_tokens`` caps the reply when set; when None it is omitted and the model decides.
+
+    Raises:
+        UnknownProviderError: ``provider`` is not an OpenAI-compatible provider.
+        ProviderUnavailableError: the openai SDK is not installed, or the provider needs a
+            key and none is set (or passed).
+    """
+    spec = _SPEC_BY_PROVIDER.get(provider)
+    if spec is None:
+        raise UnknownProviderError(
+            f"{provider!r} is not an OpenAI-compatible provider; "
+            f"choose one of {', '.join(_SPEC_BY_PROVIDER)}"
+        )
+    key = api_key if api_key is not None else keys.get_api_key(provider)
+    if spec.needs_key and not key:
+        raise ProviderUnavailableError(
+            f"no API key for {provider}: set {keys.ENV_BY_PROVIDER[provider]} or pass api_key="
+        )
+    base_url = _ollama_base_url() if spec.is_local else spec.base_url
+    return OpenAICompatibleClient(
+        provider        = provider,
+        base_url        = base_url,
+        api_key         = key or "ollama",   # Ollama ignores the key, but the SDK needs a non-empty one
+        model           = model or spec.chat_model,
+        embed_model     = spec.embed_model,
+        has_native_json = spec.has_native_json,
+        max_tokens      = max_tokens,
+    )
+
+
+def _ollama_base_url() -> str:
+    """Ollama's OpenAI-compatible endpoint, from ``OLLAMA_HOST`` or the local default. Adds
+    a scheme (Ollama accepts a bare ``host:port`` that httpx cannot use) and the ``/v1``
+    suffix the SDK expects."""
+    raw  = os.environ.get("OLLAMA_HOST") or "http://localhost:11434"
+    host = (raw if "://" in raw else f"http://{raw}").rstrip("/")
+    return host if host.endswith("/v1") else host + "/v1"
+
+
+def _extract_chat_text(response: object) -> str:
+    """The first message's text from a chat-completions response, or an ``LLMError`` when
+    the reply carries none (an empty choice list or empty content)."""
+    choices = getattr(response, "choices", None)
+    if not choices:
+        raise LLMError("completion returned no choices")
+    text = getattr(getattr(choices[0], "message", None), "content", None)
+    if not isinstance(text, str) or not text.strip():   # blank reply is empty, like Claude's
+        raise LLMError("completion returned an empty reply")
+    return text
+
+
+def _extract_stream_text(chunk: object) -> str | None:
+    """The incremental text of one streaming chunk, or None for a chunk that carries no
+    content (role-only openers, finish markers)."""
+    choices = getattr(chunk, "choices", None)
+    if not choices:
+        return None
+    delta = getattr(getattr(choices[0], "delta", None), "content", None)
+    return delta if isinstance(delta, str) else None
+
+
+def _extract_embedding_vectors(response: object) -> list[list[float]]:
+    """The embedding vectors from an embeddings response, one per input, in order. An item
+    that carries no vector is an error, not a silently-empty result."""
+    data = getattr(response, "data", None)
+    if not isinstance(data, list) or not data:
+        raise LLMError("embedding returned no vectors")
+    # The API tags each item with its input `index`; sort by it so the vectors line up with
+    # the input order even if the response arrives (or is batched) out of order.
+    items = sorted(data, key=lambda item: getattr(item, "index", 0))
+    vectors: list[list[float]] = []
+    for item in items:
+        embedding = getattr(item, "embedding", None)
+        if not isinstance(embedding, list) or not embedding:
+            raise LLMError("embedding response held an item with no vector")
+        vectors.append(list(embedding))
+    return vectors

thinchat/providers.py

@@ -0,0 +1,68 @@
+"""Name a provider, get a client.
+
+The one place that maps each provider name to its client factory, so a caller -- a CLI, a
+config value, another package -- asks for a client by provider string and never re-authors
+the mapping. The roster (``PROVIDERS``) is *derived* from the factory map, so the two
+cannot drift. Adding a provider is one entry here.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Protocol
+
+from thinchat.claude_client import _make_claude_client
+from thinchat.client import Client, Provider
+from thinchat.errors import UnknownProviderError
+from thinchat.openai_client import _make_openai_client
+
+__all__ = ["PROVIDERS", "make_client"]
+
+
+class _ClientFactory(Protocol):
+    """The call shape every provider factory shares once its provider name is bound: the
+    override knobs (model, api_key, max_tokens) in, a client out. Typed (not
+    ``Callable[..., Client]``) so a call with a mistyped kwarg is caught statically."""
+
+    def __call__(
+        self, *, model: str | None = None, api_key: str | None = None,
+        max_tokens: int | None = None,
+    ) -> Client: ...
+
+
+# One factory per provider -- the single source of the roster. claude has its own factory;
+# openai/gemini/ollama share the OpenAI-compatible one (bound to their name).
+_FACTORY_BY_PROVIDER: dict[Provider, _ClientFactory] = {
+    "claude": _make_claude_client,
+    "openai": partial(_make_openai_client, "openai"),
+    "gemini": partial(_make_openai_client, "gemini"),
+    "ollama": partial(_make_openai_client, "ollama"),
+}
+
+# The providers thinchat supports, in insertion order -- derived from the factory map so
+# the roster and the dispatch never drift.
+PROVIDERS: tuple[Provider, ...] = tuple(_FACTORY_BY_PROVIDER)
+
+
+def make_client(
+    provider: str, *, model: str | None = None, api_key: str | None = None,
+    max_tokens: int | None = None,
+) -> Client:
+    """Construct the client for ``provider`` (one of ``PROVIDERS``). ``model`` overrides
+    the provider's default model; ``api_key`` overrides the environment key (for tests, or
+    a caller that manages its own secrets); ``max_tokens`` caps the reply length (a positive
+    integer, validated by the provider). When ``max_tokens`` is None, claude falls back to a
+    default (Anthropic requires the field) and the OpenAI-compatible providers omit it,
+    letting the model decide.
+
+    Raises:
+        UnknownProviderError: ``provider`` is not one of ``PROVIDERS``.
+        ProviderUnavailableError: the provider's SDK is not installed, or it needs a key
+            and none is available.
+    """
+    if provider not in _FACTORY_BY_PROVIDER:
+        raise UnknownProviderError(
+            f"unknown provider {provider!r}; choose one of {', '.join(PROVIDERS)}"
+        )
+    factory = _FACTORY_BY_PROVIDER[provider]   # `provider` narrowed to a known key by the check above
+    return factory(model=model, api_key=api_key, max_tokens=max_tokens)

thinchat/structured_output.py

@@ -0,0 +1,65 @@
+"""Turn a model's text reply into a JSON object, and ask for one in the first place.
+
+Structured output has two halves. A client that supports it natively (OpenAI's
+``response_format``) constrains the reply to a schema at the API; one that does not is
+steered by appending the schema to the prompt. Either way the reply is text that must be
+parsed, and models wrap JSON in prose or ```json fences often enough that a bare
+``json.loads`` is too brittle -- so parsing strips the common wrappers first. Schema
+validation stops at "it is a JSON object": deep validation would need a schema library,
+and the caller, which owns the schema, checks its own fields.
+"""
+
+from __future__ import annotations
+
+import json
+
+from thinchat.errors import LLMError
+
+__all__ = ["make_json_instruction", "parse_json"]
+
+
+def make_json_instruction(schema: dict[str, object]) -> str:
+    """The line appended to a system prompt to steer a client with no native structured
+    output: reply as JSON matching this schema, nothing else."""
+    return (
+        "Reply with a single JSON object matching this JSON Schema, and nothing else -- "
+        f"no prose, no code fences:\n{json.dumps(schema)}"
+    )
+
+
+def parse_json(reply: str) -> dict[str, object]:
+    """Parse ``reply`` into a JSON object. Tolerates a ```json fence and a prose preamble or
+    trailer around the object; it takes the outermost ``{`` .. ``}`` span, so brace
+    characters *inside* the surrounding prose can widen the span and fail the parse (raising,
+    never returning a wrong object). Returns the parsed object.
+
+    Raises:
+        LLMError: the reply is empty, holds no JSON object, or the JSON is not an object.
+    """
+    text = _unfence(reply).strip()
+    if not text:
+        raise LLMError("structured request returned an empty reply")
+    # A model that adds a sentence around the object still parses if we take the outermost
+    # brace span; a bare json.loads would fail on the surrounding prose.
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end <= start:
+        raise LLMError(f"structured reply held no JSON object: {text[:120]}")
+    try:
+        parsed = json.loads(text[start : end + 1])
+    except json.JSONDecodeError as err:
+        raise LLMError(f"structured reply was not valid JSON: {text[:120]}") from err
+    if not isinstance(parsed, dict):
+        raise LLMError("structured reply was JSON but not an object")
+    return parsed
+
+
+def _unfence(text: str) -> str:
+    """Strip a leading ```json / ``` fence and its closing ``` if present, else return
+    ``text`` unchanged -- the one wrapper common enough to handle before brace-scanning."""
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return text
+    body = stripped[3:]
+    if body[:4].lower() == "json":
+        body = body[4:]
+    return body.rsplit("```", 1)[0]

thinchat-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: thinchat
+Version: 0.1.0
+Summary: A tiny, unified client for four LLM providers: claude, openai, gemini, ollama.
+Project-URL: Homepage, https://github.com/seokhoonj/thinchat
+Project-URL: Repository, https://github.com/seokhoonj/thinchat
+Project-URL: Issues, https://github.com/seokhoonj/thinchat/issues
+Author-email: seokhoonj <seokhoonj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,completion,embeddings,gemini,llm,ollama,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: httpx>=0.23
+Requires-Dist: openai>=1.30
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# thinchat
+
+**English** | [한국어](README.ko.md)
+
+A tiny, unified client for four LLM providers — **claude, openai, gemini, ollama**.
+
+Name a provider, then call it. Every client offers completion — whole, streamed, or
+JSON-structured — and, where the provider has one, embeddings, each with an async twin. No
+gateway, no router, no cost tracking: just the calls, over the providers' own SDKs.
+
+## How it works
+
+```mermaid
+flowchart LR
+  M["make_client(provider)"] --> C["Client<br/>openai-compatible · or claude"]
+  C --> V["complete · stream · parse · embed<br/>(+ a-prefixed async twins)"]
+  V --> S{{"vendor SDK"}}
+  S -->|ok| O(["str · dict · list float · stream"])
+  S -->|"SDK / transport error"| E(["LLMError"])
+```
+
+`make_client` looks the provider up in one factory map: openai/gemini/ollama share a single
+class over the openai SDK (they differ only in data); claude has its own over anthropic.
+A call builds the request, hits the SDK, and either extracts the reply or maps the failure
+to one `LLMError`.
+
+## Install
+
+```sh
+pip install thinchat
+```
+
+Both provider SDKs (openai and anthropic) come with it, so every provider works out of the
+box; each is imported lazily the first time you construct its client.
+
+## Use
+
+```python
+from thinchat import make_client
+
+llm = make_client("claude")                     # key from CLAUDE_API_KEY
+print(llm.complete("Say hi in one word."))
+print(llm.complete("Name a color.", system="Answer in one word."))   # system= steers any verb
+
+# Structured output: reply parsed into a JSON object. The schema steers generation
+# but is not validated locally, so check the returned dict's fields yourself.
+verdict = llm.parse(
+    "Is this an ad? 'Buy now, 50% off — order today'",
+    schema={"type": "object",
+            "properties": {"is_ad": {"type": "boolean"}, "reason": {"type": "string"}},
+            "required": ["is_ad"]},
+)
+print(verdict["is_ad"])
+
+# Streaming.
+for chunk in make_client("claude").stream("Count to five."):
+    print(chunk, end="")
+
+# Embeddings (openai / gemini / ollama; Claude has none).
+vectors = make_client("openai").embed(["hello", "world"])
+```
+
+Every verb has an async twin — `acomplete`, `astream`, `aparse`, `aembed`:
+
+```python
+llm = make_client("claude")
+text = await llm.acomplete("Summarize in one line: ...")
+```
+
+## Providers
+
+| provider | key env           | embeddings |
+|----------|-------------------|------------|
+| `claude` | `CLAUDE_API_KEY`  | no         |
+| `openai` | `OPENAI_API_KEY`  | yes        |
+| `gemini` | `GEMINI_API_KEY`  | yes        |
+| `ollama` | none (local)      | yes        |
+
+openai, gemini, and ollama speak the same OpenAI-compatible API, so one SDK serves all
+three; only the base URL, key, and default models differ. Ollama runs locally
+(`OLLAMA_HOST`, default `http://localhost:11434`) and needs no key.
+
+`max_tokens` caps the reply length — `make_client("claude", max_tokens=8192)`. Anthropic
+requires the field, so claude defaults to 4096; the OpenAI-compatible providers omit it unless
+you pass one, letting the model decide.
+
+Keys are read from the environment. Set them once in your shell profile (`~/.bashrc`,
+`~/.zshrc`) so every session picks them up — thinchat is a library and never imposes a file
+location of its own:
+
+```sh
+export CLAUDE_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+export GEMINI_API_KEY="..."          # ollama runs locally and needs no key
+```
+
+Or pass a key explicitly, which overrides the environment:
+
+```python
+llm = make_client("claude", api_key="sk-ant-...", model="claude-haiku-4-5-20251001")
+```
+
+## Capabilities
+
+A client whose provider lacks a capability raises `UnsupportedError`. The capabilities are
+`completion`, `streaming`, `structured_output`, and `embeddings`; check first with `supports`:
+
+```python
+make_client("claude").supports("embeddings")   # False
+```
+
+## Errors
+
+Everything thinchat raises on purpose derives from `ThinchatError`, so one `except` handles
+the package's failures:
+
+- `UnknownProviderError` — the name isn't one of the four providers.
+- `ProviderUnavailableError` — the provider's SDK isn't installed, or no API key is set.
+- `UnsupportedError` — the provider lacks the capability (e.g. embeddings on Claude).
+- `LLMError` — the API call failed, or the reply was empty or malformed.
+
+## Lifecycle
+
+A client holds an HTTP connection pool. For a one-off script you can ignore it; for a
+server that builds a client per request, close it so connections do not leak — use it as a
+context manager, or call `close()` / `aclose()`:
+
+```python
+with make_client("claude") as llm:
+    llm.complete("...")                 # sync: closes the pool on exit
+
+async with make_client("claude") as llm:
+    await llm.acomplete("...")          # async: closes the async pool too
+```
+
+`close()` frees the sync pool; if you drove async verbs, release with `aclose()` or
+`async with` so the async pool is closed as well.
+
+## License
+
+MIT

thinchat-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+thinchat/__init__.py,sha256=7KEdu_en4HK1RwDOMfDlsHu1ZS-nZcndoDdx-uWXDhM,1771
+thinchat/claude_client.py,sha256=u7HKCJ5khHfWYmjrJfbnPKSCl1MmhqutbTIuRDq95CU,6271
+thinchat/client.py,sha256=6ZqofpyZGCIhGS92TtTenLoK28i1dRhnrSASJM3ERJE,10353
+thinchat/errors.py,sha256=tOhURTUmQ4a4qIvrw6WhpGEHkJt5GmvsNT-F8RpUkpw,1772
+thinchat/keys.py,sha256=YzX0Qnzm6GCmQ4794aftYHKfF0VtiWt6C7R9UXcujgU,1314
+thinchat/openai_client.py,sha256=MH16O5wmEgKk7tasLR5yTxGDXlhGqqTS7ygpZfNg6II,13930
+thinchat/providers.py,sha256=fUXidKH0pJWxm8tXwbs7TeJomP_WqUNL2wr8MIgnkYM,2950
+thinchat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thinchat/structured_output.py,sha256=l5mdzF0SsWFrB_BoPBt1CkEjiC3K4ZqmYM6Qges2lbQ,2858
+thinchat-0.1.0.dist-info/METADATA,sha256=dibtTqv_6yDkemiT5HS3EBpJ7fpn01fXe9pmPm6sLJw,6078
+thinchat-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thinchat-0.1.0.dist-info/licenses/LICENSE,sha256=O5S_tbTQR3TmHsllCuNieSABx8AubsZe-hyiFVsOE8o,1066
+thinchat-0.1.0.dist-info/RECORD,,

thinchat-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

thinchat-0.1.0.dist-info/licenses/LICENSE

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