Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /dislovelhl_enhanced-agent-bus /tool_documentation.py
"""
Model-First Tool Documentation System for ACGS-2.
Implements Anthropic's best practice of designing tool interfaces from
the model's perspective. Provides structured documentation that helps
AI agents understand when and how to use tools effectively.
Constitutional Hash: 608508a9bd224290
"""
import json
from collections.abc import Callable
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, TypeAlias, TypedDict, TypeVar, Unpack, cast
try:
from enhanced_agent_bus._compat.types import JSONDict as ImportedJSONDict
from enhanced_agent_bus._compat.types import JSONList as ImportedJSONList
except ImportError:
ImportedJSONDict = dict[str, Any]
ImportedJSONList = list[Any]
JSONDict: TypeAlias = ImportedJSONDict
JSONList: TypeAlias = ImportedJSONList
from enhanced_agent_bus.observability.structured_logging import get_logger
from enhanced_agent_bus.schema_safety import (
sanitize_schema_fragment,
sanitize_tool_input_schema,
)
logger = get_logger(__name__)
ToolHandlerFunc = Callable[..., object]
F = TypeVar("F", bound=ToolHandlerFunc)
# Constitutional compliance
try:
from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH
except ImportError:
CONSTITUTIONAL_HASH = "standalone"
__all__ = [
"AGENT_TOOLS",
"CONSTITUTIONAL_HASH",
"CONSTITUTIONAL_TOOLS",
"GOVERNANCE_TOOLS",
"ToolCategory",
"ToolDefinition",
"ToolExample",
"ToolParameter",
"ToolRegistry",
"create_tool_registry",
"tool",
]
class ToolCategory(Enum):
"""Categories for organizing tools."""
CONSTITUTIONAL = "constitutional"
GOVERNANCE = "governance"
AGENT = "agent"
MEMORY = "memory"
RESEARCH = "research"
WORKFLOW = "workflow"
UTILITY = "utility"
AUTOMATION = "automation"
@dataclass
class ToolParameter:
"""
Tool parameter definition with rich documentation.
Follows model-first design: describe parameters the way an AI would understand them.
"""
name: str
type: str
description: str
required: bool = True
default: object | None = None
enum_values: list[str] | None = None
examples: JSONList = field(default_factory=list)
constraints: str | None = None
def to_dict(self) -> JSONDict:
"""Convert to dictionary for schema generation."""
result = {
"name": self.name,
"type": self.type,
"description": self.description,
"required": self.required,
}
if self.default is not None:
result["default"] = self.default
if self.enum_values:
result["enum"] = self.enum_values
if self.examples:
result["examples"] = self.examples
if self.constraints:
result["constraints"] = self.constraints
return result
def to_json_schema(self) -> JSONDict:
"""Convert to JSON Schema format."""
schema: JSONDict = {
"description": self.description,
}
# Map Python types to JSON Schema types
type_mapping = {
"str": "string",
"string": "string",
"int": "integer",
"integer": "integer",
"float": "number",
"number": "number",
"bool": "boolean",
"boolean": "boolean",
"list": "array",
"array": "array",
"dict": "object",
"object": "object",
"any": None,
}
mapped_type = type_mapping.get(self.type.lower(), "string")
if mapped_type is not None:
schema["type"] = mapped_type
if self.enum_values:
schema["enum"] = self.enum_values
if self.default is not None:
schema["default"] = self.default
if self.examples:
schema["examples"] = self.examples
return sanitize_schema_fragment(schema)
@dataclass
class ToolExample:
"""
Example usage of a tool.
Shows input/output pairs to help models understand expected behavior.
"""
description: str
input: JSONDict
output: object
notes: str | None = None
def to_dict(self) -> JSONDict:
"""Convert to dictionary."""
result = {
"description": self.description,
"input": self.input,
"output": self.output,
}
if self.notes:
result["notes"] = self.notes
return result
@dataclass
class ToolDefinition:
"""
Complete tool definition with model-first documentation.
Structured to help AI agents:
1. Understand WHEN to use the tool
2. Know WHAT to expect as output
3. Handle EDGE CASES appropriately
4. Avoid COMMON MISTAKES
"""
name: str
description: str
category: ToolCategory
# When to use/not use
use_when: list[str] = field(default_factory=list)
do_not_use_for: list[str] = field(default_factory=list)
# Parameters
parameters: list[ToolParameter] = field(default_factory=list)
# Output documentation
returns: str = ""
return_type: str = "any"
# Examples
examples: list[ToolExample] = field(default_factory=list)
# Edge cases and errors
edge_cases: list[str] = field(default_factory=list)
common_errors: dict[str, str] = field(default_factory=dict)
# Relationships
related_tools: list[str] = field(default_factory=list)
prerequisites: list[str] = field(default_factory=list)
# Metadata
version: str = "1.0.0"
constitutional_hash: str = CONSTITUTIONAL_HASH
handler: ToolHandlerFunc | None = None
def to_dict(self) -> JSONDict:
"""Convert to dictionary for serialization."""
return {
"name": self.name,
"description": self.description,
"category": self.category.value,
"use_when": self.use_when,
"do_not_use_for": self.do_not_use_for,
"parameters": [p.to_dict() for p in self.parameters],
"returns": self.returns,
"return_type": self.return_type,
"examples": [e.to_dict() for e in self.examples],
"edge_cases": self.edge_cases,
"common_errors": self.common_errors,
"related_tools": self.related_tools,
"prerequisites": self.prerequisites,
"version": self.version,
"constitutional_hash": self.constitutional_hash,
}
def to_prompt_format(self) -> str:
"""
Format tool definition for inclusion in prompts.
This is the key model-first format that helps AI agents understand the tool.
"""
lines = [
f"### {self.name}",
"",
self.description,
"",
]
# When to use
if self.use_when:
lines.append("**USE THIS WHEN:**")
for item in self.use_when:
lines.append(f"- {item}")
lines.append("")
# When NOT to use
if self.do_not_use_for:
lines.append("**DO NOT USE FOR:**")
for item in self.do_not_use_for:
lines.append(f"- {item}")
lines.append("")
# Parameters
if self.parameters:
lines.append("**PARAMETERS:**")
for param in self.parameters:
required = "(required)" if param.required else "(optional)"
lines.append(f"- `{param.name}` ({param.type}) {required}: {param.description}")
if param.constraints:
lines.append(f" - Constraints: {param.constraints}")
if param.examples:
lines.append(f" - Examples: {', '.join(str(e) for e in param.examples)}")
lines.append("")
# Returns
if self.returns:
lines.append("**RETURNS:**")
lines.append(self.returns)
lines.append("")
# Examples
if self.examples:
lines.append("**EXAMPLES:**")
for example in self.examples:
lines.append(f"- {example.description}")
lines.append(f" Input: `{json.dumps(example.input)}`")
lines.append(f" Output: `{json.dumps(example.output)}`")
if example.notes:
lines.append(f" Note: {example.notes}")
lines.append("")
# Edge cases
if self.edge_cases:
lines.append("**EDGE CASES:**")
for case in self.edge_cases:
lines.append(f"- {case}")
lines.append("")
# Common errors
if self.common_errors:
lines.append("**COMMON ERRORS:**")
for error, solution in self.common_errors.items():
lines.append(f"- `{error}`: {solution}")
lines.append("")
# Related tools
if self.related_tools:
lines.append(f"**RELATED:** {', '.join(self.related_tools)}")
return "\n".join(lines)
def to_openai_schema(self) -> JSONDict:
"""Generate OpenAI-compatible function schema."""
properties = {}
required = []
for param in self.parameters:
properties[param.name] = param.to_json_schema()
if param.required:
required.append(param.name)
return {
"name": self.name,
"description": self.description,
"parameters": sanitize_tool_input_schema(
{
"type": "object",
"properties": properties,
"required": required,
}
),
}
def to_anthropic_schema(self) -> JSONDict:
"""Generate Anthropic-compatible tool schema."""
input_schema = sanitize_tool_input_schema(
{
"type": "object",
"properties": {},
"required": [],
}
)
for param in self.parameters:
properties = cast(JSONDict, input_schema["properties"])
properties[param.name] = param.to_json_schema()
if param.required:
required = cast(list[str], input_schema["required"])
required.append(param.name)
return {
"name": self.name,
"description": self._build_rich_description(),
"input_schema": sanitize_tool_input_schema(input_schema),
}
def _build_rich_description(self) -> str:
"""Build rich description for Anthropic tool format."""
parts = [self.description]
if self.use_when:
parts.append("\n\nUSE THIS WHEN:")
parts.extend(f"\n- {item}" for item in self.use_when)
if self.do_not_use_for:
parts.append("\n\nDO NOT USE FOR:")
parts.extend(f"\n- {item}" for item in self.do_not_use_for)
if self.returns:
parts.append(f"\n\nRETURNS:\n{self.returns}")
if self.edge_cases:
parts.append("\n\nEDGE CASES:")
parts.extend(f"\n- {case}" for case in self.edge_cases)
return "".join(parts)
class ToolRegistry:
"""
Registry for tool definitions.
Provides centralized management and retrieval of tool documentation.
"""
def __init__(self, constitutional_hash: str = CONSTITUTIONAL_HASH):
self._tools: dict[str, ToolDefinition] = {}
self._constitutional_hash = constitutional_hash
self._categories: dict[ToolCategory, list[str]] = {cat: [] for cat in ToolCategory}
def register(self, tool: ToolDefinition) -> None:
"""Register a tool definition."""
tool.constitutional_hash = self._constitutional_hash
self._tools[tool.name] = tool
self._categories[tool.category].append(tool.name)
logger.debug(f"Registered tool: {tool.name} in category {tool.category.value}")
def get(self, name: str) -> ToolDefinition | None:
"""Get a tool by name."""
return self._tools.get(name)
def get_by_category(self, category: ToolCategory) -> list[ToolDefinition]:
"""Get all tools in a category."""
return [self._tools[name] for name in self._categories[category] if name in self._tools]
def list_tools(self) -> list[str]:
"""List all registered tool names."""
return list(self._tools.keys())
def get_all_by_category(self) -> dict[str, list[ToolDefinition]]:
"""Get all tool definitions grouped by category."""
return {
cat.value: [self._tools[name] for name in names]
for cat, names in self._categories.items()
}
def get_all(self) -> list[ToolDefinition]:
"""Get all tool definitions."""
return list(self._tools.values())
def to_prompt_format(self, category: ToolCategory | None = None) -> str:
"""Generate prompt-format documentation for tools."""
if category:
tools = self.get_by_category(category)
else:
tools = self.get_all()
return "\n\n---\n\n".join(tool.to_prompt_format() for tool in tools)
def to_openai_schemas(self) -> list[JSONDict]:
"""Generate OpenAI-compatible schemas for all tools."""
return [tool.to_openai_schema() for tool in self._tools.values()]
def to_anthropic_schemas(self) -> list[JSONDict]:
"""Generate Anthropic-compatible schemas for all tools."""
return [tool.to_anthropic_schema() for tool in self._tools.values()]
def find_related(self, tool_name: str) -> list[ToolDefinition]:
"""Find tools related to the given tool."""
tool = self.get(tool_name)
if not tool:
return []
related = []
for related_name in tool.related_tools:
related_tool = self.get(related_name)
if related_tool:
related.append(related_tool)
return related
def get_stats(self) -> JSONDict:
"""Get registry statistics."""
return {
"total_tools": len(self._tools),
"by_category": {cat.value: len(names) for cat, names in self._categories.items()},
"constitutional_hash": self._constitutional_hash,
}
class ToolDecoratorOptions(TypedDict, total=False):
return_type: str
examples: list[ToolExample]
edge_cases: list[str]
common_errors: dict[str, str]
related_tools: list[str]
prerequisites: list[str]
version: str
def tool(
name: str,
description: str,
category: ToolCategory = ToolCategory.UTILITY,
use_when: list[str] | None = None,
do_not_use_for: list[str] | None = None,
returns: str = "",
**kwargs: Unpack[ToolDecoratorOptions],
) -> Callable[[F], F]:
"""
Decorator to create a documented tool from a function.
Usage:
@tool(
name="my_tool",
description="Does something useful",
category=ToolCategory.UTILITY,
use_when=["You need to do X"],
)
async def my_tool(arg1: str, arg2: int = 10):
return result
"""
def decorator(func: F) -> F:
# Extract parameters from function signature
import inspect
sig = inspect.signature(func)
parameters = []
for param_name, param in sig.parameters.items():
if param_name in ("self", "cls"):
continue
param_type = "any"
if param.annotation != inspect.Parameter.empty:
param_type = getattr(param.annotation, "__name__", str(param.annotation))
required = param.default == inspect.Parameter.empty
default = None if required else param.default
parameters.append(
ToolParameter(
name=param_name,
type=param_type,
description=f"Parameter: {param_name}",
required=required,
default=default,
)
)
tool_def = ToolDefinition(
name=name,
description=description,
category=category,
use_when=use_when or [],
do_not_use_for=do_not_use_for or [],
parameters=parameters,
returns=returns,
handler=func,
**kwargs,
)
func._tool_definition = tool_def # type: ignore[attr-defined]
return func
return decorator
def create_tool_registry(
constitutional_hash: str = CONSTITUTIONAL_HASH,
include_defaults: bool = True,
) -> ToolRegistry:
"""
Factory function to create a tool registry.
Args:
constitutional_hash: Constitutional hash for compliance
include_defaults: Whether to include default ACGS-2 tools
Returns:
Configured ToolRegistry
"""
registry = ToolRegistry(constitutional_hash)
if include_defaults:
for tool_def in CONSTITUTIONAL_TOOLS + GOVERNANCE_TOOLS + AGENT_TOOLS + WUYING_TOOLS:
registry.register(tool_def)
return registry
# =============================================================================
# Pre-defined ACGS-2 Tool Definitions
# =============================================================================
CONSTITUTIONAL_TOOLS = [
ToolDefinition(
name="validate_constitutional_compliance",
description="Validates an action against the constitutional governance framework.",
category=ToolCategory.CONSTITUTIONAL,
use_when=[
"You need to check if an action complies with constitutional principles",
"Before executing any governance-impacting operation",
"When MACI role requires cross-validation",
],
do_not_use_for=[
"Read-only queries that don't modify governance state",
"Actions already validated in the current workflow",
],
parameters=[
ToolParameter(
name="action",
type="string",
description="The type of action to validate (e.g., 'modify_policy', 'approve_request')",
required=True,
examples=["modify_policy", "approve_request", "escalate_issue"],
),
ToolParameter(
name="context",
type="object",
description="Additional context for validation including resource IDs and metadata",
required=False,
default={},
),
ToolParameter(
name="strict_mode",
type="boolean",
description="Whether to use strict validation (rejects on any uncertainty)",
required=False,
default=True,
),
],
returns="""- is_compliant: boolean indicating compliance status
- violations: list of violated principles (if any)
- confidence: 0.0-1.0 confidence score
- hash_verified: whether constitutional hash matches
- recommendations: suggested remediation actions""",
return_type="object",
examples=[
ToolExample(
description="Validate a policy modification",
input={"action": "modify_policy", "context": {"policy_id": "POL-123"}},
output={
"is_compliant": True,
"violations": [],
"confidence": 0.98,
"hash_verified": True,
},
),
ToolExample(
description="Detect a violation",
input={"action": "delete_audit_log", "context": {}},
output={
"is_compliant": False,
"violations": ["IMMUTABILITY_PRINCIPLE"],
"confidence": 0.99,
"hash_verified": True,
},
notes="Audit logs cannot be deleted per constitutional principles",
),
],
edge_cases=[
"Empty action: Returns is_compliant=false with 'empty_action' violation",
"Invalid policy_id: Returns is_compliant=false with 'policy_not_found' violation",
"Network timeout: Raises ConstitutionalValidationTimeout (retry recommended)",
],
common_errors={
"InvalidActionError": "Ensure action is a valid string from the allowed actions list",
"HashMismatchError": "Constitutional hash mismatch - system integrity may be compromised",
},
related_tools=["get_constitutional_principles", "audit_action"],
),
ToolDefinition(
name="get_constitutional_principles",
description="Retrieves the current set of constitutional principles governing the system.",
category=ToolCategory.CONSTITUTIONAL,
use_when=[
"You need to understand what principles apply to a decision",
"Explaining why an action was approved or rejected",
"Building prompts that reference constitutional constraints",
],
do_not_use_for=[
"Modifying constitutional principles (use propose_amendment)",
"Checking specific action compliance (use validate_constitutional_compliance)",
],
parameters=[
ToolParameter(
name="category",
type="string",
description="Filter principles by category",
required=False,
enum_values=["safety", "ethics", "governance", "privacy", "all"],
default="all",
),
],
returns="List of constitutional principles with their IDs, descriptions, and severity levels",
return_type="array",
examples=[
ToolExample(
description="Get all principles",
input={"category": "all"},
output=[
{
"id": "PRIN-001",
"name": "Transparency",
"category": "ethics",
"severity": "high",
},
{
"id": "PRIN-002",
"name": "Immutability",
"category": "governance",
"severity": "critical",
},
],
),
],
edge_cases=[
"Unknown category: Returns empty list with warning",
],
related_tools=["validate_constitutional_compliance", "propose_amendment"],
),
]
GOVERNANCE_TOOLS = [
ToolDefinition(
name="create_governance_proposal",
description="Creates a new governance proposal for system changes that require approval.",
category=ToolCategory.GOVERNANCE,
use_when=[
"Proposing changes to system policies or configurations",
"Requesting approval for high-impact actions",
"Initiating multi-stakeholder decision processes",
],
do_not_use_for=[
"Minor configuration changes that don't require approval",
"Emergency actions (use emergency_action instead)",
"Read-only queries or status checks",
],
parameters=[
ToolParameter(
name="title",
type="string",
description="Short, descriptive title for the proposal",
required=True,
constraints="Max 100 characters",
examples=["Update Rate Limiting Policy", "Add New Agent Role"],
),
ToolParameter(
name="description",
type="string",
description="Detailed description of the proposed change and its rationale",
required=True,
constraints="Min 50 characters for adequate context",
),
ToolParameter(
name="impact_level",
type="string",
description="Expected impact level of the change",
required=True,
enum_values=["low", "medium", "high", "critical"],
),
ToolParameter(
name="changes",
type="object",
description="Specific changes to be made if approved",
required=True,
),
ToolParameter(
name="deadline",
type="string",
description="ISO 8601 datetime for voting deadline",
required=False,
examples=["2024-12-31T23:59:59Z"],
),
],
returns="""- proposal_id: Unique identifier for tracking
- status: Current status (pending, under_review, approved, rejected)
- required_approvals: Number of approvals needed
- current_approvals: Current approval count""",
return_type="object",
examples=[
ToolExample(
description="Create a policy update proposal",
input={
"title": "Increase API Rate Limit",
"description": "Propose increasing the API rate limit from 100 to 200 requests per minute to accommodate growth.",
"impact_level": "medium",
"changes": {"rate_limit": {"old": 100, "new": 200}},
},
output={
"proposal_id": "PROP-2024-001",
"status": "pending",
"required_approvals": 3,
"current_approvals": 0,
},
),
],
edge_cases=[
"Duplicate proposal: Returns existing proposal_id with warning",
"Invalid impact_level: Validation error with allowed values",
],
related_tools=["vote_on_proposal", "get_proposal_status", "cancel_proposal"],
),
ToolDefinition(
name="audit_action",
description="Records an action in the immutable audit log for compliance and traceability.",
category=ToolCategory.GOVERNANCE,
use_when=[
"After completing any governance action",
"Recording decisions and their rationale",
"Creating compliance trails for regulatory purposes",
],
do_not_use_for=[
"Temporary or debug logging (use standard logging)",
"High-frequency operational events (use metrics instead)",
],
parameters=[
ToolParameter(
name="action_type",
type="string",
description="Type of action being audited",
required=True,
examples=["policy_change", "access_grant", "approval", "rejection"],
),
ToolParameter(
name="actor_id",
type="string",
description="Identifier of the entity performing the action",
required=True,
),
ToolParameter(
name="details",
type="object",
description="Action details and context",
required=True,
),
ToolParameter(
name="outcome",
type="string",
description="Result of the action",
required=True,
enum_values=["success", "failure", "partial"],
),
],
returns="audit_id: Immutable identifier for the audit record",
return_type="string",
examples=[
ToolExample(
description="Audit a policy change",
input={
"action_type": "policy_change",
"actor_id": "agent-001",
"details": {
"policy_id": "POL-123",
"field": "rate_limit",
"old": 100,
"new": 200,
},
"outcome": "success",
},
output="AUDIT-2024-001234",
),
],
edge_cases=[
"Audit service unavailable: Queues action for retry, returns pending_audit_id",
],
related_tools=["query_audit_log", "export_audit_report"],
),
]
AGENT_TOOLS = [
ToolDefinition(
name="spawn_agent",
description="Spawns a new specialized agent in the swarm with specified capabilities.",
category=ToolCategory.AGENT,
use_when=[
"A task requires specialized capabilities not available in current agents",
"Workload demands additional parallel processing capacity",
"Specific domain expertise is needed for a subtask",
],
do_not_use_for=[
"Tasks that can be handled by existing agents",
"When at maximum agent capacity (check get_swarm_status first)",
"Short-lived, simple operations",
],
parameters=[
ToolParameter(
name="name",
type="string",
description="Human-readable name for the agent",
required=True,
constraints="Max 50 characters, alphanumeric and hyphens only",
examples=["code-analyzer", "research-specialist"],
),
ToolParameter(
name="capabilities",
type="array",
description="List of capabilities the agent should have",
required=True,
examples=[["CODE_ANALYSIS", "PATTERN_DETECTION"], ["RESEARCH", "SUMMARIZATION"]],
),
ToolParameter(
name="priority",
type="string",
description="Agent priority for resource allocation",
required=False,
enum_values=["low", "normal", "high", "critical"],
default="normal",
),
],
returns="""- agent_id: Unique identifier for the spawned agent
- status: Current agent status (initializing, ready, busy)
- capabilities: Confirmed list of capabilities""",
return_type="object",
examples=[
ToolExample(
description="Spawn a code analysis agent",
input={
"name": "code-analyzer-1",
"capabilities": ["CODE_ANALYSIS", "SECURITY_SCAN"],
"priority": "high",
},
output={
"agent_id": "agent-a1b2c3d4",
"status": "ready",
"capabilities": ["CODE_ANALYSIS", "SECURITY_SCAN"],
},
),
],
edge_cases=[
"Max agents reached: Returns error with suggestion to terminate idle agents",
"Invalid capability: Returns error with list of valid capabilities",
"Name conflict: Appends unique suffix automatically",
],
common_errors={
"MaxAgentsExceeded": "Terminate unused agents or wait for capacity",
"InvalidCapability": "Check VALID_CAPABILITIES for allowed values",
},
related_tools=["terminate_agent", "get_swarm_status", "assign_task"],
prerequisites=["get_swarm_status (recommended to check capacity)"],
),
ToolDefinition(
name="assign_task",
description="Assigns a task to an available agent based on capability matching.",
category=ToolCategory.AGENT,
use_when=[
"You have a specific task that needs to be executed by an agent",
"Delegating work to specialized agents in the swarm",
"Breaking down complex tasks into agent-executable units",
],
do_not_use_for=[
"Tasks that you can handle directly",
"When no suitable agents are available (spawn one first)",
"Extremely time-sensitive operations (may have queue delay)",
],
parameters=[
ToolParameter(
name="description",
type="string",
description="Clear description of what the task requires",
required=True,
constraints="Be specific about expected outcomes",
),
ToolParameter(
name="required_capabilities",
type="array",
description="Capabilities needed to complete this task",
required=True,
),
ToolParameter(
name="priority",
type="string",
description="Task priority",
required=False,
enum_values=["low", "normal", "high", "critical"],
default="normal",
),
ToolParameter(
name="deadline",
type="string",
description="Optional ISO 8601 deadline",
required=False,
),
ToolParameter(
name="agent_id",
type="string",
description="Specific agent to assign to (optional, auto-selects if omitted)",
required=False,
),
],
returns="""- task_id: Unique task identifier for tracking
- assigned_agent: ID of the agent assigned to the task
- estimated_completion: Estimated completion time
- status: Current task status""",
return_type="object",
examples=[
ToolExample(
description="Assign a code review task",
input={
"description": "Review the authentication module for security vulnerabilities",
"required_capabilities": ["CODE_ANALYSIS", "SECURITY_SCAN"],
"priority": "high",
},
output={
"task_id": "task-x1y2z3",
"assigned_agent": "agent-a1b2c3d4",
"estimated_completion": "2024-01-15T12:00:00Z",
"status": "assigned",
},
),
],
edge_cases=[
"No matching agent: Returns error suggesting spawn_agent",
"All agents busy: Queues task and returns queue position",
],
related_tools=["spawn_agent", "get_task_status", "cancel_task"],
),
]
WUYING_TOOLS = [
ToolDefinition(
name="browser_automation",
description="Opens a headless or headed browser in a Wuying sandbox for web tasks.",
category=ToolCategory.AUTOMATION,
use_when=[
"Interacting with web applications that require JS rendering",
"Scraping data from dynamic websites",
"Verifying UI changes in a live environment",
],
parameters=[
ToolParameter(
name="url",
type="string",
description="Target URL to navigate to",
required=True,
),
ToolParameter(
name="action",
type="string",
description="Action to perform (click, type, screenshot, evaluate)",
required=True,
enum_values=["navigate", "click", "type", "screenshot", "extract_text"],
),
ToolParameter(
name="selector",
type="string",
description="CSS selector for elements (if applicable)",
required=False,
),
ToolParameter(
name="value",
type="string",
description="Value to type or script to evaluate",
required=False,
),
],
returns="Action result, screenshot (base64) or extracted content",
return_type="object",
related_tools=["computer_use", "spawn_agent"],
edge_cases=[
"Page load timeout: Returns status=timeout",
"Selector not found: Returns error with current DOM snippet",
],
),
ToolDefinition(
name="computer_use",
description="Controls a cloud desktop instance via Wuying for general computing tasks.",
category=ToolCategory.AUTOMATION,
use_when=[
"Executing GUI-based software",
"Performing complex cross-application workflows",
"Legacy system interaction via remote desktop",
],
parameters=[
ToolParameter(
name="command",
type="string",
description="Command to execute or input to send",
required=True,
),
ToolParameter(
name="action_type",
type="string",
description="Type of interaction",
required=True,
enum_values=["shell", "mouse_click", "keyboard_input", "screenshot"],
),
ToolParameter(
name="coordinates",
type="array",
description="X, Y coordinates for mouse actions",
required=False,
),
],
returns="Command output or visual confirmation",
return_type="object",
related_tools=["browser_automation", "spawn_agent"],
),
]
"""
Model-First Tool Documentation System for ACGS-2.
Implements Anthropic's best practice of designing tool interfaces from
the model's perspective. Provides structured documentation that helps
AI agents understand when and how to use tools effectively.
Constitutional Hash: 608508a9bd224290
"""
import json
from collections.abc import Callable
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, TypeAlias, TypedDict, TypeVar, Unpack, cast
try:
from enhanced_agent_bus._compat.types import JSONDict as ImportedJSONDict
from enhanced_agent_bus._compat.types import JSONList as ImportedJSONList
except ImportError:
ImportedJSONDict = dict[str, Any]
ImportedJSONList = list[Any]
JSONDict: TypeAlias = ImportedJSONDict
JSONList: TypeAlias = ImportedJSONList
from enhanced_agent_bus.observability.structured_logging import get_logger
from enhanced_agent_bus.schema_safety import (
sanitize_schema_fragment,
sanitize_tool_input_schema,
)
logger = get_logger(__name__)
ToolHandlerFunc = Callable[..., object]
F = TypeVar("F", bound=ToolHandlerFunc)
# Constitutional compliance
try:
from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH
except ImportError:
CONSTITUTIONAL_HASH = "standalone"
__all__ = [
"AGENT_TOOLS",
"CONSTITUTIONAL_HASH",
"CONSTITUTIONAL_TOOLS",
"GOVERNANCE_TOOLS",
"ToolCategory",
"ToolDefinition",
"ToolExample",
"ToolParameter",
"ToolRegistry",
"create_tool_registry",
"tool",
]
class ToolCategory(Enum):
"""Categories for organizing tools."""
CONSTITUTIONAL = "constitutional"
GOVERNANCE = "governance"
AGENT = "agent"
MEMORY = "memory"
RESEARCH = "research"
WORKFLOW = "workflow"
UTILITY = "utility"
AUTOMATION = "automation"
class ToolParameter:
"""
Tool parameter definition with rich documentation.
Follows model-first design: describe parameters the way an AI would understand them.
"""
name: str
type: str
description: str
required: bool = True
default: object | None = None
enum_values: list[str] | None = None
examples: JSONList = field(default_factory=list)
constraints: str | None = None
def to_dict(self) -> JSONDict:
"""Convert to dictionary for schema generation."""
result = {
"name": self.name,
"type": self.type,
"description": self.description,
"required": self.required,
}
if self.default is not None:
result["default"] = self.default
if self.enum_values:
result["enum"] = self.enum_values
if self.examples:
Xet Storage Details
- Size:
- 37.4 kB
- Xet hash:
- 2d9032a86bfbb449d94995692871d6c7c1fdc0433e83f8e39c420cf12c6a3cea
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.