Qualia Plugins Guide¶

Introduction¶

Qualia’s plugin system allows extending core functionality through modular packages. Plugins can add new features, override existing ones, or provide experimental implementations while maintaining clean separation from core components.

Plugin Structure¶

A typical Qualia plugin follows this structure:

qualia-plugin-name/
├── conf/                    # Configuration examples
│   └── dataset_name/       
│       └── model_conf.toml
├── docs/                    
│   ├── conf.py
│   ├── index.rst
│   └── Makefile
├── src/
│   └── qualia_plugin_name/  # Must follow qualia_plugin_* naming
│       ├── deployment/      # Target-specific deployment
│       │   └── qualia_codegen/
│       │       ├── __init__.py
│       │       └── target_name.py
│       ├── learningframework/  # Framework implementations
│       │   ├── __init__.py
│       │   └── custom_framework.py
│       ├── learningmodel/     # Model architectures
│       │   └── pytorch/      # Organized by framework
│       │       ├── __init__.py
│       │       ├── layers/   # Custom layer implementations
│       │       │   ├── __init__.py
│       │       │   └── custom_layers.py
│       │       └── models.py
│       ├── postprocessing/   # Conversion & post-processing
│       │   ├── __init__.py
│       │   └── custom_converter.py
│       ├── preprocessing/    # Data preprocessing
│       │   ├── __init__.py
│       │   └── custom_preprocessor.py
│       ├── __init__.py
│       └── py.typed
├── tests/
│   └── functional/
├── LICENSE
├── pyproject.toml          # Project metadata & dependencies
└── README.md

Using Plugins¶

Configuration¶

To use a plugin, add it to your configuration file under the [bench] section:

[bench]
plugins = ['qualia_plugin_snn', 'qualia_plugin_spleat']

Plugin Loading Process¶

Qualia-Core scans the plugins list in order
For each plugin, it imports and merges these packages:
- preprocessing
- learningframework
- postprocessing
Plugins listed later can override earlier plugins
Other packages are loaded on-demand by the plugin’s modules

Creating a Plugin¶

1. Setup Project Structure¶

Use the Qualia Plugin Template to create a new plugin:

# Clone the template
git clone https://your-gitlab-server/qualia-plugin-template.git qualia-plugin-name
cd qualia-plugin-name

# Initialize project structure
mkdir -p src/qualia_plugin_name/{learningframework,learningmodel,postprocessing,preprocessing}
touch src/qualia_plugin_name/{__init__.py,py.typed}

2. Configure Project Metadata¶

Edit pyproject.toml:

[project]
name = "qualia-plugin-name"
version = "0.1.0"
description = "Your plugin description"
dependencies = [
    "qualia-core>=2.0.0",
    # Add your dependencies
]

[project.optional-dependencies]
dev = ["pytest", "pylint", "mypy"]

3. Implement Plugin Features¶

Adding New Features¶

Create new modules in appropriate directories:

# src/qualia_plugin_name/learningframework/custom_framework.py
from qualia_core.learningframework import BaseLearningFramework

class CustomFramework(BaseLearningFramework):
    def __init__(self, config):
        super().__init__(config)
        # Your implementation

    def train(self, model, train_loader, val_loader):
        # Training implementation
        pass

Overriding Existing Features¶

Inherit and extend existing classes:

# src/qualia_plugin_name/postprocessing/custom_converter.py
from qualia_core.postprocessing import BaseConverter

class CustomConverter(BaseConverter):
    def __init__(self, config):
        super().__init__(config)
        # Additional initialization

    def convert(self, model):
        # Custom conversion logic
        pass

4. Plugin Integration Points¶

Plugins can integrate with Qualia in several ways:

Learning Frameworks
- Add new frameworks via learningframework/
- Override existing framework behaviors
- Example: Adding SNN support

# Example: Adding a new learning framework
from qualia_core.learningframework import register_framework

@register_framework
class SNNFramework(BaseLearningFramework):
    name = "snn"  # Used in config files
    
    def __init__(self, config):
        super().__init__(config)

Model Architectures
- Implement new models in learningmodel/
- Organize by framework (pytorch/, keras/)
- Example: Custom neural architectures
Processing Pipelines
- Add preprocessing steps
- Implement custom data augmentation
- Create post-processing transformations
Deployment
- Add new target platforms
- Customize deployment processes
- Implement evaluation methods

Plugin Categories¶

Plugins typically fall into three categories:

External Dependency Plugins
- Handle non-AGPL-3.0 compatible dependencies
- Example: qualia-plugin-snn (SpikingJelly integration)
Proprietary Features
- Closed-source implementations
- Example: qualia-plugin-spleat
Experimental Features
- Research and development
- Example: qualia-plugin-som

Best Practices¶

Naming Conventions
- Package name: qualia-plugin-*
- Python package: qualia_plugin_*
- Class names: CamelCase, descriptive
Documentation
- Include clear README
- Document configuration options
- Provide usage examples
Testing
- Write unit tests
- Include functional tests
- Test with different configurations
Type Hints
- Use type annotations
- Include py.typed file
- Support mypy checking

Common Issues and Solutions¶

Plugin Not Loading
- Check package name in plugins list
- Verify installation in environment
- Check import paths
Version Conflicts
- Specify compatible versions in pyproject.toml
- Use appropriate version constraints
- Test with target Qualia version
Integration Problems
- Follow base class interfaces
- Use proper registration decorators
- Check configuration format

Example Configurations¶

# Example configuration using plugin features
[bench]
plugins = ['qualia_plugin_snn']

[learningframework]
name = "snn"  # Provided by plugin
timesteps = 100

[model_template]
name = "SCNN"  # Custom model from plugin
layers = [64, 128, 10]

Would you like me to expand on any particular section or add more specific examples?