NDR-python/docs/developer_notes/ndr_matlab_python_bridge.yaml at main · VH-Lab/NDR-python · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
# The NDR Bridge Protocol: YAML Specification

# =============================================================================
# 1. File Purpose & Placement
# =============================================================================
# Name:     ndr_matlab_python_bridge.yaml
# Location: One file per sub-package directory
#           (e.g., src/ndr/reader/ndr_matlab_python_bridge.yaml).
# Role:     This is the Primary Contract. It defines how MATLAB names and types
#           map to Python. If a function is not here, it does not officially
#           exist in the Python port.

# =============================================================================
# 2. Standard Header
# =============================================================================
# Every bridge file must begin with this metadata to orient the agent:

project_metadata:
  bridge_version: "1.1"
  naming_policy: "Strict MATLAB Mirror"
  indexing_policy: "Semantic Parity (1-based for user concepts, 0-based for internal data)"

# =============================================================================
# 3. The "Active Maintenance" Instruction
# =============================================================================
# When an agent or developer works on a function:
#
# 1. Check:  Does the function/class exist in the YAML?
# 2. Add/Update: If it is missing or the MATLAB signature has changed,
#    update the YAML first.
# 3. Record Hash: Store the short git hash of the MATLAB .m file being
#    ported in the `matlab_last_sync_hash` field. Obtain the hash with:
#      git log -1 --format="%h" -- <path-to-matlab-file>
# 4. Notify: The agent MUST explicitly tell the user:
#    "I have updated the ndr_matlab_python_bridge.yaml to include
#    [Function Name]. Please review the interface contract."
#
# =============================================================================
# 3a. Detecting Upstream MATLAB Changes
# =============================================================================
# The `matlab_last_sync_hash` field enables efficient change detection:
#
# 1. For each entry, compare `matlab_last_sync_hash` against the current
#    HEAD hash of the corresponding MATLAB .m file:
#      git log -1 --format="%h" -- <matlab_path>
# 2. If the hashes differ, the MATLAB file has changed since the last sync
#    and the Python port may need to be updated.
# 3. After re-syncing, update `matlab_last_sync_hash` to the new hash and
#    record the sync date in `decision_log`.

# =============================================================================
# 4. Structure for Classes and Functions
# =============================================================================

# --- Example: Class ---
# - name: base                        # Exact MATLAB Name
#   type: class
#   matlab_path: "+ndr/+reader/base.m"
#   python_path: "ndr/reader/base.py"
#   python_class: "ndr_reader_base"
#   matlab_last_sync_hash: "a4c9e07"  # Git hash of base.m when last ported/synced
#
#   properties:
#     - name: MightHaveTimeGaps
#       type_matlab: "logical"
#       type_python: "bool"
#       decision_log: "Mirroring property name exactly."
#
#   methods:
#     - name: readchannels_epochsamples
#       input_arguments:
#         - name: channeltype
#           type_matlab: "char"
#           type_python: "str"
#         - name: channel
#           type_matlab: "numeric"
#           type_python: "int | list[int]"
#         - name: epochstreams
#           type_matlab: "cell array of char"
#           type_python: "list[str]"
#         - name: epoch_select
#           type_matlab: "numeric"
#           type_python: "int"
#           decision_log: "Semantic Parity: User provides 1-based ID."
#         - name: s0
#           type_python: "int"
#         - name: s1
#           type_python: "int"
#       output_arguments:
#         - name: data
#           type_matlab: "double | int16 | int32"
#           type_python: "numpy.ndarray"

# --- Example: Standalone Function ---
# - name: ndrpath
#   type: function
#   matlab_path: "+ndr/+fun/ndrpath.m"
#   python_path: "ndr/fun/ndrpath.py"
#   matlab_last_sync_hash: "8f3a2b1"
#   input_arguments: []
#   output_arguments:
#     - name: p
#       type_matlab: "char"
#       type_python: "str"
#   decision_log: "Synchronized with MATLAB main as of 2026-04-11."

# =============================================================================
# 5. Building a New Bridge YAML File
# =============================================================================
# When adding a brand-new sub-package to NDR-python (for example
# `src/ndr/newformat/`), create a fresh `ndr_matlab_python_bridge.yaml`
# next to the Python source using the following procedure:
#
# 1. Create the file at `src/ndr/<namespace>/ndr_matlab_python_bridge.yaml`.
# 2. Start with the Standard Header from Section 2 (copy verbatim).
# 3. For each MATLAB class in `+ndr/+<namespace>/`, add a `classes:` entry with:
#      - `name` (MATLAB class name, e.g. `intan_rhd`)
#      - `type: class`
#      - `matlab_path` (e.g. `"+ndr/+reader/intan_rhd.m"`)
#      - `python_path` (e.g. `"ndr/reader/intan_rhd.py"`)
#      - `python_class` (derived using the Class Name Mirror Rule from
#        `docs/developer_notes/PYTHON_PORTING_GUIDE.md`, e.g.
#        `ndr_reader_intan__rhd`)
#      - `inherits` (if applicable)
#      - `matlab_last_sync_hash` (from `git log -1 --format="%h" -- <matlab_path>`)
#      - `properties:` and `methods:` blocks with `input_arguments` /
#        `output_arguments`, each argument carrying `name`, `type_matlab`, and
#        `type_python`.
# 4. For each standalone MATLAB function, add an entry under `functions:` with
#    the same fields (minus `properties` and `methods`).
# 5. Run `python -c "import yaml, pathlib; yaml.safe_load(pathlib.Path('src/ndr/<namespace>/ndr_matlab_python_bridge.yaml').read_text())"`
#    to validate the YAML parses.
# 6. Notify the user with a one-line summary of the new contract so they can
#    review it before any Python implementation is written.
#
# Refer to `src/ndr/reader/ndr_matlab_python_bridge.yaml` for a concrete,
# non-trivial example covering both `classes:` with inherited methods and
# `static_methods:` blocks.

# =============================================================================
# 6. Summary of Field Rules
# =============================================================================
# Field                | Rule
# ---------------------|----------------------------------------------------------
# name                 | Strict Match. Case-sensitive match to the MATLAB .m file.
# matlab_last_sync_hash| The short git hash of the MATLAB .m file at the time it
#                      | was last examined/ported. Used to detect upstream changes.
# input_arguments      | Used to generate Pydantic @validate_call.
# output_arguments     | Defines the order of the Return Tuple.
# type_python          | Use Python 3.10+ syntax (e.g., str | int).
# decision_log         | Mandatory for any divergence. Should include the sync
#                      | date (e.g., "Synchronized with MATLAB main as of
#                      | 2026-04-11.").