minmo 0.1.0__py3-none-any.whl

minmo/__init__.py

@@ -0,0 +1,15 @@
+from minmo.agent import VoiceAgent
+from minmo.errors import (
+    MinmoError,
+    MinmoSchemaError,
+    MinmoDeployError,
+    MinmoAuthError,
+)
+
+__all__ = [
+    "VoiceAgent",
+    "MinmoError",
+    "MinmoSchemaError",
+    "MinmoDeployError",
+    "MinmoAuthError",
+]

minmo/agent.py

@@ -0,0 +1,179 @@
+import json
+import os
+import socket
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Optional
+
+from minmo.errors import MinmoDeployError, MinmoSchemaError
+from minmo.logging import write_session_log
+from minmo.schema import function_to_tool_schema
+
+_VALID_TRANSPORTS = ("http", "client")
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict
+    func: Callable
+    transport: str = "http"
+
+
+class VoiceAgent:
+    def __init__(
+        self,
+        prompt: str,
+        api_key: str,
+        name: str = "minmo-agent",
+        llm: Optional[dict] = None,
+        provider=None,
+        provider_options: Optional[dict] = None,
+        log_path: Optional[str] = None,
+        on_session_end: Optional[Callable] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required and cannot be empty.")
+
+        if llm is not None:
+            missing = [
+                key for key in ("base_url", "model", "api_key") if not llm.get(key)
+            ]
+            if missing:
+                raise ValueError(
+                    f"llm is missing required key(s): {', '.join(missing)}. "
+                    "minmo requires base_url, model, and api_key when llm is given."
+                )
+
+        self.prompt = prompt
+        self.api_key = api_key
+        self.name = name
+        self.llm = llm
+        self.provider_options = provider_options or {}
+        self.log_path = log_path
+        self.on_session_end = on_session_end
+        self.tools: dict[str, Tool] = {}
+        self.agent_id: Optional[str] = None
+
+        if provider is None:
+            from minmo.providers.assemblyai import AssemblyAIProvider
+
+            provider = AssemblyAIProvider()
+        self.provider = provider
+
+    def tool(
+        self, func: Optional[Callable] = None, *, transport: str = "http"
+    ) -> Callable:
+        if transport not in _VALID_TRANSPORTS:
+            raise MinmoSchemaError(
+                f"transport must be one of {_VALID_TRANSPORTS!r}, got {transport!r}."
+            )
+
+        def register(f: Callable) -> Callable:
+            schema = function_to_tool_schema(f)
+            self.tools[schema["name"]] = Tool(
+                name=schema["name"],
+                description=schema["description"],
+                parameters=schema["parameters"],
+                func=f,
+                transport=transport,
+            )
+            return f
+
+        if func is not None:
+            return register(func)
+        return register
+
+    def deploy(self, local: bool = False, host_url: Optional[str] = None) -> dict:
+        self.provider.validate_tools(list(self.tools.values()))
+
+        needs_base = any(t.transport == "http" for t in self.tools.values())
+
+        base = None
+        if needs_base:
+            if local:
+                base = self._start_local_server_and_tunnel()
+            else:
+                base = host_url or os.environ.get("MINMO_HOST_URL")
+                if not base:
+                    raise MinmoDeployError(
+                        "local=False requires host_url or the MINMO_HOST_URL env var, "
+                        "pointing at your already-deployed tool server, since at least one "
+                        "registered tool uses transport='http'."
+                    )
+
+        self._snapshot_history()
+
+        record = self.provider.deploy(
+            name=self.name,
+            prompt=self.prompt,
+            tools=list(self.tools.values()),
+            base=base,
+            llm=self.llm,
+            provider_options=self.provider_options,
+            api_key=self.api_key,
+        )
+        self.agent_id = record.get("id")
+        return record
+
+    def mint_token(self) -> str:
+        if not getattr(self, "agent_id", None):
+            raise MinmoDeployError(
+                "mint_token() requires a prior successful deploy() call."
+            )
+        return self.provider.mint_token(self.agent_id, self.api_key)
+
+    def log_session(
+        self, session_id: str, transcript: list, tool_calls: list
+    ) -> Optional[dict]:
+        if not self.log_path:
+            return None
+        record = write_session_log(self.log_path, session_id, transcript, tool_calls)
+        if self.on_session_end:
+            self.on_session_end(record)
+        return record
+
+    def _snapshot_history(self) -> None:
+        history_dir = Path(".minmo") / "history"
+        history_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%f") + "Z"
+        snapshot = {
+            "prompt": self.prompt,
+            "tool_schemas": [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "parameters": t.parameters,
+                }
+                for t in self.tools.values()
+            ],
+            "timestamp": timestamp,
+        }
+        (history_dir / f"{timestamp}.json").write_text(json.dumps(snapshot, indent=2))
+
+    def _start_local_server_and_tunnel(self) -> str:
+        import uvicorn
+        from pyngrok import ngrok
+
+        from minmo.server import create_tool_server
+
+        app = create_tool_server(self.tools)
+
+        sock = socket.socket()
+        sock.bind(("", 0))
+        port = sock.getsockname()[1]
+        sock.close()
+
+        config = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning")
+        server = uvicorn.Server(config)
+        thread = threading.Thread(target=server.run, daemon=True)
+        thread.start()
+        while not server.started:
+            time.sleep(0.05)
+
+        tunnel = ngrok.connect(port, "http")
+        return tunnel.public_url

minmo/cli.py

@@ -0,0 +1,99 @@
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from minmo.agent import VoiceAgent
+
+MAIN_PY_TEMPLATE = '''\
+from minmo import VoiceAgent
+
+agent = VoiceAgent(
+    prompt="You are a friendly voice assistant. Keep answers short.",
+    api_key="YOUR_ASSEMBLYAI_API_KEY",
+)
+
+
+@agent.tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"It's sunny in {city}."
+
+
+if __name__ == "__main__":
+    result = agent.deploy(local=True)
+    print(result)
+'''
+
+ENV_EXAMPLE_TEMPLATE = "ASSEMBLYAI_API_KEY=\n"
+
+REQUIREMENTS_TEMPLATE = "minmo\n"
+
+
+@click.group()
+def main():
+    """minmo — build voice agents without the boilerplate."""
+
+
+@main.command()
+def init():
+    """Scaffold a new minmo project in the current directory."""
+    Path("main.py").write_text(MAIN_PY_TEMPLATE)
+    Path(".env.example").write_text(ENV_EXAMPLE_TEMPLATE)
+    Path("requirements.txt").write_text(REQUIREMENTS_TEMPLATE)
+    click.echo("Scaffolded main.py, .env.example, requirements.txt")
+
+
+def _load_agent_from_main() -> VoiceAgent:
+    main_path = Path.cwd() / "main.py"
+    if not main_path.exists():
+        raise click.ClickException(
+            "No main.py found in the current directory. Run `minmo init` first."
+        )
+
+    spec = importlib.util.spec_from_file_location("minmo_user_main", main_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)  # type: ignore[union-attr]
+
+    for value in vars(module).values():
+        if isinstance(value, VoiceAgent):
+            return value
+
+    raise click.ClickException("No VoiceAgent instance found in main.py.")
+
+
+@main.command()
+@click.option(
+    "--local/--remote",
+    default=True,
+    help="Run a local tool server via ngrok tunnel (default), or deploy against an "
+    "already-hosted tool server (set MINMO_HOST_URL or use main.py's host_url).",
+)
+def deploy(local):
+    """Deploy the VoiceAgent defined in main.py."""
+    agent = _load_agent_from_main()
+    record = agent.deploy(local=local)
+    click.echo(json.dumps(record, indent=2))
+
+
+@main.command()
+def logs():
+    """Tail the most recent session log for the VoiceAgent in main.py."""
+    agent = _load_agent_from_main()
+    if not agent.log_path:
+        raise click.ClickException(
+            "The VoiceAgent in main.py has no log_path configured."
+        )
+
+    log_dir = Path(agent.log_path)
+    files = sorted(log_dir.glob("*.json"), key=lambda p: p.stat().st_mtime)
+    if not files:
+        raise click.ClickException(f"No session logs found in {log_dir}.")
+
+    click.echo(files[-1].read_text())
+
+
+if __name__ == "__main__":
+    main()

minmo/errors.py

@@ -0,0 +1,14 @@
+class MinmoError(Exception):
+    """Base class for all minmo errors."""
+
+
+class MinmoSchemaError(MinmoError):
+    """Raised when a @agent.tool function can't be turned into a JSON-Schema tool."""
+
+
+class MinmoDeployError(MinmoError):
+    """Raised when deploying an agent fails (missing config, AssemblyAI rejected the request)."""
+
+
+class MinmoAuthError(MinmoError):
+    """Raised when the AssemblyAI API key is missing, empty, or rejected."""

minmo/logging.py

@@ -0,0 +1,18 @@
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def write_session_log(
+    log_path: str, session_id: str, transcript: list, tool_calls: list
+) -> dict:
+    record = {
+        "session_id": session_id,
+        "transcript": transcript,
+        "tool_calls": tool_calls,
+        "ended_at": datetime.now(timezone.utc).isoformat(),
+    }
+    log_dir = Path(log_path)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    (log_dir / f"{session_id}.json").write_text(json.dumps(record, indent=2))
+    return record

minmo/providers/assemblyai.py

@@ -0,0 +1,95 @@
+from typing import TYPE_CHECKING, Optional
+
+import requests
+
+from minmo.errors import MinmoAuthError, MinmoDeployError
+
+if TYPE_CHECKING:
+    from minmo.agent import Tool
+
+BASE_URL = "https://agents.assemblyai.com/v1"
+DEFAULT_VOICE_ID = "alba"
+DEFAULT_TOKEN_EXPIRY_SECONDS = 60  # AssemblyAI requires 1-600; docs recommend 60-300
+
+
+class AssemblyAIProvider:
+    """A VoiceProvider implementation backed by AssemblyAI's Voice Agent API. See providers/base.py."""
+
+    def tool_url(self, base: str, tool_name: str) -> str:
+        return f"{base.rstrip('/')}/tools/{tool_name}"
+
+    def validate_tools(self, tools: "list[Tool]") -> None:
+        pass
+
+    def deploy(
+        self,
+        *,
+        name: str,
+        prompt: str,
+        tools: "list[Tool]",
+        base: Optional[str],
+        llm: Optional[dict],
+        provider_options: dict,
+        api_key: str,
+    ) -> dict:
+        voice_id = provider_options.get("voice_id", DEFAULT_VOICE_ID)
+        config: dict = {
+            "name": name,
+            "system_prompt": prompt,
+            "voice": {"voice_id": voice_id},
+        }
+        if tools:
+            config["tools"] = [self._tool_config(t, base) for t in tools]
+        if llm:
+            config["llm"] = llm
+
+        resp = requests.post(
+            f"{BASE_URL}/agents",
+            headers={"Authorization": api_key, "Content-Type": "application/json"},
+            json=config,
+            timeout=30,
+        )
+        if resp.status_code == 401:
+            raise MinmoAuthError(f"AssemblyAI rejected the API key: {resp.text}")
+        if resp.status_code >= 400:
+            raise MinmoDeployError(
+                f"AssemblyAI deploy failed ({resp.status_code}): {resp.text}"
+            )
+        record = resp.json()
+        record["info"] = (
+            f"Hosted on AssemblyAI's servers as agent '{record.get('id')}' — it stays "
+            "there until you delete or redeploy it. To use it, call mint_token() to get "
+            "a short-lived client token, then open a voice session with that token "
+            "(browser SDK, phone bridge, etc). AssemblyAI reaches your http-transport "
+            f"tools by calling {base or '(no http tools registered)'} whenever the model "
+            "wants to use one."
+        )
+        return record
+
+    def _tool_config(self, tool: "Tool", base: Optional[str]) -> dict:
+        common = {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.parameters,
+        }
+        if tool.transport == "client":
+            return {**common, "type": "function"}
+        return {
+            **common,
+            "http": {"url": self.tool_url(base, tool.name), "http_method": "POST"},
+        }
+
+    def mint_token(self, agent_id: str, api_key: str) -> str:
+        resp = requests.get(
+            f"{BASE_URL}/token",
+            headers={"Authorization": api_key},
+            params={"expires_in_seconds": DEFAULT_TOKEN_EXPIRY_SECONDS},
+            timeout=30,
+        )
+        if resp.status_code == 401:
+            raise MinmoAuthError(f"AssemblyAI rejected the API key: {resp.text}")
+        if resp.status_code >= 400:
+            raise MinmoDeployError(
+                f"Token mint failed ({resp.status_code}): {resp.text}"
+            )
+        return resp.json()["token"]

minmo/providers/base.py

@@ -0,0 +1,56 @@
+from typing import TYPE_CHECKING, Optional, Protocol
+
+if TYPE_CHECKING:
+    from minmo.agent import Tool
+
+
+class VoiceProvider(Protocol):
+    """Everything minmo needs from a voice-agent backend.
+
+    AssemblyAI and Hume are the implementations today (see assemblyai.py,
+    hume.py). A future provider (OpenAI Realtime, ElevenLabs) implements
+    this same protocol as its own module — nothing outside providers/
+    changes.
+    """
+
+    def tool_url(self, base: str, tool_name: str) -> str:
+        """Build the public URL the provider should call for a given tool."""
+        ...
+
+    def validate_tools(self, tools: "list[Tool]") -> None:
+        """Raise MinmoDeployError early if `tools` is incompatible with what
+        this provider supports (e.g. a provider with no HTTP-tool concept
+        rejecting transport="http" tools). Called by VoiceAgent.deploy() before
+        any expensive/side-effecting base-URL resolution (local server, ngrok
+        tunnel, host_url check) so an unsupported tool set fails fast. A
+        provider with no such restrictions is a no-op.
+        """
+        ...
+
+    def deploy(
+        self,
+        *,
+        name: str,
+        prompt: str,
+        tools: "list[Tool]",
+        base: Optional[str],
+        llm: Optional[dict],
+        provider_options: dict,
+        api_key: str,
+    ) -> dict:
+        """Build AND publish the agent config, in however many network calls
+        this provider's API needs. Returns the created agent record (must
+        include an "id" the caller can store as agent_id).
+
+        `tools` is the raw list of registered Tool objects (name/description/
+        parameters/func/transport); `base` is the public URL the tool server
+        is reachable at, or None if no registered tool needs one (i.e. every
+        tool is transport="client"). The provider is responsible for turning
+        each Tool into whatever wire shape its transport needs — nothing
+        outside providers/ should know that shape.
+        """
+        ...
+
+    def mint_token(self, agent_id: str, api_key: str) -> str:
+        """Mint a short-lived client token for browser/embedded use."""
+        ...

minmo/providers/hume.py

@@ -0,0 +1,231 @@
+import json
+from typing import TYPE_CHECKING, Optional
+
+import requests
+
+from minmo.errors import MinmoAuthError, MinmoDeployError
+
+if TYPE_CHECKING:
+    from minmo.agent import Tool
+
+BASE_URL = "https://api.hume.ai/v0/evi"
+TOKEN_URL = "https://api.hume.ai/oauth2-cc/token"
+DEFAULT_VOICE = {"name": "Ava Song", "provider": "HUME_AI"}
+
+
+class HumeProvider:
+    """A VoiceProvider implementation backed by Hume AI's EVI API. See providers/base.py.
+
+    Hume has no HTTP-tool concept — every tool must be transport="client".
+    Requires provider_options={"secret_key": ...} in addition to the usual
+    api_key, since Hume issues both separately. EVI3 configs also require a
+    voice; provider_options["voice"] (a {"name", "provider"} dict) overrides
+    DEFAULT_VOICE if given.
+
+    Hume's prompts, tools, and configs are all name-unique, versioned
+    resources: POST to the collection endpoint with a name that already
+    exists returns 409. So every redeploy (same agent name, same tool
+    names) must add a new version to the existing resource instead of
+    creating a fresh one — see _get_or_create_version().
+    """
+
+    def __init__(self) -> None:
+        self._secret_key: Optional[str] = None
+
+    def tool_url(self, base: str, tool_name: str) -> str:
+        raise MinmoDeployError(
+            "HumeProvider has no HTTP-tool support — this method should never be called."
+        )
+
+    def validate_tools(self, tools: "list[Tool]") -> None:
+        http_tools = [t for t in tools if t.transport == "http"]
+        if http_tools:
+            names = ", ".join(t.name for t in http_tools)
+            raise MinmoDeployError(
+                f"HumeProvider only supports transport='client' tools; "
+                f"{names} use transport='http', which Hume cannot call. "
+                "Register these with @agent.tool(transport='client') instead."
+            )
+
+    def deploy(
+        self,
+        *,
+        name: str,
+        prompt: str,
+        tools: "list[Tool]",
+        base: Optional[str],
+        llm: Optional[dict],
+        provider_options: dict,
+        api_key: str,
+    ) -> dict:
+        self.validate_tools(tools)
+
+        secret_key = provider_options.get("secret_key")
+        if not secret_key:
+            raise MinmoDeployError(
+                "HumeProvider requires provider_options={'secret_key': ...} "
+                "(Hume issues an api_key and a secret_key separately)."
+            )
+        self._secret_key = secret_key
+
+        headers = {"X-Hume-Api-Key": api_key, "Content-Type": "application/json"}
+
+        prompt_name = f"{name} prompt"
+        prompt_record = self._get_or_create_version(
+            resource="prompts",
+            headers=headers,
+            name=prompt_name,
+            create_body={"name": prompt_name, "text": prompt},
+            version_body={"text": prompt},
+        )
+        prompt_ref = {"id": prompt_record["id"], "version": prompt_record["version"]}
+
+        tool_refs = []
+        for tool in tools:
+            tool_record = self._get_or_create_version(
+                resource="tools",
+                headers=headers,
+                name=tool.name,
+                create_body={
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": json.dumps(tool.parameters),
+                },
+                version_body={
+                    "description": tool.description,
+                    "parameters": json.dumps(tool.parameters),
+                },
+                already_created={"prompt": prompt_ref},
+            )
+            tool_refs.append(
+                {"id": tool_record["id"], "version": tool_record["version"]}
+            )
+
+        config_body: dict = {
+            "evi_version": "3",
+            "prompt": prompt_ref,
+            "voice": provider_options.get("voice", DEFAULT_VOICE),
+        }
+        if tool_refs:
+            config_body["tools"] = tool_refs
+
+        warnings = []
+        if llm:
+            config_body["language_model"] = {"model_resource": llm.get("model")}
+            warnings.append(
+                "llm.base_url and llm.api_key are not applicable to Hume's language_model "
+                "config (Hume selects from its own supported provider list by name) and "
+                "were ignored; only llm.model was passed through."
+            )
+
+        config_record = self._get_or_create_version(
+            resource="configs",
+            headers=headers,
+            name=name,
+            create_body={**config_body, "name": name},
+            version_body=config_body,
+            already_created={"prompt": prompt_ref, "tools": tool_refs},
+        )
+
+        result = dict(config_record)
+        result["info"] = (
+            f"Hosted on Hume as a versioned config resource named '{name}' (id "
+            f"{config_record.get('id')}, version {config_record.get('version')}) — "
+            "redeploying with the same name adds a new version instead of replacing it. "
+            "To use it, call mint_token() (needs the secret_key you passed in "
+            "provider_options) to get an OAuth access token, then start an EVI session "
+            "with it. All tools are transport='client', so your own app code (not "
+            "minmo) must handle each tool.call over that session."
+        )
+        if warnings:
+            result["warnings"] = warnings
+        return result
+
+    def _get_or_create_version(
+        self,
+        resource: str,
+        headers: dict,
+        name: str,
+        create_body: dict,
+        version_body: dict,
+        already_created: Optional[dict] = None,
+    ) -> dict:
+        """Hume's prompts/tools/configs are name-unique, versioned resources.
+
+        If a resource with this name already exists, POST a new version onto
+        it (.../{resource}/{id}); otherwise POST the collection endpoint to
+        create it fresh. Makes deploy() safe to call repeatedly with the same
+        agent/tool names, which is the normal redeploy path.
+        """
+        list_resp = requests.get(
+            f"{BASE_URL}/{resource}",
+            headers=headers,
+            params={"name": name, "page_size": 1},
+            timeout=30,
+        )
+        if list_resp.status_code == 401:
+            raise MinmoAuthError(f"Hume rejected the API key: {list_resp.text}")
+        if list_resp.status_code == 404:
+            # Hume returns 404 (not 200 + empty page) when nothing matches the name filter.
+            existing = []
+        elif list_resp.status_code >= 400:
+            raise MinmoDeployError(
+                f"Hume list-{resource} request failed ({list_resp.status_code}): {list_resp.text}"
+            )
+        else:
+            existing = list_resp.json().get(f"{resource}_page", [])
+
+        if existing:
+            existing_id = existing[0]["id"]
+            return self._post(
+                f"{BASE_URL}/{resource}/{existing_id}",
+                headers,
+                version_body,
+                already_created=already_created,
+            )
+        return self._post(
+            f"{BASE_URL}/{resource}",
+            headers,
+            create_body,
+            already_created=already_created,
+        )
+
+    def _post(
+        self,
+        url: str,
+        headers: dict,
+        body: dict,
+        already_created: Optional[dict] = None,
+    ) -> dict:
+        resp = requests.post(url, headers=headers, json=body, timeout=30)
+        if resp.status_code == 401:
+            raise MinmoAuthError(f"Hume rejected the API key: {resp.text}")
+        if resp.status_code >= 400:
+            context = (
+                f" Already created on Hume: {already_created}."
+                if already_created
+                else ""
+            )
+            raise MinmoDeployError(
+                f"Hume request to {url} failed ({resp.status_code}): {resp.text}.{context}"
+            )
+        return resp.json()
+
+    def mint_token(self, agent_id: str, api_key: str) -> str:
+        if not self._secret_key:
+            raise MinmoDeployError(
+                "mint_token() requires a prior deploy() call (secret_key not set)."
+            )
+        resp = requests.post(
+            TOKEN_URL,
+            auth=(api_key, self._secret_key),
+            data={"grant_type": "client_credentials"},
+            timeout=30,
+        )
+        if resp.status_code == 401:
+            raise MinmoAuthError(f"Hume rejected the credentials: {resp.text}")
+        if resp.status_code >= 400:
+            raise MinmoDeployError(
+                f"Hume token mint failed ({resp.status_code}): {resp.text}"
+            )
+        return resp.json()["access_token"]

minmo/providers/openai_realtime.py

@@ -0,0 +1,139 @@
+import uuid
+from typing import TYPE_CHECKING, Optional
+
+import requests
+
+from minmo.errors import MinmoAuthError, MinmoDeployError
+
+if TYPE_CHECKING:
+    from minmo.agent import Tool
+
+BASE_URL = "https://api.openai.com/v1/realtime"
+
+
+class OpenAIRealtimeProvider:
+    """A VoiceProvider implementation backed by OpenAI's Realtime API. See providers/base.py.
+
+    OpenAI Realtime has no persistent agent resource and no HTTP-tool concept.
+    deploy() makes no network call: it validates tools, requires
+    provider_options={"model": ..., "voice": ...} (no defaults — the caller
+    must choose), and stores the built session config in-memory keyed by a
+    locally generated id — this id is valid only for the lifetime of this
+    provider instance, not a server-side resource, and cannot be persisted
+    across processes or looked up by a different OpenAIRealtimeProvider instance.
+    mint_token() does the one real network call (POST /v1/realtime/client_secrets),
+    which both mints the ephemeral client token and (implicitly, on OpenAI's side)
+    starts the session bound to that config.
+    """
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, dict] = {}
+
+    def tool_url(self, base: str, tool_name: str) -> str:
+        raise MinmoDeployError(
+            "OpenAIRealtimeProvider has no HTTP-tool support — this method should never be called."
+        )
+
+    def validate_tools(self, tools: "list[Tool]") -> None:
+        http_tools = [t for t in tools if t.transport == "http"]
+        if http_tools:
+            names = ", ".join(t.name for t in http_tools)
+            raise MinmoDeployError(
+                f"OpenAIRealtimeProvider only supports transport='client' tools; "
+                f"{names} use transport='http', which OpenAI Realtime cannot call. "
+                "Register these with @agent.tool(transport='client') instead."
+            )
+
+    def deploy(
+        self,
+        *,
+        name: str,
+        prompt: str,
+        tools: "list[Tool]",
+        base: Optional[str],
+        llm: Optional[dict],
+        provider_options: dict,
+        api_key: str,
+    ) -> dict:
+        self.validate_tools(tools)
+
+        model = provider_options.get("model")
+        if not model:
+            raise MinmoDeployError(
+                "OpenAIRealtimeProvider requires provider_options={'model': ..., 'voice': ...} "
+                "(no default model — pick the realtime model you want)."
+            )
+        voice = provider_options.get("voice")
+        if not voice:
+            raise MinmoDeployError(
+                "OpenAIRealtimeProvider requires provider_options={'model': ..., 'voice': ...} "
+                "(no default voice — pick the voice you want)."
+            )
+
+        warnings = []
+        if llm:
+            warnings.append(
+                "llm is ignored for OpenAIRealtimeProvider: the realtime model configured via "
+                "provider_options['model'] IS the LLM, there is no separate one to plug in."
+            )
+
+        session_config: dict = {
+            "type": "realtime",
+            "model": model,
+            "instructions": prompt,
+            "audio": {"output": {"voice": voice}},
+        }
+        if tools:
+            session_config["tools"] = [self._tool_config(t) for t in tools]
+
+        session_id = uuid.uuid4().hex
+        self._sessions[session_id] = session_config
+
+        result: dict = {
+            "id": session_id,
+            "hosted": False,
+            "info": (
+                f"Not hosted anywhere — '{session_id}' only exists in this process's "
+                "memory, on this OpenAIRealtimeProvider instance. Nothing is saved on "
+                "OpenAI's side yet. To use it, call mint_token() now, in this same "
+                "process, to actually send the config to OpenAI and get back a "
+                "short-lived client token; open a Realtime session with that token. "
+                "All tools are transport='client', so your own app code handles each "
+                "tool call over that session."
+            ),
+        }
+        if warnings:
+            result["warnings"] = warnings
+        return result
+
+    def _tool_config(self, tool: "Tool") -> dict:
+        return {
+            "type": "function",
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.parameters,
+        }
+
+    def mint_token(self, agent_id: str, api_key: str) -> str:
+        config = self._sessions.get(agent_id)
+        if config is None:
+            raise MinmoDeployError(
+                f"mint_token() called with unknown id {agent_id!r} — requires a prior deploy() call on this provider instance."
+            )
+
+        resp = requests.post(
+            f"{BASE_URL}/client_secrets",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={"session": config},
+            timeout=30,
+        )
+        if resp.status_code == 401:
+            raise MinmoAuthError(f"OpenAI rejected the API key: {resp.text}")
+        if resp.status_code >= 400:
+            raise MinmoDeployError(
+                f"OpenAI Realtime client_secrets request failed ({resp.status_code}): {resp.text}"
+            )
+        return resp.json()["value"]

minmo/schema.py

@@ -0,0 +1,81 @@
+import inspect
+import typing
+from typing import Callable, Optional, Union, get_args, get_origin
+
+from minmo.errors import MinmoSchemaError
+
+_PRIMITIVE_MAP = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+}
+
+
+def _hint_to_json_schema(hint, param_name: str, func_name: str) -> tuple[dict, bool]:
+    """Returns (schema, required)."""
+    origin = get_origin(hint)
+
+    if origin is Union:
+        args = [a for a in get_args(hint) if a is not type(None)]
+        if len(args) != 1:
+            raise MinmoSchemaError(
+                f"{func_name}: parameter '{param_name}' has an unsupported Union hint; "
+                "only Optional[T] is supported."
+            )
+        schema, _ = _hint_to_json_schema(args[0], param_name, func_name)
+        return schema, False
+
+    if origin in (list, typing.List):
+        (item_hint,) = get_args(hint) or (str,)
+        if item_hint is not str:
+            raise MinmoSchemaError(
+                f"{func_name}: parameter '{param_name}' uses list[{item_hint}] — "
+                "only list[str] is supported."
+            )
+        return {"type": "array", "items": {"type": "string"}}, True
+
+    if hint in _PRIMITIVE_MAP:
+        return dict(_PRIMITIVE_MAP[hint]), True
+
+    raise MinmoSchemaError(
+        f"{func_name}: parameter '{param_name}' has unsupported type hint {hint!r}. "
+        "Supported: str, int, float, bool, list[str], Optional[...] of those."
+    )
+
+
+def function_to_tool_schema(func: Callable) -> dict:
+    func_name = func.__name__
+    doc = inspect.getdoc(func)
+    if not doc:
+        raise MinmoSchemaError(
+            f"{func_name}: missing docstring — the first line becomes the tool description."
+        )
+    description = doc.strip().splitlines()[0]
+
+    hints = typing.get_type_hints(func)
+    signature = inspect.signature(func)
+
+    properties = {}
+    required = []
+    for param_name in signature.parameters:
+        if param_name not in hints:
+            raise MinmoSchemaError(
+                f"{func_name}: parameter '{param_name}' is missing a type hint."
+            )
+        schema, is_required = _hint_to_json_schema(
+            hints[param_name], param_name, func_name
+        )
+        properties[param_name] = schema
+        if is_required:
+            required.append(param_name)
+
+    return {
+        "name": func_name,
+        "description": description,
+        "parameters": {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+        },
+    }

minmo/server.py

@@ -0,0 +1,28 @@
+import jsonschema
+from fastapi import FastAPI, Request
+
+from minmo.agent import Tool
+
+
+def _make_handler(tool: Tool):
+    async def handler(request: Request):
+        payload = await request.json() if await request.body() else {}
+        try:
+            jsonschema.validate(payload, tool.parameters)
+            result = tool.func(**payload)
+            return {"result": result}
+        except (
+            Exception
+        ) as exc:  # noqa: BLE001 - intentional: surface any tool error to the model
+            return {"error": str(exc)}
+
+    return handler
+
+
+def create_tool_server(tools: dict[str, Tool]) -> FastAPI:
+    app = FastAPI()
+    for tool in tools.values():
+        if tool.transport != "http":
+            continue
+        app.add_api_route(f"/tools/{tool.name}", _make_handler(tool), methods=["POST"])
+    return app

minmo/testing.py

@@ -0,0 +1,68 @@
+import json
+
+from openai import OpenAI
+
+from minmo.agent import VoiceAgent
+from minmo.errors import MinmoError
+
+
+def simulate(agent: VoiceAgent, transcript: list[str]) -> dict:
+    if not agent.llm:
+        raise MinmoError(
+            "simulate() requires VoiceAgent(llm={'base_url', 'model', 'api_key'}) — "
+            "there is no way to call AssemblyAI's managed model directly outside a live voice session."
+        )
+
+    client = OpenAI(base_url=agent.llm["base_url"], api_key=agent.llm["api_key"])
+    model = agent.llm["model"]
+
+    tool_defs = [
+        {
+            "type": "function",
+            "function": {
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters,
+            },
+        }
+        for t in agent.tools.values()
+    ] or None
+
+    messages: list[dict] = [{"role": "system", "content": agent.prompt}]
+    tool_call_log: list[dict] = []
+
+    for line in transcript:
+        messages.append({"role": "user", "content": line})
+
+        while True:
+            response = client.chat.completions.create(
+                model=model, messages=messages, tools=tool_defs
+            )
+            message = response.choices[0].message
+            messages.append(message.model_dump())
+
+            if not message.tool_calls:
+                break
+
+            for call in message.tool_calls:
+                tool = agent.tools[call.function.name]
+                args = json.loads(call.function.arguments)
+                try:
+                    output = {"result": tool.func(**args)}
+                except (
+                    Exception
+                ) as exc:  # noqa: BLE001 - mirrors server.py's structured-error behavior
+                    output = {"error": str(exc)}
+
+                tool_call_log.append(
+                    {"name": call.function.name, "input": args, "output": output}
+                )
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": call.id,
+                        "content": json.dumps(output),
+                    }
+                )
+
+    return {"conversation": messages, "tool_calls": tool_call_log}

minmo-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: minmo
+Version: 0.1.0
+Summary: Boilerplate-free SDK for building voice agents on AssemblyAI's Voice Agent API
+Project-URL: Homepage, https://github.com/a-elhaag/minmo
+Author: Anas Elhaag
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: openai>=1.30
+Requires-Dist: pyngrok>=7.0
+Requires-Dist: requests>=2.31
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# minmo
+
+[![CI](https://github.com/a-elhaag/minmo/actions/workflows/ci.yml/badge.svg)](https://github.com/a-elhaag/minmo/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+**Boilerplate-free SDK for building voice agents** on [AssemblyAI's Voice Agent API](https://assemblyai.com/docs/voice-agents/voice-agent-api), with support for Hume and OpenAI Realtime too.
+
+Define a prompt, register Python functions as tools, deploy. minmo handles
+JSON-Schema generation, local tool hosting + tunneling, and talking to each
+provider's REST API — so you write the assistant, not the plumbing.
+
+📖 **[Full documentation](https://a-elhaag.github.io/minmo/)**
+
+## Install
+
+```bash
+pip install -e .
+```
+
+(Set `NGROK_AUTHTOKEN` in your environment if you plan to use `local=True` —
+see [pyngrok's docs](https://pyngrok.readthedocs.io/) for how to get one.)
+
+## Quickstart
+
+```python
+from minmo import VoiceAgent
+
+agent = VoiceAgent(
+    prompt="You are a friendly voice assistant. Keep answers short.",
+    api_key="YOUR_ASSEMBLYAI_API_KEY",
+)
+
+
+@agent.tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"It's sunny in {city}."
+
+
+result = agent.deploy(local=True)
+print(result)  # the created AssemblyAI agent record, including its id
+```
+
+That's it — `deploy(local=True)` starts a local tool server, tunnels it
+publicly, and registers `get_weather` as a real tool your live voice agent
+can call.
+
+`result` always includes an `"info"` field — a plain-language paragraph
+telling you whether the agent is hosted on the provider's servers or only
+exists locally, and how to actually connect to it (usually via
+`mint_token()`). Worth printing after every deploy, especially since this
+differs per provider — see below.
+
+## Testing tool logic without burning session minutes
+
+```python
+from minmo import VoiceAgent
+from minmo.testing import simulate
+
+agent = VoiceAgent(
+    prompt="You are a friendly voice assistant.",
+    api_key="YOUR_ASSEMBLYAI_API_KEY",
+    llm={"base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "YOUR_OPENAI_KEY"},
+)
+
+
+@agent.tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"It's sunny in {city}."
+
+
+result = simulate(agent, transcript=["What's the weather in Paris?"])
+print(result["tool_calls"])
+```
+
+`simulate()` calls the `llm` you configured directly (any OpenAI-compatible
+endpoint) and runs tool calls against your local Python functions — no
+AssemblyAI session, no phone call.
+
+## Client-side tools (no server, no tunnel)
+
+`@agent.tool` defaults to `transport="http"` — minmo hosts the function
+behind a URL AssemblyAI calls. Pass `transport="client"` instead to declare
+a [client-side/function tool](https://assemblyai.com/docs/voice-agents/voice-agent-api/tools/client-side-tools):
+no server, no tunnel, no `host_url` needed for that tool.
+
+```python
+@agent.tool(transport="client")
+def get_account_balance(account_id: str) -> str:
+    """Look up an account's balance."""
+    return "$42.00"
+```
+
+minmo only builds the correct agent config for this — declaring the tool
+as client-side. Running the actual session (the WebSocket connection that
+receives `tool.call` and sends back `tool.result`) is your own code's job:
+a browser app, a Twilio bridge, whatever already holds that live connection.
+If every registered tool is `transport="client"`, `deploy()` skips the local
+server and tunnel (or `host_url` requirement) entirely — nothing to host.
+
+## Providers
+
+minmo supports AssemblyAI (default), Hume, and OpenAI Realtime. They don't
+all host your agent the same way:
+
+| Provider | Hosted on their servers? | How you use it |
+|---|---|---|
+| AssemblyAI | Yes — `deploy()` creates a persistent agent record | `mint_token()` for a client token, connect a voice session with it |
+| Hume | Yes — `deploy()` creates/versions a config resource | `mint_token()` for an access token, start an EVI session with it |
+| OpenAI Realtime | No — `deploy()` only builds a config in your process's memory | Call `mint_token()` right after, in the same process, to actually send it to OpenAI and get a session token |
+
+Pass a different provider via `VoiceAgent(provider=..., provider_options=...)`;
+see each provider's docstring in `minmo/providers/` for required options.
+
+## CLI
+
+```bash
+minmo init     # scaffold main.py, .env.example, requirements.txt
+minmo deploy   # import main.py, find the VoiceAgent, deploy it
+minmo logs     # print the most recent session log
+```
+
+## Deploying to a real server (not `local=True`)
+
+```python
+agent.deploy(local=False, host_url="https://your-deployed-tool-server.example.com")
+# or set MINMO_HOST_URL in the environment instead of passing host_url
+```
+
+Your host must already be running the tool server — `local=True` is for
+development; production tool hosting is up to you (minmo's local server
+factory, `minmo.server.create_tool_server`, is reusable if you want to
+deploy it yourself behind a real domain).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Pushes are auto-formatted with [Black](https://black.readthedocs.io/) via
+GitHub Actions, and every push/PR runs the test suite across Python 3.10–3.12.
+
+## Contributing
+
+Issues and PRs welcome. Keep changes small and covered by a test.
+
+## License
+
+[MIT](LICENSE) © [Anas Elhaag](https://github.com/a-elhaag)

minmo-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+minmo/__init__.py,sha256=G7vOsyFjTOCcNvMnb4g0zRGxFv4RojRm3MGO0bf2vdo,265
+minmo/agent.py,sha256=Fy-UnO7Kk88u_XBd19gByk3eGvgnhUAVNTZSaevR9XY,5758
+minmo/cli.py,sha256=TP2qhk_-fGPG81r4qm2vXA2JCCUuKJMi37E1ICUBpns,2658
+minmo/errors.py,sha256=Ebqd7vATKCCQfJea2pJ2yxId7Om9BKz33Ll9K5n9Vps,445
+minmo/logging.py,sha256=cF_yPBMzKPG4DgWWYvYmk7Qu2goTUOBjQj-5vM8kJoQ,539
+minmo/schema.py,sha256=DJ37CZar8DZt6awDGiRBjVF4qDBuQU-aq5ymUUpBKok,2581
+minmo/server.py,sha256=iUsTmfKZQ-IudWimiAXcWiHX5-Foh6GG01lhfv7Uels,838
+minmo/testing.py,sha256=vQORRSeON0X0zne_QLfs3Z9y7H0N2964s5lO4lLPcUQ,2219
+minmo/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+minmo/providers/assemblyai.py,sha256=-XVn7JMCKS-mLDEDfL7QJH3U3kzme-5QjY4VEo-SYzo,3327
+minmo/providers/base.py,sha256=V3_3BbxS1l0I-na332MX1DMmylL1smdIHoGjq-Zc6uc,2162
+minmo/providers/hume.py,sha256=sVjT_AxyPnBUccIv8TCZZcPf-fKc-4nP7aQamijfPjY,8655
+minmo/providers/openai_realtime.py,sha256=UolKCk480dLStf52irtCx5KizYLYMz6S2VkXLrimsAE,5333
+minmo-0.1.0.dist-info/METADATA,sha256=2u-kJISPxnHLSTwPDSXKQ9UmxL9dlAy0jr3UELVcAOc,6238
+minmo-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+minmo-0.1.0.dist-info/entry_points.txt,sha256=yVq0PWqm9rSExZVypzd1ZYSp5RoQ4KJEzla4CR7XuyA,41
+minmo-0.1.0.dist-info/licenses/LICENSE,sha256=qv_G1ukgjdOZd4NueyR_BduXSsaATBk7q1GVngnlSzs,1068
+minmo-0.1.0.dist-info/RECORD,,

minmo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

minmo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+minmo = minmo.cli:main

minmo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anas Elhaag
+
+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.