Comprehensive Paramus Extension API Guide

This document provides a complete guide to the Paramus Extension API, incorporating the latest architectural improvements and dual access patterns.

Quick Start

JSON-RPC Access (External Integration)

# Start the JSON-RPC server
curl -X POST http://localhost:8050/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "api.describe", "id": 1}'

Direct Python Access (Internal Use)

from paramus.extension.api_surface.commands import extension_commands
result = extension_commands.call_api_describe()

LangChain Integration (AI Agents)

from paramus.extension.host.agent.copilot_tools import get_all_copilot_tools
tools = get_all_copilot_tools()

Available Endpoints

API Documentation

Endpoint	Description	Parameters
api.describe	Get complete API documentation	None

Test Commands

Endpoint	Description	Parameters
copilot.test.hello	Test UI system	None
copilot.test.run	Execute UI test suite	None
core.test.hello	Test core system	None
core.test.run	Execute core test suite	None

Terminal Communication

Endpoint	Description	Parameters
copilot.sendmessage.terminal	Send terminal message with full control	content (required), wait_for_ws (optional), retry_interval (optional)
copilot.quicksend.terminal	Quick terminal message without WebSocket wait	content (required)

UI Control

Endpoint	Description	Parameters
copilot.trigger.button	Trigger any button by ID	button_id (required)
copilot.trigger.new	Trigger ‘new’ button	None
copilot.trigger.sync	Trigger file tree sync	None
copilot.send.notification	Show notification popup	message (required)
copilot.update.element	Update DOM element property	element_id (required), property (required), value (required)

Alternative UI Endpoints

Endpoint	Equivalent	Description
copilot.ui.trigger.button	copilot.trigger.button	Alternative button trigger
copilot.ui.trigger.new	copilot.trigger.new	Alternative new trigger
copilot.ui.trigger.sync	copilot.trigger.sync	Alternative sync trigger
copilot.ui.send.notification	copilot.send.notification	Alternative notification
copilot.ui.update.element	copilot.update.element	Alternative element update

Architecture Benefits

Unified Command Vocabulary

• Single source of truth in commands.py

• Consistent method names across all access patterns

• Automatic availability in both JSON-RPC and direct access

Dual Access Optimization

• JSON-RPC: Best for external integration, web clients

• Direct Python: Best for internal tools, AI agents

• Performance: Choose appropriate method based on use case

Extensibility

• Easy to add new commands

• Automatic documentation generation

• Self-describing API classes

Integration Patterns

Web Application Integration

// JavaScript client example
fetch('http://localhost:8050/jsonrpc', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'copilot.trigger.sync',
    id: 1
  })
}).then(response => response.json())
  .then(data => console.log(data));

Python Script Integration

# Python client example
import requests

def paramus_api_call(method, params=None):
    payload = {"jsonrpc": "2.0", "method": method, "id": 1}
    if params:
        payload["params"] = params
    
    response = requests.post("http://localhost:8050/jsonrpc", json=payload)
    return response.json()

# Usage
result = paramus_api_call("copilot.send.notification", {
    "message": "Process completed!"
})

AI Agent Integration

# LangChain agent example
from langchain.agents import create_react_agent
from paramus.extension.host.agent.copilot_tools import get_all_copilot_tools

tools = get_all_copilot_tools()
agent = create_react_agent(llm, tools, prompt)
result = agent.invoke({"input": "Test the system and notify when complete"})

Error Handling

JSON-RPC Error Codes

Code	Message	Description
-32601	Method not found	Endpoint doesn’t exist
-32602	Invalid params	Missing or incorrect parameters
-32603	Internal error	Server-side error occurred

Response Format

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "message": "Operation completed"
  },
  "id": 1
}

Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

Development Workflow

Adding New Commands

1. Define the handler in commands.py:

def call_my_new_command(self, params=None):
    # Implementation
    return {"status": "success", "message": "Command executed"}

2. Add to command registry:

def get_command_registry(self):
    return {
        # ... existing commands ...
        'my.new.command': self.call_my_new_command,
    }

3. Update API class documentation:

def describe(cls) -> Dict[str, Any]:
    return {
        "jsonrpc_methods": {
            "my.new.command": {
                "description": "Execute my new functionality",
                "parameters": {},
                "example": "JSON-RPC call: my.new.command"
            }
        }
    }

Testing New Commands

1. Test via JSON-RPC:

curl -X POST http://localhost:8050/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "my.new.command", "id": 1}'

2. Test via Direct Python:

from paramus.extension.api_surface.commands import extension_commands
result = extension_commands.call_my_new_command()

3. Test via LangChain Tool (if applicable):

from paramus.extension.host.agent.copilot_tools import MyNewCommandTool
tool = MyNewCommandTool()
result = tool._run("")

Best Practices

Parameter Validation

def call_my_command(self, params=None):
    if not params or 'required_param' not in params:
        return {"status": "error", "message": "required_param is required"}
    
    # Process command
    return {"status": "success", "message": "Command executed"}

Error Handling

def call_my_command(self, params=None):
    try:
        # Command implementation
        result = some_operation(params)
        return {"status": "success", "result": result}
    except Exception as e:
        return {"status": "error", "message": f"Command failed: {str(e)}"}

Documentation

@classmethod
def describe(cls) -> Dict[str, Any]:
    return {
        "class": "MyClass",
        "description": "Clear description of functionality",
        "jsonrpc_methods": {
            "method.name": {
                "description": "What this method does",
                "parameters": {
                    "param": {"type": "str", "required": True, "description": "Parameter description"}
                },
                "example": "JSON-RPC call: method.name"
            }
        }
    }

This guide provides comprehensive coverage of the Paramus Extension API system, from basic usage to advanced integration patterns and development workflows.