# cjm-transcription-plugin-system
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
## Install
``` bash
$ pip install cjm_transcription_plugin_system
```
## Project Structure
nbs/
├── core.ipynb # Core data structures for audio transcription
├── plugin_interface.ipynb # Abstract base class defining the interface for transcription plugins
└── plugin_manager.ipynb # Plugin discovery, loading, and lifecycle management system
Total: 3 notebooks
## Module Dependencies
``` mermaid
graph LR
core[core<br/>core]
plugin_interface[plugin_interface<br/>plugin interface]
plugin_manager[plugin_manager<br/>plugin manager]
plugin_interface --> core
plugin_manager --> plugin_interface
plugin_manager --> core
```
*3 cross-module dependencies detected*
## CLI Reference
No CLI commands found in this project.
## Module Overview
Detailed documentation for each module in the project:
### core (`core.ipynb`)
> Core data structures for audio transcription
#### Import
``` python
from cjm_transcription_plugin_system.core import (
AudioData,
TranscriptionResult
)
```
#### Classes
``` python
@dataclass
class AudioData:
"Container for audio data and metadata."
samples: np.ndarray # Audio sample data as a numpy array
sample_rate: int # Sample rate in Hz (e.g., 16000, 44100)
duration: float # Duration of the audio in seconds
filepath: Optional[Path] # Audio file path
metadata: Dict[str, Any] = field(...) # Additional metadata
```
``` python
@dataclass
class TranscriptionResult:
"Standardized transcription output."
text: str # The transcribed text
confidence: Optional[float] # Overall confidence score (0.0 to 1.0)
segments: Optional[List[Dict]] = field(...) # List of transcription segments with timestamps and text
metadata: Optional[Dict] = field(...) # Transcription metadata
```
### plugin interface (`plugin_interface.ipynb`)
> Abstract base class defining the interface for transcription plugins
#### Import
``` python
from cjm_transcription_plugin_system.plugin_interface import (
PluginInterface,
PluginMeta
)
```
#### Classes
``` python
class PluginInterface(ABC):
"Base interface that all transcription plugins must implement."
def name(
self
) -> str: # The unique identifier for this plugin
"Unique plugin identifier."
def version(
self
) -> str: # The semantic version string (e.g., "1.0.0")
"Plugin version."
def supported_formats(
self
) -> List[str]: # List of file extensions this plugin can process
"List of supported audio formats (e.g., ['wav', 'mp3'])."
def initialize(
self,
config: Optional[Dict[str, Any]] = None # Configuration dictionary for plugin-specific settings
) -> None
"Initialize the plugin with configuration."
def execute(
self,
*args,
**kwargs
) -> Any: # Returns transcription result or plugin-specific output
"Transcribe audio to text."
def is_available(
self
) -> bool: # True if all required dependencies are available
"Check if the plugin's dependencies are available."
def get_config_schema(
self
) -> Dict[str, Any]: # JSON Schema describing configuration options
"Return JSON Schema describing the plugin's configuration options.
The schema should follow JSON Schema Draft 7 specification.
This enables automatic UI generation and validation.
Example:
{
"type": "object",
"properties": {
"model": {
"type": "string",
"enum": ["tiny", "base", "small"],
"default": "base",
"description": "Model size to use"
}
},
"required": ["model"]
}"
def get_current_config(
self
) -> Dict[str, Any]: # Current configuration state
"Return the current configuration state.
This should return the actual configuration being used by the plugin,
which may include defaults not explicitly set by the user."
def validate_config(
self,
config: Dict[str, Any] # Configuration to validate
) -> Tuple[bool, Optional[str]]: # (is_valid, error_message)
"Validate a configuration dictionary against the schema.
Returns:
Tuple of (is_valid, error_message).
If valid, error_message is None."
def get_config_defaults(
self
) -> Dict[str, Any]: # Default values from schema
"Extract default values from the configuration schema.
Returns a dictionary of default values for all properties
that have defaults defined in the schema."
def cleanup(
self
) -> None
"Optional cleanup when plugin is unloaded."
```
``` python
@dataclass
class PluginMeta:
"Metadata about a plugin."
name: str # The plugin's unique identifier
version: str # The plugin's version string
description: str = '' # A brief description of the plugin's functionality
author: str = '' # The plugin author's name or organization
package_name: str = '' # The Python package name containing the plugin
instance: Optional[PluginInterface] # The plugin instance
enabled: bool = True # Whether the plugin is enabled
```
### plugin manager (`plugin_manager.ipynb`)
> Plugin discovery, loading, and lifecycle management system
#### Import
``` python
from cjm_transcription_plugin_system.plugin_manager import (
PluginManager,
get_plugin_config_schema,
get_plugin_config,
update_plugin_config,
validate_plugin_config,
get_all_plugin_schemas,
reload_plugin
)
```
#### Functions
``` python
def get_plugin_config_schema(
self,
plugin_name: str # Name of the plugin
) -> Optional[Dict[str, Any]]: # Configuration schema or None if plugin not found
"""
Get the configuration schema for a plugin.
Returns the JSON Schema that describes all configuration options
available for the specified plugin.
"""
```
``` python
def get_plugin_config(
self,
plugin_name: str # Name of the plugin
) -> Optional[Dict[str, Any]]: # Current configuration or None if plugin not found
"""
Get the current configuration of a plugin.
Returns the actual configuration values being used by the plugin,
including any defaults.
"""
```
``` python
def update_plugin_config(
self,
plugin_name: str, # Name of the plugin
config: Dict[str, Any], # New configuration
merge: bool = True # Whether to merge with existing config or replace entirely
) -> bool: # True if successful, False otherwise
"""
Update a plugin's configuration and reinitialize it.
Args:
plugin_name: Name of the plugin to update
config: New configuration dictionary
merge: If True, merge with existing config. If False, replace entirely.
Returns:
True if configuration was successfully updated, False otherwise.
"""
```
``` python
def validate_plugin_config(
self,
plugin_name: str, # Name of the plugin
config: Dict[str, Any] # Configuration to validate
) -> Tuple[bool, Optional[str]]: # (is_valid, error_message)
"""
Validate a configuration dictionary for a plugin without applying it.
Returns:
Tuple of (is_valid, error_message). If valid, error_message is None.
"""
```
``` python
def get_all_plugin_schemas(
self
) -> Dict[str, Dict[str, Any]]: # Dictionary mapping plugin names to their schemas
"""
Get configuration schemas for all loaded plugins.
Returns a dictionary where keys are plugin names and values are
their configuration schemas.
"""
```
``` python
def reload_plugin(
self,
plugin_name: str, # Name of the plugin to reload
config: Optional[Dict[str, Any]] = None # Optional new configuration
) -> bool: # True if successful, False otherwise
"""
Reload a plugin with optional new configuration.
This is useful when you want to completely restart a plugin,
for example after updating its code during development.
"""
```
#### Classes
``` python
class PluginManager:
def __init__(self,
plugin_interface: Type[PluginInterface] = PluginInterface, # The base class/interface plugins must implement
entry_point_group: str = "transcription.plugins" # The entry point group name for plugin discovery
)
"Manages plugin discovery, loading, and lifecycle."
def __init__(self,
plugin_interface: Type[PluginInterface] = PluginInterface, # The base class/interface plugins must implement
entry_point_group: str = "transcription.plugins" # The entry point group name for plugin discovery
)
"Initialize the plugin manager."
def discover_plugins(
self
) -> List[PluginMeta]: # List of discovered plugin metadata objects
"Discover all installed plugins via entry points.
This method looks for plugins installed as packages that declare
entry points in the specified group."
def load_plugin(
self,
plugin_meta: PluginMeta, # The plugin metadata
config: Optional[Dict[str, Any]] = None # Optional configuration for the plugin
) -> bool: # True if successfully loaded, False otherwise
"Load and initialize a plugin."
def load_plugin_from_module(
self,
module_path: str, # Path to the Python module
config: Optional[Dict[str, Any]] = None # Optional configuration for the plugin
) -> bool: # True if successfully loaded, False otherwise
"Load a plugin directly from a Python module file or package.
Useful for development or local plugins."
def unload_plugin(
self,
plugin_name: str # Name of the plugin to unload
) -> bool: # True if successfully unloaded, False otherwise
"Unload a plugin and call its cleanup method."
def get_plugin(
self,
plugin_name: str # The name of the plugin to retrieve
) -> Optional[PluginInterface]: # The plugin instance if found, None otherwise
"Get a loaded plugin instance by name."
def list_plugins(
self
) -> List[PluginMeta]: # List of metadata for all loaded plugins
"List all loaded plugins."
def execute_plugin(
self,
plugin_name: str, # Name of the plugin to execute
*args, # Arguments to pass to the plugin
**kwargs # Key word arguments to pass to the plugin
) -> Any: # The result of the plugin execution
"Execute a plugin's main functionality."
def enable_plugin(
self,
plugin_name: str # The name of the plugin to enable
) -> bool: # True if plugin was enabled, False if not found
"Enable a plugin."
def disable_plugin(
self,
plugin_name: str # The name of the plugin to disable
) -> bool: # True if plugin was disabled, False if not found
"Disable a plugin without unloading it."
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cj-mills/cjm-transcription-plugin-system",
"name": "cjm-transcription-plugin-system",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Christian J. Mills",
"author_email": "9126128+cj-mills@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/cc/ac/14c83bf98baf820bcbaa63be98c9225257f2d2956b5bc034c802b1f80663/cjm_transcription_plugin_system-0.0.2.tar.gz",
"platform": null,
"description": "# cjm-transcription-plugin-system\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n## Install\n\n``` bash\n$ pip install cjm_transcription_plugin_system\n```\n\n## Project Structure\n\n nbs/\n \u251c\u2500\u2500 core.ipynb # Core data structures for audio transcription\n \u251c\u2500\u2500 plugin_interface.ipynb # Abstract base class defining the interface for transcription plugins\n \u2514\u2500\u2500 plugin_manager.ipynb # Plugin discovery, loading, and lifecycle management system\n\nTotal: 3 notebooks\n\n## Module Dependencies\n\n``` mermaid\ngraph LR\n core[core<br/>core]\n plugin_interface[plugin_interface<br/>plugin interface]\n plugin_manager[plugin_manager<br/>plugin manager]\n\n plugin_interface --> core\n plugin_manager --> plugin_interface\n plugin_manager --> core\n```\n\n*3 cross-module dependencies detected*\n\n## CLI Reference\n\nNo CLI commands found in this project.\n\n## Module Overview\n\nDetailed documentation for each module in the project:\n\n### core (`core.ipynb`)\n\n> Core data structures for audio transcription\n\n#### Import\n\n``` python\nfrom cjm_transcription_plugin_system.core import (\n AudioData,\n TranscriptionResult\n)\n```\n\n#### Classes\n\n``` python\n@dataclass\nclass AudioData:\n \"Container for audio data and metadata.\"\n \n samples: np.ndarray # Audio sample data as a numpy array\n sample_rate: int # Sample rate in Hz (e.g., 16000, 44100)\n duration: float # Duration of the audio in seconds\n filepath: Optional[Path] # Audio file path\n metadata: Dict[str, Any] = field(...) # Additional metadata\n```\n\n``` python\n@dataclass\nclass TranscriptionResult:\n \"Standardized transcription output.\"\n \n text: str # The transcribed text\n confidence: Optional[float] # Overall confidence score (0.0 to 1.0)\n segments: Optional[List[Dict]] = field(...) # List of transcription segments with timestamps and text\n metadata: Optional[Dict] = field(...) # Transcription metadata\n```\n\n### plugin interface (`plugin_interface.ipynb`)\n\n> Abstract base class defining the interface for transcription plugins\n\n#### Import\n\n``` python\nfrom cjm_transcription_plugin_system.plugin_interface import (\n PluginInterface,\n PluginMeta\n)\n```\n\n#### Classes\n\n``` python\nclass PluginInterface(ABC):\n \"Base interface that all transcription plugins must implement.\"\n \n def name(\n self\n ) -> str: # The unique identifier for this plugin\n \"Unique plugin identifier.\"\n \n def version(\n self\n ) -> str: # The semantic version string (e.g., \"1.0.0\")\n \"Plugin version.\"\n \n def supported_formats(\n self\n ) -> List[str]: # List of file extensions this plugin can process\n \"List of supported audio formats (e.g., ['wav', 'mp3']).\"\n \n def initialize(\n self,\n config: Optional[Dict[str, Any]] = None # Configuration dictionary for plugin-specific settings\n ) -> None\n \"Initialize the plugin with configuration.\"\n \n def execute(\n self,\n *args,\n **kwargs\n ) -> Any: # Returns transcription result or plugin-specific output\n \"Transcribe audio to text.\"\n \n def is_available(\n self\n ) -> bool: # True if all required dependencies are available\n \"Check if the plugin's dependencies are available.\"\n \n def get_config_schema(\n self\n ) -> Dict[str, Any]: # JSON Schema describing configuration options\n \"Return JSON Schema describing the plugin's configuration options.\n\nThe schema should follow JSON Schema Draft 7 specification.\nThis enables automatic UI generation and validation.\n\nExample:\n {\n \"type\": \"object\",\n \"properties\": {\n \"model\": {\n \"type\": \"string\",\n \"enum\": [\"tiny\", \"base\", \"small\"],\n \"default\": \"base\",\n \"description\": \"Model size to use\"\n }\n },\n \"required\": [\"model\"]\n }\"\n \n def get_current_config(\n self\n ) -> Dict[str, Any]: # Current configuration state\n \"Return the current configuration state.\n\nThis should return the actual configuration being used by the plugin,\nwhich may include defaults not explicitly set by the user.\"\n \n def validate_config(\n self,\n config: Dict[str, Any] # Configuration to validate\n ) -> Tuple[bool, Optional[str]]: # (is_valid, error_message)\n \"Validate a configuration dictionary against the schema.\n\nReturns:\n Tuple of (is_valid, error_message).\n If valid, error_message is None.\"\n \n def get_config_defaults(\n self\n ) -> Dict[str, Any]: # Default values from schema\n \"Extract default values from the configuration schema.\n\nReturns a dictionary of default values for all properties\nthat have defaults defined in the schema.\"\n \n def cleanup(\n self\n ) -> None\n \"Optional cleanup when plugin is unloaded.\"\n```\n\n``` python\n@dataclass\nclass PluginMeta:\n \"Metadata about a plugin.\"\n \n name: str # The plugin's unique identifier\n version: str # The plugin's version string\n description: str = '' # A brief description of the plugin's functionality\n author: str = '' # The plugin author's name or organization\n package_name: str = '' # The Python package name containing the plugin\n instance: Optional[PluginInterface] # The plugin instance\n enabled: bool = True # Whether the plugin is enabled\n```\n\n### plugin manager (`plugin_manager.ipynb`)\n\n> Plugin discovery, loading, and lifecycle management system\n\n#### Import\n\n``` python\nfrom cjm_transcription_plugin_system.plugin_manager import (\n PluginManager,\n get_plugin_config_schema,\n get_plugin_config,\n update_plugin_config,\n validate_plugin_config,\n get_all_plugin_schemas,\n reload_plugin\n)\n```\n\n#### Functions\n\n``` python\ndef get_plugin_config_schema(\n self,\n plugin_name: str # Name of the plugin\n) -> Optional[Dict[str, Any]]: # Configuration schema or None if plugin not found\n \"\"\"\n Get the configuration schema for a plugin.\n \n Returns the JSON Schema that describes all configuration options\n available for the specified plugin.\n \"\"\"\n```\n\n``` python\ndef get_plugin_config(\n self,\n plugin_name: str # Name of the plugin\n) -> Optional[Dict[str, Any]]: # Current configuration or None if plugin not found\n \"\"\"\n Get the current configuration of a plugin.\n \n Returns the actual configuration values being used by the plugin,\n including any defaults.\n \"\"\"\n```\n\n``` python\ndef update_plugin_config(\n self,\n plugin_name: str, # Name of the plugin\n config: Dict[str, Any], # New configuration\n merge: bool = True # Whether to merge with existing config or replace entirely\n) -> bool: # True if successful, False otherwise\n \"\"\"\n Update a plugin's configuration and reinitialize it.\n \n Args:\n plugin_name: Name of the plugin to update\n config: New configuration dictionary\n merge: If True, merge with existing config. If False, replace entirely.\n \n Returns:\n True if configuration was successfully updated, False otherwise.\n \"\"\"\n```\n\n``` python\ndef validate_plugin_config(\n self,\n plugin_name: str, # Name of the plugin\n config: Dict[str, Any] # Configuration to validate\n) -> Tuple[bool, Optional[str]]: # (is_valid, error_message)\n \"\"\"\n Validate a configuration dictionary for a plugin without applying it.\n \n Returns:\n Tuple of (is_valid, error_message). If valid, error_message is None.\n \"\"\"\n```\n\n``` python\ndef get_all_plugin_schemas(\n self\n) -> Dict[str, Dict[str, Any]]: # Dictionary mapping plugin names to their schemas\n \"\"\"\n Get configuration schemas for all loaded plugins.\n \n Returns a dictionary where keys are plugin names and values are\n their configuration schemas.\n \"\"\"\n```\n\n``` python\ndef reload_plugin(\n self,\n plugin_name: str, # Name of the plugin to reload\n config: Optional[Dict[str, Any]] = None # Optional new configuration\n) -> bool: # True if successful, False otherwise\n \"\"\"\n Reload a plugin with optional new configuration.\n \n This is useful when you want to completely restart a plugin,\n for example after updating its code during development.\n \"\"\"\n```\n\n#### Classes\n\n``` python\nclass PluginManager:\n def __init__(self, \n plugin_interface: Type[PluginInterface] = PluginInterface, # The base class/interface plugins must implement\n entry_point_group: str = \"transcription.plugins\" # The entry point group name for plugin discovery\n )\n \"Manages plugin discovery, loading, and lifecycle.\"\n \n def __init__(self,\n plugin_interface: Type[PluginInterface] = PluginInterface, # The base class/interface plugins must implement\n entry_point_group: str = \"transcription.plugins\" # The entry point group name for plugin discovery\n )\n \"Initialize the plugin manager.\"\n \n def discover_plugins(\n self\n ) -> List[PluginMeta]: # List of discovered plugin metadata objects\n \"Discover all installed plugins via entry points.\n\nThis method looks for plugins installed as packages that declare\nentry points in the specified group.\"\n \n def load_plugin(\n self,\n plugin_meta: PluginMeta, # The plugin metadata\n config: Optional[Dict[str, Any]] = None # Optional configuration for the plugin\n ) -> bool: # True if successfully loaded, False otherwise\n \"Load and initialize a plugin.\"\n \n def load_plugin_from_module(\n self,\n module_path: str, # Path to the Python module\n config: Optional[Dict[str, Any]] = None # Optional configuration for the plugin\n ) -> bool: # True if successfully loaded, False otherwise\n \"Load a plugin directly from a Python module file or package.\nUseful for development or local plugins.\"\n \n def unload_plugin(\n self,\n plugin_name: str # Name of the plugin to unload\n ) -> bool: # True if successfully unloaded, False otherwise\n \"Unload a plugin and call its cleanup method.\"\n \n def get_plugin(\n self,\n plugin_name: str # The name of the plugin to retrieve\n ) -> Optional[PluginInterface]: # The plugin instance if found, None otherwise\n \"Get a loaded plugin instance by name.\"\n \n def list_plugins(\n self\n ) -> List[PluginMeta]: # List of metadata for all loaded plugins\n \"List all loaded plugins.\"\n \n def execute_plugin(\n self,\n plugin_name: str, # Name of the plugin to execute\n *args, # Arguments to pass to the plugin\n **kwargs # Key word arguments to pass to the plugin\n ) -> Any: # The result of the plugin execution\n \"Execute a plugin's main functionality.\"\n \n def enable_plugin(\n self,\n plugin_name: str # The name of the plugin to enable\n ) -> bool: # True if plugin was enabled, False if not found\n \"Enable a plugin.\"\n \n def disable_plugin(\n self,\n plugin_name: str # The name of the plugin to disable\n ) -> bool: # True if plugin was disabled, False if not found\n \"Disable a plugin without unloading it.\"\n```\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "A flexible plugin system for audio transcription intended to make it easy to add support for multiple backends.",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/cj-mills/cjm-transcription-plugin-system"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4477d3adacad9ae21f9122e0a3024765fe2e7bb7a630c490b993abde874dc32f",
"md5": "32ee1d19fa98c9b4557c027e1ff63bd6",
"sha256": "96f74ea953d925af5456b517f680d76a08e82879dbd9bdab9d94c103a4e52d40"
},
"downloads": -1,
"filename": "cjm_transcription_plugin_system-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32ee1d19fa98c9b4557c027e1ff63bd6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17587,
"upload_time": "2025-08-31T20:31:07",
"upload_time_iso_8601": "2025-08-31T20:31:07.673455Z",
"url": "https://files.pythonhosted.org/packages/44/77/d3adacad9ae21f9122e0a3024765fe2e7bb7a630c490b993abde874dc32f/cjm_transcription_plugin_system-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ccac14c83bf98baf820bcbaa63be98c9225257f2d2956b5bc034c802b1f80663",
"md5": "1d7b8cf9fa5cf8486390da7d255a2c5e",
"sha256": "57762df689973aa3a312371ebd001fbc6938388510607f29fab596310667419b"
},
"downloads": -1,
"filename": "cjm_transcription_plugin_system-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1d7b8cf9fa5cf8486390da7d255a2c5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 18193,
"upload_time": "2025-08-31T20:31:08",
"upload_time_iso_8601": "2025-08-31T20:31:08.972150Z",
"url": "https://files.pythonhosted.org/packages/cc/ac/14c83bf98baf820bcbaa63be98c9225257f2d2956b5bc034c802b1f80663/cjm_transcription_plugin_system-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 20:31:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cj-mills",
"github_project": "cjm-transcription-plugin-system",
"github_not_found": true,
"lcname": "cjm-transcription-plugin-system"
}
JSON
