apple-foundation-models 0.1.9__cp311-cp311-macosx_11_0_arm64.whl

applefoundationmodels/__init__.py

@@ -0,0 +1,108 @@
+"""
+applefoundationmodels: Python bindings for Apple's FoundationModels framework
+
+High-level Pythonic interface for accessing Apple Intelligence on-device
+Foundation models.
+
+Basic usage:
+    from applefoundationmodels import Client
+
+    with Client() as client:
+        # Check availability
+        if not client.is_ready():
+            print("Apple Intelligence not available")
+            return
+
+        # Create a session and generate response
+        session = client.create_session()
+        response = session.generate("Hello, how are you?")
+        print(response)
+
+Async streaming:
+    import asyncio
+    from applefoundationmodels import Client
+
+    async def main():
+        with Client() as client:
+            session = client.create_session()
+            async for chunk in session.generate_stream("Tell me a story"):
+                print(chunk, end='', flush=True)
+
+    asyncio.run(main())
+"""
+
+__version__ = "0.1.0"
+
+# Public API exports
+from .client import Client, client
+from .session import Session
+from .constants import (
+    DEFAULT_TEMPERATURE,
+    DEFAULT_MAX_TOKENS,
+    MIN_TEMPERATURE,
+    MAX_TEMPERATURE,
+    TemperaturePreset,
+)
+from .types import (
+    Result,
+    Availability,
+    SessionConfig,
+    GenerationParams,
+    Stats,
+    StreamCallback,
+    ToolCallback,
+)
+from .exceptions import (
+    FoundationModelsError,
+    InitializationError,
+    NotAvailableError,
+    InvalidParametersError,
+    MemoryError,
+    JSONParseError,
+    GenerationError,
+    TimeoutError,
+    SessionNotFoundError,
+    StreamNotFoundError,
+    GuardrailViolationError,
+    ToolNotFoundError,
+    ToolExecutionError,
+    UnknownError,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes
+    "Client",
+    "Session",
+    "client",
+    # Constants
+    "DEFAULT_TEMPERATURE",
+    "DEFAULT_MAX_TOKENS",
+    "MIN_TEMPERATURE",
+    "MAX_TEMPERATURE",
+    "TemperaturePreset",
+    # Type definitions
+    "Result",
+    "Availability",
+    "SessionConfig",
+    "GenerationParams",
+    "Stats",
+    "StreamCallback",
+    "ToolCallback",
+    # Exceptions
+    "FoundationModelsError",
+    "InitializationError",
+    "NotAvailableError",
+    "InvalidParametersError",
+    "MemoryError",
+    "JSONParseError",
+    "GenerationError",
+    "TimeoutError",
+    "SessionNotFoundError",
+    "StreamNotFoundError",
+    "GuardrailViolationError",
+    "ToolNotFoundError",
+    "ToolExecutionError",
+    "UnknownError",
+]

applefoundationmodels/_foundationmodels.pyi

@@ -0,0 +1,52 @@
+"""Type stubs for _foundationmodels Cython extension."""
+
+from typing import Any, Callable, Dict, List, Optional
+
+# Initialization and cleanup
+def init() -> None: ...
+def cleanup() -> None: ...
+def get_version() -> str: ...
+
+# Availability functions
+def check_availability() -> int: ...
+def get_availability_reason() -> Optional[str]: ...
+def is_ready() -> bool: ...
+
+# Language support
+def get_supported_languages_count() -> int: ...
+def get_supported_language(index: int) -> Optional[str]: ...
+
+# Session management
+def create_session(config: Optional[Dict[str, Any]] = None) -> int: ...
+
+# Text generation
+def generate(prompt: str, temperature: float = 1.0, max_tokens: int = 1024) -> str: ...
+
+# Structured generation
+def generate_structured(
+    prompt: str,
+    schema: Dict[str, Any],
+    temperature: float = 1.0,
+    max_tokens: int = 1024,
+) -> Dict[str, Any]: ...
+
+# Streaming generation
+def generate_stream(
+    prompt: str,
+    callback: Callable[[Optional[str]], None],
+    temperature: float = 1.0,
+    max_tokens: int = 1024,
+) -> None: ...
+
+# History management
+def get_history() -> List[Any]: ...
+def clear_history() -> None: ...
+def add_message(role: str, content: str) -> None: ...
+
+# Tool calling
+def register_tools(tools: Dict[str, Callable]) -> None: ...
+def get_transcript() -> List[Dict[str, Any]]: ...
+
+# Statistics
+def get_stats() -> Dict[str, Any]: ...
+def reset_stats() -> None: ...

applefoundationmodels/base.py

@@ -0,0 +1,36 @@
+"""
+Base classes for applefoundationmodels.
+
+Provides base functionality for context-managed resources.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TypeVar
+
+T = TypeVar("T", bound="ContextManagedResource")
+
+
+class ContextManagedResource(ABC):
+    """
+    Base class for resources that support context manager protocol.
+
+    Provides standard __enter__ and __exit__ methods that call the
+    close() method on exit. Subclasses must implement close().
+    """
+
+    def __enter__(self: T) -> T:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit with automatic cleanup."""
+        self.close()
+
+    @abstractmethod
+    def close(self) -> None:
+        """
+        Close and cleanup resources.
+
+        Must be implemented by subclasses.
+        """
+        pass

applefoundationmodels/client.py

@@ -0,0 +1,231 @@
+"""
+High-level Client API for applefoundationmodels Python bindings.
+
+Provides a Pythonic interface to Apple's FoundationModels framework with
+context managers, automatic resource cleanup, and integration with the Session class.
+"""
+
+import platform
+from typing import Optional, List, cast
+from contextlib import contextmanager
+
+from . import _foundationmodels
+from .base import ContextManagedResource
+from .types import Availability, Stats
+from .session import Session
+from .exceptions import NotAvailableError
+
+
+class Client(ContextManagedResource):
+    """
+    High-level client for Apple Intelligence operations.
+
+    This class provides a Pythonic interface to Apple's FoundationModels framework,
+    managing sessions with automatic resource cleanup.
+
+    Usage:
+        with Client() as client:
+            session = client.create_session()
+            response = session.generate("Hello!")
+            print(response)
+    """
+
+    _initialized: bool = False
+
+    def __init__(self):
+        """
+        Create a new FoundationModels client.
+
+        The library is automatically initialized on first client creation.
+
+        Raises:
+            InitializationError: If library initialization fails
+            NotAvailableError: If Apple Intelligence is not available
+            RuntimeError: If platform is not supported
+        """
+        # Check platform requirements
+        if platform.system() != "Darwin":
+            raise NotAvailableError(
+                "Apple Intelligence is only available on macOS. "
+                f"Current platform: {platform.system()}"
+            )
+
+        # Check macOS version
+        mac_ver = platform.mac_ver()[0]
+        if mac_ver:
+            try:
+                major_version = int(mac_ver.split(".")[0])
+                if major_version < 26:
+                    raise NotAvailableError(
+                        f"Apple Intelligence requires macOS 26.0 or later. "
+                        f"Current version: {mac_ver}"
+                    )
+            except (ValueError, IndexError):
+                # If we can't parse the version, let it try anyway
+                pass
+
+        # Initialize library on first client creation
+        if not Client._initialized:
+            _foundationmodels.init()
+            Client._initialized = True
+
+        self._sessions: List[Session] = []
+
+    def close(self) -> None:
+        """
+        Close the client and cleanup all resources.
+
+        Destroys all sessions.
+        """
+        # Close all sessions
+        for session in self._sessions:
+            session.close()
+        self._sessions.clear()
+
+    @staticmethod
+    def check_availability() -> Availability:
+        """
+        Check Apple Intelligence availability on this device.
+
+        This is a static method that can be called without creating a client.
+
+        Returns:
+            Availability status enum value
+
+        Example:
+            >>> from applefoundationmodels import Client, Availability
+            >>> status = Client.check_availability()
+            >>> if status == Availability.AVAILABLE:
+            ...     print("Apple Intelligence is available!")
+        """
+        return Availability(_foundationmodels.check_availability())
+
+    @staticmethod
+    def get_availability_reason() -> Optional[str]:
+        """
+        Get detailed availability status message.
+
+        Returns:
+            Detailed status description with actionable guidance,
+            or None if library not initialized
+        """
+        return _foundationmodels.get_availability_reason()
+
+    @staticmethod
+    def is_ready() -> bool:
+        """
+        Check if Apple Intelligence is ready for immediate use.
+
+        Returns:
+            True if ready for use, False otherwise
+        """
+        return _foundationmodels.is_ready()
+
+    @staticmethod
+    def get_version() -> str:
+        """
+        Get library version string.
+
+        Returns:
+            Version string in format "major.minor.patch"
+        """
+        return _foundationmodels.get_version()
+
+    @staticmethod
+    def get_supported_languages() -> List[str]:
+        """
+        Get list of languages supported by Apple Intelligence.
+
+        Returns:
+            List of localized language display names
+        """
+        count = _foundationmodels.get_supported_languages_count()
+        return [
+            lang
+            for i in range(count)
+            if (lang := _foundationmodels.get_supported_language(i)) is not None
+        ]
+
+    def create_session(
+        self,
+        instructions: Optional[str] = None,
+        tools_json: Optional[str] = None,
+        enable_guardrails: bool = True,
+        prewarm: bool = False,
+    ) -> Session:
+        """
+        Create a new AI session.
+
+        Sessions maintain conversation state and can be configured with
+        tools and instructions.
+
+        Args:
+            instructions: Optional system instructions to guide AI behavior
+            tools_json: Optional JSON array of tool definitions in Claude format
+            enable_guardrails: Whether to enable content safety filtering
+            prewarm: Whether to preload session resources for faster first response
+
+        Returns:
+            New Session instance
+
+        Raises:
+            Various FoundationModelsError subclasses on failure
+
+        Example:
+            >>> session = client.create_session(
+            ...     instructions="You are a helpful assistant.",
+            ...     enable_guardrails=True
+            ... )
+        """
+        config = {}
+        if instructions is not None:
+            config["instructions"] = instructions
+        # Note: tools_json, enable_guardrails, prewarm not supported in simplified API
+
+        session_id = _foundationmodels.create_session(config if config else None)
+        session = Session(session_id, config if config else None)
+        self._sessions.append(session)
+        return session
+
+    def get_stats(self) -> Stats:
+        """
+        Get generation statistics for this client.
+
+        Returns:
+            Dictionary with statistics fields including request counts,
+            success rates, and performance metrics
+
+        Example:
+            >>> stats = client.get_stats()
+            >>> print(f"Total requests: {stats['total_requests']}")
+            >>> print(f"Average response time: {stats['average_response_time']:.2f}s")
+        """
+        return cast(Stats, _foundationmodels.get_stats())
+
+    def reset_stats(self) -> None:
+        """
+        Reset generation statistics for this client.
+
+        Clears all accumulated statistics, resetting counters to zero.
+        """
+        _foundationmodels.reset_stats()
+
+
+@contextmanager
+def client():
+    """
+    Context manager factory for creating a Client.
+
+    Usage:
+        with client() as c:
+            session = c.create_session()
+            response = session.generate("Hello!")
+
+    Yields:
+        Client instance with automatic cleanup
+    """
+    c = Client()
+    try:
+        yield c
+    finally:
+        c.close()

applefoundationmodels/constants.py

@@ -0,0 +1,30 @@
+"""
+Constants for applefoundationmodels.
+
+Provides default values and presets for generation parameters.
+"""
+
+# Generation defaults
+DEFAULT_TEMPERATURE = 1.0
+DEFAULT_MAX_TOKENS = 1024
+
+# Temperature bounds
+MIN_TEMPERATURE = 0.0
+MAX_TEMPERATURE = 2.0
+
+
+class TemperaturePreset:
+    """
+    Common temperature presets for different use cases.
+
+    Temperature controls randomness in generation:
+    - Lower values (0.1-0.3): More deterministic, good for facts and precision
+    - Medium values (0.5-0.7): Balanced creativity and consistency
+    - Higher values (1.0-1.5): More creative and varied outputs
+    """
+
+    DETERMINISTIC = 0.1  # Very low randomness, highly consistent
+    FACTUAL = 0.3  # Low randomness, good for factual responses
+    BALANCED = 0.7  # Balanced creativity and consistency
+    CREATIVE = 1.0  # More creative responses
+    VERY_CREATIVE = 1.5  # High creativity and variety

applefoundationmodels/exceptions.py

@@ -0,0 +1,134 @@
+"""
+Exception hierarchy for applefoundationmodels Python bindings.
+
+All exceptions raised by the library inherit from FoundationModelsError.
+Each exception corresponds to a specific error code from the Swift API.
+"""
+
+from typing import Optional
+
+
+class FoundationModelsError(Exception):
+    """Base exception for all FoundationModels errors."""
+
+    def __init__(self, message: str, error_code: Optional[int] = None):
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+
+
+class InitializationError(FoundationModelsError):
+    """Library initialization failed."""
+
+    pass
+
+
+class NotAvailableError(FoundationModelsError):
+    """Apple Intelligence not available on this device."""
+
+    pass
+
+
+class InvalidParametersError(FoundationModelsError):
+    """Invalid parameters provided to function."""
+
+    pass
+
+
+class MemoryError(FoundationModelsError):
+    """Memory allocation error."""
+
+    pass
+
+
+class JSONParseError(FoundationModelsError):
+    """JSON parsing or validation error."""
+
+    pass
+
+
+class GenerationError(FoundationModelsError):
+    """Text generation error."""
+
+    pass
+
+
+class TimeoutError(FoundationModelsError):
+    """Operation timeout."""
+
+    pass
+
+
+class SessionNotFoundError(FoundationModelsError):
+    """Session ID not found."""
+
+    pass
+
+
+class StreamNotFoundError(FoundationModelsError):
+    """Stream ID not found or already completed."""
+
+    pass
+
+
+class GuardrailViolationError(FoundationModelsError):
+    """Content blocked by safety filters."""
+
+    pass
+
+
+class ToolNotFoundError(FoundationModelsError):
+    """Tool callback not registered for session."""
+
+    pass
+
+
+class ToolExecutionError(FoundationModelsError):
+    """Tool execution failed or returned invalid result."""
+
+    pass
+
+
+class ToolCallError(FoundationModelsError):
+    """Tool call error (validation, schema, etc.)."""
+
+    pass
+
+
+class UnknownError(FoundationModelsError):
+    """Unknown error occurred."""
+
+    pass
+
+
+# Mapping from ai_result_t error codes to exception classes
+ERROR_CODE_TO_EXCEPTION = {
+    -1: InitializationError,
+    -2: NotAvailableError,
+    -3: InvalidParametersError,
+    -4: MemoryError,
+    -5: JSONParseError,
+    -6: GenerationError,
+    -7: TimeoutError,
+    -8: SessionNotFoundError,
+    -9: StreamNotFoundError,
+    -10: GuardrailViolationError,
+    -11: ToolNotFoundError,
+    -12: ToolExecutionError,
+    -99: UnknownError,
+}
+
+
+def raise_for_error_code(error_code: int, message: str) -> None:
+    """
+    Raise the appropriate exception for a given error code.
+
+    Args:
+        error_code: The error code from the Swift API
+        message: Error message to include in the exception
+
+    Raises:
+        FoundationModelsError: The appropriate exception subclass for the error code
+    """
+    exception_class = ERROR_CODE_TO_EXCEPTION.get(error_code, UnknownError)
+    raise exception_class(message, error_code)

applefoundationmodels/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This package supports type checking