Metadata-Version: 2.4
Name: usd-profiles-nvidia
Version: 1.15.3
Summary: NVIDIA OpenUSD Profiles
Project-URL: Homepage, https://docs.omniverse.nvidia.com/kit/docs/asset-requirements
Project-URL: Documentation, https://docs.omniverse.nvidia.com/kit/docs/asset-requirements
Author: NVIDIA
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.5
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: sphinx
Requires-Dist: myst-parser>=4.0.0; extra == 'sphinx'
Requires-Dist: sphinx>=7.2.6; extra == 'sphinx'
Description-Content-Type: text/markdown

# USD Profiles NVIDIA

A framework for defining and managing [OpenUSD](https://openusd.org) asset profiles, capabilities, and requirements.
This library provides tools for parsing profile specifications from Markdown, generating Python code,
and integrating with Sphinx documentation.

## Features

- **Profile definitions** — Define capabilities, features, and requirements in structured Markdown
- **Code generation** — Generate Python enums and dataclasses from profile specifications
- **Sphinx integration** — Custom directives and roles for rendering profile documentation
- **Validation support** — Generate validation rules from requirement specifications
- **Extensible** — Modular architecture for custom profile components

## AI Agent Guidance

AI coding agents should start with [AGENTS.md](AGENTS.md) for repository context, expectations, and common workflows.
Task-specific guidance lives in [.agents/skills/](.agents/skills/), including the profile code generation workflow in
[.agents/skills/project-setup-python/SKILL.md](.agents/skills/project-setup-python/SKILL.md) and the local venv workflow in
[.agents/skills/project-venv-setup/SKILL.md](.agents/skills/project-venv-setup/SKILL.md).

The runnable minimal code generation example is in [examples/python/minimal/](examples/python/minimal/).

## Installation

Install from PyPI:

```bash
pip install usd-profiles-nvidia
```

For Sphinx integration (directives and roles for profile documentation), install the optional dependency:

```bash
pip install usd-profiles-nvidia[sphinx]
```

## Basic Usage

### Code Generation

Generate Python code from profile specifications. Create a folder (e.g. `specs/`) with this structure and the
following files:

```
specs/
├── capabilities/
│   ├── capability-example.md
│   └── requirements/
│       └── single-root.md
├── features/
│   └── feature-example.md
└── profiles/
    └── profile-example.md
```

**specs/capabilities/requirements/single-root.md**

```markdown
# single-root

| Code          | REQ.001                   |
|---------------|---------------------------|
| Version       | 1.0.0                     |
| Compatibility | {compatibility}`OpenUSD`   |
| Validator     |                           |
| Tags          | {tag}`essential`          |

## Summary

USD stage must have a single root prim.

## Description

Every USD asset must contain one root prim from which all other prims descend.
```

**specs/capabilities/capability-example.md**

~~~markdown
# Example

## Overview

Minimal capability with one requirement.

## Requirements

```{requirements-table}
```
~~~

**specs/features/feature-example.md**

~~~markdown
# Example

| Property   | Value   |
|------------|---------|
| Version    | 1.0.0   |
| Dependency | OpenUSD |

## Description

Minimal feature with one requirement.

## Requirements

```{features-table}
REQ.001@1.0.0
```
~~~

**specs/profiles/profile-example.md**

```markdown
# Example

Minimal profile with one feature.

## Features

- [Example](../features/feature-example.md)
```

Then run:

```bash
python -m usd_profiles_nvidia.codegen --docs-root specs --destination-dir output --namespace mypackage.profiles
```

Generated code will be under `output/mypackage/profiles/`.

### NVIDIA USD Validation integration

Use the generated requirements and features with
[NVIDIA USD Validation](https://pypi.org/project/nvidia-usd-validation/).
Implement rule checkers and run validation as needed.

**Implement a rule** -- Register requirements and implement checks. For example, for the minimal example's single-root
requirement:

```python
import mypackage.profiles as cap
from nvidia_usd_validation import BaseRuleChecker, register_requirements

@register_requirements(cap.Requirements.REQ_001_V1_0_0)
class SingleRootChecker(BaseRuleChecker):
    """USD stage must have a single root prim."""

    def CheckStage(self, usdStage):
        roots = [p for p in usdStage.GetPseudoRoot().GetChildren() if p.IsValid()]
        if len(roots) != 1:
            self._AddFailedCheck(
                "Stage must have exactly one root prim.",
                requirement=cap.Requirements.REQ_001_V1_0_0,
            )
```

**Validate with the generated feature** — Enable the feature you generated and run the engine:

```python
import nvidia_usd_validation
import mypackage.profiles

engine = nvidia_usd_validation.ValidationEngine(init_rules=False)
engine.enable_feature(mypackage.profiles.Features.EXAMPLE)
results = engine.validate("path/to/asset.usd")
```

### Sphinx Integration

Add to your Sphinx `conf.py`:

```python
extensions = [
    "usd_profiles_nvidia.sphinx.ext",
]
```

Use directives in your documentation:

````markdown
```{requirements-table}
geometry/mesh-valid
geometry/mesh-normals
```

```{features-table}
geometry/feature-mesh
```
````

Use roles for inline tags and compatibility badges:

```markdown
{tag}`performance` - Display a tag badge
{compatibility}`omniverse` - Display a compatibility badge
```

## Documentation

- [Full Documentation](https://docs.omniverse.nvidia.com/kit/docs/asset-requirements)

## Requirements

Core package:

- Python 3.10 or later
- Jinja2 3.1.5 or later
- markdown-it-py 3.0.0 or later
- tomli 2.0.0 or later for Python versions earlier than 3.11

Optional Sphinx integration (`usd-profiles-nvidia[sphinx]`):

- Sphinx 7.2.6 or later
- myst-parser 4.0.0 or later

## License

Apache-2.0
