dial-langchain 0.5.0__tar.gz

dial_langchain-0.5.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/

dial_langchain-0.5.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: dial-langchain
+Version: 0.5.0
+Summary: Official Dial LangChain tools — phone numbers, SMS, WhatsApp, and voice calls for AI agents
+Requires-Python: >=3.11
+Requires-Dist: dial-sdk
+Requires-Dist: langchain-core>=0.2
+Description-Content-Type: text/markdown
+
+# dial-langchain
+
+Official [LangChain](https://www.langchain.com/) tools for [Dial](https://getdial.ai) — phone numbers, SMS, WhatsApp, and voice calls for AI agents.
+
+## Install
+
+```bash
+pip install dial-langchain
+# or
+uv add dial-langchain
+```
+
+This pulls in [`dial-sdk`](https://pypi.org/project/dial-sdk/) and `langchain-core` automatically. Requires Python 3.11+.
+
+## Quickstart
+
+Each Dial capability is a LangChain `BaseTool`. Construct it with your API key (and optional `base_url`) and hand it to an agent:
+
+```python
+from dial_langchain import (
+    ListNumbersTool,
+    SendMessageTool,
+    MakeCallTool,
+    ListCallsTool,
+    GetCallTool,
+    WaitForMessageTool,
+)
+
+tools = [
+    ListNumbersTool(api_key="sk_live_..."),
+    SendMessageTool(api_key="sk_live_..."),
+    MakeCallTool(api_key="sk_live_..."),
+]
+
+# Drop into any LangChain agent:
+from langchain.agents import create_react_agent
+agent = create_react_agent(model, tools, prompt)
+```
+
+`base_url` defaults to `https://getdial.ai`; override it for local or self-hosted setups.
+
+## Available tools
+
+| Tool | Tool name (for the LLM) |
+| --- | --- |
+| `ListNumbersTool` | `list_numbers` |
+| `PurchaseNumberTool` | `purchase_number` |
+| `SetNumberPropertiesTool` | `set_number_properties` |
+| `ListMessagesTool` | `list_messages` |
+| `SendMessageTool` | `send_message` |
+| `ListCallsTool` | `list_calls` |
+| `MakeCallTool` | `make_call` |
+| `GetCallTool` | `get_call` |
+| `WaitForMessageTool` | `wait_for_message` |
+
+Each tool wraps the corresponding [`dial-sdk`](https://pypi.org/project/dial-sdk/) call under the hood.
+
+## Related
+
+- [`dial-sdk`](https://pypi.org/project/dial-sdk/) — the underlying async Python SDK.
+- [Documentation](https://docs.getdial.ai)

dial_langchain-0.5.0/README.md

@@ -0,0 +1,61 @@
+# dial-langchain
+
+Official [LangChain](https://www.langchain.com/) tools for [Dial](https://getdial.ai) — phone numbers, SMS, WhatsApp, and voice calls for AI agents.
+
+## Install
+
+```bash
+pip install dial-langchain
+# or
+uv add dial-langchain
+```
+
+This pulls in [`dial-sdk`](https://pypi.org/project/dial-sdk/) and `langchain-core` automatically. Requires Python 3.11+.
+
+## Quickstart
+
+Each Dial capability is a LangChain `BaseTool`. Construct it with your API key (and optional `base_url`) and hand it to an agent:
+
+```python
+from dial_langchain import (
+    ListNumbersTool,
+    SendMessageTool,
+    MakeCallTool,
+    ListCallsTool,
+    GetCallTool,
+    WaitForMessageTool,
+)
+
+tools = [
+    ListNumbersTool(api_key="sk_live_..."),
+    SendMessageTool(api_key="sk_live_..."),
+    MakeCallTool(api_key="sk_live_..."),
+]
+
+# Drop into any LangChain agent:
+from langchain.agents import create_react_agent
+agent = create_react_agent(model, tools, prompt)
+```
+
+`base_url` defaults to `https://getdial.ai`; override it for local or self-hosted setups.
+
+## Available tools
+
+| Tool | Tool name (for the LLM) |
+| --- | --- |
+| `ListNumbersTool` | `list_numbers` |
+| `PurchaseNumberTool` | `purchase_number` |
+| `SetNumberPropertiesTool` | `set_number_properties` |
+| `ListMessagesTool` | `list_messages` |
+| `SendMessageTool` | `send_message` |
+| `ListCallsTool` | `list_calls` |
+| `MakeCallTool` | `make_call` |
+| `GetCallTool` | `get_call` |
+| `WaitForMessageTool` | `wait_for_message` |
+
+Each tool wraps the corresponding [`dial-sdk`](https://pypi.org/project/dial-sdk/) call under the hood.
+
+## Related
+
+- [`dial-sdk`](https://pypi.org/project/dial-sdk/) — the underlying async Python SDK.
+- [Documentation](https://docs.getdial.ai)

dial_langchain-0.5.0/dial_langchain/__init__.py

@@ -0,0 +1,23 @@
+from .tools import (
+    ListNumbersTool,
+    PurchaseNumberTool,
+    SetNumberPropertiesTool,
+    ListMessagesTool,
+    SendMessageTool,
+    ListCallsTool,
+    MakeCallTool,
+    GetCallTool,
+    WaitForMessageTool,
+)
+
+__all__ = [
+    "ListNumbersTool",
+    "PurchaseNumberTool",
+    "SetNumberPropertiesTool",
+    "ListMessagesTool",
+    "SendMessageTool",
+    "ListCallsTool",
+    "MakeCallTool",
+    "GetCallTool",
+    "WaitForMessageTool",
+]

dial_langchain-0.5.0/dial_langchain/tools.py

@@ -0,0 +1,365 @@
+import asyncio
+from typing import Optional
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+from dial_sdk import (
+    DialClient,
+    DialConfig,
+    MakeCallParams,
+    PurchaseNumberParams,
+    SendMessageParams,
+)
+
+DEFAULT_BASE_URL = "https://getdial.ai"
+
+
+# ── Numbers ──────────────────────────────────────────────────────────────────
+
+
+class ListNumbersTool(BaseTool):
+    name: str = "list_numbers"
+    description: str = "List all available Dial phone numbers on the account."
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            numbers = await client.list_numbers()
+            if not numbers:
+                return "No numbers found."
+            return "\n".join(
+                f"{n.id} | {n.number} | {n.country} | {n.capabilities}"
+                + (f' | "{n.nickname}"' if n.nickname else "")
+                for n in numbers
+            )
+        finally:
+            await client.close()
+
+
+class PurchaseNumberInput(BaseModel):
+    country: str = Field(default="US", description="ISO-3166 alpha-2 country code, e.g. 'US'")
+    area_code: str | None = Field(
+        default=None, description="Optional area code to prefer when provisioning, e.g. '415'"
+    )
+
+
+class PurchaseNumberTool(BaseTool):
+    name: str = "purchase_number"
+    description: str = "Provision (buy) a new Dial phone number. Billable."
+    args_schema: type[BaseModel] = PurchaseNumberInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, country: str = "US", area_code: str | None = None) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            number = await client.purchase_number(
+                PurchaseNumberParams(country=country, area_code=area_code)
+            )
+            return f"Purchased {number.number} (id: {number.id}, country: {number.country})"
+        finally:
+            await client.close()
+
+
+class SetNumberPropertiesInput(BaseModel):
+    number_id: str = Field(description="ID of the Dial phone number to update")
+    inbound_instruction: str | None = Field(
+        default=None, description="New system prompt for inbound calls to this number"
+    )
+    nickname: str | None = Field(
+        default=None,
+        description="Human-readable label for the number, e.g. 'Support line'. "
+        "Pass an empty string to clear it.",
+    )
+
+
+class SetNumberPropertiesTool(BaseTool):
+    name: str = "set_number_properties"
+    description: str = (
+        "Update a Dial phone number's properties: its inbound instruction (the system "
+        "prompt its AI voice agent uses on inbound calls) and/or its nickname. "
+        "Provide at least one."
+    )
+    args_schema: type[BaseModel] = SetNumberPropertiesInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(
+        self,
+        number_id: str,
+        inbound_instruction: str | None = None,
+        nickname: str | None = None,
+    ) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            kwargs: dict = {}
+            if inbound_instruction is not None:
+                kwargs["inbound_instruction"] = inbound_instruction
+            if nickname is not None:
+                kwargs["nickname"] = nickname
+            if not kwargs:
+                return "Provide at least one of inbound_instruction or nickname."
+            number = await client.set_number_properties(number_id, **kwargs)
+            nick = f' | nickname: "{number.nickname}"' if number.nickname else ""
+            return f"Updated {number.number} (id: {number.id}){nick}"
+        finally:
+            await client.close()
+
+
+# ── Messages ─────────────────────────────────────────────────────────────────
+
+
+class ListMessagesInput(BaseModel):
+    number_id: str | None = Field(
+        default=None, description="Restrict to messages on a single owned phone number id"
+    )
+    direction: str | None = Field(
+        default=None, description="Filter by direction: 'inbound' or 'outbound'"
+    )
+
+
+class ListMessagesTool(BaseTool):
+    name: str = "list_messages"
+    description: str = "List recent inbound and outbound messages on the account."
+    args_schema: type[BaseModel] = ListMessagesInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, number_id: str | None = None, direction: str | None = None) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            messages = await client.list_messages(number_id=number_id, direction=direction)
+            if not messages:
+                return "No messages found."
+            return "\n".join(
+                f"[{m.direction}] {m.from_} → {m.to}: {m.body[:50]}" for m in messages
+            )
+        finally:
+            await client.close()
+
+
+class SendMessageInput(BaseModel):
+    to: str = Field(description="Destination phone number in E.164 format, e.g. +1234567890")
+    from_number_id: str = Field(description="ID of the Dial phone number to send from")
+    body: str = Field(description="Message body text")
+    channel: str = Field(default="sms", description="Channel to use: 'sms' or 'whatsapp'")
+
+
+class SendMessageTool(BaseTool):
+    name: str = "send_message"
+    description: str = "Send an SMS or WhatsApp message to a phone number."
+    args_schema: type[BaseModel] = SendMessageInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, to: str, from_number_id: str, body: str, channel: str = "sms") -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            msg = await client.send_message(
+                SendMessageParams(to=to, from_number_id=from_number_id, body=body, channel=channel)
+            )
+            return f"Message sent successfully. ID: {msg.id}, status: {msg.status}"
+        finally:
+            await client.close()
+
+
+# ── Calls ────────────────────────────────────────────────────────────────────
+
+
+class ListCallsInput(BaseModel):
+    number_id: str | None = Field(
+        default=None, description="Restrict to calls on a single owned phone number id"
+    )
+    direction: str | None = Field(
+        default=None, description="Filter by direction: 'inbound' or 'outbound'"
+    )
+
+
+class ListCallsTool(BaseTool):
+    name: str = "list_calls"
+    description: str = "List recent inbound and outbound calls on the account."
+    args_schema: type[BaseModel] = ListCallsInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, number_id: str | None = None, direction: str | None = None) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            calls = await client.list_calls(number_id=number_id, direction=direction)
+            if not calls:
+                return "No calls found."
+            return "\n".join(
+                f"{c.id} | [{c.direction}] {c.from_} → {c.to} | "
+                f"{c.status.get('label')} | {c.duration}s"
+                for c in calls
+            )
+        finally:
+            await client.close()
+
+
+class MakeCallInput(BaseModel):
+    to: str = Field(description="Destination phone number in E.164 format, e.g. +1234567890")
+    from_number_id: str = Field(description="ID of the Dial phone number to call from")
+    outbound_instruction: str = Field(
+        description="System prompt for the AI voice agent during this call"
+    )
+    language: Optional[str] = Field(
+        default=None,
+        description=(
+            "BCP-47 language tag, e.g. 'en-US', 'he-IL'. Omit to auto-detect from the "
+            "destination number's country (the agent also handles en-US)."
+        ),
+    )
+    idempotency_key: Optional[str] = Field(
+        default=None,
+        description=(
+            "Unique key (e.g. a UUID) making the placement idempotent: re-invoking with "
+            "the same key returns the already-placed call instead of dialing again."
+        ),
+    )
+
+
+class MakeCallTool(BaseTool):
+    name: str = "make_call"
+    description: str = "Initiate an AI voice call to a phone number."
+    args_schema: type[BaseModel] = MakeCallInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(
+        self,
+        to: str,
+        from_number_id: str,
+        outbound_instruction: str,
+        language: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            call = await client.make_call(
+                MakeCallParams(
+                    to=to,
+                    from_number_id=from_number_id,
+                    outbound_instruction=outbound_instruction,
+                    language=language,
+                    idempotency_key=idempotency_key,
+                )
+            )
+            return f"Call initiated. ID: {call.id}, state: {call.status.get('state')}"
+        finally:
+            await client.close()
+
+
+class GetCallInput(BaseModel):
+    call_id: str = Field(description="ID of the call to fetch")
+
+
+class GetCallTool(BaseTool):
+    name: str = "get_call"
+    description: str = "Fetch a single call by its id, including its current status."
+    args_schema: type[BaseModel] = GetCallInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, call_id: str) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            call = await client.get_call(call_id)
+            return (
+                f"Call {call.id}: [{call.direction}] {call.from_} → {call.to} | "
+                f"state={call.status.get('state')} | label={call.status.get('label')} | "
+                f"duration={call.duration}s"
+            )
+        finally:
+            await client.close()
+
+
+# ── Events (wait-for) ──────────────────────────────────────────────────────────
+
+
+class WaitForMessageInput(BaseModel):
+    phone_number_id: str = Field(
+        default="",
+        description="Optional id of the Dial phone number to wait on. "
+        "If omitted, returns the first inbound message on any number.",
+    )
+    timeout_seconds: int = Field(
+        default=30, description="How long to wait for a message in seconds"
+    )
+
+
+class WaitForMessageTool(BaseTool):
+    name: str = "wait_for_message"
+    description: str = (
+        "Wait for the next inbound SMS or WhatsApp message and return it. "
+        "Blocks until a message arrives or the timeout elapses."
+    )
+    args_schema: type[BaseModel] = WaitForMessageInput
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+    def _run(self, *args, **kwargs):
+        raise NotImplementedError("Use async")
+
+    async def _arun(self, phone_number_id: str = "", timeout_seconds: int = 30) -> str:
+        client = DialClient(DialConfig(api_key=self.api_key, base_url=self.base_url))
+        try:
+            # Resolve the phone number id to its E.164 number so we can match the
+            # inbound event's `to` field (events carry the number, not its id).
+            target_number: str | None = None
+            if phone_number_id:
+                numbers = await client.list_numbers()
+                match = next((n for n in numbers if n.id == phone_number_id), None)
+                if match is None:
+                    return f"No owned number with id {phone_number_id}."
+                target_number = match.number
+
+            async def _first_message() -> dict | None:
+                async with client.new_events_connection() as conn:
+                    async for event in conn:
+                        if event.get("type") != "message.received":
+                            continue
+                        # Event fields live under `data` in the standardized envelope.
+                        data = event.get("data", {})
+                        if target_number and data.get("to") != target_number:
+                            continue
+                        return event
+                return None
+
+            try:
+                event = await asyncio.wait_for(_first_message(), timeout=timeout_seconds)
+            except asyncio.TimeoutError:
+                return f"No message received within {timeout_seconds}s."
+
+            if not event:
+                return f"No message received within {timeout_seconds}s."
+            data = event.get("data", {})
+            return f"Received message from {data.get('from')}: {data.get('body')}"
+        finally:
+            await client.close()

dial_langchain-0.5.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "dial-langchain"
+version = "0.5.0"
+description = "Official Dial LangChain tools — phone numbers, SMS, WhatsApp, and voice calls for AI agents"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "langchain-core>=0.2",
+    "dial-sdk",
+]
+
+[tool.uv.sources]
+dial-sdk = { path = "../sdk-python", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["dial_langchain"]

dial_langchain-0.5.0/test.py

@@ -0,0 +1,35 @@
+"""
+Quick test script for the Dial LangChain tools.
+
+Usage:
+    uv sync
+    uv run python test.py
+"""
+
+import asyncio
+import sys
+import os
+sys.path.insert(0, os.path.dirname(__file__))
+
+from dial_langchain import ListNumbersTool, ListMessagesTool, ListCallsTool, SendMessageTool, MakeCallTool, WaitForMessageTool
+
+API_KEY = "sk_live_..."
+BASE_URL = "https://getdial.ai"
+
+
+async def main():
+    list_numbers = ListNumbersTool(api_key=API_KEY, base_url=BASE_URL)
+    list_messages = ListMessagesTool(api_key=API_KEY, base_url=BASE_URL)
+    list_calls = ListCallsTool(api_key=API_KEY, base_url=BASE_URL)
+
+    print("--- Numbers ---")
+    print(await list_numbers._arun())
+
+    print("\n--- Messages ---")
+    print(await list_messages._arun())
+
+    print("\n--- Calls ---")
+    print(await list_calls._arun())
+
+
+asyncio.run(main())