Support tool calling (#4)

Author: btucker

.github/workflows/publish-to-pypi.yml

@@ -10,71 +10,106 @@ permissions:
   id-token: write # Required for trusted publishing to PyPI
 
 jobs:
-  build-wheels:
-    name: Build wheels on macOS for Python ${{ matrix.python-version }}
+  build-sdist:
+    name: Build source distribution
     runs-on: macos-26
-    strategy:
-      matrix:
-        # Build wheels for all supported Python versions
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
-      fail-fast: false
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Check macOS version
-        run: |
-          echo "macOS version:"
-          sw_vers
-          echo "Architecture:"
-          uname -m
-          echo "Python version:"
-          python --version
+          python-version: "3.12"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
         with:
           enable-cache: true
 
-      - name: Build wheel
-        env:
-          MACOSX_DEPLOYMENT_TARGET: "26.0"
-          ARCHFLAGS: "-arch arm64"
-          _PYTHON_HOST_PLATFORM: "macosx-26.0-arm64"
+      - name: Build source distribution
         run: |
-          uv build --wheel
+          uv build --sdist
 
-      - name: Verify wheel contents
+      - name: Verify source distribution
         run: |
           echo "Build artifacts:"
           ls -lh dist/
           echo ""
-          echo "Checking for dylib in wheel:"
-          if unzip -l dist/*.whl | grep -q "libfoundation_models.dylib"; then
-            echo "✓ libfoundation_models.dylib found in wheel"
-            unzip -l dist/*.whl | grep -E "(dylib|\.so)"
+          echo "Verifying Swift source is included for building:"
+          if tar -tzf dist/*.tar.gz | grep -q "foundation_models.swift"; then
+            echo "✓ Swift source found in sdist"
           else
-            echo "✗ ERROR: libfoundation_models.dylib NOT found in wheel!"
-            echo "Full wheel contents:"
-            unzip -l dist/*.whl
+            echo "✗ ERROR: Swift source NOT found in sdist!"
             exit 1
           fi
 
-      - name: Upload wheel
+      - name: Upload sdist
         uses: actions/upload-artifact@v4
         with:
-          name: wheel-${{ matrix.python-version }}
-          path: dist/*.whl
+          name: sdist
+          path: dist/*.tar.gz
+
+  # TODO: Re-enable wheel building once PyPI supports macOS 26.0 wheels
+  # Currently PyPI rejects macosx_26_0 platform tags
+  # See: https://github.com/pypi/warehouse/issues/...
+  #
+  # build-wheels:
+  #   name: Build wheels on macOS for Python ${{ matrix.python-version }}
+  #   runs-on: macos-26
+  #   strategy:
+  #     matrix:
+  #       python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+  #     fail-fast: false
+  #
+  #   steps:
+  #     - name: Checkout code
+  #       uses: actions/checkout@v4
+  #
+  #     - name: Set up Python ${{ matrix.python-version }}
+  #       uses: actions/setup-python@v5
+  #       with:
+  #         python-version: ${{ matrix.python-version }}
+  #
+  #     - name: Install uv
+  #       uses: astral-sh/setup-uv@v4
+  #       with:
+  #         enable-cache: true
+  #
+  #     - name: Build wheel
+  #       env:
+  #         MACOSX_DEPLOYMENT_TARGET: "26.0"
+  #         ARCHFLAGS: "-arch arm64"
+  #         _PYTHON_HOST_PLATFORM: "macosx-26.0-arm64"
+  #       run: |
+  #         uv build --wheel
+  #
+  #     - name: Verify wheel contents
+  #       run: |
+  #         echo "Build artifacts:"
+  #         ls -lh dist/
+  #         echo ""
+  #         echo "Checking for dylib in wheel:"
+  #         if unzip -l dist/*.whl | grep -q "libfoundation_models.dylib"; then
+  #           echo "✓ libfoundation_models.dylib found in wheel"
+  #           unzip -l dist/*.whl | grep -E "(dylib|\.so)"
+  #         else
+  #           echo "✗ ERROR: libfoundation_models.dylib NOT found in wheel!"
+  #           echo "Full wheel contents:"
+  #           unzip -l dist/*.whl
+  #           exit 1
+  #         fi
+  #
+  #     - name: Upload wheel
+  #       uses: actions/upload-artifact@v4
+  #       with:
+  #         name: wheel-${{ matrix.python-version }}
+  #         path: dist/*.whl
 
   publish:
     name: Publish to PyPI
-    needs: [build-wheels]
+    needs: [build-sdist]  # Only wait for sdist now
     runs-on: ubuntu-latest
 
     steps:
@@ -88,20 +123,6 @@ jobs:
         run: |
           echo "Downloaded artifacts:"
           ls -lh dist/
-          echo ""
-          echo "Verifying each wheel contains dylib:"
-          for wheel in dist/*.whl; do
-            echo "Checking $wheel:"
-            ls -lh "$wheel"
-            if unzip -l "$wheel" | grep -q "libfoundation_models.dylib"; then
-              echo "  ✓ dylib present"
-            else
-              echo "  ✗ ERROR: dylib missing in $wheel!"
-              echo "Wheel contents:"
-              unzip -l "$wheel"
-              exit 1
-            fi
-          done
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

MANIFEST.in

@@ -1,16 +1,12 @@
-# This file is for sdist builds only (not used for wheels)
-# Wheels use pyproject.toml [tool.setuptools.package-data] instead
+# 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
 
-# Exclude build artifacts and source files from wheels
-global-exclude *.pyc
-global-exclude __pycache__
-global-exclude *.so
-global-exclude .DS_Store
-global-exclude *.a
-global-exclude *.swift
-global-exclude *.h
-global-exclude lib/*
+# Swift source needed for compilation
+include applefoundationmodels/swift/*.swift
+
+# Exclude the lib build directory if it exists
+prune lib

README.md

@@ -157,6 +157,105 @@ with Client() as client:
     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
@@ -254,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: ...
@@ -305,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
@@ -313,8 +417,8 @@ 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
 

applefoundationmodels/_foundationmodels.pxd

@@ -22,6 +22,8 @@ cdef extern from "../applefoundationmodels/swift/foundation_models.h":
         AI_ERROR_JSON_PARSE = -5
         AI_ERROR_GENERATION = -6
         AI_ERROR_TIMEOUT = -7
+        AI_ERROR_TOOL_NOT_FOUND = -11
+        AI_ERROR_TOOL_EXECUTION = -12
         AI_ERROR_UNKNOWN = -99
 
     # Availability status
@@ -35,6 +37,12 @@ cdef extern from "../applefoundationmodels/swift/foundation_models.h":
     # Callback type for streaming
     ctypedef void (*ai_stream_callback_t)(const char *chunk)
 
+    # Callback type for tool execution
+    ctypedef int32_t (*ai_tool_callback_t)(const char *tool_name,
+                                           const char *arguments_json,
+                                           char *result_buffer,
+                                           int32_t buffer_size)
+
     # Core library functions
     int32_t apple_ai_init() nogil
     void apple_ai_cleanup() nogil
@@ -47,6 +55,11 @@ cdef extern from "../applefoundationmodels/swift/foundation_models.h":
     # Session management
     int32_t apple_ai_create_session(const char *instructions_json) nogil
 
+    # Tool calling
+    int32_t apple_ai_register_tools(const char *tools_json,
+                                    ai_tool_callback_t callback) nogil
+    char *apple_ai_get_transcript() nogil
+
     # Text generation
     char *apple_ai_generate(const char *prompt,
                            double temperature,

applefoundationmodels/_foundationmodels.pyi

@@ -43,6 +43,10 @@ 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: ...