Integrator Guide

Public API Surface

View as Markdown

AICR is both a CLI and a Go library. This page documents the stability contract for every exported Go package. External consumers should prefer the github.com/NVIDIA/aicr/pkg/client/v1 facade described in the Go library integration guide.

Stability tiers

TierMeaning
Public (stable)Compatibility-reviewed facade. During v0, breaks are detected and explicitly recorded; starting with v1.0, breaking changes require a major bump.
Public (evolving)Exported today but may change in minor bumps. Pin and audit on upgrade.
InternalTreated as implementation detail. May change without notice.

Package matrix

PackageTierPurpose
github.com/NVIDIA/aicr/pkg/client/v1Public (stable)Facade: Client, NewClient, request/result types, source constructors.
pkg/recipePublic (evolving)Recipe resolution, criteria, overlay system, component registry.
pkg/bundlerPublic (evolving)Per-component Helm/Kustomize bundle generation.
pkg/validatorPublic (evolving)Constraint evaluation, three-phase validation (executed in order: Deployment, Conformance, Performance).
pkg/collectorPublic (evolving)Observed state collection from clusters.
pkg/measurementPublic (evolving)Typed measurement model used by collectors and validators.
pkg/versionPublic (evolving)Semver constraint evaluation.
pkg/errorsPublic (evolving)Structured errors with error codes. Consumed at API boundaries.
pkg/defaultsPublic (evolving)Shared timeout and limit constants.
pkg/componentInternalBundler utilities and test helpers.
pkg/constraintsInternalConstraint type definitions.
pkg/bomInternalBill-of-materials / image inventory generation.
pkg/configInternalConfig-file loading and flag/spec resolution.
pkg/corroborateInternalCross-source corroboration of observed state.
pkg/diffInternalStructural diff between two snapshots.
pkg/fingerprintInternalCluster/provider fingerprint detection.
pkg/healthInternalHealth-check orchestration.
pkg/helmInternalHelm chart rendering helpers.
pkg/mirrorInternalChart/image mirroring to air-gapped registries.
pkg/netutilInternalNetworking utilities.
pkg/snapshotterPublic (evolving)Snapshot orchestration. The facade exposes its own Snapshot and AgentConfig types; pkg/snapshotter is the underlying implementation.
pkg/serializerInternalYAML/JSON serialization helpers.
pkg/manifestInternalHelm-compatible manifest rendering.
pkg/evidenceInternalConformance evidence capture.
pkg/trustInternalSigstore / provenance integration.
pkg/k8sInternalKubernetes client utilities.
pkg/ociInternalOCI registry helpers.
pkg/loggingInternalLogging setup.
pkg/headerInternalHTTP header helpers.
pkg/buildInternalBuild-time metadata.
pkg/serverInternalaicrd HTTP server: middleware chain and REST handlers (thin adapters over pkg/client/v1). Consumers use the HTTP API, not the Go types.
pkg/cliInternalCLI command implementations.

Facade type ownership

The github.com/NVIDIA/aicr/pkg/client/v1 package is Public (stable). Types reachable from this surface are either facade-owned structs or transparent aliases — the table below documents which.

Transparent aliases extend that contract to their target types. They are kept where identity and direct interoperability with an existing builder, interface, result, or provider-scoped state are more valuable than a duplicative facade wrapper. The API-diff gate scopes additional checks to the aliased definitions; unrelated exports in their evolving packages remain free to change.

Facade symbolTranslates to/fromNotes
aicr.Snapshotpkg/snapshotter.SnapshotFacade-owned struct. Public fields are identifying metadata; full measurement payload is preserved in an unexported field for round-trip through ValidateState. Use aicr.WrapSnapshot to lift a *snapshotter.Snapshot loaded externally.
aicr.AgentConfigpkg/snapshotter.AgentConfigFacade-owned struct covering the deployment-time agent fields. Tolerations keeps k8s.io/api/core/v1.Toleration since k8s.io is itself a stable contract. It does not mirror every pkg/snapshotter.AgentConfig field — the network-collector fields ClusterConfigPath and DiscoverNetwork are not surfaced on the facade type. AKSGPUPoolsPath is surfaced (controller-side pool projection input, required for AKS profile-qualified resolution from a collected snapshot).
aicr.PhaseResultpkg/validator.PhaseResultFacade-owned struct. Exposes Summary (CTRF counts) and RawReport (CTRF JSON bytes); Report *ctrf.Report is retained for in-tree consumers that merge per-phase reports.
aicr.Phase, aicr.PhaseDeployment / PhasePerformance / PhaseConformancestring constsFacade-owned. Values match pkg/validator/v1 constants verbatim for byte-identical wire round-trip.
aicr.ReportSummarypkg/validator/ctrf.SummaryFacade-owned struct with the CTRF count fields.
aicr.ValidateOptionpkg/validator.OptionFacade-owned functional-option type that captures into an internal struct and translates at call time.
aicr.RecipeResultpkg/recipe.RecipeResultFacade-owned struct exposing Name, Version, TranslatedAt, SelectedProfile (the recorded ADR-015 selection, nil for unprofiled recipes), and Components (enabled/deployable components only — disabled refs remain visible via Resolved().ComponentRefs). Call Resolved() for the full upstream *pkg/recipe.RecipeResult (constraints, deployment order, validation config, metadata). The previous aicr.Recipe alias was removed in #1115; ResolveRecipeFromCriteria and ResolveRecipeFromSnapshot now return *RecipeResult.
aicr.AllowListspkg/recipe.AllowListsFacade-owned struct with []string fields (Accelerators / Services / Intents / OSTypes). Use aicr.WrapAllowLists to lift a *pkg/recipe.AllowLists.
aicr.Criteriapkg/recipe.CriteriaFacade-owned struct whose enum-typed fields (Service / Accelerator / Intent / OS / Platform) project to plain strings; Nodes stays an int per the facade’s string/int contract. Use aicr.WrapCriteria to lift a *pkg/recipe.Criteria.
aicr.BundleConfigpkg/bundler/config.ConfigDeliberate transparent alias. It keeps the facade compatible with config.NewConfig and its functional options instead of duplicating the bundler’s configuration builder.
aicr.BundleAttesterpkg/bundler/attestation.AttesterDeliberate transparent alias. Existing attester implementations pass directly into BundleOptions without an adapter.
aicr.BundleArtifact*pkg/bundler/result.OutputDeliberate transparent alias. Callers receive the complete bundler result, including HasErrors, without a lossy projection.
aicr.OIDCResolveOptionspkg/bundler/attestation.ResolveOptionsDeliberate transparent alias. CLI and server callers can pass the same late-bound signing inputs used by the attestation resolver.
aicr.CriteriaRegistrypkg/recipe.CriteriaRegistryDocumented transparent alias. Kept as an alias intentionally because the registry is behavior-rich (ParseService, SetStrict, Values, …) and carries mutable per-DataProvider state — wrapping would either break the per-Client identity coupling (copy) or add no isolation win over the alias (pointer).
  1. Use github.com/NVIDIA/aicr/pkg/client/v1 for all library integration by default.
  2. If the facade does not yet expose a feature you need, open an issue against NVIDIA/aicr describing the missing capability — we’d rather extend the facade than have external consumers hard-couple to evolving subpackages.
  3. If you must import a Public (evolving) subpackage, pin AICR to a patch version and audit diffs when upgrading.
  4. Never import a package marked Internal — upgrades will break you.

See also