coreason-manifest 0.9.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, SimulationStep, SimulationTrace
-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",
     "SimulationStep",
+    "SimulationMetrics",
+    "StepType",
+    "AdversaryProfile",
+    "ChaosConfig",
+    "SimulationRequest",
     "AuditLog",
     "RecipeManifest",
 ]

coreason_manifest/definitions/__init__.py

@@ -1,4 +1,14 @@
-from .agent import AgentDefinition, AgentRuntimeConfig
+# 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,
@@ -26,6 +36,7 @@ from .events import (
 __all__ = [
     "AgentRuntimeConfig",
     "AgentDefinition",
+    "Persona",
     "GraphEvent",
     "NodeInit",
     "NodeStarted",

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
@@ -10,13 +19,12 @@ 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,
@@ -25,7 +33,8 @@ from pydantic import (
 )
 from typing_extensions import Annotated
 
-from coreason_manifest.definitions.topology import Edge, Node
+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
@@ -72,7 +81,7 @@ StrictUri = Annotated[
 ]
 
 
-class AgentMetadata(BaseModel):
+class AgentMetadata(CoReasonBaseModel):
     """Metadata for the Agent.
 
     Attributes:
@@ -93,7 +102,23 @@ class AgentMetadata(BaseModel):
     requires_auth: bool = Field(default=False, description="Whether the agent requires user authentication.")
 
 
-class AgentInterface(BaseModel):
+class Persona(CoReasonBaseModel):
+    """Definition of an Agent Persona.
+
+    Attributes:
+        name: Name of the persona.
+        description: Description of the persona.
+        directives: List of specific instructions or directives.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    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 AgentInterface(CoReasonBaseModel):
     """Interface definition for the Agent.
 
     Attributes:
@@ -108,21 +133,25 @@ class AgentInterface(BaseModel):
     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 AgentRuntimeConfig(BaseModel):
+class AgentRuntimeConfig(CoReasonBaseModel):
     """Configuration of the Agent execution.
 
     Attributes:
@@ -134,10 +163,36 @@ class AgentRuntimeConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    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.")
+    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).")
+
+        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
@@ -174,7 +229,7 @@ class ToolRiskLevel(str, Enum):
     CRITICAL = "critical"
 
 
-class ToolRequirement(BaseModel):
+class ToolRequirement(CoReasonBaseModel):
     """Requirement for an MCP tool.
 
     Attributes:
@@ -194,7 +249,25 @@ class ToolRequirement(BaseModel):
     risk_level: ToolRiskLevel = Field(..., description="The risk level of the tool.")
 
 
-class AgentDependencies(BaseModel):
+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:
@@ -204,13 +277,15 @@ class AgentDependencies(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    tools: List[ToolRequirement] = Field(default_factory=list, description="List of MCP tool requirements.")
+    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 PolicyConfig(BaseModel):
+class PolicyConfig(CoReasonBaseModel):
     """Governance policy configuration.
 
     Attributes:
@@ -234,7 +309,7 @@ class TraceLevel(str, Enum):
     NONE = "none"
 
 
-class ObservabilityConfig(BaseModel):
+class ObservabilityConfig(CoReasonBaseModel):
     """Observability configuration.
 
     Attributes:
@@ -250,7 +325,7 @@ class ObservabilityConfig(BaseModel):
     encryption_key_id: Optional[str] = Field(None, description="Optional ID of the key used for log encryption.")
 
 
-class AgentDefinition(BaseModel):
+class AgentDefinition(CoReasonBaseModel):
     """The Root Object for the CoReason Agent Manifest.
 
     Attributes:
@@ -277,6 +352,9 @@ class AgentDefinition(BaseModel):
     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,16 +1,29 @@
+# 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
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import ConfigDict, Field
+
+from coreason_manifest.definitions.base import CoReasonBaseModel
 
 from .message import ChatMessage
 
 
-class GenAITokenUsage(BaseModel):
+class GenAITokenUsage(CoReasonBaseModel):
     """Token consumption stats aligned with OTel conventions."""
 
     model_config = ConfigDict(extra="ignore")
@@ -25,8 +38,33 @@ class GenAITokenUsage(BaseModel):
     total_tokens: int = 0
     details: Dict[str, Any] = Field(default_factory=dict)
 
-
-class GenAIOperation(BaseModel):
+    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")
@@ -55,8 +93,26 @@ class GenAIOperation(BaseModel):
     error_type: Optional[str] = None
     metadata: Dict[str, Any] = Field(default_factory=dict)
 
-
-class ReasoningTrace(BaseModel):
+    @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.
@@ -83,6 +139,9 @@ class ReasoningTrace(BaseModel):
     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"
@@ -90,7 +149,7 @@ class AuditEventType(str, Enum):
     GUARDRAIL_TRIGGER = "guardrail_trigger"
 
 
-class AuditLog(BaseModel):
+class AuditLog(CoReasonBaseModel):
     """Tamper-evident legal record.
 
     IDs aligned with OpenTelemetry:

coreason_manifest/definitions/base.py

@@ -0,0 +1,47 @@
+# 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 typing import Any, Dict
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CoReasonBaseModel(BaseModel):
+    """Base model for all CoReason Pydantic models with enhanced serialization.
+
+    This base class addresses JSON serialization challenges in Pydantic v2 (e.g., UUID, datetime)
+    by providing standardized methods (`dump`, `to_json`) with optimal configuration.
+
+    For a detailed rationale, see `docs/coreason_base_model_rationale.md`.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def dump(self, **kwargs: Any) -> Dict[str, Any]:
+        """Serialize the model to a JSON-compatible dictionary.
+
+        Uses mode='json' to ensure types like UUID and datetime are serialized to strings.
+        Defaults to by_alias=True and exclude_none=True.
+        """
+        # Set defaults but allow overrides
+        kwargs.setdefault("mode", "json")
+        kwargs.setdefault("by_alias", True)
+        kwargs.setdefault("exclude_none", True)
+        return self.model_dump(**kwargs)
+
+    def to_json(self, **kwargs: Any) -> str:
+        """Serialize the model to a JSON string.
+
+        Defaults to by_alias=True and exclude_none=True.
+        """
+        # Set defaults but allow overrides
+        kwargs.setdefault("by_alias", True)
+        kwargs.setdefault("exclude_none", True)
+        return self.model_dump_json(**kwargs)