Establish Bridge Protocol for MATLAB-Python parity#22
Merged
Conversation
Relocate PYTHON_PORTING_GUIDE.md from repo root to docs/developer_notes/ and replace with updated development documentation covering the lead-follow architecture, bridge protocol, naming conventions, Pydantic validation, and code style requirements. https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1
Add ndi_xlang_principles.md covering indexing/counting parity, data containers, multiple returns, booleans, string handling, error philosophy, and AI agent instructions for maintaining consistency between MATLAB and Python implementations. https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1
Add ndi_matlab_python_bridge.yaml documenting the YAML spec for MATLAB-to-Python bridge files: standard header, active maintenance instructions, class/function structure examples, and field rules. https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1
Define the role, mandatory knowledge base, bridge file protocol, technical constraints, and directory mapping for AI agents working on the NDI MATLAB-to-Python port. https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1
Configure Cursor to follow NDI porting guidelines, strict naming policy, and bridge file active maintenance protocol. https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR establishes a formal "Bridge Protocol" to maintain strict 1:1 functional and semantic parity between the MATLAB source codebase and the Python port. The changes replace a single monolithic porting guide with a modular, contract-driven system centered on YAML bridge files.
Key Changes
Removed:
PYTHON_PORTING_GUIDE.md— The original monolithic guide that mixed high-level philosophy with low-level implementation details.Added: Three New Developer Documentation Files
docs/developer_notes/PYTHON_PORTING_GUIDE.md— Condensed technical workflow guide focused on Pydantic validation, naming rules, and linting requirements.docs/developer_notes/ndi_xlang_principles.md— Universal cross-language principles (0-vs-1 indexing, Semantic Parity for scientific counting, NumPy usage, error handling).docs/developer_notes/ndi_matlab_python_bridge.yaml— YAML specification template defining how bridge files should be structured and maintained.Added: Agent Instructions
AGENTS.md— Role definition and mandatory knowledge base for AI developers, emphasizing the Bridge Protocol and active maintenance of interface contracts..cursorrules— Cursor IDE configuration to enforce the Bridge Protocol during development.Notable Implementation Details
Bridge Protocol: Each sub-package now contains an
ndi_matlab_python_bridge.yamlfile that serves as the binding contract for function names, arguments, and return types. This is the "Primary Contract" that agents must consult and maintain.Active Maintenance Requirement: Agents are explicitly instructed to update bridge files when porting new functions and notify users of interface changes with: "INTERFACE UPDATE: I have modified the bridge contract for [Function Name]."
Semantic Parity Rule: Distinguishes between Computer Science Indexing (0-based for internal Python data structures) and Scientific Counting (1-based for user-facing concepts like Epochs and Channels) to prevent off-by-one errors across platforms.
Strict Naming Policy: Reinforces that MATLAB names are the source of truth and must not be "Pythonized" (e.g.,
ListAllDocumentsstays as-is, notlist_all_documents).Mandatory Knowledge Base: Agents must read files in a specific order:
AGENTS.md→PYTHON_PORTING_GUIDE.md→ndi_xlang_principles.md→ local bridge file.https://claude.ai/code/session_01J2cPiPbCXUV9ofBwjtASd1