05_00_14 - Interfaces

Integration interfaces for connecting the Catalog Registry with other subsystems.

Overview

Provides: 1. Symlinks - Link registry database and APIs to other subsystems 2. CMake Connector - CMake functions for C++ integration 3. Python Connector - High-level Python wrapper for easy integration

Directory Structure

05_00_14_interfaces/
├── create_symlinks.py          # Symlink creation/management script
├── connectors/
│   ├── cmake_connector.cmake   # CMake integration functions
│   └── python_connector.py     # Python integration wrapper
└── README.md                   # This file

Symlink System

Creating Symlinks

# Dry run (see what would be created)
python create_symlinks.py create --dry-run

# Create symlinks
python create_symlinks.py create

# Verify symlinks
python create_symlinks.py verify

# Remove symlinks
python create_symlinks.py remove

Symlink Map

The script creates the following symlinks:

Database Links: - 05_01_HIERARCHY_FRAMEWORK/.registry.db → 05_00_00_core_database/registry.db - 05_04_KERNELS_L0/.registry.db → 05_00_00_core_database/registry.db - 05_07_ATOMS_L1/.registry.db → 05_00_00_core_database/registry.db - 05_10_CELLS_L2/.registry.db → 05_00_00_core_database/registry.db - 05_13_ENGINES_L3/.registry.db → 05_00_00_core_database/registry.db - 05_27_IMPLEMENTATIONS/.registry.db → 05_00_00_core_database/registry.db

Python API Links: - 05_01_HIERARCHY_FRAMEWORK/audiolab_registry.py → Python API - 05_27_IMPLEMENTATIONS/audiolab_registry.py → Python API

C++ API Links: - 05_04_KERNELS_L0/audiolab_registry.hpp → C++ API - 05_07_ATOMS_L1/audiolab_registry.hpp → C++ API - 05_10_CELLS_L2/audiolab_registry.hpp → C++ API - 05_13_ENGINES_L3/audiolab_registry.hpp → C++ API

Manifest Schema Links: - 05_04_KERNELS_L0/manifest_schema.json → Schema - 05_07_ATOMS_L1/manifest_schema.json → Schema - 05_10_CELLS_L2/manifest_schema.json → Schema - 05_13_ENGINES_L3/manifest_schema.json → Schema

Validation Engine Links: - 05_27_IMPLEMENTATIONS/validation_engine.py → Validation engine

CMake Connector

Installation

# Include in your CMakeLists.txt
include(/path/to/05_00_14_interfaces/connectors/cmake_connector.cmake)

Functions

audiolab_add_module

Register a module with the registry:

audiolab_add_module(my_filter
    VERSION 1.0.0
    LEVEL L1_ATOM
    CATEGORY FILTER
    MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.yaml
)

This will: - Validate the manifest on build - Auto-index the module on install - Add registry include directories

audiolab_find_module

Query registry for a module:

audiolab_find_module(svf_filter SVF_FILTER_PATH)

if(SVF_FILTER_PATH)
    message("Found SVF Filter: ${SVF_FILTER_PATH}")
else()
    message("SVF Filter not found")
endif()

audiolab_get_dependencies

Get module dependencies:

audiolab_get_dependencies(my_module DEPS)

foreach(DEP ${DEPS})
    message("Dependency: ${DEP}")
endforeach()

Variables

After including cmake_connector.cmake, these variables are available:

• AUDIOLAB_REGISTRY_ROOT - Registry root path
• AUDIOLAB_REGISTRY_DB - Database file path
• AUDIOLAB_REGISTRY_INCLUDE - C++ API include path
• AUDIOLAB_REGISTRY_PYTHON - Python API path
• AUDIOLAB_MANIFEST_SCHEMA - Manifest schema path
• AUDIOLAB_VALIDATION_ENGINE - Validation engine path
• AUDIOLAB_AUTO_INDEXER - Auto-indexer path

Example CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(MyAudioModule)

# Include AudioLab connector
include(${CMAKE_SOURCE_DIR}/../05_00_CATALOG_REGISTRY/05_00_14_interfaces/connectors/cmake_connector.cmake)

# Add executable
add_executable(my_filter src/main.cpp)

# Register with AudioLab
audiolab_add_module(my_filter
    VERSION 1.0.0
    LEVEL L1_ATOM
    CATEGORY FILTER
    MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.yaml
)

# Get dependencies
audiolab_get_dependencies(biquad_filter BIQUAD_DEPS)
message("Biquad dependencies: ${BIQUAD_DEPS}")

Python Connector

Installation

import sys
sys.path.insert(0, '/path/to/05_00_14_interfaces/connectors')
from python_connector import AudioLabConnector

Or use convenience functions:

from python_connector import quick_search, find_module, validate

Usage Examples

Basic Usage

from python_connector import AudioLabConnector

# Connect to registry
connector = AudioLabConnector()

# Find modules
filters = connector.find_modules(category='FILTER', level='L1_ATOM')
for module in filters:
    print(f"{module.name} - {module.cpu_cycles} cycles")

# Get specific module
svf = connector.get_module('svf_filter', '1.0.0')
print(f"{svf.name}: {svf.description}")

# Close connection
connector.close()

Context Manager

with AudioLabConnector() as connector:
    results = connector.search('resonant filter', category='FILTER')
    for module in results:
        print(module.name)

Dependency Management

connector = AudioLabConnector()

# Get dependencies
deps = connector.get_dependencies('eq_cell', recursive=True)
print(f"Dependencies: {deps}")

# Get dependents
dependents = connector.get_dependents('biquad_filter')
print(f"Modules using biquad: {dependents}")

# Calculate build order
order = connector.get_build_order(['eq_cell', 'biquad_filter', 'svf_filter'])
print(f"Build order: {order}")

# Check for cycles
has_cycle = connector.check_cycles(['module_a', 'module_b'])
if has_cycle:
    print("⚠️ Circular dependency detected!")

Manifest Validation

from pathlib import Path

connector = AudioLabConnector()

# Validate single manifest
result = connector.validate_manifest(Path('manifest.yaml'))
if result['is_valid']:
    print("✅ Valid manifest")
else:
    print(f"❌ Errors: {result['errors']}")

# Validate entire project
project_result = connector.validate_project(Path('.'))
print(f"Valid: {project_result['valid']}/{project_result['total']}")

Auto-Indexing

connector = AudioLabConnector()

# Index entire project
result = connector.index_project(Path('.'), incremental=True)
print(f"Processed: {result['processed']}")
print(f"Skipped: {result['skipped']}")
print(f"Errors: {result['errors']}")

# Index single manifest
success = connector.index_manifest(Path('manifest.yaml'))
if success:
    print("✅ Indexed successfully")

Performance Queries

connector = AudioLabConnector()

# Get performance metrics
perf = connector.get_performance('svf_filter')
print(f"CPU: {perf['cpu_cycles_per_sample']} cycles/sample")
print(f"Memory: {perf['memory_kb']} KB")

# Compare modules
comparison = connector.compare_performance('svf_filter', 'biquad_filter')
print(f"CPU difference: {comparison['cpu_cycles_diff_percent']:.1f}%")

# Find efficient modules
efficient = connector.find_efficient_modules(cpu_max=50, category='FILTER')
for module in efficient:
    print(f"{module.name}: {module.cpu_cycles} cycles")

Statistics

connector = AudioLabConnector()

# Get stats
stats = connector.get_stats()
print(f"Total modules: {stats['total_modules']}")
print(f"By level: {stats['by_level']}")

# Get summary
print(connector.get_summary())

Convenience Functions

For quick one-off operations:

from python_connector import quick_search, find_module, validate

# Quick search
filters = quick_search('resonant', category='FILTER')

# Quick lookup
svf = find_module('svf_filter')

# Quick validation
is_valid = validate(Path('manifest.yaml'))

API Reference

AudioLabConnector

Constructor: - __init__(db_path=None, auto_connect=True)

Module Search: - find_modules(category=None, level=None, tag=None, cpu_max=None, limit=100) - get_module(name, version=None) - search(query, category=None)

Dependencies: - get_dependencies(module_name, version=None, recursive=True) - get_dependents(module_name, version=None) - get_build_order(modules) - check_cycles(modules)

Validation: - validate_manifest(manifest_path) - validate_project(project_path)

Auto-Indexing: - index_project(project_path, incremental=True, pattern="**/manifest.yaml") - index_manifest(manifest_path)

Performance: - get_performance(module_name, version=None) - compare_performance(module_a, module_b) - find_efficient_modules(cpu_max=100, category=None)

Statistics: - get_stats() - get_summary()

Lifecycle: - connect() - close() - Context manager support (with statement)

Integration Examples

Example 1: Build System Integration

# build_system.py
from python_connector import AudioLabConnector

def build_modules(module_names):
    """Build modules in correct dependency order"""
    with AudioLabConnector() as connector:
        # Get build order
        build_order = connector.get_build_order(module_names)

        # Build each module
        for module_name in build_order:
            module = connector.get_module(module_name)
            print(f"Building {module.name} v{module.version}...")
            # ... build logic ...

build_modules(['eq_cell', 'reverb_engine'])

Example 2: Performance Monitoring

# perf_monitor.py
from python_connector import AudioLabConnector

def monitor_performance():
    """Monitor and report on module performance"""
    with AudioLabConnector() as connector:
        # Find slow modules
        all_modules = connector.find_modules()

        slow_modules = []
        for module in all_modules:
            if module.cpu_cycles and module.cpu_cycles > 200:
                slow_modules.append(module)

        # Report
        if slow_modules:
            print("⚠️ High CPU modules:")
            for module in sorted(slow_modules, key=lambda m: m.cpu_cycles, reverse=True):
                print(f"  {module.name}: {module.cpu_cycles} cycles/sample")

monitor_performance()

Example 3: CI/CD Validation

# ci_validation.py
import sys
from pathlib import Path
from python_connector import AudioLabConnector

def validate_ci():
    """Validate all manifests in CI pipeline"""
    connector = AudioLabConnector()

    # Validate project
    result = connector.validate_project(Path('.'))

    # Print results
    print(f"Validated {result['total']} manifests")
    print(f"✅ Valid: {result['valid']}")
    print(f"❌ Invalid: {result['invalid']}")

    # Print errors
    for detail in result['details']:
        if not detail['valid']:
            print(f"\n{detail['path']}:")
            for error in detail['errors']:
                print(f"  - {error}")

    # Exit with error if any invalid
    sys.exit(0 if result['invalid'] == 0 else 1)

if __name__ == '__main__':
    validate_ci()

Deliverables

• ✅ Symlink creation/management script
• ✅ CMake connector with 3 functions
• ✅ Python connector with comprehensive API
• ✅ Complete documentation with examples
• ✅ Integration patterns for common use cases

Status

COMPLETE - All interfaces implemented and documented