feat: add protocol= + base_url= for compatible APIs (#241)

* feat: add protocol= + base_url= for compatible APIs (#230)

Add support for pointing celeste at any OpenAI-compatible or
Anthropic-compatible API using protocol= and base_url= parameters.

- Add Protocol enum (openresponses, chatcompletions) to core.py
- Remove Provider.OPENRESPONSES (protocols aren't providers)
- Separate provider and protocol as independent fields on ModalityClient
- Wire base_url as instance field, used by _build_url()
- Add protocol= and base_url= to create_client() and domain namespaces
- Default to openresponses when base_url given without protocol
- BYOA auth: protocol path defaults to NoAuth, accepts api_key or auth
- Make Model.provider optional (None for protocol-path models)
- Remove dead base_url plumbing from per-call method signatures
- Fix credentials.get_auth to use api_key without registry entry
- Clean up OllamaGenerateClient to use _build_url() pattern
- Remove redundant .value on StrEnum in integration tests

Closes #230

* fix: remove redundant | str from StrEnum parameters (#237)

StrEnum values are already strings — the | str union on Modality,
Operation, Protocol, and Provider parameters was unnecessary.
Also remove isinstance(x, str) coercions that are no-ops on StrEnums.

Author: Kamilbenkirane

src/celeste/__init__.py

@@ -6,13 +6,14 @@
 from pydantic import SecretStr
 
 from celeste import providers as _providers  # noqa: F401
-from celeste.auth import APIKey, Authentication
+from celeste.auth import APIKey, Authentication, AuthHeader, NoAuth
 from celeste.client import ModalityClient
 from celeste.core import (
     Capability,
     Modality,
     Operation,
     Parameter,
+    Protocol,
     Provider,
     UsageField,
 )
@@ -42,6 +43,8 @@
 from celeste.modalities.images.models import MODELS as _images_models
 from celeste.modalities.images.providers import PROVIDERS as _images_providers
 from celeste.modalities.text.models import MODELS as _text_models
+from celeste.modalities.text.protocols.chatcompletions import ChatCompletionsTextClient
+from celeste.modalities.text.protocols.openresponses import OpenResponsesTextClient
 from celeste.modalities.text.providers import PROVIDERS as _text_providers
 from celeste.modalities.videos.models import MODELS as _videos_models
 from celeste.modalities.videos.providers import PROVIDERS as _videos_providers
@@ -58,12 +61,15 @@
 
 logger = logging.getLogger(__name__)
 
-_CLIENT_MAP: dict[tuple[Modality, Provider], type[ModalityClient]] = {
+_CLIENT_MAP: dict[tuple[Modality, Provider | Protocol], type[ModalityClient]] = {
     **{(Modality.TEXT, p): c for p, c in _text_providers.items()},
     **{(Modality.IMAGES, p): c for p, c in _images_providers.items()},
     **{(Modality.VIDEOS, p): c for p, c in _videos_providers.items()},
     **{(Modality.AUDIO, p): c for p, c in _audio_providers.items()},
     **{(Modality.EMBEDDINGS, p): c for p, c in _embeddings_providers.items()},
+    # Protocol entries (for compatible APIs via protocol= + base_url=)
+    (Modality.TEXT, Protocol.OPENRESPONSES): OpenResponsesTextClient,
+    (Modality.TEXT, Protocol.CHATCOMPLETIONS): ChatCompletionsTextClient,
 }
 
 for _model in [
@@ -73,6 +79,7 @@
     *_audio_models,
     *_embeddings_models,
 ]:
+    assert _model.provider is not None
     _models[(_model.id, _model.provider)] = _model
 
 _CAPABILITY_TO_MODALITY_OPERATION: dict[Capability, tuple[Modality, Operation]] = {
@@ -89,6 +96,7 @@ def _resolve_model(
     operation: Operation | None = None,
     provider: Provider | None = None,
     model: Model | str | None = None,
+    protocol: Protocol | None = None,
 ) -> Model:
     """Resolve model parameter to Model object (auto-select if None, lookup if string)."""
     if model is None:
@@ -110,6 +118,21 @@ def _resolve_model(
     if isinstance(model, str):
         found = get_model(model, provider)
         if not found:
+            # Protocol path: unregistered models are expected
+            if protocol is not None:
+                if modality is None:
+                    msg = f"Model '{model}' not registered. Specify 'modality' explicitly."
+                    raise ValueError(msg)
+                operations: dict[Modality, set[Operation]] = {}
+                if modality is not None:
+                    operations[modality] = {operation} if operation else set()
+                return Model(
+                    id=model,
+                    provider=provider,
+                    display_name=model,
+                    operations=operations,
+                    streaming=True,
+                )
             if provider is None:
                 raise ModelNotFoundError(model_id=model, provider=provider)
             if modality is None:
@@ -121,7 +144,7 @@ def _resolve_model(
                 UserWarning,
                 stacklevel=3,
             )
-            operations: dict[Modality, set[Operation]] = {}
+            operations = {}
             if modality is not None:
                 operations[modality] = {operation} if operation else set()
             return Model(
@@ -158,38 +181,37 @@ def _infer_operation(model: Model, modality: Modality) -> Operation:
 
 def create_client(
     capability: Capability | None = None,
-    modality: Modality | str | None = None,
-    operation: Operation | str | None = None,
+    modality: Modality | None = None,
+    operation: Operation | None = None,
     provider: Provider | None = None,
     model: Model | str | None = None,
     api_key: str | SecretStr | None = None,
     auth: Authentication | None = None,
+    protocol: Protocol | None = None,
+    base_url: str | None = None,
 ) -> ModalityClient:
     """Create an async client for the specified AI capability or modality.
 
     Args:
         capability: The AI capability to use (deprecated, use modality instead).
-                    If not provided and model is specified, capability is inferred
-                    from the model (if unambiguous).
         modality: The modality to use (e.g., Modality.IMAGES, "images").
-                  Preferred over capability for new code.
         operation: The operation to use (e.g., Operation.GENERATE, "generate").
-                   If not provided and model supports exactly one operation for the
-                   modality, it is inferred automatically.
-        provider: Optional provider. If not specified and model ID matches multiple
-                  providers, the first match is used with a warning.
+        provider: Optional provider (e.g., Provider.OPENAI).
         model: Model object, string model ID, or None for auto-selection.
         api_key: Optional API key override (string or SecretStr).
         auth: Optional Authentication object for custom auth (e.g., GoogleADC).
+        protocol: Wire format protocol for compatible APIs (e.g., "openresponses",
+                  "chatcompletions"). Use with base_url for third-party compatible APIs.
+        base_url: Custom base URL override. Use with protocol for compatible APIs,
+                  or with provider to proxy through a custom endpoint.
 
     Returns:
         Configured client instance ready for generation operations.
 
     Raises:
         ModelNotFoundError: If no model found for the specified capability/provider.
-        ClientNotFoundError: If no client registered for capability/provider.
+        ClientNotFoundError: If no client registered for capability/provider/protocol.
         MissingCredentialsError: If required credentials are not configured.
-        UnsupportedCapabilityError: If the resolved model doesn't support the requested capability.
         ValueError: If capability/operation cannot be inferred from model.
     """
     # Translation layer: convert deprecated capability to modality/operation
@@ -208,37 +230,56 @@ def create_client(
         msg = "Either 'modality' or 'model' must be provided"
         raise ValueError(msg)
 
-    resolved_modality = Modality(modality) if isinstance(modality, str) else modality
-    resolved_operation = (
-        Operation(operation) if isinstance(operation, str) else operation
-    )
-    resolved_provider = Provider(provider) if isinstance(provider, str) else provider
+    resolved_modality = modality
+    resolved_operation = operation
+    resolved_provider = provider
+    resolved_protocol = protocol
+
+    # Default to openresponses when base_url is given without protocol or provider
+    if base_url is not None and resolved_protocol is None and resolved_provider is None:
+        resolved_protocol = Protocol.OPENRESPONSES
 
     resolved_model = _resolve_model(
         modality=resolved_modality,
         operation=resolved_operation,
         provider=resolved_provider,
         model=model,
+        protocol=resolved_protocol,
     )
 
-    key = (resolved_modality, resolved_model.provider)
-    if key not in _CLIENT_MAP:
-        raise ClientNotFoundError(
-            modality=resolved_modality, provider=resolved_model.provider
-        )
-    modality_client_class = _CLIENT_MAP[key]
-
-    resolved_auth = credentials.get_auth(
-        resolved_model.provider,
-        override_auth=auth,
-        override_key=api_key,
+    # Client lookup: protocol takes precedence for compatible API path
+    target = (
+        resolved_protocol if resolved_protocol is not None else resolved_model.provider
     )
+    if target is None:
+        raise ClientNotFoundError(modality=resolved_modality)
+
+    if (resolved_modality, target) not in _CLIENT_MAP:
+        raise ClientNotFoundError(modality=resolved_modality, provider=target)
+    modality_client_class = _CLIENT_MAP[(resolved_modality, target)]
+
+    # Auth resolution: BYOA for protocol path, credentials for provider path
+    if resolved_protocol is not None and resolved_provider is None:
+        if auth is not None:
+            resolved_auth = auth
+        elif api_key is not None:
+            resolved_auth = AuthHeader(secret=api_key)  # type: ignore[arg-type]  # validator converts str
+        else:
+            resolved_auth = NoAuth()
+    else:
+        resolved_auth = credentials.get_auth(
+            resolved_model.provider,  # type: ignore[arg-type]  # always Provider in this branch
+            override_auth=auth,
+            override_key=api_key,
+        )
 
     return modality_client_class(
         modality=resolved_modality,
         model=resolved_model,
-        provider=resolved_model.provider,
+        provider=resolved_provider,
+        protocol=resolved_protocol,
         auth=resolved_auth,
+        base_url=base_url,
     )
 
 
@@ -264,6 +305,7 @@ def create_client(
     "Output",
     "Parameter",
     "Parameters",
+    "Protocol",
     "Provider",
     "RefResolvingJsonSchemaGenerator",
     "Role",

src/celeste/client.py

@@ -10,8 +10,12 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from celeste.auth import Authentication
-from celeste.core import Modality, Provider
-from celeste.exceptions import StreamingNotSupportedError, UnsupportedParameterWarning
+from celeste.core import Modality, Protocol, Provider
+from celeste.exceptions import (
+    ClientNotFoundError,
+    StreamingNotSupportedError,
+    UnsupportedParameterWarning,
+)
 from celeste.http import HTTPClient, get_http_client
 from celeste.io import Chunk as ChunkBase
 from celeste.io import FinishReason, Input, Output, Usage
@@ -47,7 +51,9 @@ class OpenAITextClient(OpenAIResponsesMixin, TextClient):
 
     model: Model
     auth: Authentication
-    provider: Provider
+    provider: Provider | None
+    protocol: Protocol | None
+    base_url: str | None
     _content_fields: ClassVar[set[str]] = set()
 
     @property
@@ -160,13 +166,19 @@ async def generate(self, prompt: str, **parameters) -> ImageGenerationOutput:
 
     modality: Modality
     model: Model
-    provider: Provider
+    provider: Provider | None = None
+    protocol: Protocol | None = None
     auth: Authentication = Field(exclude=True)
+    base_url: str | None = Field(None, exclude=True)
 
     @property
     def http_client(self) -> HTTPClient:
         """Shared HTTP client with connection pooling."""
-        return get_http_client(self.provider, self.modality)
+        if self.provider is not None:
+            return get_http_client(self.provider, self.modality)
+        if self.protocol is not None:
+            return get_http_client(self.protocol, self.modality)
+        raise ClientNotFoundError(modality=self.modality)
 
     # Namespace properties - implemented by modality clients
     @property
@@ -226,7 +238,6 @@ def _stream(
         stream_class: type[Stream[Out, Params, Chunk]],
         *,
         endpoint: str | None = None,
-        base_url: str | None = None,
         extra_body: dict[str, Any] | None = None,
         extra_headers: dict[str, str] | None = None,
         **parameters: Unpack[Params],  # type: ignore[misc]
@@ -259,7 +270,6 @@ def _stream(
         sse_iterator = self._make_stream_request(
             request_body,
             endpoint=endpoint,
-            base_url=base_url,
             extra_headers=extra_headers,
             **parameters,
         )
@@ -269,7 +279,7 @@ def _stream(
             transform_output=self._transform_output,
             stream_metadata={
                 "model": self.model.id,
-                "provider": self.provider,
+                "provider": self.provider or self.protocol,
                 "modality": self.modality,
             },
             **parameters,
@@ -361,12 +371,16 @@ def _build_metadata(self, response_data: dict[str, Any]) -> dict[str, Any]:
             response_data = {
                 k: v for k, v in response_data.items() if k not in self._content_fields
             }
-        return {
+        metadata: dict[str, Any] = {
             "model": self.model.id,
-            "provider": self.provider,
             "modality": self.modality,
             "raw_response": response_data,
         }
+        if self.provider is not None:
+            metadata["provider"] = self.provider
+        if self.protocol is not None:
+            metadata["protocol"] = self.protocol
+        return metadata
 
     def _handle_error_response(self, response: httpx.Response) -> None:
         """Handle error responses from provider APIs."""
@@ -383,7 +397,7 @@ def _handle_error_response(self, response: httpx.Response) -> None:
                 error_msg = response.text or f"HTTP {response.status_code}"
 
             raise httpx.HTTPStatusError(
-                f"{self.provider} API error: {error_msg}",
+                f"{self.provider or self.protocol} API error: {error_msg}",
                 request=response.request,
                 response=response,
             )

src/celeste/core.py

@@ -25,10 +25,16 @@ class Provider(StrEnum):
     ELEVENLABS = "elevenlabs"
     GROQ = "groq"
     GRADIUM = "gradium"
-    OPENRESPONSES = "openresponses"
     OLLAMA = "ollama"
 
 
+class Protocol(StrEnum):
+    """Wire format protocols for compatible APIs."""
+
+    OPENRESPONSES = "openresponses"
+    CHATCOMPLETIONS = "chatcompletions"
+
+
 class Modality(StrEnum):
     """Supported modalities."""
 
@@ -167,6 +173,7 @@ def infer_modality(domain: Domain, operation: Operation) -> Modality:
     "Modality",
     "Operation",
     "Parameter",
+    "Protocol",
     "Provider",
     "UsageField",
     "infer_modality",

src/celeste/credentials.py

@@ -176,6 +176,8 @@ def get_auth(
 
         registered = _auth_registry.get(provider)
         if registered is None:
+            if override_key is not None:
+                return AuthHeader(secret=override_key)  # type: ignore[arg-type]  # validator converts str
             raise UnsupportedProviderError(provider=provider)
 
         # Auth class (GoogleADC, OAuth, etc.) → instantiate

src/celeste/http.py

@@ -9,7 +9,7 @@
 import httpx
 from httpx_sse import aconnect_sse
 
-from celeste.core import Modality, Provider
+from celeste.core import Modality, Protocol, Provider
 
 logger = logging.getLogger(__name__)
 
@@ -246,10 +246,10 @@ async def __aexit__(self, *args: Any) -> None:  # noqa: ANN401
 
 
 # Module-level registry of shared HTTPClient instances
-_http_clients: dict[tuple[Provider, Modality], HTTPClient] = {}
+_http_clients: dict[tuple[Provider | Protocol, Modality], HTTPClient] = {}
 
 
-def get_http_client(provider: Provider, modality: Modality) -> HTTPClient:
+def get_http_client(provider: Provider | Protocol, modality: Modality) -> HTTPClient:
     """Get or create shared HTTP client for provider and modality combination.
 
     Args: