Feature: Instrument Parameter Masking for AI Context Optimization and Safety

[caidish]

Summary

Add a configuration-driven parameter masking system that allows users to define which QCodes instrument parameters the AI can access, along with safety constraints (validators, step, inter_delay). This serves two purposes:

1. Context window optimization - Reduce token usage by exposing only relevant parameters
2. Safety guardrails - Constrain what values the AI can set and how it changes them

Motivation

QCodes instruments like the SR860 lock-in amplifier have dozens of parameters, but for a specific experiment, an AI might only need a few. Currently, qcodes_instrument_info returns all parameters, wasting context window space and potentially exposing parameters the AI shouldn't modify.

Proposed Solution

Configuration Schema

# ~/.instrmcp/instrument_masks.yaml
masks:
  SR860:
    description: "Lock-in amplifier - safe AI access"
    parameters:
      frequency:
        readable: true
        writable: true
        validator:
          type: range
          min: 1
          max: 100000
        step: 1.0
        inter_delay: 0.01
      
      sensitivity:
        readable: true
        writable: true
        validator:
          type: enum
          values: [1e-9, 1e-8, 1e-7, 1e-6, 1e-5, 1e-4]
      
      X:
        readable: true
        writable: false  # AI can read, not write
      
      time_constant:
        readable: true
        writable: true
        validator:
          type: enum
          values: [0.001, 0.003, 0.01, 0.03, 0.1, 0.3, 1.0]
        inter_delay: 0.5  # enforce slow changes

Enforcement Architecture

AI Request → MCP Tool → Mask Policy Check → QCodes Driver
                              ↓
                    - Is parameter in mask?
                    - Is operation allowed (read/write)?
                    - Does value pass validator?
                    - Apply step/inter_delay if defined

Key Design Decisions

Aspect	Recommendation	Rationale
Enforcement location	MCP layer (not QCodes)	Non-invasive, explicit policy, reject before hardware
Validator format	Simple YAML (range/enum/regex)	Easy to write, no Python knowledge needed
Step/delay handling	MCP sets on QCodes param, then calls set()	Leverage QCodes ramping logic

Validator Types

• range: {type: range, min: X, max: Y}
• enum: {type: enum, values: [...]}
• regex: {type: regex, pattern: "..."} (for string parameters)

Implementation Plan

Files to Modify/Create

1. instrmcp/config/instrument_masks.yaml - Default masks for common instruments
2. instrmcp/utils/mask_config.py - Config loader and validator
3. instrmcp/servers/jupyter_qcodes/core/qcodes.py - Add filtering to existing tools
4. New tool or modify qcodes_set_parameter to enforce constraints

New/Modified Tools

• qcodes_instrument_info - Filter response based on mask
• qcodes_get_parameter_values - Only return masked parameters
• qcodes_set_parameter - Validate against mask policy before setting
• qcodes_list_masks (optional) - Show available masks
• qcodes_apply_mask (optional) - Dynamically apply/remove masks

CLI Commands

instrmcp mask list              # List available masks
instrmcp mask show SR860        # Show mask details
instrmcp mask validate          # Validate mask config
instrmcp mask init              # Create user mask file

Benefits

1. Context reduction - AI only sees relevant parameters (potentially 10x fewer tokens)
2. Safety guardrails - AI cannot exceed user-defined bounds
3. Controlled ramping - Step/delay enforced automatically
4. Audit trail - Clear config showing what AI can/cannot do
5. User control - Experimentalist defines the policy, not the AI
6. Shareable configs - Teams can share instrument masks

Open Questions

• Should masks be per-instrument-instance or per-instrument-type?
• How to handle instruments not in the mask config? (allow all / deny all / warn)
• Should we ship default masks for common instruments (Keithley, SR860, etc.)?
• Integration with existing safe/unsafe mode?

Related

• Follows existing pattern of metadata_baseline.yaml for tool descriptions
• Complements existing safe mode (read-only) with finer-grained control