utcp-text 1.1.0

UTCP communication protocol plugin for direct text content (browser-compatible).

UTCP Text Plugin

A text content plugin for UTCP. This plugin allows you to pass UTCP manuals or tool definitions directly as text content, without requiring file system access. It's browser-compatible and ideal for embedded configurations.

Features

• Direct Text Content: Pass UTCP manuals or tool definitions directly as strings.
• Browser Compatible: No file system access required, works in browser environments.
• JSON & YAML Support: Parses both JSON and YAML formatted content.
• OpenAPI Support: Automatically converts OpenAPI specs to UTCP tools with optional authentication.
• Base URL Override: Override API base URLs when converting OpenAPI specs.
• Tool Authentication: Supports authentication for generated tools from OpenAPI specs via auth_tools.

Installation

pip install utcp-text

How It Works

The Text plugin operates in two main ways:

1. Tool Discovery (register_manual): It parses the content field directly as a UTCP manual or OpenAPI spec. This is how the UtcpClient discovers what tools can be called.
2. Tool Execution (call_tool): When you call a tool, the plugin returns the content field directly.

Note: For file-based tool definitions, use the utcp-file plugin instead.

Quick Start

Here is a complete example demonstrating how to define and use tools with direct text content.

1. Define Tools with Inline Content

import asyncio
import json
from utcp.utcp_client import UtcpClient

# Define a UTCP manual as a Python dict, then convert to JSON string
manual_content = json.dumps({
    "manual_version": "1.0.0",
    "utcp_version": "1.0.2",
    "tools": [
        {
            "name": "get_mock_user",
            "description": "Returns a mock user profile.",
            "tool_call_template": {
                "call_template_type": "text",
                "content": json.dumps({
                    "id": 123,
                    "name": "John Doe",
                    "email": "[e-mail]"
                })
            }
        }
    ]
})

async def main():
    # Create a client with direct text content
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "inline_tools",
            "call_template_type": "text",
            "content": manual_content
        }]
    })

    # List the tools to confirm it was loaded
    tools = await client.list_tools()
    print("Available tools:", [tool.name for tool in tools])

    # Call the tool
    result = await client.call_tool("inline_tools.get_mock_user", {})
    
    print("\nTool Result:")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

2. Using with OpenAPI Specs

You can also pass OpenAPI specs directly as text content:

import asyncio
import json
from utcp.utcp_client import UtcpClient

openapi_spec = json.dumps({
    "openapi": "3.0.0",
    "info": {"title": "Pet Store", "version": "1.0.0"},
    "servers": [{"url": "https://api.example.com"}],
    "paths": {
        "/pets": {
            "get": {
                "operationId": "listPets",
                "summary": "List all pets",
                "responses": {"200": {"description": "Success"}}
            }
        }
    }
})

async def main():
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "pet_api",
            "call_template_type": "text",
            "content": openapi_spec,
            "base_url": "https://api.petstore.io/v1"  # Optional: override base URL
        }]
    })

    tools = await client.list_tools()
    print("Available tools:", [tool.name for tool in tools])

if __name__ == "__main__":
    asyncio.run(main())

Use Cases

• Embedded Configurations: Embed tool definitions directly in your application code.
• Browser Applications: Use UTCP in browser environments without file system access.
• Dynamic Tool Generation: Generate tool definitions programmatically at runtime.
• Testing: Define mock tools inline for unit tests.

Related Documentation

• Main UTCP Documentation
• Core Package Documentation
• File Plugin - For file-based tool definitions.
• HTTP Plugin - For calling real web APIs.
• CLI Plugin - For executing command-line tools.