dora_littlehand/dora_voice_control/PLAN.md

Voice Control Simplification Plan

Current State

30 files across 7 directories (~3300 lines):

dora_voice_control/
├── behaviors/          # 2 files
│   ├── __init__.py
│   └── base.py
├── node/               # 5 files
│   ├── __init__.py
│   ├── adapter.py
│   ├── context.py
│   ├── dispatcher.py
│   └── logging.py
├── robot/              # 6 files
│   ├── __init__.py
│   ├── adapter.py      # VacuumGripperAdapter, ParallelGripperAdapter
│   ├── command_queue.py
│   ├── image_handler.py
│   ├── pose_handler.py
│   └── status_handler.py
├── scene/              # 4 files
│   ├── __init__.py
│   ├── notifier.py
│   ├── objects_handler.py
│   └── state.py
├── utils/              # 3 files
│   ├── __init__.py
│   ├── config.py
│   └── state.py
├── voice/              # 4 files
│   ├── __init__.py
│   ├── handler.py
│   ├── intent.py
│   └── parser.py
├── web/                # 4 files
│   ├── __init__.py
│   ├── api.py
│   ├── models.py
│   └── templates.py
├── __init__.py
└── main.py

Problems

1. Too many small files - Many files are <50 lines
2. Robot-specific code scattered - Adapter in robot/, behavior in behaviors/
3. Hard to add new robots - Need to touch multiple directories
4. Deep import chains - from ..node import ...

---

Proposed Structure

12 files across 3 directories:

dora_voice_control/
├── __init__.py
├── main.py
├── node.py             # Dora infrastructure (adapter, context, dispatcher, logger)
├── handlers.py         # All event handlers (voice, robot, scene)
├── scene.py            # SceneState, SceneObject
├── state.py            # SharedState, RobotStep, config loading
├── web.py              # API server (api + models + templates)
└── behaviors/
    ├── __init__.py     # get_behavior() factory
    ├── base.py         # ActionContext, ActionInfo, RobotBehavior base
    └── littlehand/
        ├── __init__.py
        └── robot.py    # LittlehandBehavior + VacuumGripperAdapter

---

File Consolidation Map

node.py (merge 5 files)

From	Content
node/logging.py	VoiceControlLogger
node/adapter.py	NodePort, DoraNodeAdapter, MockNodeAdapter
node/context.py	OutputPort, NodeContext
node/dispatcher.py	EventHandler, EventDispatcher

handlers.py (merge 7 files)

From	Content
voice/handler.py	VoiceInputHandler
voice/intent.py	Intent, IntentQueue
robot/pose_handler.py	PoseHandler
robot/status_handler.py	StatusHandler
robot/image_handler.py	ImageHandler
robot/command_queue.py	CommandQueueService
scene/objects_handler.py	ObjectsHandler
scene/notifier.py	SceneNotifier

scene.py (merge 2 files)

From	Content
scene/state.py	SceneState, SceneObject

Already consolidated - just move to root.

state.py (merge 2 files)

From	Content
utils/state.py	SharedState, RobotStep, VoiceState, DebugState
utils/config.py	VoiceConfig, ApiConfig, LLMConfig, loaders

web.py (merge 3 files)

From	Content
web/api.py	create_api(), start_api_server()
web/models.py	CommandRequest, CommandResponse
web/templates.py	HTML_TEMPLATE

behaviors/littlehand/robot.py (new)

From	Content
robot/adapter.py	VacuumGripperAdapter (robot-specific)
behaviors/base.py	Action implementations (robot-specific)

Robot adapter moves INTO the behavior folder.

---

Per-Robot Folder Structure

Each robot gets its own folder with everything it needs:

behaviors/
├── __init__.py         # get_behavior(robot_type) factory
├── base.py             # Shared base classes
│   - ActionContext
│   - ActionInfo
│   - RobotBehavior (abstract)
│
└── littlehand/         # Vacuum gripper robot
    ├── __init__.py
    └── robot.py
        - VacuumGripperAdapter
        - LittlehandBehavior (actions, LLM signature)
        - ACTIONS dict
        - CommandSignature (DSPy)

Adding a New Robot (e.g., "gripper_arm")

1. Create behaviors/gripper_arm/
2. Create robot.py with:
   • ParallelGripperAdapter
   • GripperArmBehavior
   • Custom actions
3. Register in behaviors/__init__.py

No need to touch other files.

---

Implementation Steps

Phase 1: Consolidate node/ → node.py

1. Create node.py merging adapter, context, dispatcher, logging
2. Update imports in all files
3. Delete node/ directory

Phase 2: Consolidate handlers

1. Create handlers.py merging all handlers
2. Update imports
3. Delete voice/, robot/ directories (except adapter)

Phase 3: Consolidate utils/ → state.py

1. Create state.py merging config and state
2. Update imports
3. Delete utils/ directory

Phase 4: Move scene/ → scene.py

1. Move scene/state.py to scene.py
2. Update imports
3. Delete scene/ directory

Phase 5: Consolidate web/ → web.py

1. Create web.py merging api, models, templates
2. Update imports
3. Delete web/ directory

Phase 6: Restructure behaviors per robot

1. Create behaviors/littlehand/robot.py
2. Move VacuumGripperAdapter from robot/adapter.py
3. Move action implementations from behaviors/base.py
4. Update behaviors/__init__.py factory
5. Delete old robot/adapter.py

Phase 7: Update main.py

1. Update all imports to new structure
2. Simplify initialization

---

Final Structure Comparison

Before	After
30 files	12 files
7 directories	3 directories
Robot code scattered	Robot code in one folder
Deep imports	Flat imports

---

Benefits

1. Easier navigation - Fewer files to search
2. Self-contained robots - One folder per robot type
3. Simpler imports - from .node import ... instead of from ..node import ...
4. Easier testing - Mock one module instead of many
5. Clear ownership - Robot-specific code in robot folder