Eve library

Tool Schemas

Guide

Revision 1

On this page

Version: 0.1.0 Auto-generated API documentation

Last Updated: 2025-10-03


API Reference#

API Types#

Interfaces#

ToolParameter#

Tool Schemas Module Defines JSON schemas for tools available to AI agents Tools: search, KG query, calc, TTS, STT, scheduler

typescript
export interface ToolParameter {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description: string;
  required: boolean;
  default?: any;
  enum?: any[];
  pattern?: string;
  minLength?: number;
  maxLength?: number;
  minimum?: number;
  maximum?: number;
}

ToolSchema#

typescript
export interface ToolSchema {
  name: string;
  description: string;
  category:
    | 'search'
    | 'knowledge'
    | 'computation'
    | 'speech'
    | 'scheduling'
    | 'system';
  parameters: ToolParameter[];
  returns: {
    type: string;
    description: string;
    schema?: any;
  };
  examples: Array<{
    input: Record<string, any>;
    output: any;
    description: string;
  }>;
  permissions?: string[];
  rateLimit?: {
    calls: number;
    period: 'second' | 'minute' | 'hour' | 'day';
  };
}

Classes#

ToolSchemaRegistry#

Register a tool schema

typescript
export class ToolSchemaRegistry {
  private schemas: Map<string, ToolSchema> = new Map();
  private toolsByCategory: Map<string, Set<string>> = new Map();

  constructor() {
    // Register default tools
    this.registerDefaultTools();
  }

  registerTool(schema: ToolSchema): void {
    // Validate schema
    if (!schema.name || !schema.description) {
      throw new Error('Tool schema must have name and description');
    }

    if (this.schemas.has(schema.name)) {
      throw new Error(`Tool ...

Endpoints#

Overview#

The Tool Schemas API provides endpoints for discovering, validating, and using structured schemas for AI agent tools. The system includes 6 default tools (search, kg_query, calc, tts, stt, scheduler) with comprehensive parameter validation, constraint enforcement, and OpenAPI schema export capabilities.

Base URL#

text
http://localhost:3007/v1/ai

Authentication#

All endpoints require authentication via Bearer token in the Authorization header.

Endpoints#

List All Tools#

GET /tools

Returns all available tool schemas.

Query Parameters:

  • category (optional): Filter by category (search, knowledge, computation, speech, scheduling, system)

Response: 200 OK

json
{
  "tools": [
    {
      "name": "search",
      "description": "Search the knowledge base",
      "category": "search",
      "parameters": [...],
      "returns": {...},
      "examples": [...]
    }
  ],
  "count": 6
}

Get Tool Schema#

GET /tools/:name

Retrieve a specific tool schema by name.

Response: 200 OK or 404 Not Found

json
{
  "name": "search",
  "description": "Search the knowledge base",
  "category": "search",
  "parameters": [
    {
      "name": "query",
      "type": "string",
      "description": "Search query",
      "required": true,
      "maxLength": 500
    }
  ],
  "returns": {
    "type": "object",
    "description": "Search results",
    "schema": {
      "results": "array",
      "count": "number"
    }
  },
  "examples": [
    {
      "input": { "query": "meditation techniques" },
      "output": { "results": [...], "count": 5 },
      "description": "Search for meditation content"
    }
  ],
  "permissions": ["read:content"],
  "rateLimit": {
    "calls": 100,
    "period": "minute"
  }
}

Validate Tool Input#

POST /tools/:name/validate

Validate input parameters against tool schema.

Request Body:

json
{
  "input": {
    "query": "example search",
    "limit": 10
  }
}

Response: 200 OK

json
{
  "valid": true,
  "errors": []
}

Error Response:

json
{
  "valid": false,
  "errors": [
    "Missing required parameter: query",
    "Parameter 'limit' exceeds maximum: 100"
  ]
}

Get Tools by Category#

GET /tools/category/:category

Retrieve all tools in a specific category.

Categories:

  • search - Search and retrieval tools
  • knowledge - Knowledge graph queries
  • computation - Mathematical calculations
  • speech - Text-to-speech and speech-to-text
  • scheduling - Time-based scheduling
  • system - System utilities

Response: 200 OK

json
{
  "category": "speech",
  "tools": [
    {
      "name": "tts",
      "description": "Text-to-speech synthesis",
      "category": "speech",
      ...
    },
    {
      "name": "stt",
      "description": "Speech-to-text transcription",
      "category": "speech",
      ...
    }
  ],
  "count": 2
}

Export OpenAPI Schema#

GET /tools/:name/openapi

Export tool schema in OpenAPI 3.0 format.

Response: 200 OK

json
{
  "openapi": "3.0.0",
  "info": {
    "title": "search",
    "description": "Search the knowledge base",
    "version": "1.0.0"
  },
  "paths": {
    "/search": {
      "post": {
        "summary": "Search the knowledge base",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search query",
                    "maxLength": 500
                  }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

Export All Schemas#

GET /tools/openapi

Export OpenAPI schemas for all tools.

Response: 200 OK

json
{
  "openapi": "3.0.0",
  "info": {
    "title": "AI Tools API",
    "description": "All available AI agent tools",
    "version": "1.0.0"
  },
  "paths": {
    "/search": {...},
    "/kg_query": {...},
    "/calc": {...},
    "/tts": {...},
    "/stt": {...},
    "/scheduler": {...}
  }
}

Default Tools#

1. Search Tool#

typescript
{
  name: "search",
  description: "Search the knowledge base",
  category: "search",
  parameters: [
    {
      name: "query",
      type: "string",
      description: "Search query",
      required: true,
      maxLength: 500
    },
    {
      name: "limit",
      type: "number",
      description: "Maximum results",
      required: false,
      default: 10,
      minimum: 1,
      maximum: 100
    }
  ],
  returns: {
    type: "object",
    description: "Search results with metadata",
    schema: {
      results: "array",
      count: "number",
      query: "string"
    }
  },
  permissions: ["read:content"],
  rateLimit: {
    calls: 100,
    period: "minute"
  }
}

2. Knowledge Graph Query Tool#

typescript
{
  name: "kg_query",
  description: "Query the knowledge graph",
  category: "knowledge",
  parameters: [
    {
      name: "query",
      type: "string",
      description: "SPARQL or Cypher query",
      required: true,
      maxLength: 2000
    },
    {
      name: "queryType",
      type: "string",
      description: "Query language",
      required: false,
      enum: ["sparql", "cypher"],
      default: "sparql"
    }
  ],
  returns: {
    type: "object",
    description: "Query results",
    schema: {
      bindings: "array",
      count: "number"
    }
  },
  permissions: ["read:knowledge_graph"],
  rateLimit: {
    calls: 50,
    period: "minute"
  }
}

3. Calculator Tool#

typescript
{
  name: "calc",
  description: "Evaluate mathematical expressions",
  category: "computation",
  parameters: [
    {
      name: "expression",
      type: "string",
      description: "Mathematical expression to evaluate",
      required: true,
      pattern: "^[0-9+\\-*/()\\s.]+$",
      maxLength: 200
    }
  ],
  returns: {
    type: "number",
    description: "Calculation result"
  },
  permissions: [],
  rateLimit: {
    calls: 1000,
    period: "minute"
  }
}

4. Text-to-Speech Tool#

typescript
{
  name: "tts",
  description: "Convert text to speech",
  category: "speech",
  parameters: [
    {
      name: "text",
      type: "string",
      description: "Text to synthesize",
      required: true,
      maxLength: 5000
    },
    {
      name: "voice",
      type: "string",
      description: "Voice ID",
      required: false,
      default: "default"
    },
    {
      name: "format",
      type: "string",
      description: "Audio format",
      required: false,
      enum: ["mp3", "wav", "ogg"],
      default: "mp3"
    }
  ],
  returns: {
    type: "object",
    description: "Audio file URL and metadata",
    schema: {
      url: "string",
      duration: "number",
      format: "string"
    }
  },
  permissions: ["use:tts"],
  rateLimit: {
    calls: 100,
    period: "hour"
  }
}

5. Speech-to-Text Tool#

typescript
{
  name: "stt",
  description: "Transcribe speech to text",
  category: "speech",
  parameters: [
    {
      name: "audioUrl",
      type: "string",
      description: "URL of audio file",
      required: true,
      pattern: "^https?://.+\\.(mp3|wav|ogg)$"
    },
    {
      name: "language",
      type: "string",
      description: "Audio language",
      required: false,
      default: "en"
    }
  ],
  returns: {
    type: "object",
    description: "Transcription result",
    schema: {
      text: "string",
      confidence: "number",
      words: "array"
    }
  },
  permissions: ["use:stt"],
  rateLimit: {
    calls: 50,
    period: "hour"
  }
}

6. Scheduler Tool#

typescript
{
  name: "scheduler",
  description: "Schedule tasks and reminders",
  category: "scheduling",
  parameters: [
    {
      name: "action",
      type: "string",
      description: "Scheduler action",
      required: true,
      enum: ["schedule", "cancel", "list"]
    },
    {
      name: "taskId",
      type: "string",
      description: "Task ID for cancel operation",
      required: false
    },
    {
      name: "schedule",
      type: "object",
      description: "Schedule details for scheduling",
      required: false
    }
  ],
  returns: {
    type: "object",
    description: "Scheduler response",
    schema: {
      taskId: "string",
      status: "string",
      scheduledAt: "string"
    }
  },
  permissions: ["use:scheduler"],
  rateLimit: {
    calls: 100,
    period: "minute"
  }
}

Data Models#

ToolParameter#

typescript
interface ToolParameter {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description: string;
  required: boolean;
  default?: any;
  enum?: any[];
  pattern?: string;
  minLength?: number;
  maxLength?: number;
  minimum?: number;
  maximum?: number;
}

ToolSchema#

typescript
interface ToolSchema {
  name: string;
  description: string;
  category:
    | 'search'
    | 'knowledge'
    | 'computation'
    | 'speech'
    | 'scheduling'
    | 'system';
  parameters: ToolParameter[];
  returns: {
    type: string;
    description: string;
    schema?: any;
  };
  examples: Array<{
    input: Record<string, any>;
    output: any;
    description: string;
  }>;
  permissions?: string[];
  rateLimit?: {
    calls: number;
    period: 'second' | 'minute' | 'hour' | 'day';
  };
}

Validation Rules#

Parameter Validation#

  • Required: Must be present if required: true
  • Type: Must match specified type (string, number, boolean, object, array)
  • Enum: Must be one of the allowed values
  • Pattern: Must match regex pattern
  • Length: String length must be within minLength/maxLength
  • Range: Number must be within minimum/maximum

Schema Validation#

  • Name: Must be unique across all tools
  • Description: Required, non-empty
  • Category: Must be valid category
  • Parameters: Each parameter must have name, type, description

Error Responses#

400 Bad Request

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid tool parameters",
    "details": {
      "valid": false,
      "errors": ["Missing required parameter: query"]
    }
  }
}

404 Not Found

json
{
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'unknown_tool' not found"
  }
}

500 Internal Server Error

json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Examples#

Register Custom Tool#

bash
curl -X POST http://localhost:3007/v1/ai/tools \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "translator",
    "description": "Translate text between languages",
    "category": "system",
    "parameters": [
      {
        "name": "text",
        "type": "string",
        "description": "Text to translate",
        "required": true,
        "maxLength": 5000
      },
      {
        "name": "targetLang",
        "type": "string",
        "description": "Target language code",
        "required": true,
        "enum": ["en", "es", "fr", "de", "zh", "ja"]
      }
    ],
    "returns": {
      "type": "object",
      "description": "Translation result",
      "schema": {
        "translatedText": "string",
        "sourceLanguage": "string",
        "confidence": "number"
      }
    },
    "examples": [
      {
        "input": { "text": "Hello world", "targetLang": "es" },
        "output": { "translatedText": "Hola mundo", "sourceLanguage": "en", "confidence": 0.99 },
        "description": "English to Spanish translation"
      }
    ]
  }'

Validate Search Input#

bash
curl -X POST http://localhost:3007/v1/ai/tools/search/validate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "query": "meditation techniques",
      "limit": 10
    }
  }'

Get Speech Tools#

bash
curl -X GET "http://localhost:3007/v1/ai/tools?category=speech" \
  -H "Authorization: Bearer YOUR_TOKEN"

Export OpenAPI Schema#

bash
curl -X GET "http://localhost:3007/v1/ai/tools/search/openapi" \
  -H "Authorization: Bearer YOUR_TOKEN"

Test Coverage#

The Tool Schemas feature has comprehensive test coverage:

  • Unit Tests: 54 tests (100% code coverage)
  • Integration Tests: 19 tests (all HTTP endpoints)
  • E2E Tests: 23 Playwright tests
  • Total: 96 tests passing

Implementation#

  • Language: TypeScript with strict type safety
  • File: apps/lilith/svc-ai/src/tool-schemas.ts
  • Lines of Code: 609
  • Dependencies: None (in-memory storage)

Limitations#

  • Tools are stored in-memory (not persisted to database)
  • No pagination on list endpoints
  • Tool schemas cannot be deleted after registration
  • Rate limiting is metadata only (not enforced)

Future Enhancements#

  • Database persistence (PostgreSQL)
  • Dynamic tool loading from external sources
  • Tool execution engine integration
  • Real-time schema validation
  • Tool versioning and deprecation
  • Usage analytics and monitoring

Generated: 2025-10-03 API Version: 1.0.0 Test Coverage: 96 tests passing

Implementation Status#

Implementation Status#

Current Status: 11/15 Criteria Met (73% Complete) ✅

Completion: 11/15 criteria met (73%)