[codex] Add cuVSLAM agent-readiness package

.agent/validation_result.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/nvidia-isaac/cuVSLAM/.agent/validation_result.schema.json",
+  "title": "cuVSLAM Agent Readiness Validation Result",
+  "type": "object",
+  "required": ["schema_version", "product", "mode", "status", "timestamp_utc", "repo", "checks"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "product": {
+      "type": "string",
+      "const": "cuVSLAM"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["static", "gpu"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pass", "fail"]
+    },
+    "timestamp_utc": {
+      "type": "string"
+    },
+    "repo": {
+      "type": "object",
+      "required": ["commit", "root"],
+      "properties": {
+        "commit": {
+          "type": ["string", "null"]
+        },
+        "root": {
+          "type": "string"
+        }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status", "detail"],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail"]
+          },
+          "detail": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

.codex/skills/cuvslam-agent-readiness/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: cuvslam-agent-readiness
+description: Validate cuVSLAM agent-readiness scaffolding and route agents to static or GPU validation lanes.
+---
+
+# cuVSLAM Agent Readiness
+
+## Description
+
+Use this skill when an agent needs to validate cuVSLAM readiness, emit a
+machine-readable validation result, or decide whether the current environment is
+only suitable for static checks or full GPU runtime validation.
+
+## Prerequisites
+
+- Python 3.9 or newer for static validation.
+- CUDA Toolkit 12 or 13 and NVIDIA GPU hardware for full runtime validation.
+- A built or wheel-installed PyCuVSLAM package before running GPU validation.
+- No secrets are required for either validation lane.
+
+## Commands
+
+Run the no-secret static lane:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+```
+
+Run the root readiness test:
+
+```bash
+python3 -m unittest discover -s tests -p "test_*.py" -v
+```
+
+Run the GPU lane after installing or building PyCuVSLAM:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+```
+
+## Output
+
+The validation command writes `reports/validation_result.json`. The output uses
+`.agent/validation_result.schema.json` and contains `status`, `mode`,
+`timestamp_utc`, repository commit metadata, and a list of named checks.
+
+## Troubleshooting
+
+- For static failures, read each failed `checks[].name` in
+  `reports/validation_result.json` and restore the missing readiness file.
+- For cache permission failures, set `PYTHONPYCACHEPREFIX=.cache/pycache`.
+- For GPU import failures, install a cuVSLAM wheel matching Python, CUDA, OS,
+  and architecture, or build the repository first.
+
+## Safety
+
+The static lane is no-secret and does not download datasets or access cameras.
+The GPU lane runs local imports and tests only; do not add live camera,
+credential, destructive cleanup, or dataset deletion steps to the default lane.

.env_example

@@ -0,0 +1,7 @@
+# cuVSLAM local development placeholders.
+# No secrets are required for the default no-secret readiness lane.
+
+CUVSLAM_DATASET_ROOT=dataset
+CUVSLAM_BUILD_DIR=build
+CUVSLAM_VALIDATION_OUTPUT=reports/validation_result.json
+PYTHONPYCACHEPREFIX=.cache/pycache

.github/workflows/agent-readiness.yml

@@ -0,0 +1,49 @@
+name: Agent Readiness
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      run_gpu_validation:
+        description: Run the self-hosted GPU validation lane.
+        required: false
+        default: "false"
+
+jobs:
+  static-readiness:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run readiness unit tests
+        run: python3 -m unittest discover -s tests -p "test_*.py" -v
+
+      - name: Emit static validation result
+        run: python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+
+      - name: Upload validation result
+        uses: actions/upload-artifact@v4
+        with:
+          name: cuvslam-static-validation-result
+          path: reports/validation_result.json
+
+  gpu-validation:
+    if: github.event_name == 'workflow_dispatch' && inputs.run_gpu_validation == 'true'
+    runs-on: [self-hosted, linux, x64, gpu]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run GPU validation
+        run: python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+
+      - name: Upload GPU validation result
+        uses: actions/upload-artifact@v4
+        with:
+          name: cuvslam-gpu-validation-result
+          path: reports/validation_result.json

.gitignore

@@ -9,6 +9,7 @@
 __pycache__/
 *.egg-info
 build/
+reports/
 dataset/
 /datasets/
 ext_src

AGENTS.md

@@ -0,0 +1,80 @@
+# Agent Instructions
+
+## Use This When
+
+Use this repository to build, test, or validate cuVSLAM, the CUDA-accelerated
+visual odometry, visual-inertial odometry, mapping, and localization library.
+
+## Prerequisites
+
+- Ubuntu 22.04 or 24.04 on x86_64 or Jetson.
+- Python 3.9 or newer.
+- CMake 3.19 or newer, gcc/g++, git, and git-lfs.
+- CUDA Toolkit 12 or 13 for full build and runtime validation.
+- NVIDIA GPU hardware for cuVSLAM tracking, mapping, localization, and Python
+  API tests.
+- No secrets are required for the no-secret static readiness lane.
+
+## Repo Map
+
+- `README.md`: product overview, installation, build, and first-run guidance.
+- `examples/README.md`: dataset and live-camera examples.
+- `python/pyproject.toml`: PyCuVSLAM package metadata.
+- `python/test/`: Python API tracking, mapping, and binding tests.
+- `TROUBLESHOOTING.md`: calibration, synchronization, image quality, and
+  debugging guidance.
+- `agent-readiness.yaml`: agent-readiness CI contract.
+- `scripts/agent_readiness_smoke.py`: emits `reports/validation_result.json`.
+
+## Commands
+
+Run the no-secret static readiness lane:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+```
+
+Run the root readiness unit test:
+
+```bash
+python3 -m unittest discover -s tests -p "test_*.py" -v
+```
+
+Compile Python sources without running GPU code:
+
+```bash
+PYTHONPYCACHEPREFIX=.cache/pycache python3 -m compileall python scripts tests -q
+```
+
+Run full Python API validation after building or installing PyCuVSLAM on a
+CUDA-capable host:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+```
+
+## Output
+
+The readiness lanes write `reports/validation_result.json` using the schema in
+`.agent/validation_result.schema.json`. A passing static result proves that
+agent-readiness scaffolding, docs, and Python syntax are healthy. A passing GPU
+result proves that PyCuVSLAM imports and the Python API regression tests pass in
+the current environment.
+
+## Troubleshooting
+
+- If static validation fails, inspect the failed check names in
+  `reports/validation_result.json`.
+- If Python bytecode writes fail on macOS or in a sandbox, set
+  `PYTHONPYCACHEPREFIX=.cache/pycache`.
+- If GPU validation fails at `cuvslam_import`, install a release wheel matching
+  the Python, CUDA, OS, and architecture combination or build from source first.
+- If tracking quality is poor, use `TROUBLESHOOTING.md` to check calibration,
+  synchronization, frame continuity, image quality, and coordinate frames.
+
+## Safety
+
+- Do not commit datasets, camera recordings, generated maps, `.env`, build
+  directories, or generated `reports/` outputs.
+- Do not add secret-bearing environment variables to examples or CI.
+- Keep destructive cleanup outside the default validation commands.

README.md

@@ -28,6 +28,28 @@ cuVSLAM is the library by NVIDIA, providing various Visual Tracking Camera modes
 The quickest way to get started is to [install PyCuVSLAM from a pre-built wheel](#install-from-wheels)
 and explore the [examples](examples/).
 
+## Agent Quick Start
+
+Use this path when validating the repository in a no-secret CI or coding-agent
+environment before running CUDA/GPU workflows:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+python3 -m unittest discover -s tests -p "test_*.py" -v
+```
+
+Expected static success signal: `reports/validation_result.json` exists and has
+`status=pass` and `mode=static`. Full runtime validation still requires CUDA,
+NVIDIA GPU hardware, and a built or wheel-installed PyCuVSLAM package:
+
+```bash
+python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+```
+
+Agent-specific routing, outputs, and troubleshooting are documented in
+[`AGENTS.md`](AGENTS.md), [`llms.txt`](llms.txt), and
+[`agent-readiness.yaml`](agent-readiness.yaml).
+
 ## ROS2 Support
 
 To use cuVSLAM in a ROS2 environment:

agent-readiness.yaml

@@ -0,0 +1,66 @@
+agent_readiness:
+  product: cuVSLAM
+  tier_target: agent_native
+  product_promise: CUDA-accelerated visual odometry, visual-inertial odometry, mapping, and localization for robotics camera workflows.
+  release_surface: open_source
+  validation_path: python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+  success_criteria:
+    - reports/validation_result.json has status=pass and mode=gpu on a CUDA-capable host.
+    - Static no-secret readiness emits reports/validation_result.json without secrets, datasets, or GPU hardware.
+    - Python API tracking and map tests pass after a built or wheel-installed cuVSLAM package is available.
+  prerequisites:
+    runtime: Ubuntu 22.04 or 24.04, Python 3.9+, CMake 3.19+, CUDA Toolkit 12 or 13, and NVIDIA GPU for real tracking validation.
+    secrets: none
+    hardware: NVIDIA GPU required for full cuVSLAM runtime validation; CPU is sufficient for static syntax smoke.
+  runner:
+    needs:
+      - python>=3.9
+      - cuda>=12 for runtime tests
+      - nvidia-gpu for full validation
+      - no-secret-lane
+  release_thresholds:
+    minimum_tier: agent_native
+    max_blocking_issues: 0
+  jobs:
+    - name: static-agent-readiness
+      priority: P0
+      prompt: Run the no-secret static readiness lane and report the validation_result.json path.
+      expected_artifacts:
+        - reports/validation_result.json
+    - name: pycuvslam-tracking-and-map-regression
+      priority: P0
+      prompt: Run the Python tracking and map regression tests after installing or building cuVSLAM, then report the validation_result.json path.
+      expected_artifacts:
+        - reports/validation_result.json
+  entrypoints:
+    docs:
+      - README.md
+      - AGENTS.md
+      - llms.txt
+      - TROUBLESHOOTING.md
+      - examples/README.md
+      - python/pyproject.toml
+      - .codex/skills/cuvslam-agent-readiness/SKILL.md
+    skills:
+      - .codex/skills/cuvslam-agent-readiness
+    cli:
+      - python3 scripts/agent_readiness_smoke.py --help
+      - python3 python/setup.py --help
+    services:
+      - .agent/validation_result.schema.json
+  smoke_tests:
+    no_secret:
+      - python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+    dry_run:
+      - PYTHONPYCACHEPREFIX=.cache/pycache python3 -m compileall python scripts tests -q
+  required_artifacts:
+    - reports/validation_result.json
+  agent_tasks:
+    - name: static-agent-readiness
+      prompt: Run the no-secret static readiness lane and report the validation_result.json path.
+      expected_artifacts:
+        - reports/validation_result.json
+    - name: pycuvslam-tracking-and-map-regression
+      prompt: Run the Python tracking and map regression tests after installing or building cuVSLAM, then report the validation_result.json path.
+      expected_artifacts:
+        - reports/validation_result.json

llms.txt

@@ -0,0 +1,29 @@
+# cuVSLAM LLM Entry Point
+
+Product: cuVSLAM
+Repository: https://github.com/nvidia-isaac/cuVSLAM
+
+Purpose:
+cuVSLAM provides CUDA-accelerated visual odometry, visual-inertial odometry,
+mapping, and localization for robotics camera workflows.
+
+Canonical files:
+- README.md
+- AGENTS.md
+- agent-readiness.yaml
+- TROUBLESHOOTING.md
+- examples/README.md
+- python/pyproject.toml
+- python/test/test_tracking.py
+- python/test/test_map.py
+- .agent/validation_result.schema.json
+- .codex/skills/cuvslam-agent-readiness/SKILL.md
+
+Fast no-secret validation:
+python3 scripts/agent_readiness_smoke.py --mode static --output reports/validation_result.json
+
+GPU validation after building or installing PyCuVSLAM:
+python3 scripts/agent_readiness_smoke.py --mode gpu --output reports/validation_result.json
+
+Expected primary artifact:
+reports/validation_result.json

requirements.txt

@@ -0,0 +1,5 @@
+# Root manifest for agent-readiness and example setup discovery.
+# Python binding package metadata lives in python/pyproject.toml.
+# Python binding test dependencies live in python/test/requirements.txt.
+
+-r examples/requirements.txt