candle_graph/
lib.rs

1//! TensorFlow Profiler-style execution graphs for [Candle](https://github.com/huggingface/candle) runs.
2//!
3//! Record one representative JSONL trace with [`instrument::TraceSession`], qualify its structural
4//! health and evidence capabilities with [`evidence::build_evidence`], and inspect it through the
5//! CLI or, with the `visualizer` feature, [`viewer::render_evidence_html`].
6//!
7//! There is **no static Rust analysis** — the graph comes only from what executed.
8//!
9//! Keep these evidence planes distinct:
10//!
11//! - span duration is host timing unless the producer declares stronger synchronization semantics;
12//! - [`timing`] device intervals retain their own device clock;
13//! - [`trace::memory`] logical storage lifetimes do not imply physical allocator usage; and
14//! - optional [`nsight`] evidence retains the Nsight clock and artifact provenance.
15//!
16//! Failed or structurally invalid captures remain diagnostic but do not produce a derived
17//! [`graph::ExecutionGraph`]. Finalized evidence can be published and deeply verified through
18//! [`artifact`], while eligible repeated timing comparisons require verified bundles through
19//! [`comparison`].
20
21pub mod artifact;
22pub mod campaign;
23pub mod capability;
24pub mod cli;
25pub mod comparison;
26pub mod evidence;
27pub mod graph;
28pub mod instrument;
29pub mod nsight;
30pub mod phase;
31pub mod publication;
32pub mod timing;
33pub mod trace;
34#[cfg(feature = "visualizer")]
35pub mod viewer;
36
37pub use artifact::{
38    publish_bundle, verify_bundle, BundleManifest, BundleVerificationReceipt,
39    SCHEMA as BUNDLE_SCHEMA,
40};
41pub use campaign::{
42    build_series, campaign_status, CampaignManifest, CampaignStatus, CaptureState, CaptureStatus,
43    PlannedCapture, SeriesReport, CAMPAIGN_SCHEMA, CAMPAIGN_STATUS_SCHEMA, SERIES_SCHEMA,
44};
45pub use capability::{
46    CaptureContract, CoverageLevel, ExpectedGradient, GradientContract, GradientFamilyContract,
47    GradientFamilyExpectation, MeasurementScope, GRADIENT_MANIFEST_SCHEMA,
48};
49pub use comparison::{
50    compare_unverified_traces, compare_verified_bundles, ComparisonInputVerification,
51    ComparisonInputs, ComparisonReason, ComparisonReasonCode, ComparisonVerdict,
52    ReplicatedComparison, TensorStatsComparison, TensorStatsComparisonRow, VerifiedBundleInput,
53    SCHEMA as COMPARISON_SCHEMA,
54};
55pub use evidence::{build_evidence, EvidencePacket, SCHEMA as EVIDENCE_SCHEMA};
56pub use graph::{build_from_trace, ExecutionGraph, SCHEMA as GRAPH_SCHEMA};
57#[cfg(feature = "candle")]
58pub use instrument::candle;
59pub use instrument::{
60    CaptureSelector, DeviceIntervalRecord, DeviceMemoryRecord, MemoryRecord, OpRecord, ProfileRun,
61    SpanGuard, SpanId, SpanKind, TensorRecord, TraceSession,
62};
63pub use nsight::{GpuEvidenceStatus, NsightEvidence};
64pub use phase::{ExecutionPhase, ExecutionStep};
65pub use publication::{
66    reconcile_published_bundle, CaptureBegin, CaptureRun, PublicationReceipt, PublicationStatus,
67    PUBLICATION_SCHEMA,
68};
69pub use trace::{parse_trace, write_jsonl, TraceDocument, TraceEvent, SCHEMA as TRACE_SCHEMA};
70pub use trace::{ComparisonIdentity, TimingMode};
candle_graph/lib.rs

candle_graph/
lib.rs
