[TAO-2523][Docs] Refresh developer docs: codebase tour, deeper architecture, GitHub-era CI by vpraveen-nv · Pull Request #32 · NVIDIA-TAO/tao-data-services

vpraveen-nv · 2026-08-12T23:32:24Z

Brings the tao-data-services developer docs to parity with tao-pytorch's docs tree and addresses feedback that the repo structure, modules, and architecture are hard for new developers to pick up.

What changed

New docs/codebase_tour.md — annotated repo tree, module map, service + auto-label backend inventory, anatomy of the annotations service, the two config conventions, and a consolidated sharp-edges list (analytics naming, default_specs limits, unconditional nvidia-smi, multi-GPU keyed on generate, monitor_status coverage, codec policy, the two API stories).
Expanded docs/architecture.md — shared launcher behavior, configuration flow and field factories, a models-and-weights table (Grounding DINO / MAL / VLM / CLIP), the dev-mode vs production API distinction, and tao-core / tao-pytorch submodule boundaries.
Two new diagrams (config_flow.svg, module_map.svg) in tao-pytorch's diagram style.
GitHub-era CI corrections: removed stale .gitlab-ci.yml / ci/ / Jenkinsfile references, documented the pre-commit + GitHub Actions checks that actually run, fixed the targeted pytest map to reference only tests that exist, and corrected the digest bump locations.
Fixed the generated-README template in tools/update_readme_supported_commands.py (it referenced ci/run_static_tests.py and ci/utils.py, which no longer exist) and regenerated README.md.

Verification

Every path, subtask list, and launcher behavior cross-checked against source at origin/main.
python tools/update_readme_supported_commands.py --check passes; py_compile on the tool passes; git diff --check clean; SVGs valid; all relative doc links resolve.
No runtime code touched beyond the README-generator template text.

JIRA: TAO-2523

…ecture, GitHub-era CI Bring the developer docs to parity with tao-pytorch's docs tree and address feedback that the repo structure, modules, and architecture are hard for new developers to pick up: - Add docs/codebase_tour.md: annotated repo tree, package module map, service and auto-label backend inventory, anatomy of the annotations service, the two config conventions, and a consolidated sharp-edges list (analytics naming, default_specs limits, unconditional nvidia-smi, multigpu keyed on 'generate', monitor_status coverage, codec policy, two API stories). - Expand docs/architecture.md: shared launcher behavior, configuration flow and field factories, models-and-weights table (Grounding DINO / MAL / VLM / CLIP), the dev-mode vs production API distinction, and tao-core / tao-pytorch submodule boundaries. - Add docs/assets/config_flow.svg and module_map.svg in the same style as tao-pytorch's diagrams. - Refresh agent_onboarding, development_workflows, testing_and_debugging, and index: remove stale .gitlab-ci.yml / ci/ / Jenkinsfile references, document the pre-commit + GitHub Actions checks that actually run, fix the targeted pytest map to reference only tests that exist, and correct the base-image digest bump locations (manifest + release Dockerfile ARG defaults). - Fix the stale generated-README template text in tools/update_readme_supported_commands.py (referenced ci/run_static_tests.py and ci/utils.py, which no longer exist) and regenerate README.md. - Apply the TAO documentation style guide to the new and touched pages. All paths, subtask lists, launcher behavior, and CI configuration verified against source at origin/main. Signed-off-by: Varun Praveen <vpraveen@nvidia.com>

tao-pr-bot · 2026-08-12T23:32:36Z

For security reasons, CI does not run automatically on NVIDIA's runners — it must be triggered per commit.

Comment /build to run CI on your latest commit, and make sure blossom-ci is green before merging.
Re-run /build after each new push — CI is pinned to the head commit, so a stale run won't count.

Tip

Should this fix also ship in a release? Add a release/X.Y.Z label (matching the target release branch) and tao-cherry-pick-bot will backport it after merge.

Important

Before merging: every file needs a license header and every commit must be DCO signed-off — see the 📖 Contribution guide for details.

Address developer review feedback on the docs refresh: - Architecture no longer opens with the development container launcher. New opening sections explain what the product is (the container it ships as and its user-facing console commands) and how customers run it as of TAO 7.0 (agent + tao-skills + Execution SDK over the container CLI), with the removed TAO Launcher and FTMS surfaces called out explicitly as history and in-repo remnants labeled as legacy integration surfaces. - New Terminology section defining service/model family, subtask, specification, the shared command dispatcher, and the dev-only container launcher - and explicitly disambiguating them from the removed TAO Launcher. - New Test Environment Setup section: submodule init, dev container entry, pip install tao-core/. (the step the README missed), PYTHONPATH notes, and which suites need GPUs or private datasets. - Terminology sweep: 'launcher' now refers only to the dev container tool; the in-repo dispatch code is the 'shared command dispatcher'. Consumption-mode statements verified against the public docs source (release_notes.rst 'Removed in 7.0', migrating_to_tao_7.0.rst, overview.rst deployment-modes table). Signed-off-by: Varun Praveen <vpraveen@nvidia.com>

vpraveen-nv · 2026-08-14T15:05:24Z

Thanks for the detailed review — pushed an update addressing each point:

"Architecture starts with tao_ds, but that's a dev tool" — restructured. architecture.md now opens with What TAO Data Services Is (the <version>-dataservices container and its console commands as the product surface) and How Users Run Data Services, before any development tooling. The tao_ds walkthrough is now explicitly labeled a development-only stand-in for whatever runs the container in production.
Undefined terms / "which launcher?" — new Terminology section defining service, subtask, specification, the shared command dispatcher (core/entrypoint/entrypoint.py), and tao_ds — and explicitly disambiguating all of them from the TAO Launcher, which was deprecated in 6.0 and removed in 7.0. The word "launcher" now refers only to the dev container tool everywhere in the docs.
"How would customers run data services?" — documented from the public docs source: as of 7.0 the supported surface is agent + tao-skills + the TAO Execution SDK (dispatching to local Docker / Lepton / Brev / SLURM / K8s), with the container CLI (annotations convert -e ...) as the layer underneath. TAO Launcher and FTMS/nvidia-tao-client are called out as removed, and the FTMS-era code still in this repo (api/app.py, the release-container CMD, JOB_ID teeing) is labeled a legacy integration surface rather than a way users run the product.
Test environment setup — new Test Environment Setup section in testing_and_debugging.md: submodule init, enter the dev container, pip install /workspace/tao-core/. (the step the README missed — nvidia_tao_core is not in requirements-pip.txt, only its transitive deps), PYTHONPATH for nvidia_tao_pytorch-dependent tests, and which suites need GPUs/private datasets.
"Misses context outside the repo" — the codebase tour and index now open with where this repo sits in the ecosystem (sibling backends, the container it builds, pointer to the new context sections).

The consumption-mode statements are sourced from the public docs (release_notes.rst "Removed in 7.0", migrating_to_tao_7.0.rst, the deployment-modes table in overview.rst) — if the team's converged story differs from what's published there, happy to adjust.

…PU/CPU functions) Review feedback: the units of this repository are batch CLI functions, not long-running services, so 'service' was misleading despite the product name. The Terminology table now defines 'function' with the GPU/CPU classification (GPU functions: augmentation, auto_label, embedding, tmm; CPU functions: annotations, analytics, image, gap_analysis), and the docs use 'function' consistently for the unit while keeping 'Data Services' as the product name and 'microservice' for the FTMS-era Flask code. Signed-off-by: Varun Praveen <vpraveen@nvidia.com>

vpraveen-nv · 2026-08-14T16:21:49Z

Follow-up commit: renamed the unit noun from "service" to function, since these are batch CLI functions rather than long-running services. The Terminology table now classifies them as GPU functions (augmentation, auto_label, embedding, tmm) and CPU functions (annotations, analytics, image, gap_analysis), and the docs use "function" consistently for the unit — "Data Services" stays as the product name, and "microservice" stays reserved for the FTMS-era Flask code.

ddevendran-nvidia · 2026-08-14T17:04:06Z

+
+| Term | Meaning here |
+| :--- | :--- |
+| Function | One dataset-preparation capability with its own console command and package, such as `annotations` or `augmentation`. Functions are classified by compute: **GPU functions** (`augmentation`, `auto_label`, `embedding`, `tmm`) and **CPU functions** (`annotations`, `analytics`, `image`, `gap_analysis`). Despite the product name "Data Services," these are batch CLI functions, not long-running services. |


They are classified by type of functionality and not the compute they use. It just happens that a kind of functionality typically uses GPU or CPU.

Also what does it mean by "batch CLI"? What gets batched?

ddevendran-nvidia

Didn't go through everything, but here are some initial comments

ddevendran-nvidia · 2026-08-14T17:05:20Z

+
+| Term | Meaning here |
+| :--- | :--- |
+| Function | One dataset-preparation capability with its own console command and package, such as `annotations` or `augmentation`. Functions are classified by compute: **GPU functions** (`augmentation`, `auto_label`, `embedding`, `tmm`) and **CPU functions** (`annotations`, `analytics`, `image`, `gap_analysis`). Despite the product name "Data Services," these are batch CLI functions, not long-running services. |


Also what does it mean by "batch CLI"? What gets batched?

ddevendran-nvidia · 2026-08-14T17:06:44Z

+| Term | Meaning here |
+| :--- | :--- |
+| Function | One dataset-preparation capability with its own console command and package, such as `annotations` or `augmentation`. Functions are classified by compute: **GPU functions** (`augmentation`, `auto_label`, `embedding`, `tmm`) and **CPU functions** (`annotations`, `analytics`, `image`, `gap_analysis`). Despite the product name "Data Services," these are batch CLI functions, not long-running services. |
+| Subtask | One operation of a function, implemented as one module in the function's `scripts/` package and selected as the first CLI argument: `annotations convert`, `analytics analyze`. |


This is a confusing statement. What is "one operation of a function"?

ddevendran-nvidia · 2026-08-14T17:07:13Z

+| Function | One dataset-preparation capability with its own console command and package, such as `annotations` or `augmentation`. Functions are classified by compute: **GPU functions** (`augmentation`, `auto_label`, `embedding`, `tmm`) and **CPU functions** (`annotations`, `analytics`, `image`, `gap_analysis`). Despite the product name "Data Services," these are batch CLI functions, not long-running services. |
+| Subtask | One operation of a function, implemented as one module in the function's `scripts/` package and selected as the first CLI argument: `annotations convert`, `analytics analyze`. |
+| Specification (spec) | The YAML experiment file passed with `-e`, validated against the function's dataclass schema. |
+| Shared command dispatcher | `nvidia_tao_ds/core/entrypoint/entrypoint.py` — the in-repo code every console command delegates to. Not a product. |


Why does it say "not a product"?

ddevendran-nvidia · 2026-08-14T17:08:54Z

 ![Runtime dispatch flow](assets/runtime_flow.svg)

-## Runtime Dispatch
+For development, `tao_ds` (dev-only, see Terminology) stands in for whatever


This is confusing. Is it talking about the tao_ds command or tao ds as the data services container?

ddevendran-nvidia · 2026-08-14T17:09:12Z

-   `PYTHONPATH=/workspace:$PYTHONPATH`, and starts Docker with the requested
-   GPUs, mounts, environment variables, shared memory, ulimits, UID/GID, and
-   optional service-mode ports.
+   `docker/manifest.json`, mounts the repository as `/workspace`, and starts


Huh, I thought mounting as /workspace was specific to CR. Good to know

ddevendran-nvidia · 2026-08-14T17:12:42Z

-`runner/tao_ds.py --run_as_service`.
+## Models and Weights
+
+The functions orchestrate models from other TAO repositories rather than


orchestrate is a bad word here. Don't they simply "use" models from other TAO repositories?

ddevendran-nvidia · 2026-08-14T17:13:06Z

-| `nvidia_tao_ds/core/utils/default_specs.py` | Default experiment YAML generation from dataclass configs. |
-| `nvidia_tao_ds/core/logging/` | TAO Data Services logging helpers. |
-| `nvidia_tao_ds/core/llm_clients/` | OpenAI-compatible, Gemini, and base LLM client abstractions used by auto-label workflows. |
+Two schema conventions coexist:


Hmmm, why does it think that two schema conventions exist? For mining and rcca we decided to have nesting in the directory structure. All the modules are meant to follow the typical schema convention.

ddevendran-nvidia · 2026-08-14T17:24:13Z

 ## Configuration Flow

-Most command scripts combine three files:
+![Configuration flow](assets/config_flow.svg)


This diagram doesn't explain the config flow to me. I don't know that it should be a "flow".

It should be:

The schema for the config is defined as a dataclass under config.

A user can either 1) generate a default spec from the default spec function (this function doesn't work for the mining and rcca modules???), or 2) build their own spec

The user can also override spec parameters at runtime by using the Hydra convention

The parameters that get used are the provided spec + the overwritten parameters

vpraveen-nv requested a review from a team as a code owner August 12, 2026 23:32

vpraveen-nv mentioned this pull request Aug 13, 2026

[TAO-2523][Docs] Add codebase tour and module map; fix stale CI references NVIDIA-TAO/tao-pytorch#100

Open

ddevendran-nvidia reviewed Aug 14, 2026

View reviewed changes

Uh oh!

Conversation

vpraveen-nv commented Aug 12, 2026

Uh oh!

tao-pr-bot Bot commented Aug 12, 2026

Uh oh!

vpraveen-nv commented Aug 14, 2026

Uh oh!

vpraveen-nv commented Aug 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ddevendran-nvidia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants