Metadata-Version: 2.4
Name: toolregistry
Version: 0.9.1
Summary: ToolRegistry: A Protocol-Agnostic Tool Management Library for Function-Calling LLMs (OpenAI, Anthropic, Gemini, LangChain, MCP)
Author-email: Oaklight <oaklight@gmx.com>
License-Expression: MIT
Project-URL: Documentation, https://toolregistry.readthedocs.io
Project-URL: Repository, https://github.com/Oaklight/ToolRegistry
Project-URL: Issues, https://github.com/Oaklight/ToolRegistry/issues
Keywords: llm,tool-calling,function-calling,ai-agents,openai,anthropic,gemini,mcp,openapi,langchain,tool-use,agentic-ai
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.7.2
Requires-Dist: cloudpickle>=3.0.0
Requires-Dist: llm-rosetta<0.6.0,>=0.5.1
Provides-Extra: mcp
Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
Requires-Dist: httpx>=0.28.1; extra == "mcp"
Provides-Extra: openapi
Provides-Extra: langchain
Requires-Dist: langchain-core<0.4,>=0.3; extra == "langchain"
Requires-Dist: langchain-community<0.4,>=0.3; extra == "langchain"
Provides-Extra: dev
Requires-Dist: python-dotenv>=1.0.1; extra == "dev"
Requires-Dist: openai>=1.79.0; extra == "dev"
Requires-Dist: fastapi>=0.115.12; extra == "dev"
Requires-Dist: ty>=0.0.21; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Requires-Dist: deprecated>=1.2.18; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: coverage>=7.0.0; extra == "test"
Dynamic: license-file

# ToolRegistry

[![PyPI version](https://img.shields.io/pypi/v/toolregistry?color=green)](https://pypi.org/project/toolregistry/)
[![GitHub release](https://img.shields.io/github/v/release/Oaklight/ToolRegistry?color=green)](https://github.com/Oaklight/ToolRegistry/releases/latest)
[![CI](https://github.com/Oaklight/ToolRegistry/actions/workflows/ci.yml/badge.svg)](https://github.com/Oaklight/ToolRegistry/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Oaklight/toolregistry)

[English Version](README_en.md) | [中文版](README_zh.md)

A protocol-agnostic tool management library for function-calling LLMs.

**[Documentation](https://toolregistry.readthedocs.io)** · **[arXiv Paper](https://arxiv.org/abs/2507.10593)**

## Ecosystem

| Package | Description | PyPI | Docs |
|---------|-------------|------|------|
| **toolregistry** | Core library — tool registration, schema generation, execution | [![PyPI](https://img.shields.io/pypi/v/toolregistry?color=green)](https://pypi.org/project/toolregistry/) | [Docs](https://toolregistry.readthedocs.io/) |
| **toolregistry-server** | Server adapters — expose tools via OpenAPI & MCP | [![PyPI](https://img.shields.io/pypi/v/toolregistry-server?color=green)](https://pypi.org/project/toolregistry-server/) | [Docs](https://toolregistry-server.readthedocs.io/) |
| **toolregistry-hub** | Ready-to-use tools — calculator, web search, file ops, etc. | [![PyPI](https://img.shields.io/pypi/v/toolregistry-hub?color=green)](https://pypi.org/project/toolregistry-hub/) | [Docs](https://toolregistry-hub.readthedocs.io/) |

```mermaid
graph LR
    Hub["toolregistry-hub<br/><i>Ready-to-use tool implementations</i>"]
    Server["toolregistry-server<br/><i>OpenAPI & MCP protocol adapters</i>"]
    Core["toolregistry<br/><i>Tool registration, schema generation, execution</i>"]

    Hub --> Server --> Core
```

## Features

- **Protocol-agnostic** — register tools from native Python functions/classes, MCP servers, OpenAPI specs, or LangChain tools through a unified interface
- **Multi-provider schemas** — generate tool schemas for OpenAI, Anthropic, and Gemini via [llm-rosetta](https://github.com/Oaklight/llm-rosetta)
- **Concurrent execution** — thread and process pool backends with per-tool timeout and concurrency control
- **Permission system** — tag-based policies (`READ_ONLY`, `DESTRUCTIVE`, `NETWORK`, etc.) with allow/deny/ask rules
- **Tool metadata & tags** — classify tools with `ToolTag`, `ToolMetadata`, namespace support, and source tracking
- **Admin panel** — built-in Web UI for monitoring tools, permissions, and runtime config (i18n: EN/ZH)
- **Think-augmented calling** — inject chain-of-thought reasoning into tool calls ([arXiv:2601.18282](https://arxiv.org/abs/2601.18282))
- **Declarative config** — load tool sources from JSONC/YAML config files
- **Zero-dependency core** — HTTP client, YAML parser, JSON Schema resolver all vendored; only `pydantic` and `llm-rosetta` as runtime deps

## Quick Start

```python
from toolregistry import ToolRegistry

registry = ToolRegistry()

@registry.register
def add(a: float, b: float) -> float:
    """Add two numbers together."""
    return a + b

# Use with any LLM provider
schemas = registry.get_schemas(api_format="openai-chat")  # or "anthropic", "gemini"
result = registry["add"](1, 2)  # 3.0
```

See the [Usage Guide](https://toolregistry.readthedocs.io/en/stable/usage/basics.html) for MCP, OpenAPI, LangChain integrations and more.

## Installation

Requires **Python >= 3.10**.

```bash
pip install toolregistry                   # core
pip install toolregistry[mcp]              # + MCP support
pip install toolregistry[langchain]        # + LangChain support
pip install toolregistry-hub               # ready-to-use tools (separate package)
```

## Citation

```bibtex
@software{toolregistry2025,
  title={ToolRegistry: A Protocol-Agnostic Tool Management Library for OpenAI-Compatible LLM Applications},
  author={Peng Ding},
  year={2025},
  url={https://github.com/Oaklight/ToolRegistry},
  note={A Python library for unified tool registration, execution, and management across multiple protocols in OpenAI-compatible LLM applications}
}

@article{ding2025toolregistry,
  title={ToolRegistry: A Protocol-Agnostic Tool Management Library for Function-Calling LLMs},
  author={Ding, Peng},
  journal={arXiv preprint arXiv:2507.10593},
  year={2025}
}
```

## License

MIT — see [LICENSE](LICENSE) for details.
