celeste-ai 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

celeste/__init__.py

@@ -1,27 +1,116 @@
-"""Celeste AI Framework"""
+import importlib.metadata
+import logging
 
-__version__ = "0.0.1"
-__author__ = "agent-kai"
+from pydantic import SecretStr
 
-from celeste.core import Capability, Provider
+from celeste.client import Client, get_client_class, register_client
+from celeste.core import Capability, Parameter, Provider
+from celeste.credentials import credentials
+from celeste.http import HTTPClient, close_all_http_clients
+from celeste.io import Input, Output, Usage
+from celeste.models import Model, get_model, list_models, register_models
+from celeste.parameters import Parameters
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_model(
+    capability: Capability,
+    provider: Provider | None,
+    model: Model | str | None,
+) -> Model:
+    """Resolve model parameter to Model object (auto-select if None, lookup if string)."""
+    if model is None:
+        # Auto-select first available model
+        models = list_models(provider=provider, capability=capability)
+        if not models:
+            msg = f"No model found for {capability}"
+            raise ValueError(msg)
+        return models[0]
+
+    if isinstance(model, str):
+        # String ID requires provider
+        if not provider:
+            msg = "provider required when model is a string ID"
+            raise ValueError(msg)
+        found = get_model(model, provider)
+        if not found:
+            msg = f"Model '{model}' not found for provider {provider}"
+            raise ValueError(msg)
+        return found
+
+    return model
 
 
 def create_client(
     capability: Capability,
-    provider: Provider,
-    model: str,  # TODO: Use real Model type
-) -> None:
-    """
-    Placeholder for the universal client factory.
+    provider: Provider | None = None,
+    model: Model | str | None = None,
+    api_key: SecretStr | None = None,
+) -> Client:
+    """Create an async client for the specified AI capability.
+
+    Args:
+        capability: The AI capability to use (e.g., TEXT_GENERATION).
+        provider: Optional provider. Required if model is a string ID.
+        model: Model object, string model ID, or None for auto-selection.
+        api_key: Optional SecretStr override. If not specified, loaded from environment.
 
-    The full implementation will provide a unified interface for all AI capabilities.
+    Returns:
+        Configured client instance ready for generation operations.
+
+    Raises:
+        ValueError: If no model found or resolution fails.
+        NotImplementedError: If no client registered for capability/provider.
     """
-    raise NotImplementedError(
-        "Celeste AI is in development. "
-        "This is a placeholder package to reserve the name. "
-        "Follow updates at: https://github.com/celeste-kai/celeste-ai"
+    # Resolve model
+    resolved_model = _resolve_model(capability, provider, model)
+
+    # Get client class and credentials
+    client_class = get_client_class(capability, resolved_model.provider)
+    resolved_key = credentials.get_credentials(
+        resolved_model.provider, override_key=api_key
+    )
+
+    # Create and return client
+    return client_class(
+        model=resolved_model,
+        provider=resolved_model.provider,
+        capability=capability,
+        api_key=resolved_key,
     )
 
 
-# Placeholder exports
-__all__ = ["create_client"]
+def _load_from_entry_points() -> None:
+    """Load models and clients from installed packages via entry points."""
+    entry_points = importlib.metadata.entry_points(group="celeste.packages")
+
+    for ep in entry_points:
+        register_func = ep.load()
+        # The function should register models and clients when called
+        register_func()
+
+
+# Load from entry points on import
+_load_from_entry_points()
+
+# Exports
+__all__ = [
+    "Capability",
+    "Client",
+    "HTTPClient",
+    "Input",
+    "Model",
+    "Output",
+    "Parameter",
+    "Parameters",
+    "Provider",
+    "Usage",
+    "close_all_http_clients",
+    "create_client",
+    "get_client_class",
+    "get_model",
+    "list_models",
+    "register_client",
+    "register_models",
+]

celeste/artifacts.py

@@ -1,51 +1,47 @@
-"""Unified artifact types for the Celeste AI framework."""
+"""Unified artifact types for Celeste."""
 
-from typing import Any, Optional, Union
+from typing import Any
 
 from pydantic import BaseModel, Field
 
-from celeste.mime_types import AudioMimeType, ImageMimeType, VideoMimeType
+from celeste.mime_types import AudioMimeType, ImageMimeType, MimeType, VideoMimeType
 
 
 class Artifact(BaseModel):
-    """Base class for all media artifacts.
+    """Base class for all media artifacts."""
 
-    Artifacts can be represented in three ways:
-    - url: Remote HTTP/HTTPS URL (may expire, e.g., DALL-E URLs last 1 hour)
-    - data: In-memory bytes (for immediate use without download)
-    - path: Local filesystem path (for local providers or saved files)
-
-    Providers typically populate only one of these fields.
-    """
-
-    url: Optional[str] = None
-    data: Optional[bytes] = None
-    path: Optional[str] = None
-    mime_type: Optional[str] = None  # Standard MIME type for the artifact
+    url: str | None = None
+    data: bytes | None = None
+    path: str | None = None
+    mime_type: MimeType | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     @property
     def has_content(self) -> bool:
         """Check if artifact has any content."""
-        return bool(self.url or self.data or self.path)
+        return bool(
+            (self.url and self.url.strip())
+            or self.data
+            or (self.path and self.path.strip())
+        )
 
 
 class ImageArtifact(Artifact):
     """Image artifact from generation/edit operations."""
 
-    mime_type: Optional[Union[ImageMimeType, str]] = None
+    mime_type: ImageMimeType | None = None
 
 
 class VideoArtifact(Artifact):
     """Video artifact from generation operations."""
 
-    mime_type: Optional[Union[VideoMimeType, str]] = None
+    mime_type: VideoMimeType | None = None
 
 
 class AudioArtifact(Artifact):
     """Audio artifact from TTS/transcription operations."""
 
-    mime_type: Optional[Union[AudioMimeType, str]] = None
+    mime_type: AudioMimeType | None = None
 
 
 __all__ = [

celeste/client.py

@@ -0,0 +1,150 @@
+"""Base client and client registry for AI capabilities."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Unpack
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from celeste.core import Capability, Provider
+from celeste.http import HTTPClient, get_http_client
+from celeste.io import Input, Output, Usage
+from celeste.models import Model
+from celeste.parameters import ParameterMapper, Parameters
+from celeste.streaming import Stream
+
+
+class Client[In: Input, Out: Output](ABC, BaseModel):
+    """Base class for all capability-specific clients."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    model: Model
+    provider: Provider
+    capability: Capability
+    api_key: SecretStr = Field(exclude=True)
+
+    def model_post_init(self, __context: object) -> None:
+        """Validate capability compatibility."""
+        if self.capability not in self.model.capabilities:
+            raise ValueError(
+                f"Model '{self.model.id}' does not support capability {self.capability.value}"
+            )
+
+    @property
+    def http_client(self) -> HTTPClient:
+        """Shared HTTP client with connection pooling for this provider."""
+        return get_http_client(self.provider, self.capability)
+
+    @classmethod
+    @abstractmethod
+    def parameter_mappers(cls) -> list[ParameterMapper]:
+        """Provider-specific parameter mappers."""
+        ...
+
+    @abstractmethod
+    def _init_request(self, inputs: In) -> dict[str, Any]:
+        """Initialize provider-specific base request structure."""
+        pass
+
+    @abstractmethod
+    def _parse_usage(self, response_data: dict[str, Any]) -> Usage:
+        """Parse usage information from provider response."""
+        pass
+
+    @abstractmethod
+    def _parse_content(
+        self, response_data: dict[str, Any], **parameters: Unpack[Parameters]
+    ) -> object:
+        """Parse content from provider response."""
+        pass
+
+    def _transform_output(
+        self, content: object, **parameters: Unpack[Parameters]
+    ) -> object:
+        """Transform content using parameter mapper output transformations."""
+        for mapper in self.parameter_mappers():
+            value = parameters.get(mapper.name)
+            if value is not None:
+                content = mapper.parse_output(content, value)
+        return content
+
+    def _build_request(
+        self, inputs: In, **parameters: Unpack[Parameters]
+    ) -> dict[str, Any]:
+        """Build complete request by combining base request with parameters."""
+        request = self._init_request(inputs)
+
+        # Apply parameter mappers from registry
+        for mapper in self.parameter_mappers():
+            value = parameters.get(mapper.name)
+            request = mapper.map(request, value, self.model)
+
+        return request
+
+    def stream(self, *args: Any, **parameters: Unpack[Parameters]) -> Stream[Out]:  # noqa: ANN401
+        """Stream content - signature varies by capability.
+
+        Args:
+            *args: Capability-specific positional arguments (same as generate).
+            **parameters: Capability-specific keyword arguments (same as generate).
+
+        Returns:
+            Stream yielding chunks and providing final Output.
+
+        Raises:
+            NotImplementedError: If capability doesn't support streaming.
+        """
+        msg = f"Streaming not supported for {self.capability.value} with provider {self.provider.value}"
+        raise NotImplementedError(msg)
+
+    @abstractmethod
+    async def generate(self, *args: Any, **parameters: Unpack[Parameters]) -> Out:  # noqa: ANN401
+        """Generate content - signature varies by capability.
+
+        Args:
+            *args: Capability-specific positional arguments (prompt, text, image_url, etc.).
+            **parameters: Capability-specific keyword arguments (temperature, max_tokens, etc.).
+
+        Returns:
+            Output of the parameterized type (e.g., TextGenerationOutput).
+        """
+        pass
+
+
+_clients: dict[tuple[Capability, Provider], type[Client]] = {}
+
+
+def register_client(
+    capability: Capability, provider: Provider, client_class: type[Client]
+) -> None:
+    """Register a provider-specific client class for a capability.
+
+    Args:
+        capability: The capability this client implements.
+        provider: The provider this client uses.
+        client_class: The client class to register.
+    """
+    _clients[(capability, provider)] = client_class
+
+
+def get_client_class(capability: Capability, provider: Provider) -> type[Client]:
+    """Get the registered client class for a capability and provider.
+
+    Args:
+        capability: The capability to get a client for.
+        provider: The provider to use.
+
+    Returns:
+        The registered client class.
+
+    Raises:
+        NotImplementedError: If no client is registered for this capability/provider.
+    """
+    if (capability, provider) not in _clients:
+        raise NotImplementedError(
+            f"No client registered for {capability.value} with provider {provider.value}"
+        )
+    return _clients[(capability, provider)]
+
+
+__all__ = ["Client", "get_client_class", "register_client"]

celeste/constraints.py

@@ -0,0 +1,180 @@
+"""Constraint models for parameter validation."""
+
+import math
+import re
+from abc import ABC, abstractmethod
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel, Field
+
+
+class Constraint(BaseModel, ABC):
+    """Base constraint for parameter validation."""
+
+    @abstractmethod
+    def __call__(self, value: Any) -> Any:  # noqa: ANN401
+        """Validate value against constraint and return validated value."""
+        ...
+
+
+class Choice[T](Constraint):
+    """Choice constraint - value must be one of the provided options."""
+
+    options: list[T] = Field(min_length=1)
+
+    def __call__(self, value: T) -> T:
+        """Validate value is in options."""
+        if value not in self.options:
+            msg = f"Must be one of {self.options}, got {value!r}"
+            raise ValueError(msg)
+        return value
+
+
+class Range(Constraint):
+    """Range constraint - value must be within min/max bounds.
+
+    If step is provided, value must be at min + (n * step) for some integer n.
+    """
+
+    min: float | int
+    max: float | int
+    step: float | None = None
+
+    def __call__(self, value: float | int) -> float | int:
+        """Validate value is within range and matches step increment."""
+        if not isinstance(value, (int, float)):
+            msg = f"Must be numeric, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        if not self.min <= value <= self.max:
+            msg = f"Must be between {self.min} and {self.max}, got {value}"
+            raise ValueError(msg)
+
+        if self.step is not None:
+            remainder = (value - self.min) % self.step
+            # Use epsilon for floating-point comparison tolerance
+            epsilon = 1e-9
+            if not math.isclose(remainder, 0, abs_tol=epsilon) and not math.isclose(
+                remainder, self.step, abs_tol=epsilon
+            ):
+                # Calculate nearest valid values for actionable error message
+                closest_below = self.min + (
+                    int((value - self.min) / self.step) * self.step
+                )
+                closest_above = closest_below + self.step
+                msg = f"Value must match step {self.step}. Nearest valid: {closest_below} or {closest_above}, got {value}"
+                raise ValueError(msg)
+
+        return value
+
+
+class Pattern(Constraint):
+    """Pattern constraint - value must match regex pattern."""
+
+    pattern: str
+
+    def __call__(self, value: str) -> str:
+        """Validate value matches pattern."""
+        if not isinstance(value, str):
+            msg = f"Must be string, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        if not re.fullmatch(self.pattern, value):
+            msg = f"Must match pattern {self.pattern!r}, got {value!r}"
+            raise ValueError(msg)
+
+        return value
+
+
+class Str(Constraint):
+    """String type constraint with optional length validation."""
+
+    max_length: int | None = None
+    min_length: int | None = None
+
+    def __call__(self, value: str) -> str:
+        """Validate value is a string."""
+        if not isinstance(value, str):
+            msg = f"Must be string, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        if self.min_length is not None and len(value) < self.min_length:
+            msg = f"String too short (min {self.min_length}), got {len(value)}"
+            raise ValueError(msg)
+
+        if self.max_length is not None and len(value) > self.max_length:
+            msg = f"String too long (max {self.max_length}), got {len(value)}"
+            raise ValueError(msg)
+
+        return value
+
+
+class Int(Constraint):
+    """Integer type constraint."""
+
+    def __call__(self, value: int) -> int:
+        """Validate value is an integer."""
+        # isinstance(True, int) is True, so exclude bools explicitly
+        if not isinstance(value, int) or isinstance(value, bool):
+            msg = f"Must be int, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        return value
+
+
+class Float(Constraint):
+    """Float type constraint (accepts int as well)."""
+
+    def __call__(self, value: float) -> float:
+        """Validate value is numeric."""
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            msg = f"Must be float or int, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        return float(value)
+
+
+class Bool(Constraint):
+    """Boolean type constraint."""
+
+    def __call__(self, value: bool) -> bool:
+        """Validate value is a boolean."""
+        if not isinstance(value, bool):
+            msg = f"Must be bool, got {type(value).__name__}"
+            raise TypeError(msg)
+
+        return value
+
+
+class Schema(Constraint):
+    """Schema constraint - value must be a Pydantic BaseModel subclass or list[BaseModel]."""
+
+    def __call__(self, value: type[BaseModel]) -> type[BaseModel]:
+        """Validate value is BaseModel or list[BaseModel]."""
+        # For list[T], validate inner type T
+        if get_origin(value) is list:
+            inner = get_args(value)[0]
+            if not (isinstance(inner, type) and issubclass(inner, BaseModel)):
+                msg = f"List type must be BaseModel, got {inner}"
+                raise TypeError(msg)
+            return value
+
+        # For plain type, validate directly
+        if not (isinstance(value, type) and issubclass(value, BaseModel)):
+            msg = f"Must be BaseModel, got {value}"
+            raise TypeError(msg)
+
+        return value
+
+
+__all__ = [
+    "Bool",
+    "Choice",
+    "Constraint",
+    "Float",
+    "Int",
+    "Pattern",
+    "Range",
+    "Schema",
+    "Str",
+]

celeste/core.py

@@ -1,9 +1,9 @@
-"""Core enumerations for the Celeste AI Framework."""
+"""Core enumerations for Celeste."""
 
-from enum import Enum, Flag, auto
+from enum import StrEnum
 
 
-class Provider(str, Enum):
+class Provider(StrEnum):
     """Supported AI providers."""
 
     OPENAI = "openai"
@@ -17,19 +17,36 @@ class Provider(str, Enum):
     STABILITYAI = "stabilityai"
     LUMA = "luma"
     TOPAZLABS = "topazlabs"
-    OLLAMA = "ollama"
-    TRANSFORMERS = "transformers"
-    LOCAL = "local"
+    PERPLEXITY = "perplexity"
 
 
-class Capability(Flag):
+class Capability(StrEnum):
     """Supported AI capabilities."""
 
     # Text
-    TEXT_GENERATION = auto()
+    TEXT_GENERATION = "text_generation"
+    EMBEDDINGS = "embeddings"
 
     # Image
-    IMAGE_GENERATION = auto()
+    IMAGE_GENERATION = "image_generation"
 
+    # Video
+    VIDEO_INTELLIGENCE = "video_intelligence"
+    VIDEO_GENERATION = "video_generation"
 
-__all__ = ["Capability", "Provider"]
+    # Audio
+    AUDIO_INTELLIGENCE = "audio_intelligence"
+
+    # Search
+    SEARCH = "search"
+
+
+class Parameter(StrEnum):
+    """Universal parameters across most capabilities."""
+
+    TEMPERATURE = "temperature"
+    SEED = "seed"
+    MAX_TOKENS = "max_tokens"
+
+
+__all__ = ["Capability", "Parameter", "Provider"]