Skip to content

Examples

Complete, copy-pasteable examples for common use cases.

Basic Library Usage

Calculator

from toolregistry_hub import Calculator

Calculator.evaluate("sqrt(144) + 2**3")          # 20.0
Calculator.evaluate("log(100, 10) + sin(pi/2)")  # 3.0
Calculator.list_allowed_fns()                     # list every supported function
Calculator.help("log")                            # help for one function

Date & Time

from toolregistry_hub import DateTime

DateTime.now()                                                   # current time (UTC)
DateTime.now("Asia/Shanghai")                                    # current time in Shanghai
DateTime.convert_timezone("14:30", "America/Chicago", "Asia/Tokyo")  # timezone conversion

File Operations

from toolregistry_hub import FileOps, FileReader, FileSearch, PathInfo

# Search
FileSearch.grep(r"TODO", path="src/")
FileSearch.tree("src/", max_depth=2)
py_files = FileSearch.glob("**/*.py", path="src/")

# Read
content = FileReader.read("config.py", limit=20)

# Edit (safe string replacement)
diff = FileOps.edit("config.py",
                    old_string="DEBUG = True",
                    new_string="DEBUG = False")
print(diff)

# Metadata
info = PathInfo.info("/path/to/file")

Web Search (multiple engines)

from toolregistry_hub import Fetch
from toolregistry_hub.websearch import WebSearch

# Fetch a page
Fetch().fetch_content("https://example.com")

# Unified search — picks whichever engine is configured
ws = WebSearch()
results = ws.search("Python 3.12 new features", max_results=3)
for r in results:
    print(f"{r.title}: {r.url}")

Choosing an engine

from toolregistry_hub.websearch import BraveSearch, TavilySearch

brave = BraveSearch()          # needs BRAVE_API_KEY
tavily = TavilySearch()        # needs TAVILY_API_KEY

results = brave.search("MCP protocol", max_results=5)

The environment variable each engine needs is listed in the environment reference.

Server Deployment

OpenAPI mode

pip install toolregistry-hub[server]

# Start — every tool is loaded by default
toolregistry-hub openapi --port 8000
# → Swagger UI: http://localhost:8000/docs

# Client call
import requests

resp = requests.post("http://localhost:8000/call/Calculator/evaluate",
                     json={"expression": "2**10"})
print(resp.json())  # {"result": 1024}

MCP mode

# stdio transport (for AI agents)
toolregistry-hub mcp

# SSE transport
toolregistry-hub mcp --transport sse --port 8080

Docker Quick Start

docker run -d \
  -p 8000:8000 \
  -e API_BEARER_TOKEN=my-secret \
  oaklight/toolregistry-hub:latest \
  openapi --host 0.0.0.0

# Verify
curl -H "Authorization: Bearer my-secret" \
     http://localhost:8000/call/Calculator/evaluate \
     -d '{"expression": "1+1"}'

Registering Custom Tools

Register your own tool classes through tools.jsonc:

// tools.jsonc
{
  "tools": [
    {
      "module": "my_tools.weather",
      "class": "WeatherTool"
    }
  ]
}

# my_tools/weather.py
class WeatherTool:
    @staticmethod
    def get_weather(city: str) -> str:
        """Get the weather for a city"""
        return f"{city}: sunny, 25°C"

toolregistry-hub openapi --tools-config tools.jsonc --port 8000
# WeatherTool is now available through the API

Using the Hub in an AI Agent

Combine the ToolRegistry core library with the hub tools:

from toolregistry import ToolRegistry
from toolregistry_hub import Calculator, DateTime

registry = ToolRegistry()
registry.register_from_class(Calculator)
registry.register_from_class(DateTime)

# Export in OpenAI function-calling format
tools_schema = registry.get_tools_json()

More