Skip to content

Commit 842583c

Browse files
BB-84CBB-84C
committed
1
1 parent 1e36d36 commit 842583c

File tree

2 files changed

+193
-0
lines changed

2 files changed

+193
-0
lines changed

‎docs/plans/2026-02-25-parameter-schema-streamline-methods-only-design.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Parameter Schema Streamline (Methods-Only) Design
2+
3+
Date: 2026-02-25
4+
5+
## Goal
6+
7+
Streamline parameter schema and runtime contract to structured methods-only IO.
8+
9+
- Remove top-level parameter keys: `unit`, `value_type`, `vals`, `snapshot_value`.
10+
- Stop exposing scalar QCodes parameters as the primary interface.
11+
- Route runtime behavior through `arg_fields` / `response_fields` for all commands.
12+
13+
## Decision
14+
15+
Adopt Option 1 (hard migration):
16+
17+
- Methods-only runtime contract, even for single-argument commands.
18+
- Accept API breaks now (pre-production).
19+
20+
## Current coupling to remove
21+
22+
- `snapshot_value` is currently only passed into QCodes `add_parameter` registration.
23+
- `value_type` and `vals` currently drive scalar coercion and QCodes validators.
24+
- `unit` currently appears in scalar-oriented parameter output.
25+
26+
With methods-only contract, these top-level scalar parameter descriptors become redundant.
27+
28+
## Target contract
29+
30+
### Schema (`parameters` entries)
31+
32+
Keep:
33+
34+
- `label`
35+
- `get_cmd` (`command`, `description`, `arg_fields`, `response_fields`)
36+
- `set_cmd` (`command`, `description`, `arg_fields`)
37+
- `safety`
38+
39+
Remove:
40+
41+
- `unit`
42+
- `value_type`
43+
- `vals`
44+
- `snapshot_value`
45+
46+
### Runtime API
47+
48+
Primary methods:
49+
50+
- `get_parameter_snapshot(name)`
51+
- `set_parameter_fields(name, args=..., plan_only=...)`
52+
- `execute_action(name, args=..., plan_only=...)`
53+
54+
No scalar-first behavior assumptions.
55+
56+
### CLI payload
57+
58+
`nqctl capabilities` parameter items should expose only structured command metadata and safety.
59+
No scalar schema keys listed above.
60+
61+
## Migration rules
62+
63+
- Generator stops emitting removed top-level keys.
64+
- Loader accepts legacy files containing removed keys (ignore) for transition.
65+
- CLI and driver logic must avoid reading removed keys.
66+
67+
## Risks
68+
69+
- Breaking downstream code using `instrument.<param>()` scalar API.
70+
- Test churn due to broad contract updates.
71+
72+
Accepted per project stage (development/testing).
73+
74+
## Validation
75+
76+
- Update tests to assert methods-only structured behavior.
77+
- Verify full suite after schema and runtime changes.

‎docs/plans/2026-02-25-parameter-schema-streamline-methods-only-implementation.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Parameter Schema Streamline (Methods-Only) Implementation Plan
2+
3+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+
**Goal:** Remove scalar-oriented parameter schema keys (`unit`, `value_type`, `vals`, `snapshot_value`) and migrate runtime/CLI/QCodes behavior to fully structured methods-only command execution.
6+
7+
**Architecture:** Shift parameter semantics to command metadata only (`arg_fields`/`response_fields` + safety). Remove QCodes scalar registration path and expose structured method APIs as the authoritative interface for reads/writes/actions. Keep loader backward-compatible with old YAML by ignoring removed keys.
8+
9+
**Tech Stack:** Python, QCodes driver layer, YAML manifest generator/loader, pytest.
10+
11+
---
12+
13+
### Task 1: Add failing tests for methods-only schema and capabilities payload
14+
15+
**Files:**
16+
- Modify: `tests/test_cli.py`
17+
- Modify: `tests/test_qcodes_extensions.py`
18+
- Modify: `tests/test_parameter_manifest_generator.py`
19+
20+
**Step 1:** Add tests asserting generated parameters no longer include top-level `unit`, `value_type`, `vals`, `snapshot_value`.
21+
22+
**Step 2:** Add tests asserting `nqctl capabilities` parameter items omit the same keys.
23+
24+
**Step 3:** Add loader tests to ensure legacy keys are accepted/ignored (backward-compatible parse).
25+
26+
**Step 4:** Run focused tests (expected fail initially):
27+
28+
Run: `python -m pytest tests/test_cli.py tests/test_qcodes_extensions.py tests/test_parameter_manifest_generator.py -q`
29+
30+
### Task 2: Remove scalar keys from generator and emitted manifest
31+
32+
**Files:**
33+
- Modify: `nanonis_qcodes_controller/qcodes_driver/manifest_generator.py`
34+
- Modify: `config/parameters.yaml` (regenerated)
35+
- Modify: `nanonis_qcodes_controller/resources/config/parameters.yaml` (synced)
36+
37+
**Step 1:** Stop emitting top-level parameter keys: `unit`, `type/value_type`, `vals`, `snapshot_value`.
38+
39+
**Step 2:** Keep generated parameter entries limited to `label`, `get_cmd`, `set_cmd`, `safety`.
40+
41+
**Step 3:** Regenerate `config/parameters.yaml` and sync packaged copy.
42+
43+
**Step 4:** Run focused generator tests:
44+
45+
Run: `python -m pytest tests/test_parameter_manifest_generator.py -q`
46+
47+
### Task 3: Update loader model to structured-only parameter contract
48+
49+
**Files:**
50+
- Modify: `nanonis_qcodes_controller/qcodes_driver/extensions.py`
51+
- Modify: `nanonis_qcodes_controller/qcodes_driver/__init__.py`
52+
- Test: `tests/test_qcodes_extensions.py`
53+
54+
**Step 1:** Make parameter dataclass optional/default for removed scalar keys and ensure runtime logic does not require them.
55+
56+
**Step 2:** Parser should ignore legacy keys when present and construct structured specs from command blocks.
57+
58+
**Step 3:** Update tests for both minimal new schema and legacy compatibility.
59+
60+
**Step 4:** Run focused tests:
61+
62+
Run: `python -m pytest tests/test_qcodes_extensions.py -q`
63+
64+
### Task 4: Remove scalar QCodes parameter registration path
65+
66+
**Files:**
67+
- Modify: `nanonis_qcodes_controller/qcodes_driver/instrument.py`
68+
- Test: `tests/test_qcodes_driver.py`
69+
70+
**Step 1:** Replace `_register_parameters` scalar `add_parameter` behavior with methods-only interface (no scalar parameter assumptions).
71+
72+
**Step 2:** Ensure reads/writes route exclusively through:
73+
- `get_parameter_snapshot`
74+
- `set_parameter_fields`
75+
- `execute_action`
76+
77+
**Step 3:** Update any internal logic still using `value_type`/`vals`-derived scalar conversion to field-type-driven conversion.
78+
79+
**Step 4:** Add tests that multi-arg commands are fully handled and all fields are considered (not first or first-k only).
80+
81+
**Step 5:** Run focused tests:
82+
83+
Run: `python -m pytest tests/test_qcodes_driver.py -q`
84+
85+
### Task 5: Update CLI payload and docs for streamlined schema
86+
87+
**Files:**
88+
- Modify: `nanonis_qcodes_controller/cli.py`
89+
- Modify: `README.md`
90+
- Modify: `docs/cli_contract.md` (if contract examples include removed keys)
91+
- Test: `tests/test_cli.py`
92+
93+
**Step 1:** Remove removed scalar keys from capabilities payload serialization.
94+
95+
**Step 2:** Keep CLI `get/set/act` output structured and field-driven.
96+
97+
**Step 3:** Update docs to reflect methods-only schema shape.
98+
99+
**Step 4:** Run focused tests:
100+
101+
Run: `python -m pytest tests/test_cli.py tests/test_docs_parameters_manifest.py tests/test_release_docs.py -q`
102+
103+
### Task 6: Full verification and release-readiness check
104+
105+
**Files:**
106+
- Verify all modified files
107+
108+
**Step 1:** Run lint/format/type checks:
109+
- `ruff check .`
110+
- `black --check .`
111+
- `mypy nanonis_qcodes_controller`
112+
113+
**Step 2:** Run full test suite:
114+
- `python -m pytest $(git ls-files "tests/*.py")`
115+
116+
**Step 3:** If all pass, summarize breaking changes explicitly for release notes.

0 commit comments

Comments
 (0)