devagent-physical-engine 0.12.4__tar.gz → 0.13.0__tar.gz

{devagent_physical_engine-0.12.4/src/devagent_physical_engine.egg-info → devagent_physical_engine-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devagent-physical-engine
-Version: 0.12.4
+Version: 0.13.0
 Summary: Verification-first agentic engineering, simulation, and evidence runtime for robotics and industrial automation.
 Author: Tom Ha
 License: All Rights Reserved
@@ -143,6 +143,24 @@ While the command runs, stage-by-stage progress is printed to `stderr` and the f
 
 Use `--quiet` when a script or CI job needs JSON without terminal progress.
 
+## Commercial project spine
+
+v0.13 adds durable customer project, site, and workcell identity around the existing verification engine. Project manifests are fingerprinted, Twin builds can be persisted as immutable revisions, and project evidence is stored locally in SQLite with content hashes.
+
+Create and inspect a project:
+
+```bash
+devagent-physical project init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+
+devagent-physical project show warehouse-cnc-04
+devagent-physical project revisions warehouse-cnc-04
+```
+
+The default store is `~/.devagent/projects.db`. This project spine is the durable boundary for upcoming customer Twin import, requirement traceability, physical test campaigns, regression analysis, and FAT reporting. It does not by itself claim customer geometry import, physical qualification, site qualification, or real execution.
+
 ## Task-specific visual simulation
 
 For the supported v0.12 UR5e `load` scope, `--visualize` continues from the verified high-level task into a physical simulation path:
@@ -408,6 +426,7 @@ A green `main` release is tied to the exact CI-tested commit. Release artifacts
 
 Detailed engineering documentation lives in the repository:
 
+- [Commercial project spine](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md)
 - [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
 - [Architecture](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md)
 - [Agent Core](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AGENT_CORE.md)
@@ -424,9 +443,9 @@ Detailed engineering documentation lives in the repository:
 
 ## Project status
 
-**v0.12.4 — Beta software / evidence-gated task-specific physical simulation.**
+**v0.13.0 — Beta software / commercial project spine + evidence-gated task-specific physical simulation.**
 
-The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
+The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. v0.13 adds durable project/site/workcell identity, immutable Twin revisions, and content-addressed local evidence; it does not claim arbitrary customer Twin import or customer-site qualification. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
 
 ## Ownership
 

{devagent_physical_engine-0.12.4 → devagent_physical_engine-0.13.0}/README.md

@@ -102,6 +102,24 @@ While the command runs, stage-by-stage progress is printed to `stderr` and the f
 
 Use `--quiet` when a script or CI job needs JSON without terminal progress.
 
+## Commercial project spine
+
+v0.13 adds durable customer project, site, and workcell identity around the existing verification engine. Project manifests are fingerprinted, Twin builds can be persisted as immutable revisions, and project evidence is stored locally in SQLite with content hashes.
+
+Create and inspect a project:
+
+```bash
+devagent-physical project init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+
+devagent-physical project show warehouse-cnc-04
+devagent-physical project revisions warehouse-cnc-04
+```
+
+The default store is `~/.devagent/projects.db`. This project spine is the durable boundary for upcoming customer Twin import, requirement traceability, physical test campaigns, regression analysis, and FAT reporting. It does not by itself claim customer geometry import, physical qualification, site qualification, or real execution.
+
 ## Task-specific visual simulation
 
 For the supported v0.12 UR5e `load` scope, `--visualize` continues from the verified high-level task into a physical simulation path:
@@ -367,6 +385,7 @@ A green `main` release is tied to the exact CI-tested commit. Release artifacts
 
 Detailed engineering documentation lives in the repository:
 
+- [Commercial project spine](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md)
 - [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
 - [Architecture](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md)
 - [Agent Core](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AGENT_CORE.md)
@@ -383,9 +402,9 @@ Detailed engineering documentation lives in the repository:
 
 ## Project status
 
-**v0.12.4 — Beta software / evidence-gated task-specific physical simulation.**
+**v0.13.0 — Beta software / commercial project spine + evidence-gated task-specific physical simulation.**
 
-The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
+The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. v0.13 adds durable project/site/workcell identity, immutable Twin revisions, and content-addressed local evidence; it does not claim arbitrary customer Twin import or customer-site qualification. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
 
 ## Ownership
 
@@ -393,4 +412,4 @@ DevAgent Smart Physical Engine
 Copyright © 2026 Tom Ha  
 Original creator: Tom Ha  
 Original project: https://github.com/tomha85/devagent-physical-engine  
-All rights reserved.
+All rights reserved.

{devagent_physical_engine-0.12.4 → devagent_physical_engine-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devagent-physical-engine"
-version = "0.12.4"
+version = "0.13.0"
 description = "Verification-first agentic engineering, simulation, and evidence runtime for robotics and industrial automation."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{devagent_physical_engine-0.12.4 → devagent_physical_engine-0.13.0}/src/devagent_physical_engine/__init__.py

@@ -10,6 +10,15 @@ from .models import (
     WorldState,
 )
 from .physical_motion import JointTrajectoryPoint, MotionExecutionMetrics, PhysicalMotionPlan
+from .project import (
+    EvidenceArtifactRecord,
+    ProjectError,
+    ProjectManifest,
+    ProjectService,
+    ProjectTwinBuildOutcome,
+    SQLiteProjectRepository,
+    TwinRevisionRecord,
+)
 from .robot_platform import (
     BUILTIN_ROBOT_PROFILES,
     QualificationState,
@@ -30,6 +39,13 @@ __all__ = [
     "JointTrajectoryPoint",
     "MotionExecutionMetrics",
     "PhysicalMotionPlan",
+    "ProjectError",
+    "ProjectManifest",
+    "ProjectService",
+    "ProjectTwinBuildOutcome",
+    "SQLiteProjectRepository",
+    "TwinRevisionRecord",
+    "EvidenceArtifactRecord",
     "BUILTIN_ROBOT_PROFILES",
     "QualificationState",
     "RobotProfile",
@@ -41,4 +57,4 @@ __all__ = [
     "TwinValidator",
 ]
 
-__version__ = "0.12.4"
+__version__ = "0.13.0"

{devagent_physical_engine-0.12.4 → devagent_physical_engine-0.13.0}/src/devagent_physical_engine/cli.py

@@ -24,6 +24,34 @@ def _parser() -> argparse.ArgumentParser:
     sub.add_parser("qualify", help="Run deterministic cross-vendor smoke qualification")
     add_qualification_parsers(sub)
 
+    project = sub.add_parser(
+        "project",
+        help="Manage durable customer project/site/workcell context and Twin revisions",
+    )
+    project.add_argument(
+        "--db",
+        default="~/.devagent/projects.db",
+        help="SQLite project/evidence database path",
+    )
+    project_sub = project.add_subparsers(dest="project_command", required=True)
+
+    project_init = project_sub.add_parser("init", help="Create a new customer project")
+    project_init.add_argument("project_id")
+    project_init.add_argument("--name", required=True)
+    project_init.add_argument("--site", required=True)
+    project_init.add_argument("--workcell", required=True)
+
+    project_sub.add_parser("list", help="List known customer projects")
+
+    project_show = project_sub.add_parser("show", help="Show one project and latest Twin revision")
+    project_show.add_argument("project_id")
+
+    project_revisions = project_sub.add_parser(
+        "revisions",
+        help="List immutable Twin revisions for a project",
+    )
+    project_revisions.add_argument("project_id")
+
     setup = sub.add_parser(
         "setup",
         help="Configure an explicit system profile; pip installation never changes OS packages",
@@ -92,6 +120,92 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _project_command(args: argparse.Namespace) -> int:
+    from .project import ProjectError, ProjectManifest, SQLiteProjectRepository
+
+    repository = SQLiteProjectRepository(args.db)
+    try:
+        if args.project_command == "init":
+            manifest = repository.create_project(
+                ProjectManifest(
+                    project_id=args.project_id,
+                    name=args.name,
+                    site_id=args.site,
+                    workcell_id=args.workcell,
+                )
+            )
+            print(
+                json.dumps(
+                    {
+                        **manifest.to_dict(),
+                        "manifest_hash": manifest.fingerprint,
+                        "database": str(repository.path),
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+
+        if args.project_command == "list":
+            projects = repository.list_projects()
+            print(
+                json.dumps(
+                    {
+                        "database": str(repository.path),
+                        "projects": [
+                            {**item.to_dict(), "manifest_hash": item.fingerprint}
+                            for item in projects
+                        ],
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+
+        if args.project_command == "show":
+            project = repository.get_project(args.project_id)
+            latest = repository.latest_twin_revision(project.project_id)
+            print(
+                json.dumps(
+                    {
+                        "project": {**project.to_dict(), "manifest_hash": project.fingerprint},
+                        "latest_twin_revision": None if latest is None else latest.to_dict(),
+                        "database": str(repository.path),
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+
+        if args.project_command == "revisions":
+            project = repository.get_project(args.project_id)
+            revisions = repository.list_twin_revisions(project.project_id)
+            print(
+                json.dumps(
+                    {
+                        "project_id": project.project_id,
+                        "revisions": [item.to_dict() for item in revisions],
+                        "database": str(repository.path),
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+    except ProjectError as exc:
+        print(
+            json.dumps(
+                {
+                    "passed": False,
+                    "failure_code": str(exc),
+                    "database": str(repository.path),
+                },
+                indent=2,
+            )
+        )
+        return 10
+    return 2
+
+
 def _setup_profile(args: argparse.Namespace) -> int:
     from .ros2 import RosDoctor, SubprocessRosRunner
     from .setup_profile import (
@@ -367,6 +481,9 @@ def main(argv: list[str] | None = None) -> int:
     if qualification_code is not None:
         return qualification_code
 
+    if args.command == "project":
+        return _project_command(args)
+
     if args.command == "setup":
         return _setup_profile(args)
 

{devagent_physical_engine-0.12.4 → devagent_physical_engine-0.13.0}/src/devagent_physical_engine/physical_motion.py

@@ -160,6 +160,12 @@ class MotionExecutionMetrics:
     min_clearance_m: float | None = None
     final_tcp_error_m: float | None = None
     energy_proxy: float | None = None
+    joint_state_sample_rate_hz: float | None = None
+    max_sample_gap_s: float | None = None
+    trajectory_duration_error_s: float | None = None
+    tracking_sample_count: int | None = None
+    tracking_scope: str = "endpoint_only"
+    tracking_interpolation: str = "unspecified"
     planner_retries: int | None = None
     trajectory_retries: int | None = None
     failure_codes: tuple[str, ...] = ()
@@ -168,6 +174,10 @@ class MotionExecutionMetrics:
     def __post_init__(self) -> None:
         if not self.metrics_origin.strip():
             raise PhysicalMotionError("metrics_origin_required")
+        if not self.tracking_scope.strip():
+            raise PhysicalMotionError("tracking_scope_required")
+        if not self.tracking_interpolation.strip():
+            raise PhysicalMotionError("tracking_interpolation_required")
         for name in (
             "observed_duration_s",
             "planned_duration_s",
@@ -178,6 +188,9 @@ class MotionExecutionMetrics:
             "min_clearance_m",
             "final_tcp_error_m",
             "energy_proxy",
+            "joint_state_sample_rate_hz",
+            "max_sample_gap_s",
+            "trajectory_duration_error_s",
         ):
             value = getattr(self, name)
             if value is None:
@@ -185,7 +198,7 @@ class MotionExecutionMetrics:
             numeric = float(value)
             if not isfinite(numeric) or numeric < 0:
                 raise PhysicalMotionError(f"metric_invalid:{name}")
-        for name in ("planner_retries", "trajectory_retries"):
+        for name in ("tracking_sample_count", "planner_retries", "trajectory_retries"):
             value = getattr(self, name)
             if value is not None and value < 0:
                 raise PhysicalMotionError(f"metric_invalid:{name}")

devagent_physical_engine-0.13.0/src/devagent_physical_engine/pose_math.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import acos, isfinite, sqrt
+
+
+class PoseMathError(ValueError):
+    pass
+
+
+def _finite(values: tuple[float, ...], *, code: str) -> tuple[float, ...]:
+    converted = tuple(float(value) for value in values)
+    if any(not isfinite(value) for value in converted):
+        raise PoseMathError(code)
+    return converted
+
+
+def normalize_quaternion(
+    quaternion_xyzw: tuple[float, float, float, float],
+) -> tuple[float, float, float, float]:
+    values = _finite(tuple(quaternion_xyzw), code="quaternion_non_finite")
+    if len(values) != 4:
+        raise PoseMathError("quaternion_size_invalid")
+    norm = sqrt(sum(value * value for value in values))
+    if norm <= 1e-12:
+        raise PoseMathError("quaternion_zero")
+    normalized = tuple(value / norm for value in values)
+    # q and -q encode the same rotation. Keep one deterministic representation.
+    for component in (normalized[3], normalized[0], normalized[1], normalized[2]):
+        if abs(component) <= 1e-15:
+            continue
+        return tuple(-value for value in normalized) if component < 0.0 else normalized
+    raise PoseMathError("quaternion_zero")
+
+
+def quaternion_multiply(
+    first: tuple[float, float, float, float],
+    second: tuple[float, float, float, float],
+) -> tuple[float, float, float, float]:
+    ax, ay, az, aw = normalize_quaternion(first)
+    bx, by, bz, bw = normalize_quaternion(second)
+    return normalize_quaternion(
+        (
+            aw * bx + ax * bw + ay * bz - az * by,
+            aw * by - ax * bz + ay * bw + az * bx,
+            aw * bz + ax * by - ay * bx + az * bw,
+            aw * bw - ax * bx - ay * by - az * bz,
+        )
+    )
+
+
+def quaternion_conjugate(
+    quaternion_xyzw: tuple[float, float, float, float],
+) -> tuple[float, float, float, float]:
+    x, y, z, w = normalize_quaternion(quaternion_xyzw)
+    return (-x, -y, -z, w)
+
+
+def rotate_vector(
+    quaternion_xyzw: tuple[float, float, float, float],
+    vector_xyz: tuple[float, float, float],
+) -> tuple[float, float, float]:
+    qx, qy, qz, qw = normalize_quaternion(quaternion_xyzw)
+    vx, vy, vz = _finite(tuple(vector_xyz), code="vector_non_finite")
+    if len((vx, vy, vz)) != 3:
+        raise PoseMathError("vector_size_invalid")
+    # Unit-quaternion vector rotation without constructing temporary quaternions.
+    tx = 2.0 * (qy * vz - qz * vy)
+    ty = 2.0 * (qz * vx - qx * vz)
+    tz = 2.0 * (qx * vy - qy * vx)
+    return (
+        vx + qw * tx + (qy * tz - qz * ty),
+        vy + qw * ty + (qz * tx - qx * tz),
+        vz + qw * tz + (qx * ty - qy * tx),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class RigidPose:
+    position_m: tuple[float, float, float]
+    quaternion_xyzw: tuple[float, float, float, float]
+
+    def __post_init__(self) -> None:
+        position = _finite(tuple(self.position_m), code="pose_position_non_finite")
+        if len(position) != 3:
+            raise PoseMathError("pose_position_size_invalid")
+        object.__setattr__(self, "position_m", position)
+        object.__setattr__(
+            self,
+            "quaternion_xyzw",
+            normalize_quaternion(tuple(self.quaternion_xyzw)),
+        )
+
+    @classmethod
+    def identity(cls) -> "RigidPose":
+        return cls((0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 1.0))
+
+    def compose(self, child: "RigidPose") -> "RigidPose":
+        offset = rotate_vector(self.quaternion_xyzw, child.position_m)
+        return RigidPose(
+            tuple(self.position_m[index] + offset[index] for index in range(3)),
+            quaternion_multiply(self.quaternion_xyzw, child.quaternion_xyzw),
+        )
+
+    def inverse(self) -> "RigidPose":
+        inverse_q = quaternion_conjugate(self.quaternion_xyzw)
+        inverse_position = rotate_vector(
+            inverse_q,
+            tuple(-value for value in self.position_m),
+        )
+        return RigidPose(inverse_position, inverse_q)
+
+    def relative_to(self, parent: "RigidPose") -> "RigidPose":
+        return parent.inverse().compose(self)
+
+    def position_error_m(self, other: "RigidPose") -> float:
+        return sqrt(
+            sum(
+                (self.position_m[index] - other.position_m[index]) ** 2
+                for index in range(3)
+            )
+        )
+
+    def orientation_error_rad(self, other: "RigidPose") -> float:
+        first = normalize_quaternion(self.quaternion_xyzw)
+        second = normalize_quaternion(other.quaternion_xyzw)
+        dot = abs(sum(a * b for a, b in zip(first, second)))
+        return 2.0 * acos(max(-1.0, min(1.0, dot)))
+
+    def to_dict(self) -> dict[str, list[float]]:
+        return {
+            "position_m": list(self.position_m),
+            "quaternion_xyzw": list(self.quaternion_xyzw),
+        }