Library Usage¶

ToolRegistry Hub is first and foremost a Python library. Every tool can be imported and called directly in your code — no server, no HTTP, no configuration files. This is the simplest and most flexible way to use the hub.

Library vs Server

	Library	Server
Install	`pip install toolregistry-hub`	`pip install toolregistry-hub[server]`
Usage	`from toolregistry_hub import ...`	`toolregistry-hub openapi`
Best for	Scripts, notebooks, AI agents, embedding in your app	Remote access, multi-client, MCP integration
Latency	Direct function call	HTTP / stdio round-trip
Dependencies	Minimal (mostly stdlib)	FastAPI, uvicorn, or MCP SDK

Installation¶

pip install toolregistry-hub

That's it. No server dependencies, no extra configuration.

Quick Start¶

from toolregistry_hub import Calculator, DateTime, BashTool

# Evaluate a math expression
result = Calculator.evaluate("sqrt(144) + 2**3")
print(result)  # 20.0

# Get current time in a timezone
now = DateTime.now("Asia/Shanghai")
print(now)  # 2026-04-01T12:34:56+08:00

# Run a shell command (with built-in safety checks)
output = BashTool.execute("ls -la", timeout=10)
print(output["stdout"])

Most tool classes use static methods — no instantiation needed, no state to manage. Some tools like Fetch, WebSearch, and search providers are instance-based for configuration flexibility.

Available Tools¶

Calculation & Conversion¶

from toolregistry_hub import Calculator, UnitConverter

# Calculator — evaluate expressions with built-in math functions
Calculator.evaluate("log(100, 10) + sin(pi/2)")  # 3.0
Calculator.list_allowed_fns()  # list all available functions
Calculator.help("log")  # get help on a specific function

# UnitConverter — convert between units
UnitConverter.convert(100, "celsius_to_fahrenheit")  # 212.0
UnitConverter.list_conversions(category="temperature")

Date & Time¶

from toolregistry_hub import DateTime

# Current time (default: UTC)
DateTime.now()

# Current time in a specific timezone
DateTime.now("America/New_York")

# Convert between timezones
DateTime.convert_timezone("14:30", "America/Chicago", "Asia/Tokyo")

File Operations¶

from toolregistry_hub import FileOps, FileReader, FileSearch, PathInfo

# Edit a file with exact string replacement
diff = FileOps.edit("config.py", old_string="DEBUG = True", new_string="DEBUG = False")
print(diff)  # unified diff output

# Read a file with line numbers
content = FileReader.read("src/main.py", limit=50)

# Read a Jupyter notebook
nb = FileReader.read_notebook("analysis.ipynb")

# Search for files
py_files = FileSearch.glob("**/*.py", path="src/")
matches = FileSearch.grep(r"def test_", path="tests/")
tree = FileSearch.tree("src/", max_depth=3)

# Get file metadata in one call
info = PathInfo.info("/path/to/file")
# → {exists, type, size, last_modified, permissions}

Shell Execution¶

from toolregistry_hub import BashTool

result = BashTool.execute("python --version", timeout=30, cwd="/my/project")
print(result)
# {
#     "stdout": "Python 3.11.5\n",
#     "stderr": "",
#     "exit_code": 0,
#     "timed_out": False
# }

BashTool has a built-in deny list that blocks dangerous commands (rm -rf /, sudo, fork bombs, etc.). See the Bash Tool page for the full security model.

Web Search & Fetch¶

from toolregistry_hub import Fetch, BraveSearch, TavilySearch
from toolregistry_hub.websearch import WebSearch

# Fetch and extract content from a URL
content = Fetch().fetch_content("https://example.com")

# Fetch with Jina Reader API key (optional, for authenticated access)
fetcher = Fetch(api_keys=["jina_key1", "jina_key2"])
content = fetcher.fetch_content("https://example.com")

# Unified web search — auto-selects the best available engine
ws = WebSearch()
results = ws.search("Python 3.12 new features", max_results=5)
for r in results:
    print(f"{r.title}: {r.url}")

# Specify a particular engine
results = ws.search("Python async", engine="brave", max_results=5)

# List available engines and their configuration status
engines = ws.list_engines()

# Direct engine usage (requires API keys via environment variables)
results = BraveSearch().search("Python 3.12 new features", max_results=5)
for r in results:
    print(f"{r.title}: {r.url}")

Scheduling¶

from toolregistry_hub import CronTool

# Schedule a recurring prompt (every 5 minutes)
job = CronTool.create(cron="*/5 * * * *", prompt="Check server health")

# Schedule a one-shot reminder
job = CronTool.create(
    cron="30 14 28 4 *",
    prompt="Deploy release to staging",
    recurring=False,
)

# List and manage scheduled jobs
jobs = CronTool.list()
CronTool.delete(job_id="abc123")

Cognitive Tools¶

from toolregistry_hub import ThinkTool, TodoList

# Structured thinking (useful as an LLM tool)
ThinkTool.think(
    thinking_mode="planning",
    focus_area="database migration",
    thought_process="We need to migrate from SQLite to PostgreSQL..."
)

# Task management
TodoList.update([
    "[db-migrate] Plan schema changes (planned)",
    "[db-migrate] Write migration script (in-progress)",
])

Use in AI Agents¶

The library shines when embedded in AI agent pipelines. Since every tool is a plain Python class with static methods, you can register them with any agent framework:

from toolregistry import ToolRegistry
from toolregistry_hub import Calculator, FileOps, BashTool, FileSearch

# Build a registry with selected tools
registry = ToolRegistry()
registry.register_static_tools(Calculator, namespace="calculator")
registry.register_static_tools(FileOps, namespace="file_ops")
registry.register_static_tools(BashTool, namespace="bash")
registry.register_static_tools(FileSearch, namespace="file_search")

# Generate tool schemas for your LLM
tools_json = registry.get_tools_json(format="openai")

Or use the hub's built-in registry that loads all tools at once:

from toolregistry_hub.server.registry import get_registry

registry = get_registry()  # all tools registered and ready

Environment Variables¶

Some tools require API keys to function. Set them as environment variables or use a .env file:

Variable	Tool	Required
`BRAVE_API_KEY`	BraveSearch	For Brave search
`TAVILY_API_KEY`	TavilySearch	For Tavily search
`SERPER_API_KEY`	SerperSearch	For Serper search
`BRIGHTDATA_API_KEY`	BrightDataSearch	For BrightData search
`SCRAPELESS_API_KEY`	ScrapelessSearch	For Scrapeless search
`SEARXNG_URL`	SearXNGSearch	For self-hosted SearXNG
`JINA_API_KEY`	Fetch (Jina Reader)	Optional, for authenticated Jina Reader access (comma-separated for multi-key rotation)
`CDP_ENDPOINT`	Fetch (CDP Rendering)	Optional, WebSocket URL of a CDP-compatible browser for self-hosted SPA rendering (e.g., `ws://localhost:9222`)
`WEBSEARCH_PRIORITY`	WebSearch (auto mode)	Comma-separated engine priority (e.g., `searxng,brave,tavily`)

Tools without API key requirements (Calculator, DateTime, FileOps, BashTool, etc.) work out of the box with zero configuration.