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

coreason_manifest/__init__.py

@@ -1,6 +1,6 @@
 from .definitions.agent import AgentDefinition
 from .definitions.audit import AuditLog
-from .definitions.simulation import SimulationScenario, SimulationTrace, SimulationTurn
+from .definitions.simulation import SimulationScenario, SimulationStep, SimulationTrace
 from .definitions.topology import Edge, Node, Topology
 from .recipes import RecipeManifest
 
@@ -11,7 +11,7 @@ __all__ = [
     "Edge",
     "SimulationScenario",
     "SimulationTrace",
-    "SimulationTurn",
+    "SimulationStep",
     "AuditLog",
     "RecipeManifest",
 ]

coreason_manifest/definitions/__init__.py

@@ -0,0 +1,49 @@
+from .agent import AgentDefinition, AgentRuntimeConfig
+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",
+    "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

@@ -8,6 +8,7 @@ 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 uuid import UUID
@@ -24,6 +25,8 @@ from pydantic import (
 )
 from typing_extensions import Annotated
 
+from coreason_manifest.definitions.topology import Edge, Node
+
 # SemVer Regex pattern (simplified for standard SemVer)
 # Modified to accept optional 'v' or 'V' prefix (multiple allowed) for input normalization
 SEMVER_REGEX = (
@@ -105,20 +108,6 @@ class AgentInterface(BaseModel):
     injected_params: List[str] = Field(default_factory=list, description="List of parameters injected by the system.")
 
 
-class Step(BaseModel):
-    """A single step in the execution graph.
-
-    Attributes:
-        id: Unique identifier for the step.
-        description: Description of the step.
-    """
-
-    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.")
-
-
 class ModelConfig(BaseModel):
     """LLM Configuration parameters.
 
@@ -133,34 +122,38 @@ class ModelConfig(BaseModel):
     temperature: float = Field(..., ge=0.0, le=2.0, description="Temperature for generation.")
 
 
-class AgentTopology(BaseModel):
-    """Topology of the Agent execution.
+class AgentRuntimeConfig(BaseModel):
+    """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(..., description="A collection of execution units.")
+    edges: List[Edge] = Field(..., description="Directed connections defining control flow.")
+    entry_point: str = Field(..., description="The ID of the starting node.")
     llm_config: ModelConfig = Field(..., alias="model_config", description="Specific LLM parameters.")
 
-    @field_validator("steps")
+    @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 +162,101 @@ 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 ToolRiskLevel(str, Enum):
+    """Risk level for the tool."""
+
+    SAFE = "safe"
+    STANDARD = "standard"
+    CRITICAL = "critical"
+
+
+class ToolRequirement(BaseModel):
+    """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 AgentDependencies(BaseModel):
     """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[ToolRequirement] = 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 PolicyConfig(BaseModel):
+    """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(BaseModel):
+    """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(BaseModel):
     """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 +273,10 @@ 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.")
     integrity_hash: str = Field(
         ...,
         pattern=r"^[a-fA-F0-9]{64}$",

coreason_manifest/definitions/audit.py

@@ -1,7 +1,122 @@
-from pydantic import BaseModel
+import hashlib
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .message import ChatMessage
+
+
+class GenAITokenUsage(BaseModel):
+    """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)
+
+
+class GenAIOperation(BaseModel):
+    """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)
+
+
+class ReasoningTrace(BaseModel):
+    """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
+
+
+class AuditEventType(str, Enum):
+    SYSTEM_CHANGE = "system_change"
+    PREDICTION = "prediction"
+    GUARDRAIL_TRIGGER = "guardrail_trigger"
 
 
 class AuditLog(BaseModel):
-    """Audit log entry."""
+    """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()
+
 
-    pass
+# --- Backward Compatibility ---
+# Adapters or Aliases
+CognitiveStep = GenAIOperation
+TokenUsage = GenAITokenUsage