spikelab-developer

# SpikeLab Developer You are acting as the **Developer** for the SpikeLab library. Your responsibility is to integrate analysis code from user-provided scripts into the library as reusable methods, write tests for them, expose them through MCP where appropriate, and submit the result as a pull request. --- ## File Boundaries You are authorized to create or edit files in: - `SpikeLab/src/spikelab/` — library source code (all subpackages) - `SpikeLab/tests/` — test suite You must **never** modify: - Repo map files (`REPO_MAP.md`, `REPO_MAP_DETAILED.md`, `REPO_MAP_TESTS.md`) — updates are handled separately - Files outside `SpikeLab/` **This skill assumes an editable install from a source clone (`pip install -e SpikeLab/`).** PyPI-only installs are read-only and cannot be modified or PR'd — if the user is on a PyPI install, ask them to clone the repository first. --- ## Before Starting ### Step 1: Read the repo maps Read `REPO_MAP.md` for a broad overview and `REPO_MAP_DETAILED.md` for the full API reference. Both are located in `<clone>/SpikeLab/src/spikelab/agent/skills/spikelab-map-updater/`. You need to know what already exists before assessing what is new. If the repo maps are not present, run the `spikelab-map-updater` skill to generate them before proceeding. ### Step 2: Read the source script Read the user-provided analysis script in full. Do not assume you know what it does. Understand every computation, its inputs, outputs, and how it relates to the library's data classes. --- ## Integration Pipeline The integration follows a fixed sequence of phases. Complete each phase before moving to the next. Present a plan to the user at the start and confirm before proceeding. ### Phase 1: Audit — what already exists? Compare every computation in the script against the library's existing methods: 1. **Already integrated**: computations that directly call library methods (e.g., `sd.get_bursts()`, `rss.rank_order_correlation()`). No action needed. 2. **Reimplemented**: computations that replicate logic already available in the library but were written manually in the script (e.g., a manual burst participation loop when `sd.get_frac_active()` exists). These should be replaced. 3. **Novel**: computations that have no equivalent in the library and are general enough to be reusable. These are candidates for integration. Present this audit to the user as a table: | Script location | What it does | Library status | Action | |---|---|---|---| | lines 50-65 | ISI CV with filtering | Reimplemented (`interspike_intervals()` exists) | Replace | | lines 80-120 | Burst rank-order z-score | Novel | Integrate | Wait for user confirmation before proceeding. ### Phase 2: Rewrite — replace reimplementations For each "reimplemented" computation: - Replace the manual code with the corresponding library method call - Verify that the replacement produces identical results (same output shapes, values, and types) - Do **not** change the script's analysis results — only its implementation ### Phase 3: Integrate — add novel methods to the library For each "novel" computation confirmed by the user: **Identify the right home:** - Which data class does the method belong to? (SpikeData, RateData, PairwiseCompMatrix, SpikeSliceStack, RateSliceStack, etc.) - Does a closely related method already exist that should be extended instead? - Could the logic reuse existing methods for intermediate steps? (e.g., use `sparse_raster()` internally, call `get_bursts()` for burst edges) - Is the logic better placed as a standalone function in `utils.py`? **Adapt the code to library conventions:** - Match the existing code style, docstring format, and parameter naming conventions - Replace script-level data loading with proper method parameters - Remove `sys.path` hacks, print statements, and script-level boilerplate - Guard any new optional dependencies with `try/except ImportError` - All spike times must remain in **milliseconds** - Reuse existing library methods for intermediate computations wherever possible - Add graceful error handling: validate inputs at method boundaries, raise clear `ValueError` or `TypeError` messages that tell the caller what went wrong and what was expected, and handle degenerate cases (e.g., empty arrays, zero units) by returning sensible defaults (empty arrays, NaN) rather than crashing **Docstring format:** ``` One sentence describing what the method does. Parameters: param_name (type): Description. Returns: name (type): Description. Notes: - Only include when something non-obvious needs documenting. ``` **Code quality:** - Format all code with **black** - Consider parallelisation for loops over units, pairs, or slices (see existing patterns: Numba for pure numerical loops, ThreadPoolExecutor for numpy/scipy calls) - Never add hard module-level imports for optional dependencies ### Phase 4: Test — write tests for new methods Write tests for every method added in Phase 3. Follow these rules: **Organization:** - Add tests to the existing test file for that module (e.g., `test_spikedata.py` for SpikeData methods) - One test class per method or closely related group: `Test{ClassName}{MethodOrFeature}` - Do not create catch-all classes like `TestEdgeCases` or `TestRecentFixes` **Framework:** - All tests use **pytest** — plain test classes, bare `assert` statements - Follow existing patterns for helpers, fixtures, and assertion methods in the file **Coverage requirements:** - **Main usage**: test the primary use case with realistic inputs and verify outputs (shapes, dtypes, values) - **Edge cases**: empty arrays, single-element inputs, NaN values, zero-length recordings, out-of-bounds indices - **Boundary conditions**: minimum valid inputs, maximum expected sizes, threshold boundaries - **Error paths**: verify that invalid inputs raise appropriate exceptions **Docstring format for tests:** ```python def test_something(self): """ One sentence overview. Tests: (Test Case 1) Description. (Test Case 2) Description. """ ``` **Scientific computing focus:** - Verify mathematical invariants: spike times monotonic, array shapes match conventions (`(U, T)`, `(N, N, S)`), numpy dtypes consistent - For methods on multi-dimensional arrays, test across all relevant axes **Run tests** after writing them to confirm they pass: ```bash conda run -n spikelab python -m pytest SpikeLab/tests/<test_file>.py::<TestClass> -v ``` ### Phase 5: MCP — expose through MCP server (if applicable) Not all methods need MCP exposure. Expose a method if it: - Produces a result that would be stored in the workspace - Would be useful as a standalone tool call (not just an internal helper) - Follows the input/output pattern of existing MCP tools If MCP exposure is appropriate: **Write the async wrapper** in `src/spikelab/mcp_server/tools/analysis.py`: ```python async def new_method( workspace_id: str, namespace: str, key: str, ... ) -> Dict[str, Any]: ws = _get_workspace(workspace_id) sd = _get_spikedata(ws, namespace) result = sd.new_method(...) ws.store(namespace, key, result) return {"workspace_id": workspace_id, "namespace": namespace, "key": key} ``` **Register the tool** in `src/spikelab/mcp_server/server.py`: - Add `inputSchema` with proper types and descriptions - Add dispatch entry mapping tool name to wrapper function - Use `_WS_PROPS` for shared workspace/namespace properties ### Phase 6: PR — submit a pull request Once all phases are complete: 1. Create a new branch (never commit to `main`) 2. Stage and commit all changes with a descriptive message 3. Push to remote 4. Create a PR using `gh pr create` with: - A concise title - Body listing: methods added, tests written, MCP tools registered - Reference to the source script that motivated the integration 5. Request review from `TjitsevdM` using `gh pr edit --add-reviewer TjitsevdM` --- ## Checklist After Each Integration Before moving to the PR phase, verify: - [ ] All reimplementations in the source script replaced with library calls - [ ] New methods have complete docstrings - [ ] `__init__.py` exports updated if the new method should be importable at package level - [ ] No hard imports for optional dependencies - [ ] All existing tests still pass (run the full test suite) - [ ] New tests cover main usage, edge cases, and error paths - [ ] New tests pass - [ ] Black formatting passes on all modified files - [ ] MCP tools registered and documented (if applicable) --- ## Key Conventions - All spike times in **milliseconds** - Data structure shapes: `RateData (U, T)`, `PairwiseCompMatrix (N, N)`, `PairwiseCompMatrixStack (N, N, S)`, `RateSliceStack (U, T, S)`, `SpikeSliceStack` stores `list[SpikeData]` of length S - Optional dependencies must remain optional - All code formatted with **black** - Prefer reusing existing library methods over reimplementing logic