apple-foundation-models 0.1.3__tar.gz → 0.1.9__tar.gz

apple_foundation_models-0.1.9/MANIFEST.in

@@ -0,0 +1,17 @@
+# Controls what goes into the source distribution (.tar.gz)
+# The source distribution must contain all files needed to build the wheel
+
+# Documentation
+include README.md
+include LICENSE
+
+# Cython source files needed for compilation
+include applefoundationmodels/*.pyx
+include applefoundationmodels/*.pxd
+
+# Swift source needed for compilation
+include applefoundationmodels/swift/*.swift
+include applefoundationmodels/swift/*.h
+
+# Exclude the lib build directory if it exists
+prune lib

{apple_foundation_models-0.1.3/apple_foundation_models.egg-info → apple_foundation_models-0.1.9}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: apple-foundation-models
-Version: 0.1.3
-Summary: Python bindings for Apple's FoundationModels framework - on-device AI
+Version: 0.1.9
+Summary: Python bindings for Apple's FoundationModels framework - on-device AI (requires macOS 26.0+)
 Author: Ben Tucker
 Maintainer: Ben Tucker
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/btucker/apple-foundation-models-py
 Project-URL: Repository, https://github.com/btucker/apple-foundation-models-py
 Project-URL: Documentation, https://github.com/btucker/apple-foundation-models-py#readme
@@ -12,35 +12,39 @@ Project-URL: Issues, https://github.com/btucker/apple-foundation-models-py/issue
 Keywords: apple,intelligence,ai,llm,foundation-models,on-device
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Cython
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: mypy>=0.991; extra == "dev"
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
 Dynamic: license-file
 
-# apple-foundation-models-py
+# apple-foundation-models
 
 Python bindings for Apple's FoundationModels framework - Direct access to on-device Apple Intelligence.
 
 ## Features
 
 - **High-level Pythonic API**: Context managers, async/await, type hints
+- **Structured Outputs**: JSON Schema and Pydantic model support
 - **Async Streaming**: Native `async for` support for streaming responses
 - **Type Safety**: Full type annotations with mypy support
 - **Memory Safe**: Automatic resource cleanup, no manual memory management
@@ -49,7 +53,7 @@ Python bindings for Apple's FoundationModels framework - Direct access to on-dev
 ## Requirements
 
 - macOS 26.0+ (macOS Sequoia or later)
-- Python 3.8 or higher
+- Python 3.9 or higher
 - Apple Intelligence enabled on your device
 
 ## Installation
@@ -60,6 +64,13 @@ Python bindings for Apple's FoundationModels framework - Direct access to on-dev
 pip install apple-foundation-models
 ```
 
+**Optional dependencies:**
+
+```bash
+# For Pydantic model support in structured outputs
+pip install apple-foundation-models[pydantic]
+```
+
 ### From Source
 
 ```bash
@@ -75,7 +86,7 @@ pip install -e .
 
 - macOS 26.0+ (Sequoia) with Apple Intelligence enabled
 - Xcode command line tools (`xcode-select --install`)
-- Python 3.8 or higher
+- Python 3.9 or higher
 
 **Note:** The Swift dylib is built automatically during installation.
 
@@ -153,9 +164,137 @@ with Client() as client:
         schema=schema
     )
 
-    print(result['object'])  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
+    print(result)  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
 ```
 
+#### Using Pydantic Models
+
+You can also use Pydantic models for structured outputs (requires `pip install pydantic>=2.0`):
+
+```python
+from applefoundationmodels import Client
+from pydantic import BaseModel
+
+class Person(BaseModel):
+    name: str
+    age: int
+    city: str
+
+with Client() as client:
+    session = client.create_session()
+
+    # Pass Pydantic model directly - no need for JSON schema!
+    result = session.generate_structured(
+        "Extract person info: Alice is 28 and lives in Paris",
+        schema=Person
+    )
+
+    print(result)  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
+
+    # Parse directly into a Pydantic model for validation
+    person = Person(**result)
+    print(person.name, person.age, person.city)  # Alice 28 Paris
+```
+
+### Tool Calling
+
+Tool calling allows the model to call your Python functions to access real-time data, perform actions, or integrate with external systems. Tools work with a simple decorator-based API:
+
+```python
+from applefoundationmodels import Client
+
+with Client() as client:
+    session = client.create_session()
+
+    # Register a tool with the @session.tool decorator
+    @session.tool(description="Get current weather for a location")
+    def get_weather(location: str, units: str = "celsius") -> str:
+        """Fetch weather information from your weather API."""
+        # Your implementation here
+        return f"Weather in {location}: 22°{units[0].upper()}, sunny"
+
+    @session.tool()
+    def calculate(expression: str) -> float:
+        """Evaluate a mathematical expression safely."""
+        # Your implementation here
+        return eval(expression)  # Use safe_eval in production!
+
+    # The model will automatically call tools when needed
+    response = session.generate(
+        "What's the weather in Paris and what's 15 times 23?"
+    )
+    print(response)
+    # "The weather in Paris is 22°C and sunny. 15 times 23 equals 345."
+
+    # View the full conversation including tool calls
+    for entry in session.transcript:
+        print(f"{entry['type']}: {entry.get('content', '')}")
+```
+
+**Features:**
+- **Automatic schema generation** from Python type hints
+- **Parallel tool execution** when the model calls multiple tools
+- **Full transcript access** showing all tool calls and outputs
+- **Error handling** with detailed error information
+- **Type-safe** with complete type annotations
+
+**Schema Extraction:**
+
+The library automatically extracts JSON schemas from your Python functions:
+
+```python
+@session.tool(description="Search documentation")
+def search_docs(query: str, limit: int = 10, category: str = "all") -> list:
+    """Search the documentation database."""
+    # Implementation...
+    return results
+
+# Automatically generates:
+# {
+#   "name": "search_docs",
+#   "description": "Search documentation",
+#   "parameters": {
+#     "type": "object",
+#     "properties": {
+#       "query": {"type": "string"},
+#       "limit": {"type": "integer"},
+#       "category": {"type": "string"}
+#     },
+#     "required": ["query"]
+#   }
+# }
+```
+
+**Transcript Access:**
+
+View the complete conversation history including tool interactions:
+
+```python
+# After generating with tools
+for entry in session.transcript:
+    match entry['type']:
+        case 'prompt':
+            print(f"User: {entry['content']}")
+        case 'tool_calls':
+            for call in entry['tool_calls']:
+                print(f"Calling tool: {call['id']}")
+        case 'tool_output':
+            print(f"Tool result: {entry['content']}")
+        case 'response':
+            print(f"Assistant: {entry['content']}")
+```
+
+**Supported Parameter Types:**
+
+Tool calling works with various parameter signatures:
+- No parameters
+- Single parameters (string, int, float, bool)
+- Multiple parameters with mixed types
+- Optional parameters with default values
+- Lists and nested objects
+
+See `examples/tool_calling_comprehensive.py` for complete examples of all supported patterns.
+
 ### Generation Parameters
 
 ```python
@@ -253,6 +392,10 @@ class Session:
     def generate_structured(prompt: str, schema: dict, **params) -> dict: ...
     async def generate_stream(prompt: str, **params) -> AsyncIterator[str]: ...
 
+    def tool(description: str = None, name: str = None) -> Callable: ...
+    @property
+    def transcript() -> List[dict]: ...
+
     def get_history() -> List[dict]: ...
     def clear_history() -> None: ...
     def add_message(role: str, content: str) -> None: ...
@@ -304,6 +447,7 @@ All exceptions inherit from `FoundationModelsError`:
 - `GuardrailViolationError` - Content blocked by safety filters
 - `ToolNotFoundError` - Tool not registered
 - `ToolExecutionError` - Tool execution failed
+- `ToolCallError` - Tool call error (validation, schema, etc.)
 - `UnknownError` - Unknown error
 
 ## Examples
@@ -312,24 +456,41 @@ See the `examples/` directory for complete working examples:
 
 - `basic_chat.py` - Simple conversation
 - `streaming_chat.py` - Async streaming
-- `tool_calling.py` - Tool registration (coming soon)
 - `structured_output.py` - JSON schema validation
+- `tool_calling_comprehensive.py` - Complete tool calling demonstration with all parameter types
 
 ## Development
 
 ### Building from Source
 
+This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable builds and dependency management:
+
 ```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
 # Install development dependencies
-pip install -e ".[dev]"
+uv sync --extra dev
 
 # Run tests
-pytest
+uv run pytest
 
 # Type checking
-mypy applefoundationmodels
+uv run mypy applefoundationmodels
 
 # Format code
+uv run black applefoundationmodels examples
+
+# Build wheels
+uv build --wheel
+```
+
+You can also use pip if preferred:
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy applefoundationmodels
 black applefoundationmodels examples
 ```
 

{apple_foundation_models-0.1.3 → apple_foundation_models-0.1.9}/README.md

@@ -1,10 +1,11 @@
-# apple-foundation-models-py
+# apple-foundation-models
 
 Python bindings for Apple's FoundationModels framework - Direct access to on-device Apple Intelligence.
 
 ## Features
 
 - **High-level Pythonic API**: Context managers, async/await, type hints
+- **Structured Outputs**: JSON Schema and Pydantic model support
 - **Async Streaming**: Native `async for` support for streaming responses
 - **Type Safety**: Full type annotations with mypy support
 - **Memory Safe**: Automatic resource cleanup, no manual memory management
@@ -13,7 +14,7 @@ Python bindings for Apple's FoundationModels framework - Direct access to on-dev
 ## Requirements
 
 - macOS 26.0+ (macOS Sequoia or later)
-- Python 3.8 or higher
+- Python 3.9 or higher
 - Apple Intelligence enabled on your device
 
 ## Installation
@@ -24,6 +25,13 @@ Python bindings for Apple's FoundationModels framework - Direct access to on-dev
 pip install apple-foundation-models
 ```
 
+**Optional dependencies:**
+
+```bash
+# For Pydantic model support in structured outputs
+pip install apple-foundation-models[pydantic]
+```
+
 ### From Source
 
 ```bash
@@ -39,7 +47,7 @@ pip install -e .
 
 - macOS 26.0+ (Sequoia) with Apple Intelligence enabled
 - Xcode command line tools (`xcode-select --install`)
-- Python 3.8 or higher
+- Python 3.9 or higher
 
 **Note:** The Swift dylib is built automatically during installation.
 
@@ -117,9 +125,137 @@ with Client() as client:
         schema=schema
     )
 
-    print(result['object'])  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
+    print(result)  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
 ```
 
+#### Using Pydantic Models
+
+You can also use Pydantic models for structured outputs (requires `pip install pydantic>=2.0`):
+
+```python
+from applefoundationmodels import Client
+from pydantic import BaseModel
+
+class Person(BaseModel):
+    name: str
+    age: int
+    city: str
+
+with Client() as client:
+    session = client.create_session()
+
+    # Pass Pydantic model directly - no need for JSON schema!
+    result = session.generate_structured(
+        "Extract person info: Alice is 28 and lives in Paris",
+        schema=Person
+    )
+
+    print(result)  # {'name': 'Alice', 'age': 28, 'city': 'Paris'}
+
+    # Parse directly into a Pydantic model for validation
+    person = Person(**result)
+    print(person.name, person.age, person.city)  # Alice 28 Paris
+```
+
+### Tool Calling
+
+Tool calling allows the model to call your Python functions to access real-time data, perform actions, or integrate with external systems. Tools work with a simple decorator-based API:
+
+```python
+from applefoundationmodels import Client
+
+with Client() as client:
+    session = client.create_session()
+
+    # Register a tool with the @session.tool decorator
+    @session.tool(description="Get current weather for a location")
+    def get_weather(location: str, units: str = "celsius") -> str:
+        """Fetch weather information from your weather API."""
+        # Your implementation here
+        return f"Weather in {location}: 22°{units[0].upper()}, sunny"
+
+    @session.tool()
+    def calculate(expression: str) -> float:
+        """Evaluate a mathematical expression safely."""
+        # Your implementation here
+        return eval(expression)  # Use safe_eval in production!
+
+    # The model will automatically call tools when needed
+    response = session.generate(
+        "What's the weather in Paris and what's 15 times 23?"
+    )
+    print(response)
+    # "The weather in Paris is 22°C and sunny. 15 times 23 equals 345."
+
+    # View the full conversation including tool calls
+    for entry in session.transcript:
+        print(f"{entry['type']}: {entry.get('content', '')}")
+```
+
+**Features:**
+- **Automatic schema generation** from Python type hints
+- **Parallel tool execution** when the model calls multiple tools
+- **Full transcript access** showing all tool calls and outputs
+- **Error handling** with detailed error information
+- **Type-safe** with complete type annotations
+
+**Schema Extraction:**
+
+The library automatically extracts JSON schemas from your Python functions:
+
+```python
+@session.tool(description="Search documentation")
+def search_docs(query: str, limit: int = 10, category: str = "all") -> list:
+    """Search the documentation database."""
+    # Implementation...
+    return results
+
+# Automatically generates:
+# {
+#   "name": "search_docs",
+#   "description": "Search documentation",
+#   "parameters": {
+#     "type": "object",
+#     "properties": {
+#       "query": {"type": "string"},
+#       "limit": {"type": "integer"},
+#       "category": {"type": "string"}
+#     },
+#     "required": ["query"]
+#   }
+# }
+```
+
+**Transcript Access:**
+
+View the complete conversation history including tool interactions:
+
+```python
+# After generating with tools
+for entry in session.transcript:
+    match entry['type']:
+        case 'prompt':
+            print(f"User: {entry['content']}")
+        case 'tool_calls':
+            for call in entry['tool_calls']:
+                print(f"Calling tool: {call['id']}")
+        case 'tool_output':
+            print(f"Tool result: {entry['content']}")
+        case 'response':
+            print(f"Assistant: {entry['content']}")
+```
+
+**Supported Parameter Types:**
+
+Tool calling works with various parameter signatures:
+- No parameters
+- Single parameters (string, int, float, bool)
+- Multiple parameters with mixed types
+- Optional parameters with default values
+- Lists and nested objects
+
+See `examples/tool_calling_comprehensive.py` for complete examples of all supported patterns.
+
 ### Generation Parameters
 
 ```python
@@ -217,6 +353,10 @@ class Session:
     def generate_structured(prompt: str, schema: dict, **params) -> dict: ...
     async def generate_stream(prompt: str, **params) -> AsyncIterator[str]: ...
 
+    def tool(description: str = None, name: str = None) -> Callable: ...
+    @property
+    def transcript() -> List[dict]: ...
+
     def get_history() -> List[dict]: ...
     def clear_history() -> None: ...
     def add_message(role: str, content: str) -> None: ...
@@ -268,6 +408,7 @@ All exceptions inherit from `FoundationModelsError`:
 - `GuardrailViolationError` - Content blocked by safety filters
 - `ToolNotFoundError` - Tool not registered
 - `ToolExecutionError` - Tool execution failed
+- `ToolCallError` - Tool call error (validation, schema, etc.)
 - `UnknownError` - Unknown error
 
 ## Examples
@@ -276,24 +417,41 @@ See the `examples/` directory for complete working examples:
 
 - `basic_chat.py` - Simple conversation
 - `streaming_chat.py` - Async streaming
-- `tool_calling.py` - Tool registration (coming soon)
 - `structured_output.py` - JSON schema validation
+- `tool_calling_comprehensive.py` - Complete tool calling demonstration with all parameter types
 
 ## Development
 
 ### Building from Source
 
+This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable builds and dependency management:
+
 ```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
 # Install development dependencies
-pip install -e ".[dev]"
+uv sync --extra dev
 
 # Run tests
-pytest
+uv run pytest
 
 # Type checking
-mypy applefoundationmodels
+uv run mypy applefoundationmodels
 
 # Format code
+uv run black applefoundationmodels examples
+
+# Build wheels
+uv build --wheel
+```
+
+You can also use pip if preferred:
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy applefoundationmodels
 black applefoundationmodels examples
 ```