Metadata-Version: 2.5
Name: jetson-containers-agent
Version: 0.11.2
Summary: Agent + CLI (jca) wrapping the jetson-containers family (dusty-nv, NVIDIA-AI-IOT, jetson-ai-lab forks): track upstreams, diff packages across forks, and build/run containers on Jetson.
Project-URL: Homepage, https://github.com/agentculture/jetson-containers-agent
Project-URL: Issues, https://github.com/agentculture/jetson-containers-agent/issues
Author: AgentCulture
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# jetson-containers-agent

Agent + CLI (`jca`) wrapping the jetson-containers family (dusty-nv, NVIDIA-AI-IOT, jetson-ai-lab forks): track upstreams, diff packages across forks, and build/run containers on Jetson.

## The family

[jetson-containers](https://github.com/dusty-nv/jetson-containers) is the
modular Docker build system for Jetson AI/ML containers. Several copies of it
now evolve independently:

| Remote | Variant | Default branch | Relationship |
|--------|---------|----------------|--------------|
| [`dusty-nv/jetson-containers`](https://github.com/dusty-nv/jetson-containers) | `dusty` | `master` | the original |
| [`NVIDIA-AI-IOT/jetson-containers`](https://github.com/NVIDIA-AI-IOT/jetson-containers) | `nv` | `dev` | independent repo, **not** a GitHub fork |
| [`jetson-ai-lab/jetson-containers`](https://github.com/jetson-ai-lab/jetson-containers) | `lab` | `master` | GitHub fork of dusty-nv |

`jca` answers questions like "which fork has the newest vllm / pytorch /
JetPack support?" It computes cross-fork divergence with git, because the
GitHub compare API doesn't work across non-fork repos. It builds by
delegating to a fork's own `jetson-containers` tooling instead of
reimplementing it.

## Status

Early. The repo is scaffolded, and the domain verbs are being built against
[issue #1](https://github.com/agentculture/jetson-containers-agent/issues/1):

| Verb | Layer | State |
|------|-------|-------|
| `jca remotes`, `jca status`, `jca sync` | registry and tracking (read-only) | planned |
| `jca packages`, `jca diff <pkg> --between A B` | package-level diff (read-only) | planned |
| `jca build`, `jca run` | delegated build/run (dry-run by default, `--apply`) | planned |

Available today are the agent-first verbs and `jca switch`:

| Verb | What it does |
|------|--------------|
| `jca whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
| `jca learn` | Print a structured self-teaching prompt. |
| `jca explain <path>` | Markdown docs for any noun/verb path. |
| `jca overview` | Read-only descriptive snapshot of the agent. |
| `jca doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
| `jca cli overview` | Describe the CLI surface itself. |
| `jca switch [<variant>]` | Point `.local/jetson-containers` (git-ignored) at a variant checkout; no argument shows the active one. |

Every command supports `--json`. Results go to stdout and errors/diagnostics
to stderr (never mixed). Exit codes: `0` success, `1` user error, `2`
environment error, `3+` reserved. `jca` never pushes to or opens PRs on the
upstream repos.

## Quickstart

```bash
uv sync
uv run pytest -n auto              # run the test suite (no network, no Jetson needed)
uv run jca whoami                  # identity from culture.yaml
uv run jca learn                   # self-teaching prompt (add --json)
uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
```

## Working with the variant checkouts

The forks are **cloned and maintained from this repo** as sibling working
clones, not as git submodules. A symlink selects the active one:

```text
../jetson-containers-dusty/
../jetson-containers-nv/
../jetson-containers-lab/
../jetson-containers -> jetson-containers-<active>
```

To select a variant for work in this repo, use `jca switch`. It keeps its
symlink inside the repo, in the git-ignored `.local/` folder, and finds
checkouts in `.local/` first, then in the workspace:

```bash
uv run jca switch            # active variant + every checkout found
uv run jca switch nv         # .local/jetson-containers -> ../jetson-containers-nv
uv run jca switch --json     # machine-readable; includes launcher state
```

The bundled `jetson-containers-variants` skill manages this layout. Set
`JCA_WORKSPACE` to use a directory other than this repo's parent:

```bash
S=.claude/skills/jetson-containers-variants/scripts/variants.py
python3 $S clone --all       # clone missing variants at their default branch
python3 $S status            # active variant, branch/HEAD/dirty, ahead/behind
python3 $S switch nv         # point ../jetson-containers at the nv clone
python3 $S sync              # fetch; fast-forward only clean default-branch checkouts
```

Heads-up: the upstream `install.sh` links `/usr/local/bin/jetson-containers`
and `autotag` **directly into one checkout**. The global command therefore
ignores `switch` until those links go through `../jetson-containers`.
`status` and `launcher` detect this and print the `sudo ln -sfn …` fix. The
skill never runs sudo itself.

The variant registry is
`.claude/skills/jetson-containers-variants/data/variants.json`. Add user forks
there.

## Agent harnesses

This is an [AgentCulture](https://github.com/agentculture) mesh agent
(`culture.yaml`: suffix `jetson-containers-agent`, `backend: claude`). Four
harnesses work in this clone, and each reads exactly one root file:

| Harness | File(s) |
|---------|---------|
| Claude Code (also the mesh resident) | [`CLAUDE.md`](CLAUDE.md) |
| Pi / associate | [`AGENTS.override.md`](AGENTS.override.md) + [`.pi/SYSTEM.md`](.pi/SYSTEM.md) |
| colleague | [`AGENTS.colleague.md`](AGENTS.colleague.md) |
| Qwen Code | [`QWEN.md`](QWEN.md) |

There is intentionally **no `AGENTS.md`**. The skill kit lives in
`.claude/skills/`: the guildmaster kit vendored cite-don't-import, plus local
skills. See [`docs/skill-sources.md`](docs/skill-sources.md). For why the
interactive harness and the mesh resident are separate choices, see
[`docs/harness-selection.md`](docs/harness-selection.md).

## Neighbours

`jca` owns the container source repos and their divergence. For other Jetson
concerns, see `jetson-cli` (device setup), `jetson` (knowledge base),
`jetson-ai-lab-cli` (the jetson-ai-lab site and models), `jetson-arena`
(benchmarks), and `jetson-orin-cli` / `jetson-thor-cli` (board-specific).

## Contributing

Every PR bumps the version (`version-bump` skill), and CI blocks merge
otherwise. Merges to `main` publish to PyPI via Trusted Publishing. See
[`CLAUDE.md`](CLAUDE.md) for the full conventions.

## License

Apache 2.0. See [`LICENSE`](LICENSE).
