Skip to content

API Reference

InferGuard is CLI-first. The generated reference below documents the typed objects and validation helpers that are useful when producing, validating, or consuming InferGuard evidence artifacts.

Agent trace schema

inferguard.schemas.agent_trace

Validators for the locked agent-trace/v1 JSONL schema.

AgentTraceValidationError

Bases: ValueError

Raised when an agent-trace/v1 event is malformed.

ValidationError dataclass

Non-throwing trace-integrity validation error.

validate_agent_trace_event(data: dict[str, Any], *, source: str = 'event') -> AgentTraceEvent

Validate and normalize one locked agent-trace/v1 JSON object.

iter_agent_trace_jsonl(path: Path | str) -> Iterable[AgentTraceEvent]

Yield validated events from a JSONL trace file.

dump_agent_trace_event(event: AgentTraceEvent | dict[str, Any]) -> dict[str, Any]

Return a schema-shaped dictionary after validation.

validate_trace_integrity(events: list[dict[str, Any]]) -> list[ValidationError]

Return graph-level integrity errors for an agent-trace/v1 event list.

Event-level schema validation remains handled by validate_agent_trace_event; this function adds JSONL-wide checks such as unique node IDs, valid parent references, one trace ID, summary/node count consistency, and summary ordering.

Telemetry schema

inferguard.schemas.telemetry

Validators for the locked inferguard-telemetry/v1 upload payload.

TelemetryValidationError

Bases: ValueError

Raised when an inferguard-telemetry/v1 payload is malformed.

validate_telemetry_payload(data: dict[str, Any], *, source: str = 'payload') -> TelemetryPayload

Validate one locked inferguard-telemetry/v1 payload.

load_telemetry_payload(path: Path | str) -> TelemetryPayload

Read and validate a telemetry payload JSON file.

Request profile types

inferguard.request_profile.types

Dataclass contracts for per-request profiling artifacts.

Metrics collection types

inferguard.collect_metrics.types

Contracts for the NeoCloud/GMI collect-metrics command.

CollectMetricsOptions dataclass

Options for collect-metrics.

labels() -> dict[str, str]

Return non-empty operator labels for timeline rows.

EngineMetricsSample dataclass

One normalized engine metrics row for one scrape interval and group.

GpuMetricsSample dataclass

One dcgm-correlated/v1 GPU metrics row.

MetricsSummary dataclass

Top-level normalized metrics summary.

Bottleneck diagnosis types

inferguard.diagnose_bottleneck.types

Contracts for PRD ยง4.5 bottleneck diagnosis artifacts.

Verdict

Bases: StrEnum

The locked eight-class operator verdict surface.

Evidence dataclass

One metric observation used to support or reject a verdict.

Downgrade dataclass

A claim-status downgrade with an operator-readable reason.

BottleneckDiagnosis dataclass

The emitted bottleneck_diagnosis.json contract.

Router verdict models

inferguard.router.verdict

Router verdict schemas.