Overview

Overview#

The Paramus Extension Framework provides a comprehensive and extensible API system that allows developers to interact with the Paramus ecosystem through well-defined interfaces. The system offers dual access paths to serve both external integrations and internal AI agent use cases.

Key Features#

  • Dual Access Architecture: JSON-RPC for external clients, Direct Python API for internal agents

  • Centralized Command Vocabulary: All commands defined in a single registry

  • Self-Documenting APIs: Each extension class implements a describe() method with JSON-RPC method documentation

  • Registry System: Central registry for all API classes with automatic registration via decorators

  • JSON-RPC Support: HTTP-based remote procedure call interface for external integrations

  • LangChain Integration: Direct Python tools for AI agents and internal automation

  • WebSocket Integration: Real-time communication with the Paramus UI system

Dual Access Architecture#

The extension API provides two distinct access patterns to the same underlying command system:

JSON-RPC Server Path#

  • Purpose: External access via HTTP for web browsers, other applications

  • Location: host/jsonrpc_server.py

  • Protocol: JSON-RPC 2.0 over HTTP

  • Use Case: Remote control, integration with external tools, web interfaces

  • Example: POST /jsonrpc with method "copilot.test.hello"

Copilot Tools Path#

  • Purpose: Internal AI agent access via LangChain

  • Location: host/agent/copilot_tools.py

  • Protocol: Direct Python method calls

  • Use Case: LangChain agents, AI assistants running inside Paramus

  • Example: CopilotTestHelloTool()._run("")

Both paths converge on the same command registry, ensuring consistency while optimizing for their specific use cases.

Architecture Components#

Command Registry System (api_surface/commands.py)#

The ExtensionCommands class serves as the central hub for all API commands:

  • Centralized Vocabulary: All extension commands defined in one place

  • Method Registry: get_command_registry() maps endpoint names to handler methods

  • Automatic Discovery: Commands are categorized and discoverable

  • Dual Interface Support: Used by both JSON-RPC server and Copilot tools

API Surface Classes#

The API surface consists of several key components:

Test API (api_surface/ui/test.py)#

  • Basic testing and validation functionality

  • Hello world methods for system verification

  • Available via copilot.test.* endpoints

MessageTerminal API (api_surface/ui/message_terminal.py)#

  • Send messages to the Paramus terminal interface

  • WebSocket-based communication

  • Synchronous and asynchronous message sending

  • Available via copilot.sendmessage.terminal and copilot.quicksend.terminal

UIBridge API (api_surface/ui/ui_bridge.py)#

  • Interface to the Universal WebSocket UI Bridge

  • Trigger UI actions and DOM manipulation

  • Real-time notifications and updates

  • Available via copilot.trigger.*, copilot.send.*, and copilot.update.*

Core API (api_surface/core/test.py)#

  • Core system testing and validation

  • Backend functionality testing

  • Available via core.test.* endpoints

JSON-RPC Server (host/jsonrpc_server.py)#

The JSON-RPC server provides HTTP-based access:

  • External Integration: Enables remote control from web browsers, other applications

  • Protocol Handling: JSON-RPC 2.0 request parsing and response formatting

  • Method Routing: Automatically routes requests using the command registry

  • Error Handling: Comprehensive error handling and status reporting

Copilot Tools (host/agent/copilot_tools.py)#

The Copilot tools provide LangChain integration:

  • AI Agent Interface: BaseTool implementations for LangChain agents

  • Direct Execution: Bypasses HTTP overhead for internal use

  • Parameter Handling: Intelligent parameter parsing and validation

  • Tool Organization: Categorized tools for different functional areas

Getting Started#

For External Integration (JSON-RPC)#

To use the API via JSON-RPC:

  1. Start the JSON-RPC server on http://localhost:8050/jsonrpc

  2. Send HTTP POST requests with JSON-RPC 2.0 format

  3. Use method names from the command registry (e.g., copilot.test.hello)

import requests
import json

payload = {
    "jsonrpc": "2.0",
    "method": "copilot.test.hello",
    "id": 1
}

response = requests.post("http://localhost:8050/jsonrpc", json=payload)
result = response.json()

For Internal Agents (Direct Python)#

To use the API via LangChain tools:

  1. Import the Copilot tools from host.agent.copilot_tools

  2. Create tool instances for your agent

  3. Use tools directly in LangChain agent workflows

from paramus.extension.host.agent.copilot_tools import get_all_copilot_tools
from langchain.agents import initialize_agent

tools = get_all_copilot_tools()
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
result = agent.run("Test the copilot system")

For Direct Python Usage#

To use the API classes directly:

  1. Import the command registry from api_surface.commands

  2. Get the registry and call methods directly

  3. Handle responses and errors appropriately

from paramus.extension.api_surface.commands import extension_commands

# Get available commands
registry = extension_commands.get_command_registry()

# Call a command directly
result = registry["copilot.test.hello"]()
print(result)  # {"status": "success", "message": "..."}

Benefits of the Architecture#

  • Unified Command Vocabulary: Both access paths use identical command names

  • Consistent Behavior: Same underlying methods called regardless of access path

  • Flexible Integration: Choose HTTP for external access, direct calls for internal agents

  • Centralized Maintenance: All commands defined in one place

  • Performance Optimization: Direct calls avoid HTTP overhead for internal use

  • Protocol Abstraction: Same functionality available via different protocols

Contents