long-tamp 0.1.0__tar.gz

long_tamp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CNRS
+
+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.

long_tamp-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: long-tamp
+Version: 0.1.0
+Summary: Long-TAMP - Manipulation Planning Framework
+Author-email: Thanh Nguyen <dvtnguyen@laas.fr>
+Maintainer-email: Thanh Nguyen <dvtnguyen@laas.fr>
+License: MIT
+Project-URL: Homepage, https://github.com/thanhndv212/long-tamp
+Project-URL: Documentation, https://long-tamp.readthedocs.io
+Project-URL: Repository, https://github.com/thanhndv212/long-tamp
+Project-URL: Issues, https://github.com/thanhndv212/long-tamp/issues
+Keywords: robotics,manipulation,motion-planning,hpp,agimus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: pin>=2.6
+Requires-Dist: viser
+Requires-Dist: trimesh
+Requires-Dist: pycollada
+Provides-Extra: hpp
+Requires-Dist: hpp-python>=9.0.2; extra == "hpp"
+Requires-Dist: hpp-gepetto-viewer>=9.0.2; extra == "hpp"
+Provides-Extra: toppra
+Requires-Dist: hpp-toppra>=9.0.2; extra == "toppra"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin>=7.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: long-tamp[dev,docs]; extra == "all"
+Dynamic: license-file
+
+# Long-TAMP - Long-Horizon Task-and-Motion Planning
+
+Long-horizon, multi-arm task-and-motion planning (TAMP) for manipulation, built on HPP (Humanoid Path Planner).
+
+`long_tamp` plans **long, multi-step manipulation sequences** for **several robot arms** on **many movable objects** in a shared scene. **Motion planning** is HPP's constraint-graph planner, driven through a plain-Python task API. **Task planning** is a declarative task plan compiled to **BehaviorTree.CPP**, for standalone, ROS-free mission execution (see *Task Planning* below).
+
+## Capabilities
+
+- **Long-horizon sequence planning.** `GraspSequencePlanner` chains an arbitrary number of grasp/place/hand-over phases, each with its own minimal phase-local constraint graph, so planning cost grows **linearly (O(N))** with the number of grasps instead of combinatorially (**O(N!)**).
+- **Multiple robots & objects.** The scene composes several arms into one shared, mutually-collision-aware planning model — able to act independently, cooperate, or hand off objects — alongside any number of free-flying objects/tools, with grasp legality data-driven via `VALID_PAIRS` so adding one is a config change.
+- **Reproducibility, introspection & crash recovery.** Crash-safe JSONL run logging plus a path-capture mechanism (`PathRecorder`) record every phase/edge/path so a run can be replayed, continuity-checked, and checkpointed/resumed rather than replanned from scratch.
+- **Declarative task planning → BehaviorTree.CPP.** A versioned, capability-checked task plan (`tasks/task_planning/`) compiles deterministically to a BehaviorTree.CPP tree, run by a standalone C++ host through an embedded-CPython bridge with no ROS and no network hop (see *Task Planning* below).
+- **Scene visualization.** Interactive 3D viewers: browser-based **viser** (default, no X11) or **gepetto-viewer** (Qt).
+
+## Installation
+
+`long_tamp` has two dependency tiers: a pure-Python tier, and the HPP native bindings
+(`hpp-python`, `hpp-toppra`, `hpp-gepetto-viewer`) — C++ extension modules.
+
+| Platform | Pure-Python tier (`pip install -e .`) | HPP native bindings |
+|---|---|---|
+| Linux x86_64/aarch64 | ✅ PyPI | ✅ PyPI — `pip install -e ".[hpp,toppra]"` |
+| macOS | ✅ PyPI | ❌ no wheels (PyPI, conda-forge, robotpkg) — needs Docker/Linux |
+| Windows | untested | untested — likely needs Docker/WSL2 |
+
+On Linux, everything installs from PyPI in one command, no system packages or Docker
+required. Elsewhere, the pure-Python tier still installs natively via pip, but the planner
+itself needs a Linux environment for the native bindings — see
+[`docs/INSTALL.md`](docs/INSTALL.md) for the robotpkg/source-build/Docker fallback, the
+CMake install path, the NumPy ABI pitfall (robotpkg wants NumPy 1.x, the PyPI wheels want
+NumPy 2.x — don't mix them), and runtime backend detection.
+
+## Usage
+
+Writing a task means implementing `ManipulationTask`'s lifecycle contract (`get_objects()`,
+`create_constraints()`, `create_graph()`, `build_initial_config()`,
+`generate_configurations()`, then `setup()` / `run()`) — either by hand, or, for new tasks,
+via a declarative YAML config (recommended). Full, runnable examples live in
+[`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) §§4–6 rather than
+duplicated here, alongside multi-phase sequences, resume/replay/checkpoints, and backend
+selection.
+
+- **Start from a template**: `script/templates/task_config_template.yaml` +
+  `task_my_task.py` — copy, fill in the `<PLACEHOLDER>`s, run.
+- **Read a real, minimal example**: `script/twin/task_lift_ball.py` (bimanual scene).
+
+## Package structure & architecture
+
+`tasks/` orchestrates `planning/`, which is backend-agnostic and depends only on `backends/`
+(the one place HPP-specific bindings are imported); `config/`, `logging/`, `visualization/`,
+`utils/`, and `cli/` are horizontal support layers used from `tasks/` and `script/`.
+
+```mermaid
+flowchart TB
+    script["script/<br/>end-user task scripts<br/>(one per robot/mission)"]
+    tasks["tasks/<br/>ManipulationTask, GraspSequencePlanner,<br/>InteractiveGraspSequenceBuilder"]
+    planning["planning/<br/>SceneBuilder, ConstraintBuilder, GraphBuilder,<br/>ConfigGenerator, GraspStateTracker,<br/>SequentialConstraintGraphFactory,<br/>SequentialGraspFilter, path_io,<br/>path_recorder, path_replay"]
+    backends["backends/<br/>BackendBase (ABC) → PyHPPBackend<br/>only layer importing pyhpp.*"]
+
+    config["config/<br/>BaseTaskConfig, YamlTaskLoader"]
+    logging_["logging/<br/>RunLogger, JSONL event schema"]
+    viz["visualization/<br/>graph diagrams, frame display, video"]
+    utils["utils/<br/>transforms, interactive menus"]
+    cli["cli/<br/>argparse helpers, interactive pickers"]
+
+    script --> tasks
+    tasks --> planning
+    planning --> backends
+
+    tasks -.uses.-> config
+    tasks -.uses.-> logging_
+    tasks -.uses.-> viz
+    script -.uses.-> cli
+    cli -.uses.-> utils
+    config -.uses.-> utils
+
+    style backends fill:#4c566a,stroke:#2e3440,color:#fff
+    style planning fill:#5e81ac,stroke:#2e3440,color:#fff
+    style tasks fill:#81a1c1,stroke:#2e3440,color:#fff
+    style script fill:#88c0d0,stroke:#2e3440,color:#000
+```
+
+Per-phase planning data flow, the loop every mission ultimately runs through:
+
+```mermaid
+flowchart TD
+    yaml["YAML config"] -->|YamlTaskLoader| loaded["file_paths, joint_bounds_class, task_config"]
+    loaded --> setup["ManipulationTask.setup"]
+
+    setup --> scene["SceneBuilder<br/>load robots, env, objects"]
+    setup --> constraints["ConstraintBuilder /<br/>FactoryConstraintRegistry"]
+    setup --> gbuild["GraphBuilder<br/>factory or manual"]
+
+    scene --> plan["GraspSequencePlanner.plan_sequence"]
+    constraints --> plan
+    gbuild --> plan
+
+    plan --> p1["1. build_phase_graph<br/>GraphBuilder plus SequentialConstraintGraphFactory"]
+    p1 --> p2["2. GraspStateTracker picks the edge name"]
+    p2 --> p3["3. ConfigGenerator.generate_via_edge builds target config"]
+    p3 --> p4["4. backend.solve builds the path, then optimize and time-parameterize"]
+    p4 --> p5["5. RunLogger.log phase_end, optional auto-save of path"]
+    p5 -->|next phase| p1
+    p5 --> result["concatenated multi-phase path, O of N planning cost"]
+```
+
+Both diagrams are copied from **[`ARCHITECTURE.md`](ARCHITECTURE.md)**, which is the
+maintained source — it's dated at the top and covers dependency direction and what each
+class does in more depth than fits here. If the two ever disagree, trust `ARCHITECTURE.md`
+and update this copy to match.
+
+## Task Planning (BehaviorTree.CPP)
+
+Alongside the plain-Python `ManipulationTask` API, `tasks/task_planning/` is a second,
+declarative entry point: a versioned JSON **TaskPlan IR** (`sequence` / `fallback` / `retry` /
+`condition` / `operation` / `transaction` nodes), validated against a `CapabilityRegistry`,
+compiles deterministically to a **BehaviorTree.CPP** tree. A standalone C++ host
+(`examples/behaviortree/`) runs that tree via an in-process, embedded-CPython bridge — one
+process, no ROS, no network hop. It ships with built-in checkpoint/resume and path-capture
+validation for long, restartable missions, and is the intended integration point for a future
+model-proposed (VLM/LLM) plan.
+
+| Stage | File |
+|-------|------|
+| IR validation & fingerprinting | `tasks/task_planning/model.py` (`TaskPlan`) |
+| Capability policy | `tasks/task_planning/capabilities.py` (`CapabilityRegistry`) |
+| IR → BT XML compiler | `tasks/task_planning/compiler.py` |
+| C++ host + CPython bridge | `examples/behaviortree/` |
+
+Build with `-DBUILD_BEHAVIORTREE_EXAMPLES=ON`. Full IR schema, the compiler's node mapping,
+build/run steps, checkpointing, and how to add a mission or capability:
+[`docs/usage/behaviortree-integration.md`](docs/usage/behaviortree-integration.md).
+
+## Run Logging
+
+`long_tamp` includes a structured run logger that writes a crash-safe JSONL event
+stream for every planning run — one event per phase/edge attempt, plus a JSON snapshot and a
+replay-ready YAML on close. Use it to replay configurations, debug failures, and audit
+results.
+
+Logging is **on by default** for every `ManipulationTask` (`log_dir="auto"` creates
+`/tmp/long_tamp/<task_slug>_<timestamp>/`; pass an explicit path to redirect it, or
+`None` to disable). `RunLogger` also works standalone, independent of `ManipulationTask`.
+
+| Event | When emitted |
+|-------|-------------|
+| `run_start` | `ManipulationTask.__init__` (with `log_dir`) |
+| `config_snapshot` | `setup()` — full `BaseTaskConfig` + setup params |
+| `sequence_start` | Start of `plan_sequence()` — all call params + `q_init` |
+| `phase_start` | Before each grasp phase — `gripper`, `handle`, `q_start` |
+| `edge_start` | Before each transition edge attempt |
+| `edge_end` | After each edge — `success`, timing, `q_to` or `error` |
+| `phase_end` | After each phase — timing, `state_after`, saved files |
+| `run_end` | On normal return or `KeyboardInterrupt` |
+
+For runnable examples — standalone use, inspecting a log afterward
+(`print_run_summary`/`load_run_log`/`get_replay_config`), and configuring the underlying
+Python `logging` hierarchy — see [`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) §10.
+
+## Documentation
+
+- **Installation**: [`docs/INSTALL.md`](docs/INSTALL.md) — pip (primary), robotpkg/source-build fallback, CMake install path, optional extras, backend detection.
+- **Architecture**: [`ARCHITECTURE.md`](ARCHITECTURE.md) — module layering, dependency direction, data flow. Dated at the top; check it before trusting a claim about what exists.
+- **Usage guide (living reference)**: [`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) — writing a task, multi-phase sequences, resume/replay/checkpoints, backends, example scripts.
+- **Development report**: [`docs/legacy/report/development-report.md`](docs/legacy/report/development-report.md) — *why* the framework is built this way: architecture decisions vs. bare HPP, measured before/after numbers, project timeline, and a bugs-found appendix. A point-in-time report, not a living reference.
+- **Design rationale for specific mechanisms**: [`docs/features/`](docs/features/); **upstream HPP defects worked around here**: [`docs/bugs/`](docs/bugs/).
+- **API Reference**: See docstrings in source files.
+- **ROS-free BehaviorTree.CPP integration**: [`docs/usage/behaviortree-integration.md`](docs/usage/behaviortree-integration.md).
+
+## License
+
+MIT - See [LICENSE](LICENSE) file
+
+
+---
+
+**Last Updated**: 2026-09-02

long_tamp-0.1.0/README.md

@@ -0,0 +1,177 @@
+# Long-TAMP - Long-Horizon Task-and-Motion Planning
+
+Long-horizon, multi-arm task-and-motion planning (TAMP) for manipulation, built on HPP (Humanoid Path Planner).
+
+`long_tamp` plans **long, multi-step manipulation sequences** for **several robot arms** on **many movable objects** in a shared scene. **Motion planning** is HPP's constraint-graph planner, driven through a plain-Python task API. **Task planning** is a declarative task plan compiled to **BehaviorTree.CPP**, for standalone, ROS-free mission execution (see *Task Planning* below).
+
+## Capabilities
+
+- **Long-horizon sequence planning.** `GraspSequencePlanner` chains an arbitrary number of grasp/place/hand-over phases, each with its own minimal phase-local constraint graph, so planning cost grows **linearly (O(N))** with the number of grasps instead of combinatorially (**O(N!)**).
+- **Multiple robots & objects.** The scene composes several arms into one shared, mutually-collision-aware planning model — able to act independently, cooperate, or hand off objects — alongside any number of free-flying objects/tools, with grasp legality data-driven via `VALID_PAIRS` so adding one is a config change.
+- **Reproducibility, introspection & crash recovery.** Crash-safe JSONL run logging plus a path-capture mechanism (`PathRecorder`) record every phase/edge/path so a run can be replayed, continuity-checked, and checkpointed/resumed rather than replanned from scratch.
+- **Declarative task planning → BehaviorTree.CPP.** A versioned, capability-checked task plan (`tasks/task_planning/`) compiles deterministically to a BehaviorTree.CPP tree, run by a standalone C++ host through an embedded-CPython bridge with no ROS and no network hop (see *Task Planning* below).
+- **Scene visualization.** Interactive 3D viewers: browser-based **viser** (default, no X11) or **gepetto-viewer** (Qt).
+
+## Installation
+
+`long_tamp` has two dependency tiers: a pure-Python tier, and the HPP native bindings
+(`hpp-python`, `hpp-toppra`, `hpp-gepetto-viewer`) — C++ extension modules.
+
+| Platform | Pure-Python tier (`pip install -e .`) | HPP native bindings |
+|---|---|---|
+| Linux x86_64/aarch64 | ✅ PyPI | ✅ PyPI — `pip install -e ".[hpp,toppra]"` |
+| macOS | ✅ PyPI | ❌ no wheels (PyPI, conda-forge, robotpkg) — needs Docker/Linux |
+| Windows | untested | untested — likely needs Docker/WSL2 |
+
+On Linux, everything installs from PyPI in one command, no system packages or Docker
+required. Elsewhere, the pure-Python tier still installs natively via pip, but the planner
+itself needs a Linux environment for the native bindings — see
+[`docs/INSTALL.md`](docs/INSTALL.md) for the robotpkg/source-build/Docker fallback, the
+CMake install path, the NumPy ABI pitfall (robotpkg wants NumPy 1.x, the PyPI wheels want
+NumPy 2.x — don't mix them), and runtime backend detection.
+
+## Usage
+
+Writing a task means implementing `ManipulationTask`'s lifecycle contract (`get_objects()`,
+`create_constraints()`, `create_graph()`, `build_initial_config()`,
+`generate_configurations()`, then `setup()` / `run()`) — either by hand, or, for new tasks,
+via a declarative YAML config (recommended). Full, runnable examples live in
+[`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) §§4–6 rather than
+duplicated here, alongside multi-phase sequences, resume/replay/checkpoints, and backend
+selection.
+
+- **Start from a template**: `script/templates/task_config_template.yaml` +
+  `task_my_task.py` — copy, fill in the `<PLACEHOLDER>`s, run.
+- **Read a real, minimal example**: `script/twin/task_lift_ball.py` (bimanual scene).
+
+## Package structure & architecture
+
+`tasks/` orchestrates `planning/`, which is backend-agnostic and depends only on `backends/`
+(the one place HPP-specific bindings are imported); `config/`, `logging/`, `visualization/`,
+`utils/`, and `cli/` are horizontal support layers used from `tasks/` and `script/`.
+
+```mermaid
+flowchart TB
+    script["script/<br/>end-user task scripts<br/>(one per robot/mission)"]
+    tasks["tasks/<br/>ManipulationTask, GraspSequencePlanner,<br/>InteractiveGraspSequenceBuilder"]
+    planning["planning/<br/>SceneBuilder, ConstraintBuilder, GraphBuilder,<br/>ConfigGenerator, GraspStateTracker,<br/>SequentialConstraintGraphFactory,<br/>SequentialGraspFilter, path_io,<br/>path_recorder, path_replay"]
+    backends["backends/<br/>BackendBase (ABC) → PyHPPBackend<br/>only layer importing pyhpp.*"]
+
+    config["config/<br/>BaseTaskConfig, YamlTaskLoader"]
+    logging_["logging/<br/>RunLogger, JSONL event schema"]
+    viz["visualization/<br/>graph diagrams, frame display, video"]
+    utils["utils/<br/>transforms, interactive menus"]
+    cli["cli/<br/>argparse helpers, interactive pickers"]
+
+    script --> tasks
+    tasks --> planning
+    planning --> backends
+
+    tasks -.uses.-> config
+    tasks -.uses.-> logging_
+    tasks -.uses.-> viz
+    script -.uses.-> cli
+    cli -.uses.-> utils
+    config -.uses.-> utils
+
+    style backends fill:#4c566a,stroke:#2e3440,color:#fff
+    style planning fill:#5e81ac,stroke:#2e3440,color:#fff
+    style tasks fill:#81a1c1,stroke:#2e3440,color:#fff
+    style script fill:#88c0d0,stroke:#2e3440,color:#000
+```
+
+Per-phase planning data flow, the loop every mission ultimately runs through:
+
+```mermaid
+flowchart TD
+    yaml["YAML config"] -->|YamlTaskLoader| loaded["file_paths, joint_bounds_class, task_config"]
+    loaded --> setup["ManipulationTask.setup"]
+
+    setup --> scene["SceneBuilder<br/>load robots, env, objects"]
+    setup --> constraints["ConstraintBuilder /<br/>FactoryConstraintRegistry"]
+    setup --> gbuild["GraphBuilder<br/>factory or manual"]
+
+    scene --> plan["GraspSequencePlanner.plan_sequence"]
+    constraints --> plan
+    gbuild --> plan
+
+    plan --> p1["1. build_phase_graph<br/>GraphBuilder plus SequentialConstraintGraphFactory"]
+    p1 --> p2["2. GraspStateTracker picks the edge name"]
+    p2 --> p3["3. ConfigGenerator.generate_via_edge builds target config"]
+    p3 --> p4["4. backend.solve builds the path, then optimize and time-parameterize"]
+    p4 --> p5["5. RunLogger.log phase_end, optional auto-save of path"]
+    p5 -->|next phase| p1
+    p5 --> result["concatenated multi-phase path, O of N planning cost"]
+```
+
+Both diagrams are copied from **[`ARCHITECTURE.md`](ARCHITECTURE.md)**, which is the
+maintained source — it's dated at the top and covers dependency direction and what each
+class does in more depth than fits here. If the two ever disagree, trust `ARCHITECTURE.md`
+and update this copy to match.
+
+## Task Planning (BehaviorTree.CPP)
+
+Alongside the plain-Python `ManipulationTask` API, `tasks/task_planning/` is a second,
+declarative entry point: a versioned JSON **TaskPlan IR** (`sequence` / `fallback` / `retry` /
+`condition` / `operation` / `transaction` nodes), validated against a `CapabilityRegistry`,
+compiles deterministically to a **BehaviorTree.CPP** tree. A standalone C++ host
+(`examples/behaviortree/`) runs that tree via an in-process, embedded-CPython bridge — one
+process, no ROS, no network hop. It ships with built-in checkpoint/resume and path-capture
+validation for long, restartable missions, and is the intended integration point for a future
+model-proposed (VLM/LLM) plan.
+
+| Stage | File |
+|-------|------|
+| IR validation & fingerprinting | `tasks/task_planning/model.py` (`TaskPlan`) |
+| Capability policy | `tasks/task_planning/capabilities.py` (`CapabilityRegistry`) |
+| IR → BT XML compiler | `tasks/task_planning/compiler.py` |
+| C++ host + CPython bridge | `examples/behaviortree/` |
+
+Build with `-DBUILD_BEHAVIORTREE_EXAMPLES=ON`. Full IR schema, the compiler's node mapping,
+build/run steps, checkpointing, and how to add a mission or capability:
+[`docs/usage/behaviortree-integration.md`](docs/usage/behaviortree-integration.md).
+
+## Run Logging
+
+`long_tamp` includes a structured run logger that writes a crash-safe JSONL event
+stream for every planning run — one event per phase/edge attempt, plus a JSON snapshot and a
+replay-ready YAML on close. Use it to replay configurations, debug failures, and audit
+results.
+
+Logging is **on by default** for every `ManipulationTask` (`log_dir="auto"` creates
+`/tmp/long_tamp/<task_slug>_<timestamp>/`; pass an explicit path to redirect it, or
+`None` to disable). `RunLogger` also works standalone, independent of `ManipulationTask`.
+
+| Event | When emitted |
+|-------|-------------|
+| `run_start` | `ManipulationTask.__init__` (with `log_dir`) |
+| `config_snapshot` | `setup()` — full `BaseTaskConfig` + setup params |
+| `sequence_start` | Start of `plan_sequence()` — all call params + `q_init` |
+| `phase_start` | Before each grasp phase — `gripper`, `handle`, `q_start` |
+| `edge_start` | Before each transition edge attempt |
+| `edge_end` | After each edge — `success`, timing, `q_to` or `error` |
+| `phase_end` | After each phase — timing, `state_after`, saved files |
+| `run_end` | On normal return or `KeyboardInterrupt` |
+
+For runnable examples — standalone use, inspecting a log afterward
+(`print_run_summary`/`load_run_log`/`get_replay_config`), and configuring the underlying
+Python `logging` hierarchy — see [`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) §10.
+
+## Documentation
+
+- **Installation**: [`docs/INSTALL.md`](docs/INSTALL.md) — pip (primary), robotpkg/source-build fallback, CMake install path, optional extras, backend detection.
+- **Architecture**: [`ARCHITECTURE.md`](ARCHITECTURE.md) — module layering, dependency direction, data flow. Dated at the top; check it before trusting a claim about what exists.
+- **Usage guide (living reference)**: [`docs/usage/standalone-usage.md`](docs/usage/standalone-usage.md) — writing a task, multi-phase sequences, resume/replay/checkpoints, backends, example scripts.
+- **Development report**: [`docs/legacy/report/development-report.md`](docs/legacy/report/development-report.md) — *why* the framework is built this way: architecture decisions vs. bare HPP, measured before/after numbers, project timeline, and a bugs-found appendix. A point-in-time report, not a living reference.
+- **Design rationale for specific mechanisms**: [`docs/features/`](docs/features/); **upstream HPP defects worked around here**: [`docs/bugs/`](docs/bugs/).
+- **API Reference**: See docstrings in source files.
+- **ROS-free BehaviorTree.CPP integration**: [`docs/usage/behaviortree-integration.md`](docs/usage/behaviortree-integration.md).
+
+## License
+
+MIT - See [LICENSE](LICENSE) file
+
+
+---
+
+**Last Updated**: 2026-09-02

long_tamp-0.1.0/pyproject.toml

@@ -0,0 +1,126 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "long-tamp"
+version = "0.1.0"
+description = "Long-TAMP - Manipulation Planning Framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Thanh Nguyen", email = "dvtnguyen@laas.fr"}
+]
+maintainers = [
+    {name = "Thanh Nguyen", email = "dvtnguyen@laas.fr"}
+]
+keywords = ["robotics", "manipulation", "motion-planning", "hpp", "agimus"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering",
+]
+
+# Hard runtime deps.
+#   numpy / pyyaml — imported unguarded in core modules (numpy, yaml_loader,
+#                    utils/transforms).
+#   pin (pinocchio) — imported unguarded at module scope in utils/transforms.py
+#                    (SE3, Quaternion, rpyToMatrix are used directly by its
+#                    functions, not just for type hints), which every task
+#                    config transitively imports. `import long_tamp` does not
+#                    work without it — it is not actually optional.
+#   viser / trimesh / pycollada — the browser viewer (pyhpp_viser) is the
+#                    default viewer, so its PyPI-side deps ship by default. The
+#                    pyhpp_viser bindings themselves come from hpp-gepetto-viewer
+#                    (see the [hpp] extra below).
+dependencies = [
+    # No upper bound: the PyPI-native HPP stack (see [hpp] extra) is a cmeel
+    # build — cmeel-boost (a transitive dep of hpp-python) requires numpy>=2.
+    # A robotpkg/source-built HPP environment (see docs/INSTALL.md) is instead
+    # compiled against NumPy 1.x — install there with `pip install --no-deps
+    # -e .` so this constraint (and the `pin` one below) never gets a chance
+    # to pull in a PyPI NumPy 2.x / pinocchio that collides with it.
+    "numpy>=1.26",
+    "pyyaml>=5.1",
+    "pin>=2.6",
+    "viser",
+    "trimesh",
+    "pycollada",
+]
+
+[project.optional-dependencies]
+# The full native HPP stack, prebuilt (cmeel) wheels from PyPI — no robotpkg,
+# no source build, no Docker. Linux only today (manylinux_2_28, x86_64/aarch64),
+# Python 3.10-3.14 — see docs/INSTALL.md for the current platform matrix and
+# the robotpkg/source-build fallback for unsupported platforms.
+hpp = [
+    "hpp-python>=9.0.2",
+    "hpp-gepetto-viewer>=9.0.2",
+]
+
+# TOPPRA time-parameterization (optional optimizer). Also a real PyPI (cmeel)
+# wheel now — see docs/INSTALL.md.
+toppra = [
+    "hpp-toppra>=9.0.2",
+]
+
+dev = [
+    "pytest>=6.0",
+    "pytest-cov",
+    "black",
+    "ruff",
+    "sphinx",
+    "sphinx-rtd-theme",
+]
+
+# MkDocs site over docs/ — `mkdocs serve` / `mkdocs build` (see mkdocs.yml).
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocs-include-markdown-plugin>=7.0",
+]
+
+all = [
+    "long-tamp[dev,docs]",
+]
+
+[project.urls]
+Homepage = "https://github.com/thanhndv212/long-tamp"
+Documentation = "https://long-tamp.readthedocs.io"
+Repository = "https://github.com/thanhndv212/long-tamp"
+Issues = "https://github.com/thanhndv212/long-tamp/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+long_tamp = ["py.typed"]
+
+[tool.ruff]
+extend-exclude = ["cmake"]
+line-length = 88
+
+[tool.ruff.lint]
+extend-select = ["I", "NPY", "RUF", "UP", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow_planning: real-scene planning checks run nightly in isolated processes"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = "-v --cov=long_tamp --cov-report=html --cov-report=term"
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+extend-exclude = '''
+/(
+  | cmake
+)/
+'''

long_tamp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+