linkforge-core 1.5.2__tar.gz → 1.5.4__tar.gz

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkforge-core
-Version: 1.5.2
+Version: 1.5.4
 Summary: LinkForge Core: Programmable IR and Physical Validation Engine for Robotics
 Project-URL: Homepage, https://github.com/arounamounchili/linkforge
 Project-URL: Documentation, https://linkforge.readthedocs.io/
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 
 Writing and maintaining URDF or SRDF by hand is fragile: inertia values are guessed, collision geometries drift, and physics bugs surface only after a simulator crash (or worse, on hardware). LinkForge Core solves this by treating your robot as **source code with physical constraints**, not a static XML document.
 
-It provides a mathematically rigorous, zero-dependency Intermediate Representation (IR) engine with hardened physical validation, scientific inertia solvers (Mirtich / Sylvester), and lossless round-trip translation between **URDF**, **XACRO**, and **SRDF**.
+It provides a mathematically rigorous, lightweight Intermediate Representation (IR) engine with hardened physical validation, scientific inertia solvers (Mirtich / Sylvester), and lossless round-trip translation between **URDF**, **XACRO**, and **SRDF**.
 
 ## Installation
 
@@ -49,14 +49,14 @@ It provides a mathematically rigorous, zero-dependency Intermediate Representati
 pip install linkforge-core
 ```
 
-Zero external dependencies. No Blender, no ROS installation, no C++ compilation required.
+Minimal pure-Python dependencies (only PyYAML). No Blender, no ROS installation, no C++ compilation required.
 
 ## Why LinkForge Core?
 
 - **Physically Guaranteed Sim Stability**: Zero-mass links or unphysical inertia tensors cause simulators like Gazebo or Isaac Sim to crash. LinkForge Core uses the **Mirtich algorithm** (Divergence Theorem) to calculate exact inertia properties from geometries, validated against **Sylvester's Criterion** to ensure physical validity.
 - **Standardized & Namespaced Assembly**: Easily compile complex robots, merge multiple sub-assemblies (e.g. attaching a gripper to an arm), and apply joint prefixing and limits programmatically using the fluent **Composer API**.
 - **Hardened Sandboxed Security**: Safely parse untrusted third-party robot descriptions. LinkForge Core blocks path-traversal attacks and restrains file reading to designated package boundaries.
-- **Light & Portable**: Zero external dependencies. No C++ compilation required, making it highly portable across standard Python environments, CI/CD pipelines, and HPC clusters.
+- **Light & Portable**: Minimal pure-Python footprint with no C++ extensions. Highly portable across standard Python environments, CI/CD pipelines, and HPC clusters.
 
 ## Quickstart
 
@@ -116,6 +116,36 @@ else:
         print(f"  [{issue.code.name}] {issue.message} on {issue.affected_objects}")
 ```
 
+### Modular Assembly & Sub-Assemblies
+
+Compose validated sub-assemblies from reusable robot components with automated naming prefixing and transform offsets:
+
+```python
+from linkforge.core import RobotBuilder, read_urdf
+
+base_builder = RobotBuilder(robot=read_urdf("mobile_base.urdf"))
+arm_builder  = RobotBuilder(robot=read_urdf("manipulator.urdf"))
+
+# Attach arm onto the base, auto-resolving naming conflicts
+base_builder.attach(
+    arm_builder,
+    at_link="top_plate",
+    prefix="left_arm_",
+    xyz=(0, 0, 0.1),
+)
+
+# Add a MoveIt 2 planning group for the combined assembly
+base_builder.semantic.group(
+    "arm_chain",
+    base_link="top_plate",
+    tip_link="left_arm_end_effector",
+)
+
+robot = base_builder.build(validate=True)
+urdf_xml = base_builder.export_urdf()
+srdf_xml = base_builder.export_srdf()
+```
+
 ### MoveIt 2 & SRDF Semantic Composition
 
 Programmatically compose MoveIt 2 planning groups, end-effectors, and self-collision matrices for SRDF without manually editing XML:
@@ -133,7 +163,8 @@ builder.semantic.group(
     tip_link="wrist_link",
 )
 
-# Define an end-effector
+# Define an end-effector group and register the end-effector
+builder.semantic.group("gripper_group", links=["gripper_link"])
 builder.semantic.end_effector(
     name="gripper",
     group="gripper_group",

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/README.md

@@ -12,7 +12,7 @@
 
 Writing and maintaining URDF or SRDF by hand is fragile: inertia values are guessed, collision geometries drift, and physics bugs surface only after a simulator crash (or worse, on hardware). LinkForge Core solves this by treating your robot as **source code with physical constraints**, not a static XML document.
 
-It provides a mathematically rigorous, zero-dependency Intermediate Representation (IR) engine with hardened physical validation, scientific inertia solvers (Mirtich / Sylvester), and lossless round-trip translation between **URDF**, **XACRO**, and **SRDF**.
+It provides a mathematically rigorous, lightweight Intermediate Representation (IR) engine with hardened physical validation, scientific inertia solvers (Mirtich / Sylvester), and lossless round-trip translation between **URDF**, **XACRO**, and **SRDF**.
 
 ## Installation
 
@@ -20,14 +20,14 @@ It provides a mathematically rigorous, zero-dependency Intermediate Representati
 pip install linkforge-core
 ```
 
-Zero external dependencies. No Blender, no ROS installation, no C++ compilation required.
+Minimal pure-Python dependencies (only PyYAML). No Blender, no ROS installation, no C++ compilation required.
 
 ## Why LinkForge Core?
 
 - **Physically Guaranteed Sim Stability**: Zero-mass links or unphysical inertia tensors cause simulators like Gazebo or Isaac Sim to crash. LinkForge Core uses the **Mirtich algorithm** (Divergence Theorem) to calculate exact inertia properties from geometries, validated against **Sylvester's Criterion** to ensure physical validity.
 - **Standardized & Namespaced Assembly**: Easily compile complex robots, merge multiple sub-assemblies (e.g. attaching a gripper to an arm), and apply joint prefixing and limits programmatically using the fluent **Composer API**.
 - **Hardened Sandboxed Security**: Safely parse untrusted third-party robot descriptions. LinkForge Core blocks path-traversal attacks and restrains file reading to designated package boundaries.
-- **Light & Portable**: Zero external dependencies. No C++ compilation required, making it highly portable across standard Python environments, CI/CD pipelines, and HPC clusters.
+- **Light & Portable**: Minimal pure-Python footprint with no C++ extensions. Highly portable across standard Python environments, CI/CD pipelines, and HPC clusters.
 
 ## Quickstart
 
@@ -87,6 +87,36 @@ else:
         print(f"  [{issue.code.name}] {issue.message} on {issue.affected_objects}")
 ```
 
+### Modular Assembly & Sub-Assemblies
+
+Compose validated sub-assemblies from reusable robot components with automated naming prefixing and transform offsets:
+
+```python
+from linkforge.core import RobotBuilder, read_urdf
+
+base_builder = RobotBuilder(robot=read_urdf("mobile_base.urdf"))
+arm_builder  = RobotBuilder(robot=read_urdf("manipulator.urdf"))
+
+# Attach arm onto the base, auto-resolving naming conflicts
+base_builder.attach(
+    arm_builder,
+    at_link="top_plate",
+    prefix="left_arm_",
+    xyz=(0, 0, 0.1),
+)
+
+# Add a MoveIt 2 planning group for the combined assembly
+base_builder.semantic.group(
+    "arm_chain",
+    base_link="top_plate",
+    tip_link="left_arm_end_effector",
+)
+
+robot = base_builder.build(validate=True)
+urdf_xml = base_builder.export_urdf()
+srdf_xml = base_builder.export_srdf()
+```
+
 ### MoveIt 2 & SRDF Semantic Composition
 
 Programmatically compose MoveIt 2 planning groups, end-effectors, and self-collision matrices for SRDF without manually editing XML:
@@ -104,7 +134,8 @@ builder.semantic.group(
     tip_link="wrist_link",
 )
 
-# Define an end-effector
+# Define an end-effector group and register the end-effector
+builder.semantic.group("gripper_group", links=["gripper_link"])
 builder.semantic.end_effector(
     name="gripper",
     group="gripper_group",

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "linkforge-core"
-version = "1.5.2" # x-release-please-version
+version = "1.5.4" # x-release-please-version
 description = "LinkForge Core: Programmable IR and Physical Validation Engine for Robotics"
 readme = "README.md"
 license = "Apache-2.0"

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/__init__.py

@@ -11,7 +11,7 @@ for parsing, generating, and validating robot descriptions across formats.
 from __future__ import annotations
 
 # Versioning
-__version__ = "1.5.2"  # x-release-please-version
+__version__ = "1.5.4"  # x-release-please-version
 
 # Sub-Package Exposure
 # (Ensures lf.models, lf.parsers, etc. are accessible via dot-notation)
@@ -26,6 +26,15 @@ from . import (
     validation,
 )
 
+# Domain Utilities
+from ._utils.math_utils import clean_float, format_float
+from ._utils.string_utils import (
+    format_scientific,
+    is_valid_name,
+    parse_scientific,
+    sanitize_name,
+)
+
 # Base Architecture: Interfaces and Resolvers
 from .base import (
     FileSystemResolver,
@@ -36,6 +45,7 @@ from .base import (
 
 # Composer API: The LinkForge way to build robots
 from .composer import (
+    IComposer,
     LinkBuilder,
     RobotBuilder,
     box,
@@ -54,6 +64,7 @@ from .constants import (
 from .exceptions import (
     LinkForgeError,
     RobotGeneratorError,
+    RobotGeneratorUnsupportedTypeError,
     RobotMathError,
     RobotModelError,
     RobotParserError,
@@ -259,12 +270,20 @@ __all__ = [
     "IResourceResolver",
     "FileSystemResolver",
     # Composer API
+    "IComposer",
     "RobotBuilder",
     "LinkBuilder",
     "box",
     "cylinder",
     "sphere",
     "mesh",
+    # Domain Utilities
+    "clean_float",
+    "format_float",
+    "sanitize_name",
+    "is_valid_name",
+    "format_scientific",
+    "parse_scientific",
     # Validation & Physics
     "RobotValidator",
     "ValidationResult",
@@ -280,6 +299,7 @@ __all__ = [
     "RobotParserError",
     "RobotParserIOError",
     "RobotGeneratorError",
+    "RobotGeneratorUnsupportedTypeError",
     "RobotValidationError",
     "RobotPhysicsError",
     "RobotMathError",

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/_utils/math_utils.py

@@ -6,11 +6,13 @@ import math
 
 from ..constants import (
     EPSILON,
+    FLOAT_CLEAN_EPSILON,
+    SCIENTIFIC_NOTATION_THRESHOLD,
     SYLVESTER_TOLERANCE_EPSILON,
 )
 
 
-def clean_float(value: float, epsilon: float = EPSILON) -> float:
+def clean_float(value: float, epsilon: float = FLOAT_CLEAN_EPSILON) -> float:
     """Clean up floating point values to avoid -0.0 and very small numbers.
 
     Args:
@@ -37,6 +39,15 @@ def format_float(value: float, precision: int = 6) -> str:
     """
     # Clean up small values and -0.0 first
     cleaned = clean_float(value)
+    if cleaned == 0.0:
+        return "0"
+
+    # Use scientific notation for very small numbers to avoid zeroing them out
+    if abs(cleaned) < SCIENTIFIC_NOTATION_THRESHOLD:
+        formatted = f"{cleaned:.{precision}e}"
+        mantissa, exp = formatted.split("e")
+        mantissa = mantissa.rstrip("0").rstrip(".")
+        return f"{mantissa}e{exp}"
 
     # Format with specified precision
     formatted = f"{cleaned:.{precision}f}"

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/_utils/path_utils.py

@@ -1,5 +1,6 @@
 """Path and resource resolution utilities for LinkForge."""
 
+import contextlib
 import os
 import re
 from pathlib import Path
@@ -91,13 +92,11 @@ def resolve_package_path(
 
 
 def _extract_package_name(xml_path: Path) -> str | None:
-    """Extract <name> from package.xml using regex for performance."""
+    """Extract <name> from package.xml."""
     try:
-        # Lightweight scan of the beginning of the file
-        with open(xml_path, encoding="utf-8") as f:
-            content = f.read(1024)
-            match = re.search(r"<name>(.*?)</name>", content)
-            return match.group(1).strip() if match else None
+        content = xml_path.read_text(encoding="utf-8")
+        match = re.search(r"<name>(.*?)</name>", content)
+        return match.group(1).strip() if match else None
     except Exception:
         return None
 
@@ -142,28 +141,13 @@ def get_export_path(resource: str, relative_to: Path | None = None) -> str:
         The string to be used in the 'filename' attribute.
     """
     # Preserve package:// URIs (never make relative)
-    if resource.startswith("package://") or resource.startswith("package:/"):
+    if resource.startswith(("package://", "package:/")):
         return resource
 
-    # Handle file:// URIs
-    if resource.startswith("file://"):
-        path = normalize_uri_to_path(resource)
-        if relative_to and path.is_absolute():
-            try:
-                # Use .absolute() on relative_to just in case it's not
-                rel = path.relative_to(relative_to.absolute())
-                return str(rel)
-            except ValueError:
-                pass
-        return resource
-
-    # Handle standard paths
-    path = Path(resource)
+    # Convert file:// URI or filesystem path to Path and relativize if possible
+    path = normalize_uri_to_path(resource)
     if relative_to and path.is_absolute():
-        try:
-            rel = path.relative_to(relative_to.absolute())
-            return str(rel)
-        except ValueError:
-            pass
+        with contextlib.suppress(ValueError):
+            return str(path.relative_to(relative_to.absolute()))
 
     return resource

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/_utils/xml_utils.py

@@ -3,7 +3,6 @@
 import math
 import xml.etree.ElementTree as ET
 from collections.abc import Callable
-from datetime import datetime
 from typing import Any
 
 from ..constants import (
@@ -77,22 +76,22 @@ def validate_xml_depth(element: ET.Element, depth: int = 0) -> None:
         validate_xml_depth(child, depth + 1)
 
 
-def get_xml_header(element: ET.Element, version: str) -> str:
+def get_xml_header(element: ET.Element, version: str | None = None) -> str:
     """Standardized header comment for XML files.
 
     Args:
         element: Root XML element (to extract robot name)
-        version: LinkForge version
+        version: Optional LinkForge version
 
     Returns:
         Header string containing XML declaration and meta comment
     """
+    version_str = f" v{version}" if version else ""
     return f"""<?xml version="1.0"?>
 <!--
   Robot: {element.get("name", "robot")}
-  Generated by: LinkForge v{version}
+  Generated by: LinkForge{version_str}
   https://github.com/arounamounchili/linkforge
-  Date: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
 -->
 """
 
@@ -111,7 +110,7 @@ def indent_xml(element: ET.Element, space: str = "  ", level: int = 0) -> None:
 def serialize_xml(
     element: ET.Element,
     pretty_print: bool = True,
-    version: str = "unknown",
+    version: str | None = None,
     namespaces: dict[str, str] | None = None,
 ) -> str:
     """Convert XML element to standardized LinkForge string.
@@ -119,7 +118,7 @@ def serialize_xml(
     Args:
         element: XML element to serialize
         pretty_print: Whether to indent
-        version: LinkForge version for header
+        version: Optional LinkForge version for header
         namespaces: Optional dict of {prefix: uri} to register
 
     Returns:
@@ -152,7 +151,6 @@ def parse_float(
     text: str | None,
     attribute_name: str = "value",
     default: float | None = None,
-    check_name: str | None = None,
 ) -> float:
     """Parse float value from XML with comprehensive validation.
 
@@ -160,7 +158,6 @@ def parse_float(
         text: String to parse
         attribute_name: Context for error messages
         default: Default value if text is None
-        check_name: Alias for attribute_name used in some parsers
 
     Returns:
         Parsed float
@@ -169,9 +166,6 @@ def parse_float(
         RobotMathError: If input is invalid
         RobotValidationError: If attribute is missing
     """
-    # Alias check_name if provided
-    report_name = check_name or attribute_name
-
     if text is not None and not text.strip():
         text = None
 
@@ -180,8 +174,8 @@ def parse_float(
             return default
         raise RobotValidationError(
             ValidationErrorCode.VALUE_EMPTY,
-            f"Missing required attribute: {report_name}",
-            target=report_name,
+            f"Missing required attribute: {attribute_name}",
+            target=attribute_name,
         )
 
     try:
@@ -189,8 +183,8 @@ def parse_float(
         if math.isnan(value) or math.isinf(value):
             raise RobotMathError(
                 ValidationErrorCode.INVALID_VALUE,
-                f"Non-finite float value '{value}' in {report_name}",
-                target=report_name,
+                f"Non-finite float value '{value}' in {attribute_name}",
+                target=attribute_name,
                 value=value,
             )
 
@@ -199,8 +193,8 @@ def parse_float(
         if not (-MAX_REASONABLE_FLOAT < value < MAX_REASONABLE_FLOAT):
             raise RobotMathError(
                 ValidationErrorCode.OUT_OF_RANGE,
-                f"Float value '{value}' in {report_name} is outside reasonable range",
-                target=report_name,
+                f"Float value '{value}' in {attribute_name} is outside reasonable range",
+                target=attribute_name,
                 value=value,
             )
 
@@ -208,8 +202,8 @@ def parse_float(
     except ValueError:
         raise RobotMathError(
             ValidationErrorCode.INVALID_VALUE,
-            f"Invalid float format '{text}' in {report_name}",
-            target=report_name,
+            f"Invalid float format '{text}' in {attribute_name}",
+            target=attribute_name,
             value=text,
         ) from None
 
@@ -218,7 +212,6 @@ def parse_int(
     text: str | None,
     attribute_name: str = "value",
     default: int | None = None,
-    check_name: str | None = None,
 ) -> int:
     """Parse integer value from XML with comprehensive validation.
 
@@ -226,7 +219,6 @@ def parse_int(
         text: String to parse
         attribute_name: Context for error messages
         default: Default value if text is None
-        check_name: Alias for attribute_name for consistent reporting
 
     Returns:
         Parsed integer
@@ -235,8 +227,6 @@ def parse_int(
         RobotMathError: If input format is invalid or value is out of range
         RobotValidationError: If attribute is missing and no default is provided
     """
-    report_name = check_name or attribute_name
-
     if text is not None and not text.strip():
         text = None
 
@@ -245,8 +235,8 @@ def parse_int(
             return default
         raise RobotValidationError(
             ValidationErrorCode.VALUE_EMPTY,
-            f"Missing required attribute: {report_name}",
-            target=report_name,
+            f"Missing required attribute: {attribute_name}",
+            target=attribute_name,
         )
 
     try:
@@ -255,16 +245,16 @@ def parse_int(
         if not (-MAX_REASONABLE_INT < value < MAX_REASONABLE_INT):
             raise RobotMathError(
                 ValidationErrorCode.OUT_OF_RANGE,
-                f"Integer value '{value}' in {report_name} is outside reasonable range",
-                target=report_name,
+                f"Integer value '{value}' in {attribute_name} is outside reasonable range",
+                target=attribute_name,
                 value=value,
             )
         return value
     except ValueError:
         raise RobotMathError(
             ValidationErrorCode.INVALID_VALUE,
-            f"Invalid integer format '{text}' in {report_name}",
-            target=report_name,
+            f"Invalid integer format '{text}' in {attribute_name}",
+            target=attribute_name,
             value=text,
         ) from None
 

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/base.py

@@ -20,9 +20,7 @@ from ._utils.path_utils import normalize_uri_to_path, resolve_package_path
 from .exceptions import (
     LinkForgeError,
     RobotGeneratorError,
-    RobotModelError,
-    RobotParserError,
-    XacroDetectedError,
+    RobotGeneratorUnsupportedTypeError,
 )
 
 if TYPE_CHECKING:
@@ -32,15 +30,10 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 
 __all__ = [
+    "FileSystemResolver",
+    "IResourceResolver",
     "RobotGenerator",
     "RobotParser",
-    "IResourceResolver",
-    "FileSystemResolver",
-    "LinkForgeError",
-    "RobotGeneratorError",
-    "RobotModelError",
-    "RobotParserError",
-    "XacroDetectedError",
 ]
 
 
@@ -98,7 +91,7 @@ class RobotGenerator(ABC, Generic[T]):
         elif isinstance(content, bytes):
             filepath.write_bytes(content)
         else:
-            raise RobotGeneratorError(self.__class__.__name__, type(content))
+            raise RobotGeneratorUnsupportedTypeError(type(content), self.__class__.__name__)
 
 
 class RobotParser(ABC, Generic[T]):

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/composer/__init__.py

@@ -5,7 +5,8 @@ by programmatically constructing links, joints, and semantic data.
 """
 
 from .helpers import box, cylinder, mesh, sphere
+from .interfaces import IComposer
 from .link_builder import LinkBuilder
 from .robot_builder import RobotBuilder
 
-__all__ = ["RobotBuilder", "LinkBuilder", "box", "cylinder", "sphere", "mesh"]
+__all__ = ["IComposer", "RobotBuilder", "LinkBuilder", "box", "cylinder", "sphere", "mesh"]

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/composer/interfaces.py

@@ -6,19 +6,18 @@ communicate without tight coupling.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from ..models.robot import Robot
     from .link_builder import LinkBuilder
 
 
+@runtime_checkable
 class IComposer(Protocol):
     """Interface for a builder that can contain and manage links."""
 
     robot: Robot
-    _active_link_builders: list[LinkBuilder]
-    _parent_stack: list[str]
 
     def link(
         self, name: str, parent: str | None = None, joint_name: str | None = None
@@ -35,3 +34,15 @@ class IComposer(Protocol):
     def build(self, validate: bool = True) -> Robot:
         """Finalize the assembly and return the completed Robot model."""
         ...
+
+    def register_link_builder(self, builder: LinkBuilder) -> None:
+        """Register an active LinkBuilder with this composer."""
+        ...
+
+    def push_parent(self, name: str) -> None:
+        """Push a parent link name onto the hierarchy context stack."""
+        ...
+
+    def pop_parent(self, name: str | None = None) -> None:
+        """Pop a parent link name from the hierarchy context stack."""
+        ...

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/composer/link_builder.py

@@ -11,7 +11,6 @@ Core Components:
 
 from __future__ import annotations
 
-import logging
 from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any
 
@@ -34,6 +33,7 @@ from ..constants import (
     HW_IF_EFFORT,
 )
 from ..exceptions import RobotValidationError, ValidationErrorCode
+from ..logging_config import get_logger
 from ..models.gazebo import GazeboElement
 from ..models.geometry import Geometry, Transform, Vector3
 from ..models.joint import (
@@ -65,7 +65,7 @@ from ..physics.inertia import calculate_inertia
 if TYPE_CHECKING:
     from .interfaces import IComposer
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 @dataclass
@@ -126,7 +126,7 @@ class LinkBuilder:
         self._committed = False
         self._in_context = False
 
-        self._builder._active_link_builders.append(self)
+        self._builder.register_link_builder(self)
 
     def __enter__(self) -> LinkBuilder:
         """Enter the context of this link.
@@ -140,7 +140,7 @@ class LinkBuilder:
         skeletal_link = Link(name=self._link_name)
         self._builder.robot.add_link(skeletal_link, overwrite=True)
 
-        self._builder._parent_stack.append(self._link_name)
+        self._builder.push_parent(self._link_name)
         return self
 
     def __exit__(
@@ -154,10 +154,7 @@ class LinkBuilder:
         Pops this link's name from the parent stack and automatically commits the
         link to flush its configured properties if no exception occurred.
         """
-        if self._builder._parent_stack and self._builder._parent_stack[-1] == self._link_name:
-            self._builder._parent_stack.pop()
-        elif self._link_name in self._builder._parent_stack:
-            self._builder._parent_stack.remove(self._link_name)
+        self._builder.pop_parent(self._link_name)
 
         if exc_type is None:
             self._commit()

{linkforge_core-1.5.2 → linkforge_core-1.5.4}/src/linkforge/core/composer/robot_builder.py

@@ -59,6 +59,24 @@ class RobotBuilder:
         self._active_link_builders: list[LinkBuilder] = []
         self._parent_stack: list[str] = []
 
+    def register_link_builder(self, builder: LinkBuilder) -> None:
+        """Register an active LinkBuilder with this composer."""
+        self._active_link_builders.append(builder)
+
+    def push_parent(self, name: str) -> None:
+        """Push a parent link name onto the hierarchy context stack."""
+        self._parent_stack.append(name)
+
+    def pop_parent(self, name: str | None = None) -> None:
+        """Pop a parent link name from the hierarchy context stack."""
+        if name is not None:
+            if self._parent_stack and self._parent_stack[-1] == name:
+                self._parent_stack.pop()
+            elif name in self._parent_stack:
+                self._parent_stack.remove(name)
+        elif self._parent_stack:
+            self._parent_stack.pop()
+
     def link(
         self, name: str, parent: str | None = None, joint_name: str | None = None
     ) -> LinkBuilder: