toolbridge

toolbridge is a developer-facing Python library for defining tools once with type-annotated Python functions and Pydantic v2 validation, then translating and running those tools across OpenAI, Anthropic, or Gemini. It gives agent loops a small canonical tool model, strict provider schemas, concurrent tool execution, streaming argument reassembly, structured output retries, and explicit refusal handling without bringing in a larger orchestration framework.

Installation

pip install toolbridge

Provider clients are optional:

pip install "toolbridge[openai]"
pip install "toolbridge[anthropic]"
pip install "toolbridge[gemini]"

Minimal Example

from toolbridge import Agent, tool

@tool("Use when adding two numbers. Do not use for non-arithmetic tasks.")
def add(left: int, right: int) -> int:
    return left + right

provider = YourProvider()
agent = Agent(provider=provider, tools=[add])
run = agent.run("What is 2 + 3?")
print(run.output)

Provider Shape Comparison

Parallel Calls

When a model response contains multiple tool calls, toolbridge fans them out with ThreadPoolExecutor, then correlates results by tool call id before the next model turn.

model response
  |-- call id=a -> tool A --\
  |-- call id=b -> tool B ----> {a: result_a, b: result_b, c: result_c}
  |-- call id=c -> tool C --/
                         next model turn

Refusal Handling

Structured output accepts a Pydantic BaseModel. Parse errors and schema violations retry up to three times with the typed error injected for the next attempt. Refusals return immediately as Refusal.

from pydantic import BaseModel
from toolbridge import Agent, Refusal

class Answer(BaseModel):
    value: int

agent = Agent(provider=provider, tools=[], output_schema=Answer)
result = agent.run("Return a number")

if isinstance(result.output, Refusal):
    print(result.output.reason)
else:
    print(result.output.value)

Provider API Key Demo

The repository includes a simple smoke-test app at examples/provider_demo.py. It defines two tools once with @tool, translates them to the selected provider's tool schema, asks the model to call tools, executes returned calls in parallel, and prints correlated results by tool call id.

Install the package and provider extras:

python3 -m pip install -e ".[openai]"
python3 -m pip install -e ".[anthropic]"
python3 -m pip install -e ".[gemini]"

Run with OpenAI:

export OPENAI_API_KEY="sk-..."
python3 examples/provider_demo.py --provider openai

Run with Anthropic:

export ANTHROPIC_API_KEY="sk-ant-..."
python3 examples/provider_demo.py --provider anthropic

Run with Gemini:

export GEMINI_API_KEY="..."
python3 examples/provider_demo.py --provider gemini

Optional model overrides:

export OPENAI_MODEL="gpt-4o-mini"
export ANTHROPIC_MODEL="claude-3-5-haiku-latest"
export GEMINI_MODEL="gemini-1.5-flash"

Deploying to PyPI

1. Create PyPI and TestPyPI API tokens.
2. Install release tools:

python3 -m pip install --upgrade build twine

3. Build the package:

python3 -m build

4. Check the artifacts:

python3 -m twine check dist/*

5. Rehearse on TestPyPI:

python3 -m twine upload --repository testpypi dist/*

6. Install from TestPyPI in a clean environment:

python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ toolbridge

7. Publish to PyPI:

python3 -m twine upload dist/*

Use __token__ as the username when twine prompts for credentials, and paste the API token as the password. Before publishing, make sure pyproject.toml has the intended version and that dist/ only contains artifacts for that version.