Python: Introducing Foundry Local Chat Clients (#2915)

* redo foundry local chat client

* fix mypy and spelling

* better docstring, updated sample

* fixed tests and added tests

* small sample update

Author: eavanvalkenburg

python/packages/foundry_local/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/foundry_local/README.md

@@ -0,0 +1,9 @@
+# Get Started with Microsoft Agent Framework Foundry Local
+
+Please install this package as the extra for `agent-framework`:
+
+```bash
+pip install agent-framework-foundry-local --pre
+```
+
+and see the [README](https://github.com/microsoft/agent-framework/tree/main/python/README.md) for more information.

python/packages/foundry_local/agent_framework_foundry_local/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._foundry_local_client import FoundryLocalClient
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "FoundryLocalClient",
+    "__version__",
+]

python/packages/foundry_local/agent_framework_foundry_local/_foundry_local_client.py

@@ -0,0 +1,160 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import Any, ClassVar
+
+from agent_framework import use_chat_middleware, use_function_invocation
+from agent_framework._pydantic import AFBaseSettings
+from agent_framework.exceptions import ServiceInitializationError
+from agent_framework.observability import use_instrumentation
+from agent_framework.openai._chat_client import OpenAIBaseChatClient
+from foundry_local import FoundryLocalManager
+from foundry_local.models import DeviceType
+from openai import AsyncOpenAI
+
+__all__ = [
+    "FoundryLocalClient",
+]
+
+
+class FoundryLocalSettings(AFBaseSettings):
+    """Foundry local model settings.
+
+    The settings are first loaded from environment variables with the prefix 'FOUNDRY_LOCAL_'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Attributes:
+        model_id: The name of the model deployment to use.
+            (Env var FOUNDRY_LOCAL_MODEL_ID)
+    Parameters:
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+    """
+
+    env_prefix: ClassVar[str] = "FOUNDRY_LOCAL_"
+
+    model_id: str
+
+
+@use_function_invocation
+@use_instrumentation
+@use_chat_middleware
+class FoundryLocalClient(OpenAIBaseChatClient):
+    """Foundry Local Chat completion class."""
+
+    def __init__(
+        self,
+        model_id: str | None = None,
+        *,
+        bootstrap: bool = True,
+        timeout: float | None = None,
+        prepare_model: bool = True,
+        device: DeviceType | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str = "utf-8",
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a FoundryLocalClient.
+
+        Keyword Args:
+            model_id: The Foundry Local model ID or alias to use. If not provided,
+                it will be loaded from the FoundryLocalSettings.
+            bootstrap: Whether to start the Foundry Local service if not already running.
+                Default is True.
+            timeout: Optional timeout for requests to Foundry Local.
+                This timeout is applied to any call to the Foundry Local service.
+            prepare_model: Whether to download the model into the cache, and load the model into
+                the inferencing service upon initialization. Default is True.
+                If false, the first call to generate a completion will load the model,
+                and might take a long time.
+            device: The device type to use for model inference.
+                The device is used to select the appropriate model variant.
+                If not provided, the default device for your system will be used.
+                The values are in the foundry_local.models.DeviceType enum.
+            env_file_path: If provided, the .env settings are read from this file path location.
+            env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+            kwargs: Additional keyword arguments, are passed to the OpenAIBaseChatClient.
+                This can include middleware and additional properties.
+
+        Examples:
+
+            .. code-block:: python
+
+                # Create a FoundryLocalClient with a specific model ID:
+                from agent_framework_foundry_local import FoundryLocalClient
+
+                client = FoundryLocalClient(model_id="phi-4-mini")
+
+                agent = client.create_agent(
+                    name="LocalAgent",
+                    instructions="You are a helpful agent.",
+                    tools=get_weather,
+                )
+                response = await agent.run("What's the weather like in Seattle?")
+
+                # Or you can set the model id in the environment:
+                os.environ["FOUNDRY_LOCAL_MODEL_ID"] = "phi-4-mini"
+                client = FoundryLocalClient()
+
+                # A FoundryLocalManager is created and if set, the service is started.
+                # The FoundryLocalManager is available via the `manager` property.
+                # For instance to find out which models are available:
+                for model in client.manager.list_catalog_models():
+                    print(f"- {model.alias} for {model.task} - id={model.id}")
+
+                # Other options include specifying the device type:
+                from foundry_local.models import DeviceType
+
+                client = FoundryLocalClient(
+                    model_id="phi-4-mini",
+                    device=DeviceType.GPU,
+                )
+                # and choosing if the model should be prepared on initialization:
+                client = FoundryLocalClient(
+                    model_id="phi-4-mini",
+                    prepare_model=False,
+                )
+                # Beware, in this case the first request to generate a completion
+                # will take a long time as the model is loaded then.
+                # Alternatively, you could call the `download_model` and `load_model` methods
+                # on the `manager` property manually.
+                client.manager.download_model(alias_or_model_id="phi-4-mini", device=DeviceType.CPU)
+                client.manager.load_model(alias_or_model_id="phi-4-mini", device=DeviceType.CPU)
+
+                # You can also use the CLI:
+                `foundry model load phi-4-mini --device Auto`
+
+        Raises:
+            ServiceInitializationError: If the specified model ID or alias is not found.
+                Sometimes a model might be available but if you have specified a device
+                type that is not supported by the model, it will not be found.
+
+        """
+        settings = FoundryLocalSettings(
+            model_id=model_id,  # type: ignore
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+        manager = FoundryLocalManager(bootstrap=bootstrap, timeout=timeout)
+        model_info = manager.get_model_info(
+            alias_or_model_id=settings.model_id,
+            device=device,
+        )
+        if model_info is None:
+            message = (
+                f"Model with ID or alias '{settings.model_id}:{device.value}' not found in Foundry Local."
+                if device
+                else f"Model with ID or alias '{settings.model_id}' for your current device not found in Foundry Local."
+            )
+            raise ServiceInitializationError(message)
+        if prepare_model:
+            manager.download_model(alias_or_model_id=model_info.id, device=device)
+            manager.load_model(alias_or_model_id=model_info.id, device=device)
+
+        super().__init__(
+            model_id=model_info.id,
+            client=AsyncOpenAI(base_url=manager.endpoint, api_key=manager.api_key),
+            **kwargs,
+        )
+        self.manager = manager

python/packages/foundry_local/agent_framework_foundry_local/py.typed

@@ -0,0 +1,87 @@
+[project]
+name = "agent-framework-foundry-local"
+description = "Foundry Local integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "[email protected]"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0b251218"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core",
+    "foundry-local-sdk>=0.5.1,<1",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_foundry_local"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+[tool.poe.tasks]
+mypy = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_foundry_local"
+test = "pytest --cov=agent_framework_foundry_local --cov-report=term-missing:skip-covered tests"
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/foundry_local/pyproject.toml

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+# ruff: noqa
+
+import asyncio
+from random import randint
+from typing import TYPE_CHECKING, Annotated
+
+from agent_framework_foundry_local import FoundryLocalClient
+
+if TYPE_CHECKING:
+    from agent_framework import ChatAgent
+
+"""
+This sample demonstrates basic usage of the FoundryLocalClient.
+Shows both streaming and non-streaming responses with function tools.
+
+Running this sample the first time will be slow, as the model needs to be
+downloaded and initialized.
+
+Also, not every model supports function calling, so be sure to check the
+model capabilities in the Foundry catalog, or pick one from the list printed
+when running this sample.
+"""
+
+
+def get_weather(
+    location: Annotated[str, "The location to get the weather for."],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def non_streaming_example(agent: "ChatAgent") -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    query = "What's the weather like in Seattle?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}\n")
+
+
+async def streaming_example(agent: "ChatAgent") -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    query = "What's the weather like in Amsterdam?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run_stream(query):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Foundry Local Client Agent Example ===")
+
+    client = FoundryLocalClient(model_id="phi-4-mini")
+    print(f"Client Model ID: {client.model_id}\n")
+    print("Other available models (tool calling supported only):")
+    for model in client.manager.list_catalog_models():
+        if model.supports_tool_calling:
+            print(
+                f"- {model.alias} for {model.task} - id={model.id} - {(model.file_size_mb / 1000):.2f} GB - {model.license}"
+            )
+    agent = client.create_agent(
+        name="LocalAgent",
+        instructions="You are a helpful agent.",
+        tools=get_weather,
+    )
+    await non_streaming_example(agent)
+    await streaming_example(agent)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())