Spout Module Standard

This document outlines the standard structure that each of Spout's twelve core modules and all addon modules should follow. By maintaining this consistent format, we ensure modules remain organized, extensible, and easy to understand—whether you're a first-time contributor or a seasoned developer.

Anatomy of a Spout Module:

order of files and folders may vary from that shown below depending on your IDE.

spout/core/(module_name)/     # Module parent directory
├── __pycache__/              # Python cache  (ingore this)
├── options/                  # Settings, prompts, and other specification files (optional)
│   └── [...].txt/ini         # various folders, txt/ini files for options/prompts, etc.
├── tests/                    # Testing infrastructure
│   ├── test_cases.json       # Test specifications and expected results JSON file
│   ├── test_results.txt      # Latest test run results
│   └── samples/              # Sample CLI inputs and outputs
│       └── [txt files]       # CLI input/output files for gen AI
│
├── (module_name)_plugins/    # Base plugins available to all users
│   └── [spoutlets]/          # official project spoutlets
├── (module_name)_local/      # User-specific custom plugins (optional)
│   └── [spoutlets]/          # User-created/cloned custom spoutlets
├── (module_name)_pro/        # Premium or advanced plugins (optional)
│   └── [spoutlets]/          # official project spoutlets
│
├── cli_info.py               # Defines CLI interface, docs and options (optional)
├── README.md                 # Module documentation and usage examples (optional)
├── script.ahk                # AutoHotkey integration script
└── spout_(module_name).py    # Main Python handler for the module

Module Component Details

Module Directories

  • options/: Contains configuration files (.txt/.ini) that define:
    • Available prompt templates and variables
    • Module-specific settings and parameters
    • Configuration options for both CLI and GUI interfaces
    • Custom string templates and reusable components
  • tests/: Testing infrastructure for quality assurance:
    • test_cases.json: Defines input test cases and expected outputs
    • test_results.txt: Logs the latest test execution results
    • samples/: Contains example inputs/outputs by generative AI

Spoutlet Template Directories

  • (module_name)_local/:
    • User-specific customizations and overrides
    • Takes highest priority when plugin names overlap
    • Git-ignored to keep personal modifications separate
    • Perfect for creating personal versions of official plugins
  • (module_name)_plugins/:
    • Base project plugins available to all users
    • Contains official, maintained plugin templates
    • lowest priority in name conflicts
    • Distributed with the main repository
  • (module_name)_pro/:
    • Premium or advanced plugins (optional)
    • Second lowest priority in name conflicts
    • Additional functionality beyond base plugins

Module Files

  • cli_info.py:
    • Defines module's command-line interface
    • Required for integrating with Spout's CLI
    • Specifies available flags and options
    • Provides command documentation
  • README.md:
    • Module documentation and examples
    • Usage instructions and best practices
    • Plugin development guidelines
    • Configuration options
  • script.ahk:
    • AutoHotkey integration script
    • Automatically loaded into Spout's GUI
    • Defines hotkeys and custom actions
    • Handles GUI interactions
  • spout_(module_name).py:
    • Main module handler
    • Implements core functionality of spoutlets
    • Provides API for scripting functions and interactions other modules
    • Manages plugin loading and execution

This standardized structure ensures consistency across modules while providing flexibility for customization through the plugin system. The priority system (local > plugins > pro) allows users to safely override and customize functionality while maintaining the ability to update the base system.