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

celeste/__init__.py

@@ -1,25 +1,116 @@
-"""
-Celeste AI Framework
+import importlib.metadata
+import logging
 
-A unified multi-modal AI framework for text, image, video, and audio generation.
+from pydantic import SecretStr
 
-This is a placeholder package to reserve the name. The full framework is coming soon!
-"""
+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
 
-__version__ = "0.0.1"
-__author__ = "agent-kai"
+logger = logging.getLogger(__name__)
 
-def create_client(*args, **kwargs):
-    """
-    Placeholder for the universal client factory.
 
-    The full implementation will provide a unified interface for all AI capabilities.
+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 | 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.
+
+    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/agent-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

@@ -0,0 +1,52 @@
+"""Unified artifact types for Celeste."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from celeste.mime_types import AudioMimeType, ImageMimeType, MimeType, VideoMimeType
+
+
+class Artifact(BaseModel):
+    """Base class for all media artifacts."""
+
+    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 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: ImageMimeType | None = None
+
+
+class VideoArtifact(Artifact):
+    """Video artifact from generation operations."""
+
+    mime_type: VideoMimeType | None = None
+
+
+class AudioArtifact(Artifact):
+    """Audio artifact from TTS/transcription operations."""
+
+    mime_type: AudioMimeType | None = None
+
+
+__all__ = [
+    "Artifact",
+    "AudioArtifact",
+    "ImageArtifact",
+    "VideoArtifact",
+]

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

@@ -0,0 +1,52 @@
+"""Core enumerations for Celeste."""
+
+from enum import StrEnum
+
+
+class Provider(StrEnum):
+    """Supported AI providers."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    MISTRAL = "mistral"
+    COHERE = "cohere"
+    XAI = "xai"
+    HUGGINGFACE = "huggingface"
+    REPLICATE = "replicate"
+    STABILITYAI = "stabilityai"
+    LUMA = "luma"
+    TOPAZLABS = "topazlabs"
+    PERPLEXITY = "perplexity"
+
+
+class Capability(StrEnum):
+    """Supported AI capabilities."""
+
+    # Text
+    TEXT_GENERATION = "text_generation"
+    EMBEDDINGS = "embeddings"
+
+    # Image
+    IMAGE_GENERATION = "image_generation"
+
+    # Video
+    VIDEO_INTELLIGENCE = "video_intelligence"
+    VIDEO_GENERATION = "video_generation"
+
+    # 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"]

celeste/credentials.py

@@ -0,0 +1,108 @@
+"""Provider API credentials management for Celeste."""
+
+from dotenv import find_dotenv
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings
+
+from celeste.core import Provider
+
+# Provider to credential field mapping
+PROVIDER_CREDENTIAL_MAP = {
+    Provider.OPENAI: "openai_api_key",
+    Provider.ANTHROPIC: "anthropic_api_key",
+    Provider.GOOGLE: "google_api_key",
+    Provider.MISTRAL: "mistral_api_key",
+    Provider.HUGGINGFACE: "huggingface_token",
+    Provider.STABILITYAI: "stabilityai_api_key",
+    Provider.REPLICATE: "replicate_api_token",
+    Provider.COHERE: "cohere_api_key",
+    Provider.XAI: "xai_api_key",
+    Provider.LUMA: "luma_api_key",
+    Provider.TOPAZLABS: "topazlabs_api_key",
+    Provider.PERPLEXITY: "perplexity_api_key",
+}
+
+
+class Credentials(BaseSettings):
+    """API credentials for all supported providers."""
+
+    openai_api_key: SecretStr | None = Field(None, alias="OPENAI_API_KEY")
+    anthropic_api_key: SecretStr | None = Field(None, alias="ANTHROPIC_API_KEY")
+    google_api_key: SecretStr | None = Field(None, alias="GOOGLE_API_KEY")
+    mistral_api_key: SecretStr | None = Field(None, alias="MISTRAL_API_KEY")
+    huggingface_token: SecretStr | None = Field(None, alias="HUGGINGFACE_TOKEN")
+    stabilityai_api_key: SecretStr | None = Field(None, alias="STABILITYAI_API_KEY")
+    replicate_api_token: SecretStr | None = Field(None, alias="REPLICATE_API_TOKEN")
+    cohere_api_key: SecretStr | None = Field(None, alias="COHERE_API_KEY")
+    xai_api_key: SecretStr | None = Field(None, alias="XAI_API_KEY")
+    luma_api_key: SecretStr | None = Field(None, alias="LUMA_API_KEY")
+    topazlabs_api_key: SecretStr | None = Field(None, alias="TOPAZLABS_API_KEY")
+    perplexity_api_key: SecretStr | None = Field(None, alias="PERPLEXITY_API_KEY")
+
+    model_config = {
+        "env_file": find_dotenv(),
+        "env_file_encoding": "utf-8",
+        "case_sensitive": False,
+        "extra": "ignore",  # Ignore unknown env vars like context7_api_key
+    }
+
+    def get_credentials(
+        self, provider: Provider, override_key: SecretStr | None = None
+    ) -> SecretStr:
+        """Get credentials for a specific provider with optional override.
+
+        Args:
+            provider: The AI provider to get credentials for.
+            override_key: Optional SecretStr to use instead of environment variable.
+
+        Returns:
+            SecretStr containing the API key for the provider.
+
+        Raises:
+            ValueError: If provider requires credentials but none are configured,
+                       or if provider is not supported (no credential mapping).
+        """
+        if override_key:
+            return override_key
+
+        if not self.has_credential(provider):
+            msg = f"Provider {provider} has no credentials configured."
+            raise ValueError(msg)
+
+        credential: SecretStr = getattr(self, PROVIDER_CREDENTIAL_MAP[provider])
+        return credential
+
+    def list_available_providers(self) -> list[Provider]:
+        """List all providers that have credentials configured.
+
+        Returns:
+            List of Provider enums that have credentials configured via environment variables.
+        """
+        return [
+            provider
+            for provider in PROVIDER_CREDENTIAL_MAP
+            if self.has_credential(provider)
+        ]
+
+    def has_credential(self, provider: Provider) -> bool:
+        """Check if a specific provider has credentials configured.
+
+        Args:
+            provider: The AI provider to check.
+
+        Returns:
+            True if provider has credentials configured, False if credentials not set.
+
+        Raises:
+            ValueError: If provider has no credential mapping.
+        """
+        credential_field = PROVIDER_CREDENTIAL_MAP.get(provider)
+        if not credential_field:
+            msg = f"Provider {provider} has no credential mapping"
+            raise ValueError(msg)
+        return getattr(self, credential_field, None) is not None
+
+
+credentials = Credentials.model_validate({})
+
+__all__ = ["Credentials", "credentials"]