Eve library

Psyche Tool Framework

Other

Revision 1

On this page

Tool orchestration framework with Model Context Protocol (MCP) support for the Psyche AI Virtual Assistant Platform.

Overview#

The Tool Framework provides comprehensive tool management and execution capabilities:

  • Tool Registry: Define and manage tools with OpenAPI-compatible schemas
  • Tool Router: Intelligent execution with retries, caching, circuit breaker
  • MCP Server: Model Context Protocol server for LLM integration
  • Mock Tools: Pre-built mock implementations for development

Architecture#

text
src/tool_framework/
├── __init__.py           # Package exports
├── main.py               # FastAPI application
├── registry/             # Tool registry
│   ├── __init__.py
│   ├── types.py          # ToolDefinition, ParameterDefinition
│   ├── registry.py       # ToolRegistry implementation
│   └── validator.py      # Tool validation
├── router/               # Tool router
│   ├── __init__.py
│   ├── types.py          # ExecutionContext, ExecutionResult
│   ├── router.py         # ToolRouter implementation
│   ├── cache.py          # LRU cache
│   └── parser.py         # Tool call parser
├── mcp/                  # MCP implementation
│   ├── __init__.py
│   ├── server.py         # MCP server (stdio, HTTP, SSE)
│   └── adapters.py       # Resource and prompt providers
└── mock_tools/           # Mock tool implementations
    ├── __init__.py
    ├── crm_tools.py      # CRM mock tools
    ├── erp_tools.py      # ERP mock tools
    ├── calendar_tools.py # Calendar mock tools
    └── email_tools.py    # Email mock tools

Features#

Tool Registry#

  • Tool definition with parameters, returns, metadata
  • Semantic versioning with constraint matching
  • Dependency resolution between tools
  • Full-text search and filtering
  • Usage tracking and analytics

Tool Router#

  • Multi-format LLM support (Anthropic, OpenAI)
  • Retry strategies (fixed, exponential, linear backoff)
  • Circuit breaker for fault tolerance
  • LRU caching with TTL
  • Parallel and batch execution
  • Pre/post execution hooks

MCP Server#

  • JSON-RPC 2.0 protocol
  • Multiple transports (stdio, HTTP, SSE)
  • Resource and prompt providers
  • Rate limiting and authentication
  • Audit logging

API Endpoints#

Health & Metrics#

text
GET /health              # Service health
GET /ready               # Readiness check
GET /metrics             # Router metrics

Tool Registry#

text
GET /tools               # List all tools
GET /tools/{id}          # Get tool by ID
GET /tools/{id}/schema   # Get OpenAPI schema
POST /tools/search       # Search tools
GET /categories          # List categories

Tool Execution#

text
POST /execute            # Execute tool directly
POST /execute/llm        # Execute from LLM format
POST /execute/batch      # Batch execution

Tool Health#

text
GET /tools/{id}/health       # Get tool health
POST /tools/{id}/reset-circuit  # Reset circuit breaker

MCP Endpoints#

text
GET /mcp/tools           # MCP tools/list
POST /mcp/tools/call     # MCP tools/call

Usage#

Registering a Tool#

python
from tool_framework import (
    ToolRegistry,
    ToolDefinition,
    ParameterDefinition,
    ParameterType,
    ToolCategory,
    tool,
)

registry = ToolRegistry()

# Using decorator
@tool(
    id="weather.get",
    name="Get Weather",
    description="Get current weather for a location",
    category=ToolCategory.UTILITY,
)
async def get_weather(location: str) -> dict:
    return {"location": location, "temperature": 72}

await registry.register(get_weather.__tool_definition__)

# Or manually
definition = ToolDefinition(
    id="calculator.add",
    name="Add Numbers",
    description="Add two numbers together",
    parameters=[
        ParameterDefinition(
            name="a",
            type=ParameterType.NUMBER,
            description="First number",
            required=True,
        ),
        ParameterDefinition(
            name="b",
            type=ParameterType.NUMBER,
            description="Second number",
            required=True,
        ),
    ],
    handler=lambda a, b: {"result": a + b},
)

await registry.register(definition)

Executing Tools#

python
from tool_framework import ToolRouter, ExecutionContext

router = ToolRouter(registry=registry)

# Direct execution
result = await router.execute(
    tool_id="calculator.add",
    arguments={"a": 5, "b": 3},
    context=ExecutionContext(request_id="req-001"),
)

print(result.data)  # {"result": 8}

# From LLM tool call
llm_tool_call = {
    "id": "call_123",
    "name": "calculator.add",
    "input": {"a": 5, "b": 3},
}

result = await router.execute_from_llm(
    tool_call=llm_tool_call,
    context=ExecutionContext(request_id="req-002"),
)

# Format for LLM response
formatted = router.format_result_for_llm(result, format="anthropic")

MCP Server#

python
from tool_framework.mcp import MCPServer

# Create server
server = MCPServer(registry=registry)

# Run in stdio mode (for Claude Desktop integration)
await server.run_stdio()

# Or HTTP mode
await server.run_http(host="0.0.0.0", port=8012)

Configuration#

Environment Variables#

Variable Description Default
SERVICE_PORT REST API port 8011
MCP_PORT MCP HTTP server port 8012
ENABLE_MOCK_TOOLS Register mock tools true
LOG_LEVEL Log level INFO
CACHE_SIZE LRU cache size 1000
CACHE_TTL Cache TTL in seconds 300
MAX_RETRIES Default max retries 3
TIMEOUT_SECONDS Default execution timeout 30

Development#

Using Nx#

bash
# Install dependencies
nx install psyche-tool-framework

# Run REST API server
nx serve psyche-tool-framework

# Run MCP server (stdio mode)
nx serve-mcp psyche-tool-framework

# Run MCP server (HTTP mode)
nx serve-mcp-http psyche-tool-framework

# Run tests
nx test psyche-tool-framework
nx test-unit psyche-tool-framework
nx test-integration psyche-tool-framework

# Run tests with coverage
nx test-cov psyche-tool-framework

# Lint and format
nx lint psyche-tool-framework
nx format psyche-tool-framework

# Docker
nx docker-build psyche-tool-framework
nx docker-run psyche-tool-framework

Direct Poetry Commands#

bash
cd apps/psyche/tool-framework
poetry install
poetry run pytest
poetry run uvicorn tool_framework.main:app --reload --host 0.0.0.0 --port 8011

Mock Tools#

The framework includes mock tools for development:

CRM Tools#

  • crm.get_customer - Get customer details
  • crm.search_customers - Search customers
  • crm.get_account_details - Get account info
  • crm.get_opportunities - List opportunities
  • crm.create_note - Create a note

ERP Tools#

  • erp.check_inventory - Check stock levels
  • erp.get_product_details - Get product info
  • erp.search_products - Search products
  • erp.create_order - Create an order
  • erp.get_order_status - Check order status

Calendar Tools#

  • calendar.get_availability - Check availability
  • calendar.create_meeting - Schedule meeting
  • calendar.reschedule_meeting - Reschedule
  • calendar.get_upcoming_meetings - List meetings

Email Tools#

  • email.send_email - Send email
  • email.send_template - Send templated email
  • email.get_email_history - Get email history
  • email.track_email - Track email status

Performance Targets#

Operation Target Latency
Tool lookup < 5ms
Simple execution < 50ms
Cached execution < 5ms
Batch (10 tools) < 500ms
Search < 100ms

License#

Proprietary - Oshun Platform