ToolRegistry¶

from toolregistry import ToolRegistry

registry = ToolRegistry()

# 注册一个简单函数
def add_numbers(a: int, b: int) -> int:
    return a + b

registry.register(add_numbers)

from toolregistry import ToolRegistry

registry = ToolRegistry()

class Calculator:
    @staticmethod
    def multiply(a: int, b: int) -> int:
        return a * b

    def divide(self, a: int, b: int) -> float:
        return a / b

# 注册类中的所有方法
registry.register_from_class(Calculator)

from toolregistry import ToolRegistry

class BaseCalculator:
    @staticmethod
    def add(a: int, b: int) -> int:
        return a + b

class AdvancedCalculator(BaseCalculator):
    @staticmethod
    def multiply(a: int, b: int) -> int:
        return a * b

registry = ToolRegistry()

# 默认行为（traverse_mro=True）：包含从 BaseCalculator 继承的方法
registry.register_from_class(AdvancedCalculator)
print(registry.get_available_tools())
# 输出：['advanced_calculator-add', 'advanced_calculator-multiply']

# 使用 traverse_mro=False：仅注册直接定义在 AdvancedCalculator 上的方法
registry2 = ToolRegistry()
registry2.register_from_class(AdvancedCalculator, traverse_mro=False)
print(registry2.get_available_tools())
# 输出：['advanced_calculator-multiply']

from toolregistry import ToolRegistry

registry = ToolRegistry()

# 使用自定义命名空间注册
registry.register(my_function, namespace="math_utils")

# 使用命名空间访问工具
available_tools = registry.get_available_tools(namespace="math_utils")

from toolregistry import ToolRegistry, ChangeEvent, ChangeEventType

registry = ToolRegistry()

def my_callback(event: ChangeEvent) -> None:
    """处理工具注册表变更。"""
    print(f"[{event.event_type.value}] {event.tool_name}")
    if event.reason:
        print(f"  原因：{event.reason}")

# 注册回调
registry.on_change(my_callback)

# 变更将触发回调
def add(a: int, b: int) -> int:
    return a + b

registry.register(add)  # 触发：[register] add
registry.disable("add", reason="维护中")  # 触发：[disable] add
registry.enable("add")  # 触发：[enable] add

# 不再需要时移除回调
registry.remove_on_change(my_callback)

from toolregistry import ToolRegistry

registry = ToolRegistry()

def add(a: int, b: int) -> int:
    return a + b

def subtract(a: int, b: int) -> int:
    return a - b

registry.register(add)
registry.register(subtract)

# 禁用一个工具并提供原因
registry.disable("subtract", reason="维护中")

# 获取所有工具的状态
status = registry.get_tools_status()
print(status)
# 输出：
# [
#     {"name": "add", "enabled": True, "reason": None, "namespace": None},
#     {"name": "subtract", "enabled": False, "reason": "维护中", "namespace": None}
# ]

# 筛选出已禁用的工具
disabled_tools = [s for s in status if not s["enabled"]]
print(disabled_tools)
# 输出：[{"name": "subtract", "enabled": False, "reason": "维护中", "namespace": None}]

from toolregistry import ToolRegistry, ToolMetadata, ToolTag

registry = ToolRegistry()

def read_file(path: str) -> str:
    """从磁盘读取文件。"""
    ...

def delete_file(path: str) -> None:
    """从磁盘删除文件。"""
    ...

def send_email(to: str, body: str) -> None:
    """发送电子邮件。"""
    ...

registry.register(read_file, metadata=ToolMetadata(tags={ToolTag.FILE_SYSTEM, ToolTag.READ_ONLY}))
registry.register(delete_file, metadata=ToolMetadata(tags={ToolTag.FILE_SYSTEM, ToolTag.DESTRUCTIVE}))
registry.register(send_email, metadata=ToolMetadata(tags={ToolTag.NETWORK}))

# match="any"（默认）：工具拥有至少一个指定标签即被禁用
disabled = registry.disable_by_tags(
    {ToolTag.DESTRUCTIVE, ToolTag.NETWORK},
    match="any",
    reason="只读模式下限制访问",
)
print(disabled)  # ['delete_file', 'send_email']

# match="all"：工具携带全部指定标签才被禁用
registry2 = ToolRegistry()
registry2.register(read_file, metadata=ToolMetadata(tags={ToolTag.FILE_SYSTEM, ToolTag.READ_ONLY}))
registry2.register(delete_file, metadata=ToolMetadata(tags={ToolTag.FILE_SYSTEM, ToolTag.DESTRUCTIVE}))

disabled2 = registry2.disable_by_tags(
    {ToolTag.FILE_SYSTEM, ToolTag.DESTRUCTIVE},
    match="all",
    reason="不允许破坏性文件系统操作",
)
print(disabled2)  # ['delete_file']

from toolregistry import ToolRegistry, PostRegisterHook, ToolMetadata, ToolTag

registry = ToolRegistry()

# 钩子：在注册时自动禁用所有特权工具
def deny_privileged(tool_name: str, tool, registry) -> str | None:
    tags = tool.metadata.tags if tool.metadata else set()
    if ToolTag.PRIVILEGED in tags:
        return f"当前环境不允许特权工具 '{tool_name}'"
    return None

registry.add_post_register_hook(deny_privileged)

def sudo_command(cmd: str) -> str:
    """以提升的权限运行命令。"""
    ...

registry.register(sudo_command, metadata=ToolMetadata(tags={ToolTag.PRIVILEGED}))

print(registry.is_enabled("sudo_command"))     # False
print(registry.get_disable_reason("sudo_command"))
# "当前环境不允许特权工具 'sudo_command'"

# 可以注册多个钩子，按注册顺序依次调用
def log_all(tool_name: str, tool, registry) -> None:
    print(f"[钩子] 已注册：{tool_name}")

registry.add_post_register_hook(log_all)