auto-atomic-operation 0.1.0__tar.gz

auto_atomic_operation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ge Haizhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auto_atomic_operation-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: auto-atomic-operation
+Version: 0.1.0
+Summary: A YAML-driven atomic operation framework for robotic manipulation.
+Author: OpenGHz
+License: MIT
+Project-URL: repository, https://github.com/OpenGHz/auto-atomic-operation.git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hydra-core
+Requires-Dist: numpy
+Requires-Dist: pydantic>=2
+Provides-Extra: mujoco
+Requires-Dist: mujoco; extra == "mujoco"
+Dynamic: license-file
+
+<div align="center">
+
+<h1>Auto Atomic Operation</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/auto-atomic-operation)](https://pypi.org/project/auto-atomic-operation/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A YAML-driven atomic operation framework for robotic manipulation.
+
+</div>
+
+`auto-atomic-operation` lets you define robotic manipulation tasks — pick, place, push, pull, move, grasp, release — as declarative YAML files. A built-in state machine handles task sequencing, pose resolution, end-effector control, and execution tracking. A plugin-based backend system decouples task logic from the underlying hardware or simulator, making it easy to run the same task definition against a real robot, a physics simulator, or a lightweight mock for testing.
+
+## Features
+
+- **Hydra-powered task configuration** — describe multi-stage manipulation tasks in YAML; full [Hydra](https://hydra.cc) support means `_target_` instantiation, variable interpolation, and command-line overrides work out of the box
+- **Flexible pose references** — specify targets relative to world, robot base, end-effector, or tracked objects
+- **Pluggable backends** — connect any robot or simulator by implementing a small set of abstract interfaces
+- **Pose randomization** — per-object position/orientation randomization with automatic collision avoidance on reset
+- **Multi-arm support** — single-arm and dual-arm (left/right) topologies
+- **Execution records** — detailed per-stage status, failure reasons, and timing after every run
+- **Mujoco backend included** — a ready-to-use backend with RGB-D cameras, tactile sensors, force/torque, IMU, and joint state support
+
+## Installation
+
+Requires **Python 3.10+**.
+
+```bash
+# Core framework only
+pip install -e .
+
+# With the built-in Mujoco backend
+pip install -e ".[mujoco]"
+```
+
+## Quick Start
+
+### 1. Define a task in YAML
+
+```yaml
+# task.yaml
+backend: auto_atom.mock.build_mock_backend
+
+task:
+  env_name: my_env
+  stages:
+    - name: pick_cup
+      object: cup
+      operation: pick
+      operator: arm_a
+      param:
+        pre_move:
+          - position: [0.45, -0.10, 0.08]
+            rotation: [0.0, 1.57, 0.0]
+            reference: object_world
+        eef:
+          close: true
+
+    - name: place_on_shelf
+      object: shelf
+      operation: place
+      operator: arm_a
+      param:
+        pre_move:
+          - position: [0.10, 0.25, 0.16]
+            orientation: [0.0, 0.0, 0.0, 1.0]
+            reference: world
+        eef:
+          close: false
+
+operators:
+  - name: arm_a
+    role: manipulator
+```
+
+### 2. Run the task
+
+```python
+from pathlib import Path
+from auto_atom.runtime import ComponentRegistry, TaskRunner
+
+ComponentRegistry.clear()
+runner = TaskRunner().from_yaml(Path("task.yaml"))
+
+runner.reset()
+while True:
+    update = runner.update()
+    if update.done:
+        break
+
+for record in runner.records:
+    print(record)
+
+runner.close()
+```
+
+## YAML Configuration Reference
+
+Task files are processed by [Hydra](https://hydra.cc) / OmegaConf, so the full Hydra feature set is available: `_target_` instantiation, `${key}` interpolation, structured configs, and command-line overrides (`key=value`).
+
+A task file has four top-level keys:
+
+| Key | Description |
+|-----|-------------|
+| `env` | Hydra `_target_` instantiation of the environment, registered via `ComponentRegistry` |
+| `backend` | Dotted import path to the backend factory function |
+| `task` | Task definition: `env_name`, `seed`, and a list of `stages` |
+| `operators` | Named operators with assigned roles |
+
+### Stage definition
+
+```yaml
+- name: <stage_name>          # Unique stage identifier
+  object: <object_name>       # Target object
+  operation: pick|place|push|pull|move|grasp|release
+  operator: <operator_name>   # Which arm/robot executes this stage
+  blocking: true              # Optional, default true
+  param:
+    pre_move:                 # Approach waypoints (list of pose configs)
+      - position: [x, y, z]
+        rotation: [rx, ry, rz]    # Euler angles (rad), or:
+        orientation: [x, y, z, w] # Quaternion
+        reference: world|base|eef|object|object_world|eef_world|auto
+    post_move:                # Retreat waypoints (same format as pre_move)
+    eef:
+      close: true|false       # Gripper open/close
+```
+
+### Pose references
+
+| Reference | Description |
+|-----------|-------------|
+| `world` | Fixed world frame |
+| `base` | Robot base frame |
+| `eef` | Current end-effector frame |
+| `object` | Object frame (tracks object movement) |
+| `object_world` | Object position with world orientation |
+| `eef_world` | EEF position snapshot at command start |
+| `auto` | Automatically determined from context |
+
+## Examples
+
+The [`examples/`](examples/) directory contains two runnable demos:
+
+### Mock example (no robot or simulator required)
+
+```bash
+python examples/run_mock_example.py
+```
+
+Uses the in-memory mock backend — ideal for testing task logic in isolation.
+
+### Mujoco pick-and-place demo
+
+```bash
+python examples/run_mujoco_pick_place_demo.py
+```
+
+A full pick-and-place task with RGB-D cameras, tactile sensors, and randomized object placement, running in the Mujoco physics simulator.
+
+## Architecture
+
+```
+auto_atom/
+├── framework.py        # Pydantic configuration models (YAML schema)
+├── runtime.py          # Task execution engine (TaskRunner, TaskFlowBuilder)
+├── mock.py             # In-memory mock backend for testing
+├── basis/
+│   └── mujoco_env.py   # UnifiedMujocoEnv — Mujoco wrapper with sensor suite
+├── backend/
+│   └── mjc/            # Mujoco backend (operators, objects, scene)
+└── utils/
+    └── pose.py         # Pose transforms and quaternion utilities
+```
+
+**Execution flow:**
+
+1. Load and validate the YAML task file via Pydantic models
+2. Instantiate the backend via the configured factory function
+3. `TaskFlowBuilder` expands stages into primitive pose-move and EEF-control actions
+4. `TaskRunner.reset()` initializes the scene (with optional randomization)
+5. `TaskRunner.update()` advances one step of the active primitive action
+6. After completion, `TaskRunner.records` holds per-stage execution history
+
+## Implementing a Custom Backend
+
+To integrate a new simulator or real robot, implement three abstract classes from `auto_atom.runtime`:
+
+- `OperatorHandler` — arm movement (`move_to_pose`) and gripper control (`control_eef`)
+- `ObjectHandler` — object pose queries and updates (`get_pose`, `set_pose`)
+- `SceneBackend` — scene lifecycle, handler resolution, and randomization
+
+See the **[Custom Backend Guide](docs/custom-backend.md)** for a step-by-step walkthrough with annotated code examples. [`auto_atom/mock.py`](auto_atom/mock.py) provides a minimal reference implementation.
+
+## License
+
+See [LICENSE](LICENSE).

auto_atomic_operation-0.1.0/README.md

@@ -0,0 +1,198 @@
+<div align="center">
+
+<h1>Auto Atomic Operation</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/auto-atomic-operation)](https://pypi.org/project/auto-atomic-operation/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A YAML-driven atomic operation framework for robotic manipulation.
+
+</div>
+
+`auto-atomic-operation` lets you define robotic manipulation tasks — pick, place, push, pull, move, grasp, release — as declarative YAML files. A built-in state machine handles task sequencing, pose resolution, end-effector control, and execution tracking. A plugin-based backend system decouples task logic from the underlying hardware or simulator, making it easy to run the same task definition against a real robot, a physics simulator, or a lightweight mock for testing.
+
+## Features
+
+- **Hydra-powered task configuration** — describe multi-stage manipulation tasks in YAML; full [Hydra](https://hydra.cc) support means `_target_` instantiation, variable interpolation, and command-line overrides work out of the box
+- **Flexible pose references** — specify targets relative to world, robot base, end-effector, or tracked objects
+- **Pluggable backends** — connect any robot or simulator by implementing a small set of abstract interfaces
+- **Pose randomization** — per-object position/orientation randomization with automatic collision avoidance on reset
+- **Multi-arm support** — single-arm and dual-arm (left/right) topologies
+- **Execution records** — detailed per-stage status, failure reasons, and timing after every run
+- **Mujoco backend included** — a ready-to-use backend with RGB-D cameras, tactile sensors, force/torque, IMU, and joint state support
+
+## Installation
+
+Requires **Python 3.10+**.
+
+```bash
+# Core framework only
+pip install -e .
+
+# With the built-in Mujoco backend
+pip install -e ".[mujoco]"
+```
+
+## Quick Start
+
+### 1. Define a task in YAML
+
+```yaml
+# task.yaml
+backend: auto_atom.mock.build_mock_backend
+
+task:
+  env_name: my_env
+  stages:
+    - name: pick_cup
+      object: cup
+      operation: pick
+      operator: arm_a
+      param:
+        pre_move:
+          - position: [0.45, -0.10, 0.08]
+            rotation: [0.0, 1.57, 0.0]
+            reference: object_world
+        eef:
+          close: true
+
+    - name: place_on_shelf
+      object: shelf
+      operation: place
+      operator: arm_a
+      param:
+        pre_move:
+          - position: [0.10, 0.25, 0.16]
+            orientation: [0.0, 0.0, 0.0, 1.0]
+            reference: world
+        eef:
+          close: false
+
+operators:
+  - name: arm_a
+    role: manipulator
+```
+
+### 2. Run the task
+
+```python
+from pathlib import Path
+from auto_atom.runtime import ComponentRegistry, TaskRunner
+
+ComponentRegistry.clear()
+runner = TaskRunner().from_yaml(Path("task.yaml"))
+
+runner.reset()
+while True:
+    update = runner.update()
+    if update.done:
+        break
+
+for record in runner.records:
+    print(record)
+
+runner.close()
+```
+
+## YAML Configuration Reference
+
+Task files are processed by [Hydra](https://hydra.cc) / OmegaConf, so the full Hydra feature set is available: `_target_` instantiation, `${key}` interpolation, structured configs, and command-line overrides (`key=value`).
+
+A task file has four top-level keys:
+
+| Key | Description |
+|-----|-------------|
+| `env` | Hydra `_target_` instantiation of the environment, registered via `ComponentRegistry` |
+| `backend` | Dotted import path to the backend factory function |
+| `task` | Task definition: `env_name`, `seed`, and a list of `stages` |
+| `operators` | Named operators with assigned roles |
+
+### Stage definition
+
+```yaml
+- name: <stage_name>          # Unique stage identifier
+  object: <object_name>       # Target object
+  operation: pick|place|push|pull|move|grasp|release
+  operator: <operator_name>   # Which arm/robot executes this stage
+  blocking: true              # Optional, default true
+  param:
+    pre_move:                 # Approach waypoints (list of pose configs)
+      - position: [x, y, z]
+        rotation: [rx, ry, rz]    # Euler angles (rad), or:
+        orientation: [x, y, z, w] # Quaternion
+        reference: world|base|eef|object|object_world|eef_world|auto
+    post_move:                # Retreat waypoints (same format as pre_move)
+    eef:
+      close: true|false       # Gripper open/close
+```
+
+### Pose references
+
+| Reference | Description |
+|-----------|-------------|
+| `world` | Fixed world frame |
+| `base` | Robot base frame |
+| `eef` | Current end-effector frame |
+| `object` | Object frame (tracks object movement) |
+| `object_world` | Object position with world orientation |
+| `eef_world` | EEF position snapshot at command start |
+| `auto` | Automatically determined from context |
+
+## Examples
+
+The [`examples/`](examples/) directory contains two runnable demos:
+
+### Mock example (no robot or simulator required)
+
+```bash
+python examples/run_mock_example.py
+```
+
+Uses the in-memory mock backend — ideal for testing task logic in isolation.
+
+### Mujoco pick-and-place demo
+
+```bash
+python examples/run_mujoco_pick_place_demo.py
+```
+
+A full pick-and-place task with RGB-D cameras, tactile sensors, and randomized object placement, running in the Mujoco physics simulator.
+
+## Architecture
+
+```
+auto_atom/
+├── framework.py        # Pydantic configuration models (YAML schema)
+├── runtime.py          # Task execution engine (TaskRunner, TaskFlowBuilder)
+├── mock.py             # In-memory mock backend for testing
+├── basis/
+│   └── mujoco_env.py   # UnifiedMujocoEnv — Mujoco wrapper with sensor suite
+├── backend/
+│   └── mjc/            # Mujoco backend (operators, objects, scene)
+└── utils/
+    └── pose.py         # Pose transforms and quaternion utilities
+```
+
+**Execution flow:**
+
+1. Load and validate the YAML task file via Pydantic models
+2. Instantiate the backend via the configured factory function
+3. `TaskFlowBuilder` expands stages into primitive pose-move and EEF-control actions
+4. `TaskRunner.reset()` initializes the scene (with optional randomization)
+5. `TaskRunner.update()` advances one step of the active primitive action
+6. After completion, `TaskRunner.records` holds per-stage execution history
+
+## Implementing a Custom Backend
+
+To integrate a new simulator or real robot, implement three abstract classes from `auto_atom.runtime`:
+
+- `OperatorHandler` — arm movement (`move_to_pose`) and gripper control (`control_eef`)
+- `ObjectHandler` — object pose queries and updates (`get_pose`, `set_pose`)
+- `SceneBackend` — scene lifecycle, handler resolution, and randomization
+
+See the **[Custom Backend Guide](docs/custom-backend.md)** for a step-by-step walkthrough with annotated code examples. [`auto_atom/mock.py`](auto_atom/mock.py) provides a minimal reference implementation.
+
+## License
+
+See [LICENSE](LICENSE).

auto_atomic_operation-0.1.0/auto_atom/__init__.py

@@ -0,0 +1,60 @@
+"""Import-friendly runtime package for the Auto Atomic Operation framework."""
+
+from .framework import (
+    AutoAtomConfig,
+    EefControlConfig,
+    OperatorConfig,
+    PoseControlConfig,
+    PoseReference,
+    StageConfig,
+    StageControlConfig,
+    TaskFileConfig,
+)
+from .mock import MockOperatorHandler, MockSceneBackend
+from .runtime import (
+    ComponentRegistry,
+    ControlResult,
+    ControlSignal,
+    ExecutionContext,
+    ExecutionRecord,
+    ObjectHandler,
+    OperatorHandler,
+    PoseRandomRange,
+    PrimitiveAction,
+    StageExecutionStatus,
+    TaskFlowBuilder,
+    TaskRunner,
+    TaskUpdate,
+    load_config,
+    load_task_file,
+)
+from .utils.pose import PoseState
+
+__all__ = [
+    "AutoAtomConfig",
+    "ComponentRegistry",
+    "ControlResult",
+    "ControlSignal",
+    "ExecutionContext",
+    "ExecutionRecord",
+    "EefControlConfig",
+    "MockOperatorHandler",
+    "MockSceneBackend",
+    "ObjectHandler",
+    "OperatorConfig",
+    "OperatorHandler",
+    "PoseControlConfig",
+    "PoseRandomRange",
+    "PoseReference",
+    "PoseState",
+    "PrimitiveAction",
+    "StageConfig",
+    "StageControlConfig",
+    "StageExecutionStatus",
+    "TaskFileConfig",
+    "TaskFlowBuilder",
+    "TaskRunner",
+    "TaskUpdate",
+    "load_config",
+    "load_task_file",
+]