spanforge 2.0.0__py3-none-any.whl

spanforge/schemas/v2.0/schema.json

@@ -0,0 +1,536 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://llm-toolkit-schema.dev/schemas/v2.0/schema.json",
+  "title": "AGENTOBS Event Envelope v2.0",
+  "description": "Normative JSON Schema for the AGENTOBS v2.0 Event Envelope (RFC-0001-AGENTOBS §5, Appendix A). Every event emitted by a conformant implementation MUST validate against this schema. Language-neutral portability contract per RFC §21.2.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event_id",
+    "event_type",
+    "timestamp",
+    "source",
+    "payload"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Schema version. MUST be '2.0' for AGENTOBS v2.0 events. '1.0' is also accepted for backward compatibility (RFC §15.5).",
+      "enum": ["1.0", "2.0"],
+      "examples": ["2.0", "1.0"]
+    },
+    "event_id": {
+      "type": "string",
+      "description": "Universally unique ULID. 26-character Crockford Base32; first character MUST be in [0-7] (RFC §6.3).",
+      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
+      "minLength": 26,
+      "maxLength": 26,
+      "examples": ["01HZ8G3EPRP1YF2QV70NMBE6J4"]
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Dot-separated namespaced event type (RFC §7). Must use a registered namespace or vendor-prefixed extension namespace.",
+      "oneOf": [
+        {
+          "enum": [
+            "llm.trace.span.started",
+            "llm.trace.span.completed",
+            "llm.trace.span.failed",
+            "llm.trace.agent.step",
+            "llm.trace.agent.completed",
+            "llm.trace.reasoning.step",
+            "llm.cost.token.recorded",
+            "llm.cost.session.recorded",
+            "llm.cost.attributed",
+            "llm.cache.hit",
+            "llm.cache.miss",
+            "llm.cache.evicted",
+            "llm.cache.written",
+            "llm.eval.score.recorded",
+            "llm.eval.regression.detected",
+            "llm.eval.scenario.started",
+            "llm.eval.scenario.completed",
+            "llm.guard.input.blocked",
+            "llm.guard.input.passed",
+            "llm.guard.output.blocked",
+            "llm.guard.output.passed",
+            "llm.fence.validated",
+            "llm.fence.retry.triggered",
+            "llm.fence.max_retries.exceeded",
+            "llm.prompt.rendered",
+            "llm.prompt.template.loaded",
+            "llm.prompt.version.changed",
+            "llm.redact.pii.detected",
+            "llm.redact.phi.detected",
+            "llm.redact.applied",
+            "llm.diff.computed",
+            "llm.diff.regression.flagged",
+            "llm.template.registered",
+            "llm.template.variable.bound",
+            "llm.template.validation.failed",
+            "llm.audit.key.rotated"
+          ]
+        },
+        {
+          "pattern": "^(?!llm\\.)[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*)+\\.[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
+        }
+      ],
+      "examples": [
+        "llm.trace.span.completed",
+        "llm.cost.token.recorded",
+        "llm.redact.pii.detected",
+        "llm.audit.key.rotated"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "UTC ISO-8601 timestamp with microsecond precision. Format: YYYY-MM-DDThh:mm:ss.ffffffZ (RFC §5.1).",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$",
+      "examples": ["2026-03-09T12:00:00.000000Z"]
+    },
+    "source": {
+      "type": "string",
+      "description": "Emitting service in 'name@semver' format (RFC §5.1).",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9._-]*@\\d+\\.\\d+\\.\\d+(?:[.-][a-zA-Z0-9.]+)?$",
+      "examples": ["agentobs@1.0.7", "my-agent@2.1.0-beta.1"]
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-type-specific data. MUST contain at least one property (RFC §5.1).",
+      "minProperties": 1
+    },
+    "trace_id": {
+      "type": "string",
+      "description": "W3C / OTel trace identifier — exactly 32 lowercase hexadecimal characters.",
+      "pattern": "^[0-9a-f]{32}$",
+      "examples": ["4bf92f3577b34da6a3ce929d0e0e4736"]
+    },
+    "span_id": {
+      "type": "string",
+      "description": "W3C / OTel span identifier — exactly 16 lowercase hexadecimal characters.",
+      "pattern": "^[0-9a-f]{16}$",
+      "examples": ["00f067aa0ba902b7"]
+    },
+    "parent_span_id": {
+      "type": "string",
+      "description": "Parent span identifier — exactly 16 lowercase hexadecimal characters.",
+      "pattern": "^[0-9a-f]{16}$"
+    },
+    "org_id": {
+      "type": "string",
+      "description": "Organisation identifier for multi-tenant deployments.",
+      "minLength": 1
+    },
+    "team_id": {
+      "type": "string",
+      "description": "Team identifier.",
+      "minLength": 1
+    },
+    "actor_id": {
+      "type": "string",
+      "description": "User or service-account that triggered the event.",
+      "minLength": 1
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Session identifier grouping a series of related events.",
+      "minLength": 1
+    },
+    "tags": {
+      "type": "object",
+      "description": "Arbitrary string key→value metadata. Maximum 50 keys recommended (RFC §19.4).",
+      "maxProperties": 50,
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1
+      },
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "checksum": {
+      "type": "string",
+      "description": "SHA-256 digest of the canonical payload JSON. Format: 'sha256:' + 64 lowercase hex (RFC §11).",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "signature": {
+      "type": "string",
+      "description": "HMAC-SHA256 audit chain signature. Format: 'hmac-sha256:' + 64 lowercase hex (RFC §11).",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    },
+    "prev_id": {
+      "type": "string",
+      "description": "ULID of the immediately preceding event in the audit chain (RFC §11).",
+      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
+      "minLength": 26,
+      "maxLength": 26
+    }
+  },
+  "$defs": {
+    "ulid": {
+      "type": "string",
+      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
+      "minLength": 26,
+      "maxLength": 26
+    },
+    "trace_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$"
+    },
+    "span_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{16}$"
+    },
+    "sha256_hex": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "minLength": 64,
+      "maxLength": 64
+    },
+    "iso_date": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "iso_timestamp_us": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$"
+    },
+    "gen_ai_system": {
+      "type": "string",
+      "description": "Provider identifier (RFC §10.1, Appendix C).",
+      "enum": [
+        "openai",
+        "anthropic",
+        "cohere",
+        "vertex_ai",
+        "aws_bedrock",
+        "az.ai.inference",
+        "groq",
+        "ollama",
+        "mistral_ai",
+        "together_ai",
+        "hugging_face",
+        "_custom"
+      ]
+    },
+    "gen_ai_operation_name": {
+      "type": "string",
+      "description": "Type of LLM operation (RFC §10.2).",
+      "enum": [
+        "chat",
+        "text_completion",
+        "embeddings",
+        "image_generation",
+        "execute_tool",
+        "invoke_agent",
+        "create_agent",
+        "reasoning"
+      ]
+    },
+    "span_kind": {
+      "type": "string",
+      "description": "OTel SpanKind for LLM operations (RFC §10.3).",
+      "enum": ["CLIENT", "SERVER", "INTERNAL", "CONSUMER", "PRODUCER"]
+    },
+    "token_usage": {
+      "type": "object",
+      "description": "Token consumption record (RFC §9.1).",
+      "required": ["input_tokens", "output_tokens", "total_tokens"],
+      "additionalProperties": false,
+      "properties": {
+        "input_tokens": {"type": "integer", "minimum": 0},
+        "output_tokens": {"type": "integer", "minimum": 0},
+        "total_tokens": {"type": "integer", "minimum": 0},
+        "cached_tokens": {"type": "integer", "minimum": 0},
+        "cache_creation_tokens": {"type": "integer", "minimum": 0},
+        "reasoning_tokens": {"type": "integer", "minimum": 0},
+        "image_tokens": {"type": "integer", "minimum": 0}
+      }
+    },
+    "model_info": {
+      "type": "object",
+      "description": "Model identity and provider information (RFC §9.2). custom_system_name is REQUIRED when system is '_custom'.",
+      "required": ["system", "name"],
+      "additionalProperties": false,
+      "properties": {
+        "system": {"$ref": "#/$defs/gen_ai_system"},
+        "name": {"type": "string", "minLength": 1},
+        "response_model": {"type": "string", "minLength": 1},
+        "version": {"type": "string", "minLength": 1},
+        "custom_system_name": {"type": "string", "minLength": 1}
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "system": {"const": "_custom"}
+            }
+          },
+          "then": {
+            "required": ["custom_system_name"]
+          }
+        }
+      ]
+    },
+    "cost_breakdown": {
+      "type": "object",
+      "description": "Typed cost attribution record (RFC §9.3).",
+      "required": ["input_cost_usd", "output_cost_usd", "total_cost_usd"],
+      "additionalProperties": false,
+      "properties": {
+        "input_cost_usd": {"type": "number", "minimum": 0},
+        "output_cost_usd": {"type": "number", "minimum": 0},
+        "total_cost_usd": {"type": "number", "minimum": 0},
+        "cached_discount_usd": {"type": "number", "minimum": 0},
+        "reasoning_cost_usd": {"type": "number", "minimum": 0},
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "default": "USD"
+        },
+        "pricing_date": {"$ref": "#/$defs/iso_date"}
+      }
+    },
+    "pricing_tier": {
+      "type": "object",
+      "description": "Pricing rates snapshot for cost reproducibility (RFC §9.4).",
+      "required": [
+        "system",
+        "model",
+        "input_per_million_usd",
+        "output_per_million_usd",
+        "effective_date"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "system": {"$ref": "#/$defs/gen_ai_system"},
+        "model": {"type": "string", "minLength": 1},
+        "input_per_million_usd": {"type": "number", "minimum": 0},
+        "output_per_million_usd": {"type": "number", "minimum": 0},
+        "effective_date": {"$ref": "#/$defs/iso_date"},
+        "cached_input_per_million_usd": {"type": "number", "minimum": 0},
+        "reasoning_per_million_usd": {"type": "number", "minimum": 0}
+      }
+    },
+    "tool_call": {
+      "type": "object",
+      "description": "A single tool invocation within a span (RFC §8.1).",
+      "required": ["tool_call_id", "function_name", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "tool_call_id": {"type": "string", "minLength": 1},
+        "function_name": {"type": "string", "minLength": 1},
+        "status": {
+          "type": "string",
+          "enum": ["success", "error", "timeout", "cancelled"]
+        },
+        "arguments_hash": {"$ref": "#/$defs/sha256_hex"},
+        "error_type": {"type": "string"},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "arguments_raw": {"type": "string"},
+        "result_raw": {"type": "string"},
+        "retry_count": {"type": "integer", "minimum": 0},
+        "external_api": {"type": "string"}
+      }
+    },
+    "span_event": {
+      "type": "object",
+      "description": "An instantaneous named event within a span.",
+      "required": ["name", "timestamp_ns"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "timestamp_ns": {"type": "integer", "minimum": 0},
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "reasoning_step": {
+      "type": "object",
+      "description": "A discrete chain-of-thought unit (RFC §8.2). Raw content MUST NOT be stored.",
+      "required": ["step_index", "reasoning_tokens"],
+      "additionalProperties": false,
+      "properties": {
+        "step_index": {"type": "integer", "minimum": 0},
+        "reasoning_tokens": {"type": "integer", "minimum": 0},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "content_hash": {"$ref": "#/$defs/sha256_hex"}
+      }
+    },
+    "decision_point": {
+      "type": "object",
+      "description": "An explicit branching decision recorded during an agent step (RFC §8.3).",
+      "required": [
+        "decision_id",
+        "decision_type",
+        "options_considered",
+        "chosen_option"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "decision_id": {"type": "string", "minLength": 1},
+        "decision_type": {
+          "type": "string",
+          "enum": [
+            "tool_selection",
+            "route_choice",
+            "loop_termination",
+            "escalation"
+          ]
+        },
+        "options_considered": {
+          "type": "array",
+          "items": {"type": "string"},
+          "minItems": 1
+        },
+        "chosen_option": {"type": "string", "minLength": 1},
+        "rationale": {"type": "string"}
+      }
+    },
+    "span_payload": {
+      "type": "object",
+      "description": "SpanPayload — a single unit of LLM work (RFC §8.1).",
+      "required": [
+        "span_id",
+        "trace_id",
+        "span_name",
+        "operation",
+        "span_kind",
+        "status",
+        "start_time_unix_nano",
+        "end_time_unix_nano",
+        "duration_ms",
+        "tool_calls"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "span_id": {"$ref": "#/$defs/span_id"},
+        "trace_id": {"$ref": "#/$defs/trace_id"},
+        "span_name": {"type": "string", "minLength": 1},
+        "operation": {"$ref": "#/$defs/gen_ai_operation_name"},
+        "span_kind": {"$ref": "#/$defs/span_kind"},
+        "status": {"type": "string", "enum": ["ok", "error", "timeout"]},
+        "start_time_unix_nano": {"type": "integer", "minimum": 0},
+        "end_time_unix_nano": {"type": "integer", "minimum": 0},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "tool_calls": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/tool_call"}
+        },
+        "reasoning_steps": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/reasoning_step"}
+        },
+        "parent_span_id": {"$ref": "#/$defs/span_id"},
+        "agent_run_id": {"type": "string", "minLength": 1},
+        "model": {"$ref": "#/$defs/model_info"},
+        "token_usage": {"$ref": "#/$defs/token_usage"},
+        "cost": {"$ref": "#/$defs/cost_breakdown"},
+        "finish_reason": {"type": "string"},
+        "error": {"type": "string"},
+        "error_type": {"type": "string"},
+        "error_category": {"type": "string"},
+        "attributes": {"type": "object"},
+        "temperature": {"type": "number"},
+        "top_p": {"type": "number"},
+        "max_tokens": {"type": "integer"},
+        "events": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/span_event"}
+        }
+      }
+    },
+    "agent_step_payload": {
+      "type": "object",
+      "description": "AgentStepPayload — one iteration of a multi-step agent loop (RFC §8.4).",
+      "required": [
+        "agent_run_id",
+        "step_index",
+        "span_id",
+        "trace_id",
+        "operation",
+        "tool_calls",
+        "reasoning_steps",
+        "decision_points",
+        "status",
+        "start_time_unix_nano",
+        "end_time_unix_nano",
+        "duration_ms"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "agent_run_id": {"type": "string", "minLength": 1},
+        "step_index": {"type": "integer", "minimum": 0},
+        "span_id": {"$ref": "#/$defs/span_id"},
+        "trace_id": {"$ref": "#/$defs/trace_id"},
+        "operation": {"$ref": "#/$defs/gen_ai_operation_name"},
+        "tool_calls": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/tool_call"}
+        },
+        "reasoning_steps": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/reasoning_step"}
+        },
+        "decision_points": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/decision_point"}
+        },
+        "status": {"type": "string", "enum": ["ok", "error", "timeout"]},
+        "start_time_unix_nano": {"type": "integer", "minimum": 0},
+        "end_time_unix_nano": {"type": "integer", "minimum": 0},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "parent_span_id": {"$ref": "#/$defs/span_id"},
+        "model": {"$ref": "#/$defs/model_info"},
+        "token_usage": {"$ref": "#/$defs/token_usage"},
+        "cost": {"$ref": "#/$defs/cost_breakdown"},
+        "error": {"type": "string"},
+        "error_type": {"type": "string"},
+        "step_name": {"type": "string"}
+      }
+    },
+    "agent_run_payload": {
+      "type": "object",
+      "description": "AgentRunPayload — root-level summary for a complete agent run (RFC §8.5).",
+      "required": [
+        "agent_run_id",
+        "agent_name",
+        "trace_id",
+        "root_span_id",
+        "total_steps",
+        "total_model_calls",
+        "total_tool_calls",
+        "total_token_usage",
+        "total_cost",
+        "status",
+        "start_time_unix_nano",
+        "end_time_unix_nano",
+        "duration_ms"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "agent_run_id": {"type": "string", "minLength": 1},
+        "agent_name": {"type": "string", "minLength": 1},
+        "trace_id": {"$ref": "#/$defs/trace_id"},
+        "root_span_id": {"$ref": "#/$defs/span_id"},
+        "total_steps": {"type": "integer", "minimum": 0},
+        "total_model_calls": {"type": "integer", "minimum": 0},
+        "total_tool_calls": {"type": "integer", "minimum": 0},
+        "total_token_usage": {"$ref": "#/$defs/token_usage"},
+        "total_cost": {"$ref": "#/$defs/cost_breakdown"},
+        "status": {
+          "type": "string",
+          "enum": ["ok", "error", "timeout", "max_steps_exceeded"]
+        },
+        "start_time_unix_nano": {"type": "integer", "minimum": 0},
+        "end_time_unix_nano": {"type": "integer", "minimum": 0},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "termination_reason": {"type": "string"}
+      }
+    }
+  }
+}