Namespace Payload Catalogue

spanforge ships typed payload dataclasses for fifteen standard namespaces. Every namespace payload is a Python dataclass that can be serialised to/from a plain dict for storage in Event.payload.

Namespaces

Compliance & Governance

Instrumentation & Telemetry

Namespace quick-reference

Namespace prefixModuleKey payload classes
consent.*spanforge.namespaces.consentConsentPayload
hitl.*spanforge.namespaces.hitlHITLPayload
model_registry.*spanforge.model_registryModelRegistryEntry
explanation.*spanforge.explainExplainabilityRecord
llm.trace.*spanforge.namespaces.traceSpanPayload, AgentStepPayload, AgentRunPayload
llm.cost.*spanforge.namespaces.costCostTokenRecordedPayload, CostSessionRecordedPayload, CostAttributedPayload
llm.cache.*spanforge.namespaces.cacheCacheHitPayload, CacheMissPayload, CacheEvictedPayload, CacheWrittenPayload
llm.diff.*spanforge.namespaces.diffDiffComputedPayload, DiffRegressionFlaggedPayload
llm.eval.*spanforge.namespaces.eval_EvalScoreRecordedPayload, EvalRegressionDetectedPayload, EvalScenarioStartedPayload, EvalScenarioCompletedPayload
llm.fence.*spanforge.namespaces.fenceFenceValidatedPayload, FenceRetryTriggeredPayload, FenceMaxRetriesExceededPayload
llm.guard.*spanforge.namespaces.guardGuardPayload
llm.prompt.*spanforge.namespaces.promptPromptRenderedPayload, PromptTemplateLoadedPayload, PromptVersionChangedPayload
llm.redact.*spanforge.namespaces.redactRedactPiiDetectedPayload, RedactPhiDetectedPayload, RedactAppliedPayload
llm.template.*spanforge.namespaces.templateTemplateRegisteredPayload, TemplateVariableBoundPayload, TemplateValidationFailedPayload
llm.audit.*spanforge.namespaces.auditAuditKeyRotatedPayload, AuditChainVerifiedPayload, AuditChainTamperedPayload

Using a namespace payload

from spanforge import Event, EventType
from spanforge.namespaces.trace import SpanPayload, TokenUsage, ModelInfo, GenAISystem

token_usage = TokenUsage(input_tokens=512, output_tokens=128, total_tokens=640)
model_info  = ModelInfo(system=GenAISystem.OPENAI, name="gpt-4o")

payload = SpanPayload(
    span_name="chat_completion",
    status="ok",
    duration_ms=340.5,
    token_usage=token_usage.to_dict(),
    model_info=model_info.to_dict(),
)

event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="my-app@1.0.0",
    org_id="org_01HX",
    payload=payload.to_dict(),
)

Ready to instrument your AI pipeline?

Try the 30-second quickstartSee the compliance checklistView on GitHub