Architecture#

This document describes the architecture of the Paramus Extension Framework, including its design principles, dual access patterns, and component interactions.

Design Principles#

Dual Access Architecture#

The framework provides two distinct access paths to the same underlying command system:

JSON-RPC Server: For external HTTP clients (web browsers, other applications)
Copilot Tools: For internal LangChain agents (AI assistants running inside Paramus)

Centralized Command Vocabulary#

All extension commands are defined in a single registry (api_surface/commands.py), ensuring consistency between both access paths while eliminating duplication.

Self-Documentation#

Every extension class implements a describe() method that provides comprehensive documentation including both direct method usage and JSON-RPC endpoint information.

Registry Pattern#

The ExtensionRegistry uses a decorator-based registration system that automatically discovers and registers API classes, eliminating manual registration overhead.

Separation of Concerns#

The framework separates different responsibilities into distinct components:

Command Vocabulary: Centralized command definitions and routing
API Surface: Public API interface classes
JSON-RPC Server: HTTP protocol handling for external clients
Copilot Tools: LangChain integration for internal agents
Documentation: Self-generating documentation system

Dual Access Architecture#

External HTTP Client                    LangChain Agent
       ↓                                       ↓
JSON-RPC Server (jsonrpc_server.py)     Copilot Tools (copilot_tools.py)
       ↓                                       ↓
       └────── Commands Registry (commands.py) ──────┘
                               ↓
                    Actual Implementation (UI/Core classes)

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
Performance: Network overhead, suitable for external integration

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, internal automation
Performance: Direct execution, optimized for internal use

Component Architecture#

┌─────────────────────────────────────────────────┐
│                 Client Layer                    │
├─────────────────────────────────────────────────┤
│  External HTTP  │  Internal LangChain Agents   │
│  Clients        │  and AI Assistants           │  
└─────────────────┴─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              Access Layer                       │
├─────────────────────────────────────────────────┤
│  JSON-RPC Server  │    Copilot Tools           │
│  (HTTP Protocol)  │    (Direct Python)         │
└─────────────────────┴─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│            Command Vocabulary                   │
├─────────────────────────────────────────────────┤
│         ExtensionCommands Registry              │
│         (commands.py)                           │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│                API Surface                      │
├─────────────────────────────────────────────────┤
│  ExtensionRegistry  │  MessageTerminal          │
│  Test Classes       │  UIBridge                 │  
│  Core Classes       │  Custom Extensions        │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              Core Services                      │
├─────────────────────────────────────────────────┤
│  WebSocket Communication                        │
│  Terminal Interface                             │
│  UI Bridge System                              │
└─────────────────────────────────────────────────┘

Core Components#

ExtensionCommands Registry (`api_surface/commands.py`)#

The ExtensionCommands class is the central component that defines all available API commands:

class ExtensionCommands:
    def get_command_registry(self):
        """Maps endpoint names to handler methods."""
        return {
            'api.describe': self.call_api_describe,
            'copilot.test.hello': self.call_test_hello_world,
            'copilot.sendmessage.terminal': self.call_terminal_send_message,
            'copilot.trigger.button': self.call_ui_trigger_button,
            # ... additional mappings
        }

Responsibilities:

Define the complete vocabulary of extension commands
Map endpoint names to handler methods
Provide consistent interface for both access paths
Handle parameter validation and response formatting

ExtensionRegistry (`api_surface/registry.py`)#

The ExtensionRegistry manages API class registration and documentation:

class ExtensionRegistry:
    _classes: Dict[str, Type] = {}
    
    @classmethod
    def register(cls, api_class: Type) -> Type:
        # Register API class
    
    @classmethod
    def describe_all(cls) -> Dict[str, Any]:
        # Generate documentation for all classes

Responsibilities:

Maintain a registry of all API classes
Provide decorator-based registration
Generate comprehensive documentation
Enable dynamic API discovery

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

Handles HTTP-based external access:

class JSONRPCHandler:
    def __init__(self):
        # Get command registry from commands module
        self.methods = extension_commands.get_command_registry()
    
    def handle_request(self, request_data):
        # Route requests to appropriate command handlers

Responsibilities:

Handle JSON-RPC 2.0 protocol
Parse HTTP requests and format responses
Route method calls to command registry
Provide error handling and status codes

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

Provides LangChain integration for AI agents:

class BaseCopilotTool(BaseTool):
    def _execute_command(self, method: str, params=None):
        registry = extension_commands.get_command_registry()
        command_func = registry[method]
        return command_func(params)

Responsibilities:

Implement LangChain BaseTool interface
Provide direct access to command registry
Handle parameter parsing and validation
Organize tools by functional categories

API Classes#

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

Basic testing and validation functionality:

System Verification: Hello world methods for testing system functionality
JSON-RPC Endpoints: Available via copilot.test.hello and copilot.test.run
Documentation: Self-documenting with both direct usage and JSON-RPC examples

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

Handles communication with the Paramus terminal interface:

WebSocket-based: Uses WebSocket for real-time communication
Flexible Sending: Supports both synchronous and asynchronous message sending
JSON-RPC Endpoints: Available via copilot.sendmessage.terminal and copilot.quicksend.terminal
Error Handling: Robust error handling for connection issues

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

Provides interface to the Universal WebSocket UI Bridge:

DOM Manipulation: Update UI elements dynamically
Event Triggering: Trigger UI actions and button clicks
Notifications: Send real-time notifications to users
JSON-RPC Endpoints: Available via copilot.trigger.*, copilot.send.*, and copilot.update.*
Alternative Endpoints: Also accessible via copilot.ui.* naming convention

CoreTest (`api_surface/core/test.py`)#

Core system testing and validation:

Backend Testing: Verify core system functionality
JSON-RPC Endpoints: Available via core.test.hello and core.test.run
System Integration: Test core services and backend components

Benefits of Dual Architecture#

Unified Command Vocabulary#

Both access paths use identical command names from commands.py
Consistent behavior regardless of access method
Single source of truth for all available commands

Flexible Integration Options#

External Integration: JSON-RPC for web browsers, remote applications
Internal Automation: Direct Python calls for AI agents and internal tools
Performance Optimization: Choose appropriate access method based on use case

Centralized Maintenance#

All commands defined in one location (commands.py)
Easy to add new commands - update only the command registry
Automatic availability in both access paths
Consistent documentation and parameter handling

Protocol Abstraction#

Same functionality available via different protocols
Client applications can choose the most appropriate access method
Future protocols can be added without changing core functionality
State Management: Update application state through UI

Host Process#

The JSONRPCHandler provides external access to the API:

class JSONRPCHandler:
    def __init__(self):
        self.methods = {
            'terminal.send_message': self._call_terminal_send_message,
            'ui.trigger_button': self._call_ui_trigger_button,
            # ... more methods
        }

Features:

Method routing and parameter validation
Error handling and response formatting
Support for both instance and static method calls
Comprehensive logging for debugging

Data Flow#

Direct Python API Usage#

Client Code → API Class Instance → Core Service → Response

Client imports and instantiates API class
Client calls method on API instance
API class interacts with core service (WebSocket, etc.)
Response is returned to client

JSON-RPC Usage#

External Client → JSON-RPC Request → Host Process → API Class → Core Service
                                                               ↓
External Client ← JSON-RPC Response ← Host Process ← API Class ← Core Service

External client sends JSON-RPC request
Host process routes request to appropriate handler
Handler creates API instance and calls method
API class interacts with core service
Response is formatted and returned via JSON-RPC

Extension Points#

Custom API Classes#

Developers can create custom API classes by:

Implementing the describe() class method
Registering with @ExtensionRegistry.register
Following the established patterns for method signatures

@ExtensionRegistry.register
class CustomAPI:
    @classmethod
    def describe(cls) -> Dict[str, Any]:
        return {
            "class": "CustomAPI",
            "description": "Custom functionality",
            "methods": {
                # method documentation
            }
        }

JSON-RPC Method Addition#

New JSON-RPC methods can be added by:

Adding method handler to JSONRPCHandler.methods
Implementing the handler method
Following naming conventions for method routing

Communication Protocols#

WebSocket Communication#

The framework uses WebSocket for real-time communication:

Terminal Messages: Bidirectional message passing
UI Updates: Real-time UI state synchronization
Event Notifications: Asynchronous event handling

JSON-RPC Protocol#

Standard JSON-RPC 2.0 protocol for external integration:

{
    "jsonrpc": "2.0",
    "method": "terminal.send_message",
    "params": {"content": "Hello World"},
    "id": 1
}

Error Handling#

API Level#

Method-specific error handling
Graceful degradation for communication failures
Comprehensive logging for debugging

Host Process Level#

JSON-RPC error formatting
Parameter validation
Method routing error handling

Transport Level#

WebSocket connection management
Retry logic for failed connections
Connection state monitoring

Security Considerations#

Input Validation: All parameters are validated before processing
Method Whitelisting: Only registered methods are accessible via JSON-RPC
Error Sanitization: Error messages are sanitized before external exposure
Access Control: Future versions will include role-based access control

Architecture

Contents

Architecture#

Design Principles#

Dual Access Architecture#

Centralized Command Vocabulary#

Self-Documentation#

Registry Pattern#

Separation of Concerns#

Dual Access Architecture#

JSON-RPC Server Path#

Copilot Tools Path#

Component Architecture#

Core Components#

ExtensionCommands Registry (api_surface/commands.py)#

ExtensionRegistry (api_surface/registry.py)#

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

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

API Classes#

Test (api_surface/ui/test.py)#

MessageTerminal (api_surface/ui/message_terminal.py)#

UIBridge (api_surface/ui/ui_bridge.py)#

CoreTest (api_surface/core/test.py)#

Benefits of Dual Architecture#

Unified Command Vocabulary#

Flexible Integration Options#

Centralized Maintenance#

Protocol Abstraction#

Host Process#

Data Flow#

Direct Python API Usage#

JSON-RPC Usage#

Extension Points#

Custom API Classes#

JSON-RPC Method Addition#

Communication Protocols#

WebSocket Communication#

JSON-RPC Protocol#

Error Handling#

API Level#

Host Process Level#

Transport Level#

Security Considerations#

ExtensionCommands Registry (`api_surface/commands.py`)#

ExtensionRegistry (`api_surface/registry.py`)#

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

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

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

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

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

CoreTest (`api_surface/core/test.py`)#