coreason-manifest 0.7.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

coreason_manifest/__init__.py

@@ -1,17 +1,98 @@
-from .definitions.agent import AgentDefinition
+# Copyright (c) 2025 CoReason, Inc.
+#
+# This software is proprietary and dual-licensed.
+# Licensed under the Prosperity Public License 3.0 (the "License").
+# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
+# For details, see the LICENSE file.
+# Commercial use beyond a 30-day trial requires a separate license.
+#
+# Source Code: https://github.com/CoReason-AI/coreason-manifest
+
+from .definitions.agent import AgentDefinition, Persona
 from .definitions.audit import AuditLog
-from .definitions.simulation import SimulationScenario, SimulationTrace, SimulationTurn
-from .definitions.topology import Edge, Node, Topology
+from .definitions.events import (
+    ArtifactGenerated,
+    CloudEvent,
+    CouncilVote,
+    EdgeTraversed,
+    GraphEvent,
+    GraphEventArtifactGenerated,
+    GraphEventCouncilVote,
+    GraphEventEdgeActive,
+    GraphEventError,
+    GraphEventNodeDone,
+    GraphEventNodeInit,
+    GraphEventNodeRestored,
+    GraphEventNodeSkipped,
+    GraphEventNodeStart,
+    GraphEventNodeStream,
+    NodeCompleted,
+    NodeInit,
+    NodeRestored,
+    NodeSkipped,
+    NodeStarted,
+    NodeStream,
+    WorkflowError,
+    migrate_graph_event_to_cloud_event,
+)
+from .definitions.simulation import (
+    SimulationMetrics,
+    SimulationScenario,
+    SimulationStep,
+    SimulationTrace,
+    StepType,
+)
+from .definitions.simulation_config import AdversaryProfile, ChaosConfig, SimulationRequest
+from .definitions.topology import (
+    AgentNode,
+    Edge,
+    GraphTopology,
+    Node,
+    StateDefinition,
+    Topology,
+)
 from .recipes import RecipeManifest
 
 __all__ = [
     "AgentDefinition",
+    "Persona",
     "Topology",
+    "GraphTopology",
     "Node",
+    "AgentNode",
     "Edge",
+    "StateDefinition",
+    "GraphEvent",
+    "CloudEvent",
+    "GraphEventNodeInit",
+    "GraphEventNodeStart",
+    "GraphEventNodeDone",
+    "GraphEventNodeStream",
+    "GraphEventNodeSkipped",
+    "GraphEventNodeRestored",
+    "GraphEventEdgeActive",
+    "GraphEventCouncilVote",
+    "GraphEventError",
+    "GraphEventArtifactGenerated",
+    "NodeInit",
+    "NodeStarted",
+    "NodeCompleted",
+    "NodeStream",
+    "NodeSkipped",
+    "NodeRestored",
+    "WorkflowError",
+    "CouncilVote",
+    "ArtifactGenerated",
+    "EdgeTraversed",
+    "migrate_graph_event_to_cloud_event",
     "SimulationScenario",
     "SimulationTrace",
-    "SimulationTurn",
+    "SimulationStep",
+    "SimulationMetrics",
+    "StepType",
+    "AdversaryProfile",
+    "ChaosConfig",
+    "SimulationRequest",
     "AuditLog",
     "RecipeManifest",
 ]

coreason_manifest/definitions/__init__.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2025 CoReason, Inc.
+#
+# This software is proprietary and dual-licensed.
+# Licensed under the Prosperity Public License 3.0 (the "License").
+# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
+# For details, see the LICENSE file.
+# Commercial use beyond a 30-day trial requires a separate license.
+#
+# Source Code: https://github.com/CoReason-AI/coreason-manifest
+
+from .agent import AgentDefinition, AgentRuntimeConfig, Persona
+from .events import (
+    ArtifactGenerated,
+    ArtifactGeneratedPayload,
+    CouncilVote,
+    CouncilVotePayload,
+    EdgeTraversed,
+    EdgeTraversedPayload,
+    GraphEvent,
+    NodeCompleted,
+    NodeCompletedPayload,
+    NodeInit,
+    # Export Aliases too
+    NodeInitPayload,
+    NodeRestored,
+    NodeSkipped,
+    NodeSkippedPayload,
+    NodeStarted,
+    NodeStartedPayload,
+    NodeStream,
+    NodeStreamPayload,
+    WorkflowError,
+    WorkflowErrorPayload,
+)
+
+__all__ = [
+    "AgentRuntimeConfig",
+    "AgentDefinition",
+    "Persona",
+    "GraphEvent",
+    "NodeInit",
+    "NodeStarted",
+    "NodeCompleted",
+    "NodeRestored",
+    "NodeSkipped",
+    "NodeStream",
+    "ArtifactGenerated",
+    "EdgeTraversed",
+    "CouncilVote",
+    "WorkflowError",
+    "NodeInitPayload",
+    "NodeStartedPayload",
+    "NodeCompletedPayload",
+    "NodeSkippedPayload",
+    "NodeStreamPayload",
+    "EdgeTraversedPayload",
+    "ArtifactGeneratedPayload",
+    "CouncilVotePayload",
+    "WorkflowErrorPayload",
+]

coreason_manifest/definitions/agent.py

@@ -1,4 +1,13 @@
-# Prosperity-3.0
+# Copyright (c) 2025 CoReason, Inc.
+#
+# This software is proprietary and dual-licensed.
+# Licensed under the Prosperity Public License 3.0 (the "License").
+# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
+# For details, see the LICENSE file.
+# Commercial use beyond a 30-day trial requires a separate license.
+#
+# Source Code: https://github.com/CoReason-AI/coreason-manifest
+
 """Pydantic models for the Coreason Manifest system.
 
 These models define the structure and validation rules for the Agent Manifest
@@ -8,14 +17,14 @@ These models define the structure and validation rules for the Agent Manifest
 from __future__ import annotations
 
 from datetime import datetime
+from enum import Enum
 from types import MappingProxyType
-from typing import Any, Dict, List, Mapping, Optional, Tuple
+from typing import Any, Dict, List, Literal, Mapping, Optional, Tuple, Union
 from uuid import UUID
 
 from pydantic import (
     AfterValidator,
     AnyUrl,
-    BaseModel,
     ConfigDict,
     Field,
     PlainSerializer,
@@ -24,6 +33,9 @@ from pydantic import (
 )
 from typing_extensions import Annotated
 
+from coreason_manifest.definitions.base import CoReasonBaseModel
+from coreason_manifest.definitions.topology import Edge, Node, validate_edge_integrity
+
 # SemVer Regex pattern (simplified for standard SemVer)
 # Modified to accept optional 'v' or 'V' prefix (multiple allowed) for input normalization
 SEMVER_REGEX = (
@@ -69,7 +81,7 @@ StrictUri = Annotated[
 ]
 
 
-class AgentMetadata(BaseModel):
+class AgentMetadata(CoReasonBaseModel):
     """Metadata for the Agent.
 
     Attributes:
@@ -90,77 +102,113 @@ class AgentMetadata(BaseModel):
     requires_auth: bool = Field(default=False, description="Whether the agent requires user authentication.")
 
 
-class AgentInterface(BaseModel):
-    """Interface definition for the Agent.
+class Persona(CoReasonBaseModel):
+    """Definition of an Agent Persona.
 
     Attributes:
-        inputs: Typed arguments the agent accepts (JSON Schema).
-        outputs: Typed structure of the result.
+        name: Name of the persona.
+        description: Description of the persona.
+        directives: List of specific instructions or directives.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    inputs: ImmutableDict = Field(..., description="Typed arguments the agent accepts (JSON Schema).")
-    outputs: ImmutableDict = Field(..., description="Typed structure of the result.")
-    injected_params: List[str] = Field(default_factory=list, description="List of parameters injected by the system.")
+    name: str = Field(..., description="Name of the persona.")
+    description: str = Field(..., description="Description of the persona.")
+    directives: List[str] = Field(..., description="List of specific instructions or directives.")
 
 
-class Step(BaseModel):
-    """A single step in the execution graph.
+class AgentInterface(CoReasonBaseModel):
+    """Interface definition for the Agent.
 
     Attributes:
-        id: Unique identifier for the step.
-        description: Description of the step.
+        inputs: Typed arguments the agent accepts (JSON Schema).
+        outputs: Typed structure of the result.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    id: str = Field(..., min_length=1, description="Unique identifier for the step.")
-    description: Optional[str] = Field(None, description="Description of the step.")
+    inputs: ImmutableDict = Field(..., description="Typed arguments the agent accepts (JSON Schema).")
+    outputs: ImmutableDict = Field(..., description="Typed structure of the result.")
+    injected_params: List[str] = Field(default_factory=list, description="List of parameters injected by the system.")
 
 
-class ModelConfig(BaseModel):
+class ModelConfig(CoReasonBaseModel):
     """LLM Configuration parameters.
 
     Attributes:
         model: The LLM model identifier.
         temperature: Temperature for generation.
+        system_prompt: The default system prompt/persona for the agent.
+        persona: The full persona definition (name, description, directives).
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     model: str = Field(..., description="The LLM model identifier.")
     temperature: float = Field(..., ge=0.0, le=2.0, description="Temperature for generation.")
+    system_prompt: Optional[str] = Field(None, description="The default system prompt/persona for the agent.")
+    persona: Optional[Persona] = Field(None, description="The full persona definition (name, description, directives).")
 
 
-class AgentTopology(BaseModel):
-    """Topology of the Agent execution.
+class AgentRuntimeConfig(CoReasonBaseModel):
+    """Configuration of the Agent execution.
 
     Attributes:
-        steps: A directed acyclic graph (DAG) of execution steps.
+        nodes: A collection of execution units (Agents, Tools, Logic).
+        edges: Directed connections defining control flow.
+        entry_point: The ID of the starting node.
         llm_config: Specific LLM parameters.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    steps: Tuple[Step, ...] = Field(..., description="A directed acyclic graph (DAG) of execution steps.")
+    nodes: List[Node] = Field(default_factory=list, description="A collection of execution units.")
+    edges: List[Edge] = Field(default_factory=list, description="Directed connections defining control flow.")
+    entry_point: Optional[str] = Field(None, description="The ID of the starting node.")
     llm_config: ModelConfig = Field(..., alias="model_config", description="Specific LLM parameters.")
+    system_prompt: Optional[str] = Field(None, description="The global system prompt/instruction for the agent.")
+
+    @model_validator(mode="after")
+    def validate_topology_or_atomic(self) -> AgentRuntimeConfig:
+        """Ensure valid configuration: either a Graph or an Atomic Agent."""
+        has_nodes = len(self.nodes) > 0
+        has_entry = self.entry_point is not None
+
+        if has_nodes:
+            if not has_entry:
+                raise ValueError("Graph execution requires an 'entry_point'.")
+        else:
+            # Atomic Agent: Must have a system prompt (either global or in model_config)
+            has_global_prompt = self.system_prompt is not None
+            has_model_prompt = self.llm_config.system_prompt is not None
+
+            if not (has_global_prompt or has_model_prompt):
+                raise ValueError("Atomic Agents require a system_prompt (global or in model_config).")
 
-    @field_validator("steps")
+        return self
+
+    @model_validator(mode="after")
+    def validate_topology_integrity(self) -> AgentRuntimeConfig:
+        """Ensure that edges connect existing nodes."""
+        validate_edge_integrity(self.nodes, self.edges)
+        return self
+
+    @field_validator("nodes")
     @classmethod
-    def validate_unique_step_ids(cls, v: Tuple[Step, ...]) -> Tuple[Step, ...]:
-        """Ensure all step IDs are unique.
+    def validate_unique_node_ids(cls, v: List[Node]) -> List[Node]:
+        """Ensure all node IDs are unique.
 
         Args:
-            v: The tuple of steps to validate.
+            v: The list of nodes to validate.
 
         Returns:
-            The validated tuple of steps.
+            The validated list of nodes.
 
         Raises:
-            ValueError: If duplicate step IDs are found.
+            ValueError: If duplicate node IDs are found.
         """
-        ids = [step.id for step in v]
+        ids = [node.id for node in v]
         if len(ids) != len(set(ids)):
             # Find duplicates
             seen = set()
@@ -169,35 +217,121 @@ class AgentTopology(BaseModel):
                 if x in seen:
                     dupes.add(x)
                 seen.add(x)
-            raise ValueError(f"Duplicate step IDs found: {', '.join(dupes)}")
+            raise ValueError(f"Duplicate node IDs found: {', '.join(dupes)}")
         return v
 
 
-class AgentDependencies(BaseModel):
+class ToolRiskLevel(str, Enum):
+    """Risk level for the tool."""
+
+    SAFE = "safe"
+    STANDARD = "standard"
+    CRITICAL = "critical"
+
+
+class ToolRequirement(CoReasonBaseModel):
+    """Requirement for an MCP tool.
+
+    Attributes:
+        uri: The MCP endpoint URI.
+        hash: Integrity check for the tool definition (SHA256).
+        scopes: List of permissions required.
+        risk_level: The risk level of the tool.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    uri: StrictUri = Field(..., description="The MCP endpoint URI.")
+    hash: str = Field(
+        ..., pattern=r"^[a-fA-F0-9]{64}$", description="Integrity check for the tool definition (SHA256)."
+    )
+    scopes: List[str] = Field(..., description="List of permissions required.")
+    risk_level: ToolRiskLevel = Field(..., description="The risk level of the tool.")
+
+
+class InlineToolDefinition(CoReasonBaseModel):
+    """Definition of an inline tool.
+
+    Attributes:
+        name: Name of the tool.
+        description: Description of the tool.
+        parameters: JSON Schema of parameters.
+        type: The type of the tool (must be 'function').
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(..., description="Name of the tool.")
+    description: str = Field(..., description="Description of the tool.")
+    parameters: Dict[str, Any] = Field(..., description="JSON Schema of parameters.")
+    type: Literal["function"] = Field("function", description="The type of the tool (must be 'function').")
+
+
+class AgentDependencies(CoReasonBaseModel):
     """External dependencies for the Agent.
 
     Attributes:
-        tools: List of MCP capability URIs required.
+        tools: List of MCP tool requirements.
         libraries: List of Python packages required (if code execution is allowed).
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    # Use AnyUrl to enforce strictly valid URIs
-    # Changed to List[StrictUri] to strictly enforce valid URI formatting and string serialization
-    tools: List[StrictUri] = Field(default_factory=list, description="List of MCP capability URIs required.")
+    tools: List[Union[ToolRequirement, InlineToolDefinition]] = Field(
+        default_factory=list, description="List of MCP tool requirements."
+    )
     libraries: Tuple[str, ...] = Field(
         default_factory=tuple, description="List of Python packages required (if code execution is allowed)."
     )
 
 
-class AgentDefinition(BaseModel):
+class PolicyConfig(CoReasonBaseModel):
+    """Governance policy configuration.
+
+    Attributes:
+        budget_caps: Dictionary defining budget limits (e.g., {"total_cost": 10.0, "total_tokens": 1000}).
+        human_in_the_loop: List of Node IDs that require human approval.
+        allowed_domains: List of allowed domains for external access.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    budget_caps: Dict[str, float] = Field(default_factory=dict, description="Budget limits.")
+    human_in_the_loop: List[str] = Field(default_factory=list, description="Node IDs requiring human approval.")
+    allowed_domains: List[str] = Field(default_factory=list, description="Allowed domains for external access.")
+
+
+class TraceLevel(str, Enum):
+    """Level of tracing detail."""
+
+    FULL = "full"
+    METADATA_ONLY = "metadata_only"
+    NONE = "none"
+
+
+class ObservabilityConfig(CoReasonBaseModel):
+    """Observability configuration.
+
+    Attributes:
+        trace_level: Level of tracing detail.
+        retention_policy: Retention policy identifier (e.g., '30_days').
+        encryption_key_id: Optional ID of the key used for log encryption.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    trace_level: TraceLevel = Field(default=TraceLevel.FULL, description="Level of tracing detail.")
+    retention_policy: str = Field(default="30_days", description="Retention policy identifier.")
+    encryption_key_id: Optional[str] = Field(None, description="Optional ID of the key used for log encryption.")
+
+
+class AgentDefinition(CoReasonBaseModel):
     """The Root Object for the CoReason Agent Manifest.
 
     Attributes:
         metadata: Metadata for the Agent.
         interface: Interface definition for the Agent.
-        topology: Topology of the Agent execution.
+        config: Configuration of the Agent execution.
         dependencies: External dependencies for the Agent.
         integrity_hash: SHA256 hash of the source code.
     """
@@ -214,8 +348,13 @@ class AgentDefinition(BaseModel):
 
     metadata: AgentMetadata
     interface: AgentInterface
-    topology: AgentTopology
+    config: AgentRuntimeConfig
     dependencies: AgentDependencies
+    policy: Optional[PolicyConfig] = Field(None, description="Governance policy configuration.")
+    observability: Optional[ObservabilityConfig] = Field(None, description="Observability configuration.")
+    custom_metadata: Optional[Dict[str, Any]] = Field(
+        None, description="Container for arbitrary metadata extensions without breaking validation."
+    )
     integrity_hash: str = Field(
         ...,
         pattern=r"^[a-fA-F0-9]{64}$",

coreason_manifest/definitions/audit.py

@@ -1,7 +1,181 @@
-from pydantic import BaseModel
+# Copyright (c) 2025 CoReason, Inc.
+#
+# This software is proprietary and dual-licensed.
+# Licensed under the Prosperity Public License 3.0 (the "License").
+# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
+# For details, see the LICENSE file.
+# Commercial use beyond a 30-day trial requires a separate license.
+#
+# Source Code: https://github.com/CoReason-AI/coreason-manifest
 
+import hashlib
+import json
+import uuid
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID
 
-class AuditLog(BaseModel):
-    """Audit log entry."""
+from pydantic import ConfigDict, Field
 
-    pass
+from coreason_manifest.definitions.base import CoReasonBaseModel
+
+from .message import ChatMessage
+
+
+class GenAITokenUsage(CoReasonBaseModel):
+    """Token consumption stats aligned with OTel conventions."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    input: int = Field(0, description="Number of input tokens (prompt).")
+    output: int = Field(0, description="Number of output tokens (completion).")
+    total: int = Field(0, description="Total number of tokens used.")
+
+    # Backward compatibility fields (mapped to new fields in logic if needed, but kept for schema)
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+    def __add__(self, other: "GenAITokenUsage") -> "GenAITokenUsage":
+        """Add two TokenUsage objects."""
+        new_details = self.details.copy()
+        new_details.update(other.details)
+        return GenAITokenUsage(
+            input=self.input + other.input,
+            output=self.output + other.output,
+            total=self.total + other.total,
+            prompt_tokens=self.prompt_tokens + other.prompt_tokens,
+            completion_tokens=self.completion_tokens + other.completion_tokens,
+            total_tokens=self.total_tokens + other.total_tokens,
+            details=new_details,
+        )
+
+    def __iadd__(self, other: "GenAITokenUsage") -> "GenAITokenUsage":
+        """In-place add two TokenUsage objects."""
+        self.input += other.input
+        self.output += other.output
+        self.total += other.total
+        self.prompt_tokens += other.prompt_tokens
+        self.completion_tokens += other.completion_tokens
+        self.total_tokens += other.total_tokens
+        self.details.update(other.details)
+        return self
+
+
+class GenAIOperation(CoReasonBaseModel):
+    """An atomic operation in the reasoning process (e.g., one LLM call), aligning with OTel Spans."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    span_id: str = Field(..., description="Unique identifier for the operation/span.")
+    trace_id: str = Field(..., description="Trace ID this operation belongs to.")
+    parent_id: Optional[str] = Field(None, description="Parent span ID.")
+
+    operation_name: str = Field(..., description="Name of the operation (e.g., chat, embedding).")
+    provider: str = Field(..., description="GenAI provider (e.g., openai, anthropic).")
+    model: str = Field(..., description="Model name used.")
+
+    start_time: datetime = Field(default_factory=datetime.now)
+    end_time: Optional[datetime] = None
+    duration_ms: float = 0.0
+
+    # Context
+    input_messages: List[ChatMessage] = Field(default_factory=list)
+    output_messages: List[ChatMessage] = Field(default_factory=list)
+
+    # Metrics
+    token_usage: Optional[GenAITokenUsage] = None
+
+    # Metadata
+    status: str = "pending"  # success, error
+    error_type: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def thought(cls, content: str, **kwargs: Any) -> "GenAIOperation":
+        """Factory method to create a simplified thought/reasoning step."""
+        defaults = {
+            "span_id": str(uuid.uuid4()),
+            "trace_id": str(uuid.uuid4()),
+            "operation_name": "thought",
+            "provider": "internal",
+            "model": "internal",
+        }
+        defaults.update(kwargs)
+        # Ensure output_messages is not duplicated if passed in kwargs
+        defaults.pop("output_messages", None)
+        return cls(
+            **defaults,
+            output_messages=[ChatMessage.assistant(content)],
+        )
+
+
+class ReasoningTrace(CoReasonBaseModel):
+    """The full audit trail of an Agent's execution session.
+
+    Aligned with OpenTelemetry for trace identification.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    trace_id: str = Field(..., description="Trace ID (OTel format).")
+    agent_id: str
+    session_id: Optional[str] = None
+
+    start_time: datetime
+    end_time: Optional[datetime] = None
+
+    # The chain of thought (Ordered list of operations)
+    steps: List[GenAIOperation] = Field(default_factory=list)
+
+    # Final outcome
+    status: str = "pending"  # options: success, failure, pending
+    final_result: Optional[str] = None
+    error: Optional[str] = None
+
+    # Aggregated stats
+    total_tokens: GenAITokenUsage = Field(default_factory=GenAITokenUsage)
+    total_cost: float = 0.0
+
+    # Flexible metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class AuditEventType(str, Enum):
+    SYSTEM_CHANGE = "system_change"
+    PREDICTION = "prediction"
+    GUARDRAIL_TRIGGER = "guardrail_trigger"
+
+
+class AuditLog(CoReasonBaseModel):
+    """Tamper-evident legal record.
+
+    IDs aligned with OpenTelemetry:
+    - audit_id: Unique record ID.
+    - trace_id: OTel Trace ID.
+    """
+
+    audit_id: UUID = Field(..., description="Unique identifier.")
+    trace_id: str = Field(..., description="Trace ID for OTel correlation.")
+    timestamp: datetime = Field(..., description="ISO8601 timestamp.")
+    actor: str = Field(..., description="User ID or Agent Component ID.")
+    event_type: AuditEventType = Field(..., description="Type of event.")
+    safety_metadata: Dict[str, Any] = Field(..., description="Safety metadata (e.g., PII detected).")
+    previous_hash: str = Field(..., description="Hash of the previous log entry.")
+    integrity_hash: str = Field(..., description="SHA256 hash of this record + previous_hash.")
+
+    def compute_hash(self) -> str:
+        """Computes the integrity hash of the record."""
+        # Use model_dump to get a dict, but exclude integrity_hash as it is the target
+        data = self.model_dump(exclude={"integrity_hash"}, mode="json")
+        # Ensure deterministic serialization
+        json_str = json.dumps(data, sort_keys=True, default=str)
+        return hashlib.sha256(json_str.encode("utf-8")).hexdigest()
+
+
+# --- Backward Compatibility ---
+# Adapters or Aliases
+CognitiveStep = GenAIOperation
+TokenUsage = GenAITokenUsage