feat: add polyglot gRPC loader infrastructure (Milestone 1)

- Add amplifier_module.proto — universal tool contract for any language
- Add loader_dispatch.py — routes module loading by amplifier.toml transport type
- Add loader_grpc.py — GrpcToolBridge wraps gRPC ToolService as Python tool
- Generate Python gRPC stubs from proto
- Add 20 tests: unit tests + integration tests with mock gRPC server
- All 475 existing tests still pass (zero regressions)

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

Author: bkrabach

bindings/python/tests/test_dispatch_integration.py

@@ -0,0 +1,19 @@
+"""Test that _session_init.py can route through loader_dispatch."""
+
+import asyncio
+
+
+def test_dispatch_functions_importable():
+    """The dispatch functions are importable from the right locations."""
+    from amplifier_core.loader_dispatch import _detect_transport
+    from amplifier_core.loader_dispatch import load_module
+
+    assert callable(load_module)
+    assert callable(_detect_transport)
+
+
+def test_session_init_still_works():
+    """_session_init.initialize_session is still importable and async."""
+    from amplifier_core._session_init import initialize_session
+
+    assert asyncio.iscoroutinefunction(initialize_session)

bindings/python/tests/test_grpc_integration.py

@@ -0,0 +1,140 @@
+"""Integration test: mock gRPC ToolService loaded by the Python session.
+
+Starts a real gRPC server in-process, connects via loader_grpc, and
+verifies the full round-trip: GetSpec + Execute.
+"""
+
+import json
+
+import pytest
+import pytest_asyncio
+
+# Skip if grpcio not installed
+grpc = pytest.importorskip("grpc")
+grpc_aio = pytest.importorskip("grpc.aio")
+
+
+@pytest_asyncio.fixture
+async def mock_tool_server():
+    """Start a mock gRPC ToolService server on a random port."""
+    from amplifier_core._grpc_gen import amplifier_module_pb2
+    from amplifier_core._grpc_gen import amplifier_module_pb2_grpc
+
+    class MockToolServicer(amplifier_module_pb2_grpc.ToolServiceServicer):
+        async def GetSpec(self, request, context):
+            return amplifier_module_pb2.ToolSpec(
+                name="mock-echo",
+                description="Echoes input back",
+                parameters_json='{"type": "object", "properties": {"message": {"type": "string"}}}',
+            )
+
+        async def Execute(self, request, context):
+            input_data = json.loads(request.input.decode("utf-8"))
+            output = {"echoed": input_data.get("message", "(empty)")}
+            return amplifier_module_pb2.ToolExecuteResponse(
+                success=True,
+                output=json.dumps(output).encode("utf-8"),
+                content_type="application/json",
+            )
+
+    server = grpc_aio.server()
+    amplifier_module_pb2_grpc.add_ToolServiceServicer_to_server(
+        MockToolServicer(), server
+    )
+    port = server.add_insecure_port("[::]:0")  # Random available port
+    await server.start()
+    yield port
+    await server.stop(grace=0)
+
+
+@pytest.mark.asyncio
+async def test_grpc_tool_bridge_full_roundtrip(mock_tool_server):
+    """Full round-trip: connect -> GetSpec -> Execute -> verify result."""
+    from amplifier_core._grpc_gen import amplifier_module_pb2
+    from amplifier_core._grpc_gen import amplifier_module_pb2_grpc
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    endpoint = f"localhost:{mock_tool_server}"
+    channel = grpc_aio.insecure_channel(endpoint)
+    stub = amplifier_module_pb2_grpc.ToolServiceStub(channel)
+
+    # Fetch spec
+    spec_response = await stub.GetSpec(amplifier_module_pb2.Empty())
+    assert spec_response.name == "mock-echo"
+
+    # Create bridge
+    bridge = GrpcToolBridge(
+        name=spec_response.name,
+        description=spec_response.description,
+        parameters_json=spec_response.parameters_json,
+        endpoint=endpoint,
+        channel=channel,
+    )
+    bridge._stub = stub
+
+    # Execute
+    result = await bridge.execute(message="hello world")
+    assert result["success"] is True
+    assert result["output"]["echoed"] == "hello world"
+
+    # Cleanup
+    await bridge.cleanup()
+
+
+@pytest.mark.asyncio
+async def test_grpc_tool_bridge_error_handling(mock_tool_server):
+    """Bridge handles gRPC errors gracefully."""
+    from amplifier_core._grpc_gen import amplifier_module_pb2_grpc
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    # Connect to wrong port (the server is on mock_tool_server port)
+    channel = grpc_aio.insecure_channel("localhost:1")  # No server here
+    stub = amplifier_module_pb2_grpc.ToolServiceStub(channel)
+
+    bridge = GrpcToolBridge(
+        name="broken",
+        description="broken",
+        parameters_json="{}",
+        endpoint="localhost:1",
+        channel=channel,
+    )
+    bridge._stub = stub
+
+    # Should return error result, not raise
+    result = await bridge.execute(message="hello")
+    assert result["success"] is False
+    assert result["error"] is not None
+
+    await channel.close()
+
+
+@pytest.mark.asyncio
+async def test_load_grpc_module_full_flow(mock_tool_server):
+    """load_grpc_module connects, fetches spec, and returns a mount function."""
+    from amplifier_core.loader_grpc import load_grpc_module
+
+    meta = {
+        "module": {"name": "mock-echo", "type": "tool", "transport": "grpc"},
+        "grpc": {"endpoint": f"localhost:{mock_tool_server}"},
+    }
+
+    # Create a minimal mock coordinator
+    class MockCoordinator:
+        def __init__(self):
+            self.mounted_tools = {}
+
+        async def mount(self, mount_point, instance, name=None):
+            self.mounted_tools[name or instance.name] = instance
+
+    coord = MockCoordinator()
+    mount_fn = await load_grpc_module("mock-echo", {}, meta, coord)
+
+    # Mount the tool
+    cleanup = await mount_fn(coord)
+
+    assert "mock-echo" in coord.mounted_tools
+    assert coord.mounted_tools["mock-echo"].name == "mock-echo"
+
+    # Cleanup
+    if cleanup:
+        await cleanup()

bindings/python/tests/test_loader_dispatch.py

@@ -0,0 +1,83 @@
+"""Tests for the polyglot loader dispatch module."""
+
+import os
+import tempfile
+
+
+def test_dispatch_module_exists():
+    """The loader_dispatch module is importable."""
+    from amplifier_core import loader_dispatch
+
+    assert hasattr(loader_dispatch, "load_module")
+
+
+def test_dispatch_no_toml_falls_back_to_python():
+    """Without amplifier.toml, dispatch falls through to Python loader."""
+    from amplifier_core.loader_dispatch import _detect_transport
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        transport = _detect_transport(tmpdir)
+        assert transport == "python"
+
+
+def test_dispatch_detects_grpc_transport():
+    """amplifier.toml with transport=grpc is detected."""
+    from amplifier_core.loader_dispatch import _detect_transport
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        toml_path = os.path.join(tmpdir, "amplifier.toml")
+        with open(toml_path, "w") as f:
+            f.write('[module]\nname = "test"\ntype = "tool"\ntransport = "grpc"\n')
+        transport = _detect_transport(tmpdir)
+        assert transport == "grpc"
+
+
+def test_dispatch_detects_python_transport():
+    """amplifier.toml with transport=python is detected."""
+    from amplifier_core.loader_dispatch import _detect_transport
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        toml_path = os.path.join(tmpdir, "amplifier.toml")
+        with open(toml_path, "w") as f:
+            f.write('[module]\nname = "test"\ntype = "tool"\ntransport = "python"\n')
+        transport = _detect_transport(tmpdir)
+        assert transport == "python"
+
+
+def test_dispatch_detects_native_transport():
+    """amplifier.toml with transport=native is detected."""
+    from amplifier_core.loader_dispatch import _detect_transport
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        toml_path = os.path.join(tmpdir, "amplifier.toml")
+        with open(toml_path, "w") as f:
+            f.write('[module]\nname = "test"\ntype = "tool"\ntransport = "native"\n')
+        transport = _detect_transport(tmpdir)
+        assert transport == "native"
+
+
+def test_dispatch_defaults_to_python_when_transport_missing():
+    """amplifier.toml without transport key defaults to python."""
+    from amplifier_core.loader_dispatch import _detect_transport
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        toml_path = os.path.join(tmpdir, "amplifier.toml")
+        with open(toml_path, "w") as f:
+            f.write('[module]\nname = "test"\ntype = "tool"\n')
+        transport = _detect_transport(tmpdir)
+        assert transport == "python"
+
+
+def test_dispatch_reads_grpc_endpoint():
+    """amplifier.toml grpc section provides endpoint."""
+    from amplifier_core.loader_dispatch import _read_module_meta
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        toml_path = os.path.join(tmpdir, "amplifier.toml")
+        with open(toml_path, "w") as f:
+            f.write(
+                '[module]\nname = "my-tool"\ntype = "tool"\ntransport = "grpc"\n\n[grpc]\nendpoint = "localhost:50052"\n'
+            )
+        meta = _read_module_meta(tmpdir)
+        assert meta["module"]["transport"] == "grpc"
+        assert meta["grpc"]["endpoint"] == "localhost:50052"

bindings/python/tests/test_loader_grpc.py

@@ -0,0 +1,114 @@
+"""Tests for the gRPC module loader."""
+
+import json
+
+
+def test_grpc_loader_module_exists():
+    """The loader_grpc module is importable."""
+    from amplifier_core import loader_grpc
+
+    assert hasattr(loader_grpc, "GrpcToolBridge")
+    assert hasattr(loader_grpc, "load_grpc_module")
+
+
+def test_grpc_tool_bridge_init():
+    """GrpcToolBridge can be constructed with spec data."""
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    bridge = GrpcToolBridge(
+        name="test-tool",
+        description="A test tool",
+        parameters_json='{"type": "object", "properties": {"query": {"type": "string"}}}',
+        endpoint="localhost:50052",
+        channel=None,  # No real connection in unit tests
+    )
+    assert bridge.name == "test-tool"
+    assert bridge.description == "A test tool"
+
+
+def test_grpc_tool_bridge_get_spec():
+    """GrpcToolBridge.get_spec() returns a dict with name, description, parameters."""
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    bridge = GrpcToolBridge(
+        name="search",
+        description="Search the web",
+        parameters_json='{"type": "object", "properties": {"query": {"type": "string"}}}',
+        endpoint="localhost:50052",
+        channel=None,
+    )
+    spec = bridge.get_spec()
+    assert spec["name"] == "search"
+    assert spec["description"] == "Search the web"
+    assert "properties" in spec["parameters"]
+
+
+def test_grpc_tool_bridge_serialize_input():
+    """GrpcToolBridge._serialize_input encodes dict to JSON bytes."""
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    bridge = GrpcToolBridge(
+        name="test",
+        description="test",
+        parameters_json="{}",
+        endpoint="localhost:50052",
+        channel=None,
+    )
+    input_dict = {"query": "hello world"}
+    data, content_type = bridge._serialize_input(input_dict)
+    assert content_type == "application/json"
+    assert json.loads(data) == {"query": "hello world"}
+
+
+def test_grpc_tool_bridge_deserialize_output():
+    """GrpcToolBridge._deserialize_output decodes JSON bytes to dict."""
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    bridge = GrpcToolBridge(
+        name="test",
+        description="test",
+        parameters_json="{}",
+        endpoint="localhost:50052",
+        channel=None,
+    )
+    output_bytes = json.dumps({"result": "found it"}).encode("utf-8")
+    result = bridge._deserialize_output(output_bytes, "application/json")
+    assert result == {"result": "found it"}
+
+
+def test_grpc_tool_bridge_deserialize_empty_output():
+    """Empty output bytes returns empty dict."""
+    from amplifier_core.loader_grpc import GrpcToolBridge
+
+    bridge = GrpcToolBridge(
+        name="test",
+        description="test",
+        parameters_json="{}",
+        endpoint="localhost:50052",
+        channel=None,
+    )
+    result = bridge._deserialize_output(b"", "application/json")
+    assert result == {}
+
+
+def test_load_grpc_module_reads_endpoint():
+    """load_grpc_module extracts endpoint from meta dict."""
+    from amplifier_core.loader_grpc import _extract_endpoint
+
+    meta = {
+        "module": {"name": "my-tool", "type": "tool", "transport": "grpc"},
+        "grpc": {"endpoint": "localhost:50099"},
+    }
+    endpoint = _extract_endpoint(meta, "my-tool")
+    assert endpoint == "localhost:50099"
+
+
+def test_load_grpc_module_default_endpoint():
+    """When no endpoint specified, uses default localhost:50051."""
+    from amplifier_core.loader_grpc import _extract_endpoint
+
+    meta = {
+        "module": {"name": "my-tool", "type": "tool", "transport": "grpc"},
+    }
+    endpoint = _extract_endpoint(meta, "my-tool")
+    assert endpoint == "localhost:50051"

proto/amplifier_module.proto

@@ -0,0 +1,39 @@
+// amplifier-core/proto/amplifier_module.proto
+syntax = "proto3";
+package amplifier.module;
+
+// Universal contract for tool modules in any language.
+// Implement this service to create an Amplifier tool in Go, TypeScript, C#, etc.
+service ToolService {
+  // Return the tool's name, description, and JSON Schema parameters.
+  rpc GetSpec(Empty) returns (ToolSpec);
+
+  // Execute the tool with JSON (or MessagePack) input.
+  rpc Execute(ToolExecuteRequest) returns (ToolExecuteResponse);
+}
+
+message Empty {}
+
+message ToolSpec {
+  string name = 1;
+  string description = 2;
+  // JSON Schema describing the tool's input parameters, as a JSON string.
+  string parameters_json = 3;
+}
+
+message ToolExecuteRequest {
+  // Serialized input payload (default: JSON, future: MessagePack).
+  bytes input = 1;
+  // MIME type: "application/json" (default if empty) or "application/msgpack".
+  string content_type = 2;
+}
+
+message ToolExecuteResponse {
+  bool success = 1;
+  // Serialized output payload.
+  bytes output = 2;
+  // MIME type of output (mirrors request content_type).
+  string content_type = 3;
+  // Error message if success is false.
+  string error = 4;
+}