spanforge.types

Namespaced event type registry and custom type validation helpers.

EventType

class EventType(str, Enum)

Exhaustive registry of all first-party SPANFORGE event types.

EventType is a str subclass, so values can be compared directly with plain strings, used as dict keys, and serialised without conversion:

assert EventType.TRACE_SPAN_COMPLETED == "llm.trace.span.completed"

Each member also carries .namespace and .description properties.

Properties

namespace -> str

The llm.<ns> namespace prefix for this event type.

EventType.TRACE_SPAN_COMPLETED.namespace  # "llm.trace"

description -> str

A one-line human-readable description of this event type.

Members

llm.diff.*

llm.prompt.*

llm.template.*

llm.trace.*

llm.cost.*

llm.eval.*

llm.guard.*

llm.redact.*

llm.fence.*

llm.audit.*

consent.*

hitl.*

model_registry.*

explanation.*

llm.cache.*

Module-level functions

is_registered(event_type: str) -> bool

Return True if event_type is a registered first-party EventType value.

from spanforge.types import is_registered

is_registered("llm.trace.span.completed")  # True
is_registered("x.my-org.custom.event")      # False

Args:

Returns: bool

namespace_of(event_type: str) -> str

Return the llm.<tool> namespace of a registered event type.

Args:

Returns: str — the namespace prefix (e.g. "llm.trace").

Raises: EventTypeError — if event_type does not match the expected pattern.

validate_custom(event_type: str) -> None

Validate a custom (third-party) event type string.

Custom event types must use a reverse-domain prefix (e.g. com.example.<…>).

Args:

Raises: EventTypeError — if event_type does not match the required pattern or claims a reserved llm.* namespace.

get_by_value(value: str) -> Optional[EventType]

Look up an EventType by its string value.

Returns None instead of raising if the value is not found.

Args:

Returns: EventType | None

Constants

EVENT_TYPE_PATTERN: str

Regex pattern that all valid event type strings (registered and custom) must match:

^(?:llm\.[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*){1,3}|[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*){2,}\.[a-z][a-z0-9_]*)$

• validate_custom() — validate a custom reverse-domain event type string (e.g. com.example.<…>)
• namespace_of() — return the namespace prefix of a given event type string

SDK Types — spanforge.sdk._types

Phase 11 introduces the following dataclass types used by SFEnterpriseClient and SFSecurityClient.

Enterprise types

Security types

Import

from spanforge.sdk._types import (
    DataResidency,
    IsolationScope,
    TenantConfig,
    EncryptionConfig,
    AirGapConfig,
    HealthEndpointResult,
    EnterpriseStatusInfo,
    DependencyVulnerability,
    StaticAnalysisFinding,
    ThreatModelEntry,
    SecurityScanResult,
    SecurityAuditResult,
)