Add MATLAB-Python bridge contracts for ndi.daq namespace

[stevevanhooser]

Summary

This PR introduces comprehensive MATLAB-Python bridge contracts for the ndi.daq namespace and its submodules. These YAML-based contracts define the interface specifications, type mappings, and semantic parity requirements between MATLAB and Python implementations.

Key Changes

• Main bridge contract (src/ndi/daq/ndi_matlab_python_bridge.yaml): Defines the primary contract for the ndi.daq namespace including:

  • Standalone utility functions (standardize_channel_type, standardize_channel_types)
  • Enums and dataclasses (ChannelType, ChannelInfo)
  • Core classes: DAQSystemString, DAQReader (base), MFDAQReader, and DAQSystem
  • Comprehensive method signatures with input/output type specifications
  • Semantic parity rules for 1-indexed user concepts vs 0-indexed internal data

• Reader submodule contract (src/ndi/daq/reader/ndi_matlab_python_bridge.yaml): Specifies contracts for:

  • SpikeInterfaceReader class (Python-specific adapter)
  • Helper functions for multi-format data access

• MFDAQ reader contract (src/ndi/daq/reader/mfdaq/ndi_matlab_python_bridge.yaml): Defines format-specific readers:

  • IntanReader for Intan RHD/RHS files
  • BlackrockReader for Blackrock NSx/NEV files
  • CEDSpike2Reader for CED Spike2 SMR/SMRX files
  • All delegate to SpikeInterfaceReader for actual data access

• Metadata reader contract (src/ndi/daq/metadatareader/ndi_matlab_python_bridge.yaml): Specifies:

  • Base MetadataReader class for TSV-based metadata
  • NewStimStimsReader for NewStim stimulus metadata
  • NielsenLabStimsReader for Nielsen Lab stimulus metadata

• Minor import cleanup in src/ndi/daq/metadatareader/__init__.py: Simplified type imports to use Any instead of specific type hints.

Notable Implementation Details

• Naming Policy: "Strict MATLAB Mirror" - Python class names and methods closely mirror MATLAB equivalents
• Indexing Policy: "Semantic Parity (1-based for user concepts, 0-based for internal data)" - User-facing APIs use 1-based indexing while internal implementations use 0-based
• Bridge Version: 1.1 - Supports comprehensive type specifications and decision logging
• Decision Logs: Each method/property includes rationale for design choices and MATLAB-Python mapping decisions
• Type Safety: Extensive use of Python type hints (str, int, float, list, dict, np.ndarray, etc.) with optional/union types where applicable

https://claude.ai/code/session_01N4hGaSLpdwZyNUFYHccwq9