feat: Add multi-turn conversation support and OpenResponses/Ollama providers (withceleste#111)

* feat: add multi-turn conversation support with Message and Role types

Adds first-class conversation primitives for multi-turn workflows:
- New types: `Message` (role + content) and `Role` enum (user/assistant/system/developer)
- All text entrypoints now accept `messages=` parameter:
  * Namespace: `celeste.text.generate(...)`, `celeste.text.stream.generate(...)`, `celeste.text.sync.generate(...)`
  * Client: `create_client(modality="text", ...).generate(...)` and `.analyze(...)`
- When `messages` are provided, they take precedence over `prompt` (which becomes optional)
- Provider normalization handles different API formats:
  * Anthropic: system/developer messages lifted to top-level `system`
  * Google: system/developer messages lifted to `system_instruction`; assistant role becomes `model`
  * Chat-style providers: `messages=[...]` arrays (Cohere/Mistral/Groq/DeepSeek/Moonshot)
  * Responses-style providers: `input=[...]` arrays (OpenAI/xAI)
- Foundation for agents and multi-step workflows requiring conversation state persistence

Files changed:
- Core types: `src/celeste/types.py`
- Text IO: `src/celeste/modalities/text/io.py`
- Text client: `src/celeste/modalities/text/client.py`
- All 9 text provider clients updated
- Namespace API: `src/celeste/namespaces/domains.py`
- Public exports: `src/celeste/__init__.py`

* feat: add OpenResponses provider and Ollama local support

Adds support for OpenAI Responses-compatible APIs and local model hosting:

OpenResponses Provider:
- New `Provider.OPENRESPONSES` implementing OpenAI Responses API surface
- Compatible with `POST /v1/responses` endpoint + SSE parsing
- Supports structured outputs via `output_schema` → `text.format = json_schema`
- Normalizes usage fields to Celeste's unified usage model
- Supports `base_url=` parameter for custom API gateways

Ollama Provider:
- New `Provider.OLLAMA` as a local wrapper over OpenResponses protocol
- Default base URL: `http://localhost:11434`
- Uses `NoAuth` authentication (no headers required)
- Supports unregistered local models with parameter validation warnings

Infrastructure:
- Added `NoAuth` class for local providers that don't require authentication
- Added `base_url=` plumbing on text APIs for targeting local gateways
- Supports rapid local iteration with unregistered models

Files added:
- `src/celeste/providers/openresponses/` (full provider implementation)
- `src/celeste/modalities/text/providers/openresponses/` (text modality client)
- `src/celeste/providers/ollama/` (Ollama wrapper)
- `src/celeste/modalities/text/providers/ollama/` (Ollama text client)

Files modified:
- `src/celeste/core.py` (Provider enums)
- `src/celeste/auth.py` (NoAuth)
- `src/celeste/client.py` (base_url support)
- `src/celeste/modalities/text/models.py` (OLLAMA_MODELS)
- Provider exports updated

* fix: resolve mypy error and apply formatting fixes for messages feature

- Fix variable name collision in anthropic client (content -> prompt_content)
- Apply ruff formatting fixes to provider clients and namespace API

* fix: add class definition to ollama client for template contract

- Convert OllamaClient from alias to proper class inheriting OpenResponsesClient
- Apply ruff formatting fixes to openresponses provider files

* fix: exclude wrapper providers from template contract test

- Revert OllamaClient to simple alias (it's just a wrapper)
- Update test to skip wrapper providers like ollama that re-export another provider's client
- Wrapper providers don't need to match the template contract since they delegate to the wrapped provider

* chore: bump version to 0.9.1

Author: Kamilbenkirane

CHANGELOG_V1.md

@@ -91,7 +91,7 @@ Date: 2026-01-15
 - File updated: `README.md`.
 
 ## Release Prep
-- Set package version to `0.9.0` for the public v1 beta.
+- Set package version to `0.9.1` for the public v1 beta.
 - Updated development status classifier to Beta.
 - Removed notebook/scraping-only runtime deps from install requirements (ipykernel, matplotlib, beautifulsoup4).
 - File updated: `pyproject.toml`.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "celeste-ai"
-version = "0.9.0"
+version = "0.9.1"
 description = "Open source, type-safe primitives for multi-modal AI. All capabilities, all providers, one interface"
 authors = [{name = "Kamilbenkirane", email = "kamil@withceleste.ai"}]
 readme = "README.md"

src/celeste/__init__.py

@@ -50,7 +50,7 @@
     StrictJsonSchemaGenerator,
     StrictRefResolvingJsonSchemaGenerator,
 )
-from celeste.types import JsonValue
+from celeste.types import Content, JsonValue, Message, Role
 from celeste.websocket import WebSocketClient, WebSocketConnection, close_all_ws_clients
 
 logger = logging.getLogger(__name__)
@@ -244,10 +244,12 @@ def create_client(
     "Capability",
     "ClientNotFoundError",
     "ConstraintViolationError",
+    "Content",
     "Error",
     "HTTPClient",
     "Input",
     "JsonValue",
+    "Message",
     "MissingCredentialsError",
     "Modality",
     "ModalityClient",
@@ -259,6 +261,7 @@ def create_client(
     "Parameters",
     "Provider",
     "RefResolvingJsonSchemaGenerator",
+    "Role",
     "StreamEmptyError",
     "StreamNotExhaustedError",
     "StreamingNotSupportedError",

src/celeste/auth.py

@@ -45,6 +45,14 @@ def get_headers(self) -> dict[str, str]:
         return {self.header: f"{self.prefix}{self.secret.get_secret_value()}"}
 
 
+class NoAuth(Authentication):
+    """Authentication that returns no headers (local providers)."""
+
+    def get_headers(self) -> dict[str, str]:
+        """Return empty headers for unauthenticated requests."""
+        return {}
+
+
 # Backwards compatibility alias
 APIKey = AuthHeader
 
@@ -78,4 +86,11 @@ def get_auth_class(auth_type: str) -> type[Authentication]:
     return _auth_classes[auth_type]
 
 
-__all__ = ["APIKey", "AuthHeader", "Authentication", "get_auth_class", "register_auth"]
+__all__ = [
+    "APIKey",
+    "AuthHeader",
+    "Authentication",
+    "NoAuth",
+    "get_auth_class",
+    "register_auth",
+]

src/celeste/client.py

@@ -180,6 +180,9 @@ def _stream(
         self,
         inputs: In,
         stream_class: type[Stream[Out, Params, Chunk]],
+        *,
+        endpoint: str | None = None,
+        base_url: str | None = None,
         extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[Params],  # type: ignore[misc]
     ) -> Stream[Out, Params, Chunk]:
@@ -207,7 +210,9 @@ def _stream(
         request_body = self._build_request(
             inputs, extra_body=extra_body, streaming=True, **parameters
         )
-        sse_iterator = self._make_stream_request(request_body, **parameters)
+        sse_iterator = self._make_stream_request(
+            request_body, endpoint=endpoint, base_url=base_url, **parameters
+        )
         return stream_class(
             sse_iterator,
             transform_output=self._transform_output,

src/celeste/core.py

@@ -25,6 +25,8 @@ class Provider(StrEnum):
     ELEVENLABS = "elevenlabs"
     GROQ = "groq"
     GRADIUM = "gradium"
+    OPENRESPONSES = "openresponses"
+    OLLAMA = "ollama"
 
 
 class Modality(StrEnum):

src/celeste/modalities/text/client.py

@@ -1,12 +1,12 @@
 """Text modality client."""
 
-from typing import Unpack
+from typing import Any, Unpack
 
 from asgiref.sync import async_to_sync
 
 from celeste.client import ModalityClient
 from celeste.core import InputType, Modality
-from celeste.types import AudioContent, ImageContent, TextContent, VideoContent
+from celeste.types import AudioContent, ImageContent, Message, TextContent, VideoContent
 
 from .io import TextInput, TextOutput
 from .parameters import TextParameters
@@ -69,7 +69,11 @@ def __init__(self, client: TextClient) -> None:
 
     def generate(
         self,
-        prompt: str,
+        prompt: str | None = None,
+        *,
+        messages: list[Message] | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextStream:
         """Stream text generation.
@@ -78,20 +82,25 @@ def generate(
             async for chunk in client.stream.generate("Hello"):
                 print(chunk.content)
         """
-        inputs = TextInput(prompt=prompt)
+        inputs = TextInput(prompt=prompt, messages=messages)
         return self._client._stream(
             inputs,
             stream_class=self._client._stream_class(),
+            base_url=base_url,
+            extra_body=extra_body,
             **parameters,
         )
 
     def analyze(
         self,
-        prompt: str,
+        prompt: str | None = None,
         *,
+        messages: list[Message] | None = None,
         image: ImageContent | None = None,
         video: VideoContent | None = None,
         audio: AudioContent | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextStream:
         """Stream media analysis (image, video, or audio).
@@ -106,11 +115,16 @@ def analyze(
             async for chunk in client.stream.analyze("Transcribe", audio=aud):
                 print(chunk.content)
         """
-        self._client._check_media_support(image=image, video=video, audio=audio)
-        inputs = TextInput(prompt=prompt, image=image, video=video, audio=audio)
+        if messages is None:
+            self._client._check_media_support(image=image, video=video, audio=audio)
+        inputs = TextInput(
+            prompt=prompt, messages=messages, image=image, video=video, audio=audio
+        )
         return self._client._stream(
             inputs,
             stream_class=self._client._stream_class(),
+            base_url=base_url,
+            extra_body=extra_body,
             **parameters,
         )
 
@@ -126,7 +140,11 @@ def __init__(self, client: TextClient) -> None:
 
     def generate(
         self,
-        prompt: str,
+        prompt: str | None = None,
+        *,
+        messages: list[Message] | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextOutput:
         """Blocking text generation.
@@ -135,16 +153,21 @@ def generate(
             result = client.sync.generate("Hello")
             print(result.content)
         """
-        inputs = TextInput(prompt=prompt)
-        return async_to_sync(self._client._predict)(inputs, **parameters)
+        inputs = TextInput(prompt=prompt, messages=messages)
+        return async_to_sync(self._client._predict)(
+            inputs, base_url=base_url, extra_body=extra_body, **parameters
+        )
 
     def analyze(
         self,
-        prompt: str,
+        prompt: str | None = None,
         *,
+        messages: list[Message] | None = None,
         image: ImageContent | None = None,
         video: VideoContent | None = None,
         audio: AudioContent | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextOutput:
         """Blocking media analysis (image, video, or audio).
@@ -159,9 +182,14 @@ def analyze(
             result = client.sync.analyze("Transcribe", audio=aud)
             print(result.content)
         """
-        self._client._check_media_support(image=image, video=video, audio=audio)
-        inputs = TextInput(prompt=prompt, image=image, video=video, audio=audio)
-        return async_to_sync(self._client._predict)(inputs, **parameters)
+        if messages is None:
+            self._client._check_media_support(image=image, video=video, audio=audio)
+        inputs = TextInput(
+            prompt=prompt, messages=messages, image=image, video=video, audio=audio
+        )
+        return async_to_sync(self._client._predict)(
+            inputs, base_url=base_url, extra_body=extra_body, **parameters
+        )
 
     @property
     def stream(self) -> "TextSyncStreamNamespace":
@@ -177,7 +205,11 @@ def __init__(self, client: TextClient) -> None:
 
     def generate(
         self,
-        prompt: str,
+        prompt: str | None = None,
+        *,
+        messages: list[Message] | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextStream:
         """Sync streaming text generation.
@@ -191,15 +223,24 @@ def generate(
             print(stream.output.usage)
         """
         # Return same stream as async version - __iter__/__next__ handle sync iteration
-        return self._client.stream.generate(prompt, **parameters)
+        return self._client.stream.generate(
+            prompt,
+            messages=messages,
+            base_url=base_url,
+            extra_body=extra_body,
+            **parameters,
+        )
 
     def analyze(
         self,
-        prompt: str,
+        prompt: str | None = None,
         *,
+        messages: list[Message] | None = None,
         image: ImageContent | None = None,
         video: VideoContent | None = None,
         audio: AudioContent | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
         **parameters: Unpack[TextParameters],
     ) -> TextStream:
         """Sync streaming media analysis (image, video, or audio).
@@ -224,7 +265,14 @@ def analyze(
         """
         # Return same stream as async version - __iter__/__next__ handle sync iteration
         return self._client.stream.analyze(
-            prompt, image=image, video=video, audio=audio, **parameters
+            prompt,
+            messages=messages,
+            image=image,
+            video=video,
+            audio=audio,
+            base_url=base_url,
+            extra_body=extra_body,
+            **parameters,
         )
 
 

src/celeste/modalities/text/io.py

@@ -10,13 +10,14 @@
 from pydantic import Field
 
 from celeste.io import Chunk, FinishReason, Input, Output, Usage
-from celeste.types import AudioContent, ImageContent, TextContent, VideoContent
+from celeste.types import AudioContent, ImageContent, Message, TextContent, VideoContent
 
 
 class TextInput(Input):
     """Input for text operations."""
 
-    prompt: str
+    prompt: str | None = None
+    messages: list[Message] | None = None
     text: str | list[str] | None = None
     image: ImageContent | None = None
     video: VideoContent | None = None

src/celeste/modalities/text/models.py

@@ -9,6 +9,7 @@
 from .providers.groq.models import MODELS as GROQ_MODELS
 from .providers.mistral.models import MODELS as MISTRAL_MODELS
 from .providers.moonshot.models import MODELS as MOONSHOT_MODELS
+from .providers.ollama.models import MODELS as OLLAMA_MODELS
 from .providers.openai.models import MODELS as OPENAI_MODELS
 from .providers.xai.models import MODELS as XAI_MODELS
 
@@ -18,6 +19,7 @@
     *DEEPSEEK_MODELS,
     *GOOGLE_MODELS,
     *GROQ_MODELS,
+    *OLLAMA_MODELS,
     *MISTRAL_MODELS,
     *MOONSHOT_MODELS,
     *OPENAI_MODELS,

src/celeste/modalities/text/providers/__init__.py

@@ -10,7 +10,9 @@
 from .groq import GroqTextClient
 from .mistral import MistralTextClient
 from .moonshot import MoonshotTextClient
+from .ollama import OllamaTextClient
 from .openai import OpenAITextClient
+from .openresponses import OpenResponsesTextClient
 from .xai import XAITextClient
 
 PROVIDERS: dict[Provider, type[TextClient]] = {
@@ -19,6 +21,8 @@
     Provider.DEEPSEEK: DeepSeekTextClient,
     Provider.GOOGLE: GoogleTextClient,
     Provider.GROQ: GroqTextClient,
+    Provider.OLLAMA: OllamaTextClient,
+    Provider.OPENRESPONSES: OpenResponsesTextClient,
     Provider.MISTRAL: MistralTextClient,
     Provider.MOONSHOT: MoonshotTextClient,
     Provider.OPENAI: OpenAITextClient,