Metadata-Version: 2.4
Name: miskeyed-xr-agent
Version: 0.1.0
Summary: Host-neutral spatial intent types for XR integrations
Keywords: openxr,xr,spatial-computing,usd
Author: miskeyed-xr-agent contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Project-URL: Homepage, https://github.com/samjay3d/miskeyed-xr-agent
Project-URL: Repository, https://github.com/samjay3d/miskeyed-xr-agent
Project-URL: Documentation, https://github.com/samjay3d/miskeyed-xr-agent/tree/main/docs
Project-URL: Issues, https://github.com/samjay3d/miskeyed-xr-agent/issues
Project-URL: Changelog, https://github.com/samjay3d/miskeyed-xr-agent/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# miskeyed-xr-agent

`miskeyed-xr-agent` is a small C++20 investigation into turning human XR input into deterministic, host-neutral spatial intent. OpenXR is an input backend, not the public data model. The project deliberately contains no renderer, scene graph, USD/Workbench/Kit dependency, network service, speech recognizer, computer vision system, or AI model.

## Milestone 1

The first milestone provides:

* host-neutral poses, rays, semantic pointing, capability snapshots, and intent frames;
* a Khronos OpenXR 1.1 loader probe that enumerates runtime capabilities and creates `select`, `aim_pose`, and `grip_pose` semantic actions;
* a host-owned-session OpenXR sampler that synchronizes semantic aim actions and locates head/aim poses at one `XrTime`;
* a versioned JSONL recording draft and hardware-free tests; and
* a bounded timeline that turns sparse final text into one spatially grounded event instead of repeating text on realtime frames; and
* a documented boundary between portable XR input and host-owned scene queries.

If you are building `miskeyed-xr-agent-usd` or an Omniverse Kit extension, start
with the concrete [host integration pass](docs/INTEGRATION.md). The included
`spatial-host-example` proves the consumer path without OpenXR or headset
hardware: intent ray in, host raycast, grounded intent out.

Python and agent-framework consumers can install the pybind11 package with
`python -m pip install miskeyed-xr-agent` and import it as
`miskeyed.xr.agent`. See the [Python agent workflow](docs/PYTHON_AGENT_WORKFLOW.md)
for the intended USD-agent handoff and the reason an agent receives a plain,
already-grounded dictionary instead of raw OpenXR objects.

Native embedders should read the [OpenXR implementation contract](docs/OPENXR_IMPLEMENTATION.md).
The separate Omniverse test app must reuse Kit's OpenXR lifecycle rather than
create a competing XR session; no Kit extension code is shipped from this core.
The [CI/release contract](docs/CI_RELEASE.md) describes the hardware-free gate
and version-first, multi-platform TestPyPI/PyPI deployment.
The [realtime digital-twin vision](docs/REALTIME_DIGITAL_TWIN_VISION.md) explains
how XR feedback, sparse language, live twin telemetry, simulation, and reviewed
scene changes fit together—and lists what remains unimplemented.
The [milestone exit contract](docs/MILESTONE1_EXIT.md) is the handoff checklist
for the separate Omniverse application.
The [Kit app learning path](docs/KIT_APP_LEARNING_PATH.md) provides a staged,
version-conscious plan for that repository without adding Kit SDK ownership or
dependencies here.

Normalized recordings are available after installation:

```sh
xr-agent-record session.jsonl < normalized-stream.jsonl
xr-agent-replay session.jsonl --speed 1
```

The command-line probe does **not** invent a headless session. A normal OpenXR session needs a platform graphics binding. The probe performs discovery without one, and reports that an embedding graphics host is required before live action synchronization and `xrLocateViews`/`xrLocateSpace` sampling. This keeps the prototype truthful and renderer-neutral.

## Build

```sh
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure
./build/xr-agent-probe
```

CMake first looks for an installed `OpenXR::openxr_loader`. By default it otherwise fetches the pinned official Khronos SDK source release. Use `-DMISKEYED_XR_BUILD_OPENXR=OFF -DMISKEYED_XR_FETCH_OPENXR=OFF` for a completely offline, core-only build.

## Current answer

OpenXR 1.1 is a good portable **runtime, tracking, and semantic action** foundation. Head/view poses, reference spaces, action sets, pose actions, and extension discovery are core. Hand joints, hand-interaction bindings, and eye gaze are optional extensions and must remain optional. Scene meshes, depth, raycasts, passthrough/camera pixels, durable anchors, text, and voice are not one uniform core capability; the host or explicit adapters own those areas. See the [capability matrix](docs/OPENXR_CAPABILITY_MATRIX.md) and [architecture decisions](docs/ARCHITECTURE.md).

## Privacy

Eye gaze is opt-in. Capability detection is not consent, and raw gaze history must not be recorded by default.

Licensed under the MIT License.
