Skip to content

Plugin System

Overview

The Plugin System is a core infrastructure component of AICO that enables extensibility through third-party modules while maintaining the system's security, privacy, and stability principles. It allows developers to create custom capabilities that integrate with AICO's core functionality without modifying the base system.

The Plugin System follows AICO's modular architecture and message-driven design, providing a secure sandbox environment for plugin execution while mediating access to system resources and the message bus.

Design Principles

The Plugin System architecture is built on the following key principles:

1. Secure Isolation

Plugins operate in isolated sandbox environments to: - Prevent unauthorized access to system resources - Protect user data and privacy - Ensure system stability by containing plugin failures - Enforce resource usage limits

2. Controlled Integration

All plugin interactions with AICO occur through controlled channels: - Mediated access to the message bus - Permission-based access control for system resources - Explicit capability grants rather than implicit access - Versioned APIs for stable integration

3. Hot-Loading Capability

Plugins can be dynamically loaded and unloaded without system restarts: - Runtime installation and activation - Graceful deactivation and removal - State preservation during updates - Version compatibility checking

4. Developer Experience

The Plugin System prioritizes a positive developer experience: - Clear, well-documented APIs - Comprehensive SDK with development tools - Streamlined testing and debugging workflows - Simplified packaging and distribution

5. User Control

Users maintain full control over plugins: - Granular permission management - Transparency about plugin capabilities and data access - Ability to enable/disable individual plugins - Performance and resource usage monitoring

Architecture Components

Plugin Manager

The Plugin Manager is the central component responsible for: - Plugin lifecycle management (installation, activation, deactivation, uninstallation) - Enforcing security policies and access controls - Resource allocation and monitoring - Plugin discovery and metadata management - Version compatibility verification

Plugin Sandbox

Each plugin runs within a dedicated sandbox that: - Isolates plugin code execution - Controls access to system resources - Monitors resource usage (CPU, memory, network) - Enforces timeout and rate limits - Provides controlled access to permitted APIs

Plugin Gateway

The Plugin Gateway mediates all communication between plugins and AICO's core systems: - Message bus access control - API request validation and routing - Event subscription management - Resource access mediation

Plugin Registry

The Plugin Registry maintains information about available and installed plugins: - Plugin metadata and capabilities - Version information and compatibility - User-configured settings and permissions - Usage statistics and health metrics

Plugin SDK

The Plugin SDK provides developers with tools for creating plugins: - API client libraries - Development templates and examples - Local testing environment - Documentation and tutorials - Packaging and distribution tools

Plugin Integration with Message Bus

Plugins integrate with AICO's core functionality primarily through the message bus, as described in the Message Bus Architecture document. The Plugin Manager mediates this integration through:

1. Topic Access Control

  • Plugins request access to specific message topics
  • The Plugin Manager enforces access policies based on plugin permissions
  • Unauthorized topic access attempts are blocked and logged
  • Access can be granted at different levels (publish-only, subscribe-only, or both)

2. Message Validation

  • All messages from plugins are validated against schema definitions
  • Malformed messages are rejected before entering the message bus
  • Rate limiting prevents message flooding
  • Message size limits are enforced

3. Topic Namespacing

  • Plugins publish to namespaced topics (e.g., plugin.{plugin_id}.{topic})
  • Core system components can subscribe to plugin topics selectively
  • Plugin-to-plugin communication is controlled through explicit permissions

4. Message Transformation

  • The Plugin Gateway can transform messages between plugin-specific and system formats
  • Version compatibility is maintained through message adaptation
  • Sensitive data can be filtered or anonymized

Plugin Lifecycle

1. Discovery and Installation

  • Plugins can be discovered through the AICO marketplace or local files
  • Installation process includes:
  • Verification of digital signatures
  • Compatibility checking
  • Dependency resolution
  • Resource requirement validation
  • User permission confirmation

2. Activation

  • User explicitly activates a plugin
  • Plugin sandbox is initialized
  • Required resources are allocated
  • Plugin connects to the message bus through the Plugin Gateway
  • Initialization hooks are called

3. Operation

  • Plugin runs within its sandbox
  • Interacts with AICO through the message bus and approved APIs
  • Resource usage is continuously monitored
  • Performance metrics are collected

4. Deactivation

  • User deactivates plugin or system triggers deactivation
  • Plugin receives deactivation signal
  • Cleanup hooks are called
  • Resources are released
  • Plugin state is preserved for future activation

5. Uninstallation

  • User initiates uninstallation
  • Plugin is deactivated if active
  • Plugin files and data are removed
  • System registry is updated

6. Updates

  • New version is discovered
  • Update verification process runs
  • Current version is deactivated
  • New version is installed
  • State migration occurs if supported
  • New version is activated

Plugin Types and Capabilities

AICO supports several types of plugins with different integration points:

1. Skill Plugins

Extend AICO's capabilities with new skills: - Custom conversation handlers - Specialized knowledge domains - Task automation - External service integration

2. Personality Extensions

Enhance AICO's personality system: - Custom personality traits - Specialized behavioral patterns - Alternative expression models - Cultural adaptations

3. Emotion Plugins

Extend emotional capabilities: - Custom emotion recognition models - Specialized emotional responses - Alternative emotion simulation approaches - Cultural emotion expression variants

4. Interface Extensions

Enhance user interaction: - Custom UI components - Alternative visualization modes - Specialized input methods - Accessibility enhancements

5. Integration Plugins

Connect with external systems: - Smart home integration - Service connectors - Device adapters - Data importers/exporters

Security Model

The Plugin System implements a comprehensive security model:

1. Permission System

  • Fine-grained capability-based permissions
  • Explicit user consent for sensitive capabilities
  • Runtime permission enforcement
  • Least-privilege principle by default

2. Sandbox Isolation

  • Process-level isolation using containerization
  • Memory protection and address space separation
  • File system access controls
  • Network access restrictions

3. Resource Controls

  • CPU usage limits and throttling
  • Memory allocation caps
  • Storage quotas
  • Network bandwidth controls
  • API rate limiting

4. Code Verification

  • Digital signature verification
  • Code scanning for known vulnerabilities
  • Runtime behavior monitoring
  • Anomaly detection

5. Data Protection

  • Access controls for user data
  • Data minimization principles
  • Privacy policy enforcement
  • Audit logging of data access

Plugin Development

Development Workflow

  1. Setup: Install the AICO Plugin SDK
  2. Create: Generate plugin scaffold using templates
  3. Develop: Implement plugin functionality
  4. Test: Use local testing environment
  5. Package: Create distributable plugin package
  6. Publish: Submit to marketplace or distribute directly

Plugin Structure

A typical plugin package includes:

plugin-name/
├── manifest.json       # Plugin metadata and requirements
├── icon.png            # Plugin icon
├── README.md           # Documentation
├── src/                # Source code
│   └── main.py         # Entry point
├── proto/              # Message definitions
│   └── messages.proto  # Plugin-specific messages
├── assets/             # Resources
│   └── ...
└── tests/              # Test suite
    └── ...

Plugin Manifest

The manifest.json file defines plugin metadata and requirements:

{
  "id": "com.example.plugin-name",
  "name": "Example Plugin",
  "version": "1.0.0",
  "description": "This plugin adds example functionality to AICO",
  "author": "Developer Name",
  "website": "https://example.com",
  "license": "MIT",
  "min_aico_version": "0.5.0",
  "permissions": [
    "conversation.history.read",
    "emotion.state.read",
    "plugin.storage.write"
  ],
  "topics": {
    "subscribe": [
      "conversation.message.new",
      "emotion.state.update"
    ],
    "publish": [
      "plugin.com.example.plugin-name.event"
    ]
  },
  "resources": {
    "memory": "128MB",
    "storage": "50MB"
  },
  "entry_point": "src/main.py",
  "settings_schema": {
    "api_key": {
      "type": "string",
      "description": "API key for external service",
      "required": false
    }
  }
}

Plugin Marketplace

The Plugin Marketplace facilitates discovery and distribution of plugins:

1. Discovery

  • Categorized browsing
  • Search functionality
  • Ratings and reviews
  • Featured and trending plugins

2. Quality Assurance

  • Automated security scanning
  • Performance testing
  • Compatibility verification
  • Community reviews

3. Installation

  • One-click installation
  • Dependency resolution
  • Version management
  • Update notifications

4. Developer Tools

  • Analytics dashboard
  • User feedback collection
  • Release management
  • Documentation hosting

Technical Implementation

Plugin Runtime

The Plugin System uses a combination of technologies to provide secure plugin execution:

  • Python Plugins: Isolated Python environments with controlled imports
  • WebAssembly: Sandboxed execution for performance-critical plugins
  • JavaScript: Isolated contexts for UI extensions

Plugin Communication

Plugins communicate with AICO through:

  • ZeroMQ: For message bus integration
  • Protocol Buffers: For structured data exchange
  • REST APIs: For synchronous operations
  • WebSockets: For real-time UI updates

Plugin Storage

Each plugin has access to:

  • Isolated Storage: Plugin-specific data storage
  • Shared Storage: Controlled access to shared data (with permissions)
  • Temporary Storage: For transient processing needs
  • Configuration Storage: For user settings

Frontend Components

The Plugin System includes dedicated frontend components to enable users to discover, install, manage, and interact with plugins. These components are integrated into AICO's Flutter-based frontend architecture.

Plugin Management UI

The Plugin Management UI provides a comprehensive interface for users to manage their plugins:

1. Plugin Marketplace

  • Discovery Interface: Browsable and searchable catalog of available plugins
  • Plugin Details View: Comprehensive information about each plugin
  • Description, screenshots, and feature list
  • Developer information and trust indicators
  • User ratings and reviews
  • Version history and changelog
  • Category Navigation: Organized browsing by plugin type and function
  • Recommendations: Personalized plugin suggestions based on usage patterns

2. Plugin Installation Flow

  • Permission Review: Clear presentation of required permissions
  • Resource Impact: Transparent display of resource requirements
  • Dependency Resolution: Automatic handling of plugin dependencies
  • Installation Progress: Visual feedback during download and installation
  • First-Run Experience: Guided setup for newly installed plugins

3. Plugin Management Dashboard

  • Installed Plugins List: Overview of all installed plugins
  • Status Controls: Enable/disable toggles for each plugin
  • Configuration Interface: Plugin-specific settings panels
  • Update Management: Version information and update controls
  • Resource Monitoring: Usage statistics for CPU, memory, and storage
  • Permission Management: Granular control over plugin permissions

Plugin Integration Points

The frontend architecture provides several integration points for plugins to extend the UI:

1. Widget Extensions

  • Conversation Widgets: Custom UI elements within conversation flow
  • Dashboard Widgets: Plugin-provided panels on the main dashboard
  • Settings Extensions: Custom configuration interfaces
  • Sidebar Components: Additional navigation or tool panels

2. Theme Integration

  • Design System Compliance: Plugins adopt AICO's design language
  • Adaptive Theming: Automatic adaptation to user theme preferences
  • Accessibility Support: Inherited accessibility features

3. Interaction Patterns

  • Command Integration: Plugin-provided commands in global command palette
  • Context Menu Extensions: Custom actions in context menus
  • Keyboard Shortcuts: Configurable shortcuts for plugin actions
  • Gesture Recognition: Custom gesture handlers for specific interactions

Frontend-Backend Communication

Plugin UI components communicate with their backend counterparts through:

  1. Message Bus Integration: Subscription to relevant topics
  2. Plugin Bridge API: Dedicated communication channel between frontend and backend plugin components
  3. State Synchronization: Mechanisms to keep plugin UI state consistent
  4. Event Handling: Standardized event propagation for plugin interactions

Implementation Technologies

The frontend plugin system leverages:

  • Flutter Plugins: For native integration capabilities
  • Dynamic UI Loading: For hot-loading plugin UI components
  • Isolated Dart Environments: For secure plugin code execution
  • WebView Integration: For web-based plugin UIs when needed

User Experience

The Plugin System is designed to provide a seamless user experience:

1. Discovery and Installation

  • Intuitive marketplace interface with featured, trending, and recommended sections
  • Rich plugin listings with screenshots, videos, and interactive previews
  • Clear permission explanations with privacy impact assessments
  • Streamlined installation process with minimal friction
  • Guided onboarding for new plugin capabilities

2. Management

  • Centralized plugin management dashboard with search and filtering
  • One-click enabling/disabling of plugins with status indicators
  • Comprehensive configuration options with defaults and presets
  • Detailed usage statistics and performance impact metrics
  • Batch operations for multiple plugin management

3. Interaction

  • Consistent integration with AICO's interface and interaction patterns
  • Clear visual indicators for plugin-provided functionality
  • Smooth transitions between core and plugin features
  • Unified experience across different plugins through design guidelines
  • Contextual discovery of plugin capabilities