ez-ptc 0.4.0

Easy Programmatic Tool Calling — framework-agnostic multi-tool execution for any LLM

ez-ptc

Easy Programmatic Tool Calling -- a lightweight, zero-dependency, framework-agnostic library for multi-tool execution with any LLM.

What is programmatic tool calling?

The idea of programmatic tool calling (PTC) was introduced by Anthropic. Instead of the traditional pattern where an LLM makes one tool call per turn, the LLM writes code that calls multiple tools, uses variables, branches on results, and loops -- all executed in a single round-trip. Anthropic described this approach in their engineering blog post and provides a first-party implementation for the Claude API.

ez-ptc takes this pattern and makes it easy to use with any LLM provider -- OpenAI, Anthropic, Google, Groq, or any framework that talks to them.

Why ez-ptc?

• Works with any LLM provider -- OpenAI, Anthropic, Google, Groq, LiteLLM, and more. Not locked to a single API.
• Zero dependencies -- pure Python, no runtime dependencies. Bring your own LLM client.
• Two modes -- prompt mode (inject into any system prompt, no framework needed) or tool mode (native integration with OpenAI, LangChain, Pydantic AI, etc.).
• MCP support -- wrap tools from any MCP server with one line: Toolkit.from_mcp(session).
• Tool chaining with return types -- documents the exact return shape of each tool so the LLM doesn't guess wrong keys and cause KeyError at runtime.

Installation

# Using uv (recommended)
uv add ez-ptc

# Using pip
pip install ez-ptc

Zero runtime dependencies. Bring your own LLM client.

For MCP server integration:

uv add "ez-ptc[mcp]"
# or: pip install "ez-ptc[mcp]"

Quick start

1. Define tools

from typing import TypedDict
from ez_ptc import Toolkit, ez_tool

class WeatherResult(TypedDict):
    location: str
    temp: int
    unit: str
    condition: str

@ez_tool
def get_weather(location: str, unit: str = "celsius") -> WeatherResult:
    """Get current weather for a location.

    Args:
        location: City and state, e.g. "San Francisco, CA"
        unit: Temperature unit - "celsius" or "fahrenheit"
    """
    # Your actual API call here
    return {"location": location, "temp": 22, "unit": unit, "condition": "sunny"}

@ez_tool
def search_products(query: str, limit: int = 5) -> list[dict]:
    """Search the product catalog.

    Args:
        query: Search query string
        limit: Maximum number of results
    """
    return [{"name": "Umbrella", "price": 24.99}]

toolkit = Toolkit([get_weather, search_products])

2. Choose your mode

Prompt mode -- framework-free, inject into any system prompt:

from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": toolkit.prompt()},
        {"role": "user", "content": "What's the weather in NYC and SF?"},
    ],
)

code = toolkit.extract_code(response.choices[0].message.content)
result = toolkit.execute_sync(code)
print(result.output)

Tool mode -- native integration with any framework:

from openai import OpenAI
import json

client = OpenAI()
execute_fn = toolkit.as_tool_sync()
tool_schema = toolkit.tool_schema(format="openai")

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the weather in NYC and SF?"},
]

for turn in range(10):
    response = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=messages,
        tools=[tool_schema],
    )
    choice = response.choices[0]
    if choice.message.tool_calls:
        messages.append(choice.message)
        for tc in choice.message.tool_calls:
            args = json.loads(tc.function.arguments)
            result = execute_fn(**args)
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
    else:
        print(choice.message.content)
        break

What the LLM writes

Instead of separate tool calls, the LLM writes a single code block:

# Built-in parallel() helper runs tools concurrently
sf, ny = parallel(
    (get_weather, "San Francisco, CA"),
    (get_weather, "New York, NY"),
)
print(f"SF: {sf['temp']}°C, {sf['condition']}")
print(f"NY: {ny['temp']}°C, {ny['condition']}")

Multiple tool calls, parallel execution, variable passing -- one round-trip.

Tool chaining

When the LLM chains tool outputs -- passing the result of one tool into a conditional or another tool call -- it needs to know the exact shape of each return value. Without that information, the LLM guesses key names, and guesses are often wrong:

# The LLM writes this...
weather = get_weather("San Francisco, CA")
print(weather["temperature"])  # KeyError! The actual key is "temp"

The fix: use TypedDict return types (or Pydantic BaseModel) and enable assist_tool_chaining:

toolkit = Toolkit([get_weather, search_products], assist_tool_chaining=True)

Now the LLM sees return type annotations alongside each tool:

def get_weather(location: str, unit: str = 'celsius') -> WeatherResult:
    """Get current weather for a location.
    ...
    """
    # Returns: {location: str, temp: int, unit: str, condition: str}

The LLM knows the exact keys and types -- weather["temp"], weather["condition"] -- and can chain tool outputs without guessing. This works in all three output methods: prompt(), as_tool(), and tool_schema().

See Tool Chaining for TypedDict, Pydantic, and explicit schema examples.

Framework support

ez-ptc works with any LLM provider or framework:

Framework	Mode	Example
Raw API (OpenAI, Anthropic)	Prompt or Tool	prompt mode, openai, anthropic
LangChain	Tool	example
Pydantic AI	Tool	example
LiteLLM	Tool	example
Google GenAI	Tool	example
MCP servers	Tool or Prompt	example, docs

MCP Tool Bridge

ez-ptc can wrap tools from any MCP server -- file systems, databases, APIs, dev tools -- and use them in a Toolkit. The LLM can then call multiple MCP tools in a single round-trip, with variables, branching, and parallel execution.

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from ez_ptc import Toolkit

server = StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-everything"])

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # One line -- discovers all tools and resources
        toolkit = await Toolkit.from_mcp(session)

        # Use like any other toolkit
        result = await toolkit.execute('r = echo(message="hello")\nprint(r)')

What gets wrapped:

• MCP Tools -- wrapped as Tool objects with full signature and positional arg support
• Static Resources -- wrapped as zero-arg tools (e.g. read_config())
• Resource Templates -- wrapped as parameterized tools (e.g. query_user_profile(user_id="42"))
• Prompts -- not tools; accessed via get_mcp_prompt() for system prompt injection

Mix MCP tools with local @ez_tool functions:

toolkit = await Toolkit.from_mcp(
    session,
    extra_tools=[my_local_tool],
    assist_tool_chaining=True,
)

Requires pip install ez-ptc[mcp]. The core library stays zero-dependency. See the MCP Bridge docs for the full guide.

How ez-ptc compares to Anthropic's native PTC

Anthropic offers first-party programmatic tool calling through their API. It runs in a managed container and is tightly integrated with the Claude model.

ez-ptc takes a different approach:

• Any LLM provider -- works with OpenAI, Anthropic, Google, Groq, or any API. Anthropic's native PTC is Claude-only.
• Any framework -- integrates with LangChain, Pydantic AI, LiteLLM, or plain HTTP calls. No vendor lock-in.
• Zero dependencies -- pure Python, no managed containers, no external services. Runs entirely in your process.
• Full sandbox control -- you configure the execution environment: allowed builtins, timeouts, and what the LLM can access.

If you are already using the Claude API and want a managed solution, Anthropic's native PTC is a good choice. If you want provider flexibility, local execution, or framework integration, ez-ptc fills that gap.

Key features

• Zero dependencies -- pure Python, bring your own LLM client
• Two modes -- prompt mode (framework-free) or tool mode (native integration)
• MCP Tool Bridge -- wrap any MCP server's tools and resources as native ez-ptc tools with Toolkit.from_mcp()
• Sandboxed execution -- restricted builtins, no file I/O, no networking, configurable timeout
• Tool chaining -- assist_tool_chaining=True documents return types so the LLM chains outputs correctly
• Parallel execution -- built-in parallel() helper lets LLMs run tools concurrently with a simple parallel((tool, arg), ...) pattern
• Async tool support -- async def tools auto-detected and handled transparently; no special LLM-side code needed

Documentation

Full documentation is available in the docs/ directory:

• Getting Started -- installation, first tool, first toolkit
• Concepts -- tools, toolkits, two modes, execution engine
• Prompt Mode -- framework-free integration
• Tool Mode -- native framework integration
• MCP Tool Bridge -- wrap MCP server tools/resources as ez-ptc tools
• Tool Chaining -- return type documentation for reliable chaining
• Framework Examples -- integration code for 7+ frameworks
• API Reference -- full API docs
• Security & Sandboxing -- execution environment details

Contributing

Contributions are welcome. See CONTRIBUTING.md for the full guide.

Quick setup:

git clone https://github.com/abhisheksatish/ez-ptc.git
cd ez-ptc
uv sync
uv run pytest tests/

Found a bug or have a feature request? Open an issue.

License

MIT