Motor Control¶

Motor Control — mvp.motor_control

Cluster: Physical AI | Type: component | MCP Tools: 28

Overview¶

Action-safety metaphor, not physical motor control

motor_control gates software actions using an impedance-style confidence model. It does not send commands to physical motors.

Impedance-style action gating block that governs simulated software action execution through a stiffness/damping model and a human-in-the-loop safety gate. Maintains a library of reusable action primitives, records motor memory for sequence replay, and enforces a safe-state fallback when risk thresholds are exceeded. Action types span file writes, code execution, API calls, PLC writes, and G-code execution - all subject to impedance and approval checks, but returned execution is simulated.

When to use:

Dry-running high-risk software, G-code, or PLC-style actions before a separate executor performs real side effects
Tuning stiffness/damping parameters to model confidence and conservatism in an action pipeline
Recording and replaying named action sequences across sessions via motor memory

Example:

from mvp.motor_control import MotorControlBlock, MotorControlInput

block = MotorControlBlock(name="motor_control")
result = block.infer(MotorControlInput(
    op="safety_check",
    action_type="gcode_execute",
    action_params={"gcode": "G0 X10 Y10 Z5"},
))
# result.value.safety_approved -> bool; result.value.safety_reason -> str

Works well with: action_gating, integration

Public API¶

`MotorControlBlock(AIBlock[MotorControlInput, MotorControlOutput, dict])`¶

Impedance-based motor control block (15 ops).

Field	Type	Default
`name`	`str`	'motor_control'
`state`	`dict`	field(default_factory=dict)
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)
`impedance_bounds`	`ImpedanceBounds`	field(default_factory=ImpedanceBounds)

Methods:

`infer(data: MotorControlInput) -> Result[MotorControlOutput]`¶

`MotorControlInput(BaseModel)`¶

Input to MotorControlBlock.

Field	Type	Default
`op`	`Literal['execute_action', 'plan_action', 'set_impedance', 'get_impedance', 'adjust_impedance', 'add_primitive', 'list_primitives', 'get_motor_memory', 'record_action', 'safety_check', 'batch_approve', 'get_safe_state', 'enter_safe_state', 'get_info', 'reset', 'ops', 'help']`	required
`action_type`	`str`	''
`action_params`	`dict`	Field(default_factory=dict)
`k`	`float`	0.6
`c`	`float`	0.2
`primitive_name`	`str`	''
`primitive_cost`	`float`	0.0
`primitive_risk`	`float`	0.0
`actions`	`list[dict]`	Field(default_factory=list)
`sequence_name`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)

`MotorControlOutput(BaseModel)`¶

Output from MotorControlBlock.

Field	Type	Default
`op`	`str`	required
`action_executed`	`bool`	False
`action_result`	`dict`	Field(default_factory=dict)
`k`	`float`	0.0
`c`	`float`	0.0
`impedance_mode`	`str`	''
`safety_approved`	`bool`	False
`safety_reason`	`str`	''
`primitives`	`list[dict]`	Field(default_factory=list)
`motor_memory`	`list[dict]`	Field(default_factory=list)
`batch_results`	`list[dict]`	Field(default_factory=list)
`is_safe_state`	`bool`	False
`metadata`	`dict`	Field(default_factory=dict)
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict`	Field(default_factory=dict)
`evidence`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None

`MotorControlMCPBlock(AIBlock[MCPMotorControlInput, MCPMotorControlOutput, dict])`¶

26-op motor control MCP block with SQLite persistence.

Field	Type	Default
`name`	`str`	'motor_control_mcp'
`state`	`dict`	field(default_factory=dict)
`db_path`	`str`	field(default_factory=lambda: os.environ.get('MOTOR_CONTROL_DB_PATH', _DEFAULT_DB))
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: MCPMotorControlInput) -> Result[MCPMotorControlOutput]`¶

`MCPMotorControlInput(BaseModel)`¶

Input to MotorControlMCPBlock — 26 ops.

Field	Type	Default
`op`	Literal['execute_action', 'plan_action', 'set_impedance', 'get_impedance', 'adjust_impedance', 'add_primitive', 'list_primitives', 'get_motor_memory', 'record_action', 'safety_check', 'batch_approve', 'get_safe_state', 'enter_safe_state', 'get_info', 'reset', 'ops', 'help', 'store_impedance_profile', 'load_impedance_profile', 'list_impedance_profiles', 'store_action_sequence', 'list_action_sequences', 'replay_sequence', 'search_primitives', 'get_action_stats', 'compare_impedance', 'export_motor_config', 'list_patterns']	required
`action_type`	`str`	''
`action_params`	`dict`	Field(default_factory=dict)
`k`	`float`	0.6
`c`	`float`	0.2
`primitive_name`	`str`	''
`primitive_cost`	`float`	0.0
`primitive_risk`	`float`	0.0
`actions`	`list[dict]`	Field(default_factory=list)
`sequence_name`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)
`profile_name`	`str`	''
`query`	`str`	''
`top_k`	`int`	10
`compare_id`	`str`	''
`sequence_json`	`str`	''

`MCPMotorControlOutput(BaseModel)`¶

Output from MotorControlMCPBlock.

Field	Type	Default
`op`	`str`	required
`action_executed`	`bool`	False
`action_result`	`dict`	Field(default_factory=dict)
`k`	`float`	0.0
`c`	`float`	0.0
`impedance_mode`	`str`	''
`safety_approved`	`bool`	False
`safety_reason`	`str`	''
`primitives`	`list[dict]`	Field(default_factory=list)
`motor_memory`	`list[dict]`	Field(default_factory=list)
`batch_results`	`list[dict]`	Field(default_factory=list)
`is_safe_state`	`bool`	False
`metadata`	`dict`	Field(default_factory=dict)
`message`	`str`	''
`count`	`int`	0
`retrieved`	`list[dict]`	Field(default_factory=list)
`completion_state`	`Literal['qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict`	Field(default_factory=dict)
`evidence`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None

`MotorControlStore`¶

SQLite-backed store for the motor_control MCP sub-package.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`store_impedance_profile(name: str, k: float, c: float, mode: str = '', tags: str = '') -> str`¶

`load_impedance_profile(name: str) -> dict | None`¶

`list_impedance_profiles(limit: int = 50) -> list[dict]`¶

`store_action_sequence(name: str, sequence: list, tags: str = '') -> str`¶

`load_action_sequence(name: str) -> dict | None`¶

`list_action_sequences(limit: int = 50) -> list[dict]`¶

`log_action(action_type: str, params: dict, k: float, c: float, approved: bool, reason: str = '') -> str`¶

`get_action_stats() -> dict`¶

`log_safety_check(action_type: str, k: float, risk: float, approved: bool, reason: str = '') -> None`¶

`store_motor_memory(name: str, actions: list, metadata: dict | None = None) -> str`¶

`list_motor_memory(limit: int = 50) -> list[dict]`¶

`log_error(op: str, error_message: str, params: dict | None = None) -> None`¶

`count_all() -> dict[str, int]`¶

MCP Tools¶

Operation	Source
`execute_action`	motor_control_mcp
`plan_action`	motor_control_mcp
`set_impedance`	motor_control_mcp
`get_impedance`	motor_control_mcp
`adjust_impedance`	motor_control_mcp
`add_primitive`	motor_control_mcp
`list_primitives`	motor_control_mcp
`get_motor_memory`	motor_control_mcp
`record_action`	motor_control_mcp
`safety_check`	motor_control_mcp
`batch_approve`	motor_control_mcp
`get_safe_state`	motor_control_mcp
`enter_safe_state`	motor_control_mcp
`get_info`	motor_control_mcp
`reset`	motor_control_mcp
`ops`	motor_control_mcp
`help`	motor_control_mcp
`store_impedance_profile`	motor_control_mcp
`load_impedance_profile`	motor_control_mcp
`list_impedance_profiles`	motor_control_mcp
`store_action_sequence`	motor_control_mcp
`list_action_sequences`	motor_control_mcp
`replay_sequence`	motor_control_mcp
`search_primitives`	motor_control_mcp
`get_action_stats`	motor_control_mcp
`compare_impedance`	motor_control_mcp
`export_motor_config`	motor_control_mcp
`list_patterns`	motor_control_mcp

Motor Control¶

Overview¶

Public API¶

MotorControlBlock(AIBlock[MotorControlInput, MotorControlOutput, dict])¶

infer(data: MotorControlInput) -> Result[MotorControlOutput]¶

MotorControlInput(BaseModel)¶

MotorControlOutput(BaseModel)¶

MotorControlMCPBlock(AIBlock[MCPMotorControlInput, MCPMotorControlOutput, dict])¶

infer(data: MCPMotorControlInput) -> Result[MCPMotorControlOutput]¶

MCPMotorControlInput(BaseModel)¶

MCPMotorControlOutput(BaseModel)¶

MotorControlStore¶

store_impedance_profile(name: str, k: float, c: float, mode: str = '', tags: str = '') -> str¶

load_impedance_profile(name: str) -> dict | None¶

list_impedance_profiles(limit: int = 50) -> list[dict]¶

store_action_sequence(name: str, sequence: list, tags: str = '') -> str¶

load_action_sequence(name: str) -> dict | None¶

list_action_sequences(limit: int = 50) -> list[dict]¶

log_action(action_type: str, params: dict, k: float, c: float, approved: bool, reason: str = '') -> str¶

get_action_stats() -> dict¶

log_safety_check(action_type: str, k: float, risk: float, approved: bool, reason: str = '') -> None¶

store_motor_memory(name: str, actions: list, metadata: dict | None = None) -> str¶

list_motor_memory(limit: int = 50) -> list[dict]¶

log_error(op: str, error_message: str, params: dict | None = None) -> None¶

count_all() -> dict[str, int]¶

MCP Tools¶

`MotorControlBlock(AIBlock[MotorControlInput, MotorControlOutput, dict])`¶

`infer(data: MotorControlInput) -> Result[MotorControlOutput]`¶

`MotorControlInput(BaseModel)`¶

`MotorControlOutput(BaseModel)`¶

`MotorControlMCPBlock(AIBlock[MCPMotorControlInput, MCPMotorControlOutput, dict])`¶

`infer(data: MCPMotorControlInput) -> Result[MCPMotorControlOutput]`¶

`MCPMotorControlInput(BaseModel)`¶

`MCPMotorControlOutput(BaseModel)`¶

`MotorControlStore`¶

`store_impedance_profile(name: str, k: float, c: float, mode: str = '', tags: str = '') -> str`¶

`load_impedance_profile(name: str) -> dict | None`¶

`list_impedance_profiles(limit: int = 50) -> list[dict]`¶

`store_action_sequence(name: str, sequence: list, tags: str = '') -> str`¶

`load_action_sequence(name: str) -> dict | None`¶

`list_action_sequences(limit: int = 50) -> list[dict]`¶

`log_action(action_type: str, params: dict, k: float, c: float, approved: bool, reason: str = '') -> str`¶

`get_action_stats() -> dict`¶

`log_safety_check(action_type: str, k: float, risk: float, approved: bool, reason: str = '') -> None`¶

`store_motor_memory(name: str, actions: list, metadata: dict | None = None) -> str`¶

`list_motor_memory(limit: int = 50) -> list[dict]`¶

`log_error(op: str, error_message: str, params: dict | None = None) -> None`¶

`count_all() -> dict[str, int]`¶