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

coreason_manifest/definitions/simulation.py

@@ -1,19 +1,79 @@
-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
 
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID
 
-class SimulationScenario(BaseModel):
+from pydantic import Field
+
+from coreason_manifest.definitions.base import CoReasonBaseModel
+
+
+class StepType(str, Enum):
+    """Type of the simulation step."""
+
+    INTERACTION = "interaction"  # Normal User/Agent turn
+    SYSTEM_EVENT = "system_event"  # Chaos injection, error, or info
+
+
+class ValidationLogic(str, Enum):
+    """Logic used to validate the scenario outcome."""
+
+    EXACT_MATCH = "exact_match"
+    FUZZY = "fuzzy"
+    CODE_EVAL = "code_eval"
+
+
+class SimulationScenario(CoReasonBaseModel):
     """Definition of a simulation scenario."""
 
-    pass
+    id: str = Field(..., description="Unique identifier for the scenario.")
+    name: str = Field(..., description="Name of the scenario.")
+    objective: str = Field(..., description="The prompt/task instructions.")
+    difficulty: int = Field(..., description="Difficulty level (1-3, aligning with GAIA levels).", ge=1, le=3)
+    expected_outcome: Any = Field(..., description="The ground truth for validation.")
+    validation_logic: ValidationLogic = Field(..., description="Logic used to validate the outcome.")
 
 
-class SimulationTrace(BaseModel):
-    """Trace of a simulation execution."""
+class SimulationStep(CoReasonBaseModel):
+    """The atomic unit of execution in a simulation."""
+
+    step_id: UUID = Field(..., description="Atomic unit of execution ID.")
+    timestamp: datetime = Field(..., description="Execution timestamp.")
+    type: StepType = Field(default=StepType.INTERACTION, description="Type of the step.")
+    node_id: str = Field(..., description="The graph node executed.")
+    inputs: Dict[str, Any] = Field(..., description="Snapshot of entry state.")
+    thought: Optional[str] = Field(None, description="The Chain-of-Thought reasoning.")
+    action: Optional[Dict[str, Any]] = Field(None, description="Tool calls or API requests.")
+    observation: Optional[Dict[str, Any]] = Field(None, description="Tool outputs.")
+    snapshot: Dict[str, Any] = Field(
+        default_factory=dict, description="Full copy of the graph state at the completion of this step."
+    )
 
-    pass
 
+class SimulationMetrics(CoReasonBaseModel):
+    """Metrics gathered during simulation."""
 
-class SimulationTurn(BaseModel):
-    """A single turn in a simulation."""
+    turn_count: int
+    total_tokens: Optional[int] = None
+    cost_usd: Optional[float] = None
+    duration_ms: Optional[float] = None
+
+
+class SimulationTrace(CoReasonBaseModel):
+    """Trace of a simulation execution."""
 
-    pass
+    trace_id: UUID = Field(..., description="Unique trace identifier.")
+    agent_version: str = Field(..., description="Agent SemVer version.")
+    steps: List[SimulationStep] = Field(..., description="List of execution steps.")
+    outcome: Dict[str, Any] = Field(..., description="Final result.")
+    metrics: SimulationMetrics = Field(..., description="Execution metrics (e.g., token usage, cost).")

coreason_manifest/definitions/simulation_config.py

@@ -0,0 +1,46 @@
+# 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 Optional
+
+from pydantic import Field
+
+from coreason_manifest.definitions.agent import Persona
+from coreason_manifest.definitions.base import CoReasonBaseModel
+from coreason_manifest.definitions.simulation import SimulationScenario
+
+
+class AdversaryProfile(CoReasonBaseModel):
+    name: str
+    goal: str
+    strategy_model: str  # e.g., "claude-3-opus"
+    attack_model: str  # e.g., "llama-3-uncensored"
+    persona: Optional[Persona] = Field(None, description="The full persona definition (name, description, directives).")
+    # Potential future field: 'system_prompt_override'
+
+
+class ChaosConfig(CoReasonBaseModel):
+    latency_ms: int = Field(default=0, ge=0)
+    error_rate: float = Field(default=0.0, ge=0.0, le=1.0)
+    noise_rate: float = Field(default=0.0, ge=0.0, le=1.0)
+    token_throttle: bool = False
+    exception_type: str = "RuntimeError"
+
+
+class SimulationRequest(CoReasonBaseModel):
+    """
+    Standard payload for triggering a simulation.
+    This would replace the local 'SimulationRequest' in the Simulator.
+    """
+
+    scenario: SimulationScenario
+    profile: AdversaryProfile
+    chaos_config: ChaosConfig = Field(default_factory=ChaosConfig)

coreason_manifest/definitions/topology.py

@@ -1,3 +1,13 @@
+# 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
+
 # Copyright (c) 2025 CoReason, Inc.
 #
 # This software is proprietary and dual-licensed.
@@ -8,12 +18,33 @@
 #
 # Source Code: https://github.com/CoReason-AI/coreason_maco
 
-from typing import Annotated, List, Literal, Optional, Union
+from enum import Enum
+from typing import Annotated, Any, Dict, List, Literal, Optional, Sequence, Union
+
+from pydantic import ConfigDict, Field, StringConstraints, model_validator
+
+from coreason_manifest.definitions.base import CoReasonBaseModel
 
-from pydantic import BaseModel, ConfigDict, Field
 
+class StateDefinition(CoReasonBaseModel):
+    """Defines the internal state (memory) of the Recipe.
 
-class CouncilConfig(BaseModel):
+    Attributes:
+        schema: JSON Schema of the keys available in the shared memory.
+        persistence: Configuration for state durability.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_: Dict[str, Any] = Field(
+        ..., alias="schema", description="JSON Schema of the keys available in the shared memory."
+    )
+    persistence: Literal["ephemeral", "persistent"] = Field(
+        default="ephemeral", description="Configuration for state durability."
+    )
+
+
+class CouncilConfig(CoReasonBaseModel):
     """Configuration for 'Architectural Triangulation'.
 
     Attributes:
@@ -27,7 +58,7 @@ class CouncilConfig(BaseModel):
     voters: List[str] = Field(..., description="List of agents or models that vote.")
 
 
-class VisualMetadata(BaseModel):
+class VisualMetadata(CoReasonBaseModel):
     """Data explicitly for the UI.
 
     Attributes:
@@ -47,13 +78,28 @@ class VisualMetadata(BaseModel):
     animation_style: Optional[str] = Field(None, description="The animation style for the node.")
 
 
-class BaseNode(BaseModel):
+class RuntimeVisualMetadata(VisualMetadata):
+    """Visual metadata with runtime extensions.
+
+    Attributes:
+        color: Color override for the node (e.g., '#00FF00').
+        progress: Progress indicator (e.g., '0.5' or '50%').
+        animation: Animation override (e.g., 'pulse').
+    """
+
+    color: Optional[str] = Field(None, description="Color override for the node.")
+    progress: Optional[str] = Field(None, description="Progress indicator.")
+    animation: Optional[str] = Field(None, description="Animation override.")
+
+
+class BaseNode(CoReasonBaseModel):
     """Base model for all node types.
 
     Attributes:
         id: Unique identifier for the node.
         council_config: Optional configuration for architectural triangulation.
         visual: Visual metadata for the UI.
+        metadata: Generic metadata for operational context (e.g. cost tracking, SLAs).
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -63,6 +109,10 @@ class BaseNode(BaseModel):
         None, description="Optional configuration for architectural triangulation."
     )
     visual: Optional[VisualMetadata] = Field(None, description="Visual metadata for the UI.")
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Generic metadata for operational context (e.g. cost tracking, SLAs).",
+    )
 
 
 class AgentNode(BaseNode):
@@ -71,10 +121,27 @@ class AgentNode(BaseNode):
     Attributes:
         type: The type of the node (must be 'agent').
         agent_name: The name of the atomic agent to call.
+        system_prompt: Overrides the registry default prompt. Required for ad-hoc/optimized agents.
+        config: Runtime-specific configuration (e.g., model parameters, temperature). Merged with registry defaults.
+        overrides: Runtime overrides for the agent (e.g., temperature, prompt_template_vars).
     """
 
     type: Literal["agent"] = Field("agent", description="Discriminator for AgentNode.")
     agent_name: str = Field(..., description="The name of the atomic agent to call.")
+    system_prompt: Optional[str] = Field(
+        default=None,
+        description="Overrides the registry default prompt. Required for ad-hoc/optimized agents.",
+    )
+    config: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Runtime-specific configuration (e.g., model parameters, temperature). Merged with registry defaults."
+        ),
+    )
+    overrides: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Runtime overrides for the agent (e.g., temperature, prompt_template_vars).",
+    )
 
 
 class HumanNode(BaseNode):
@@ -101,13 +168,67 @@ class LogicNode(BaseNode):
     code: str = Field(..., description="The Python logic code to execute.")
 
 
+class DataMappingStrategy(str, Enum):
+    """Strategy for mapping data."""
+
+    DIRECT = "direct"
+    JSONPATH = "jsonpath"
+    LITERAL = "literal"
+
+
+class DataMapping(CoReasonBaseModel):
+    """Defines how to transform data between parent and child."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: str = Field(..., description="The path/key source.")
+    strategy: DataMappingStrategy = Field(default=DataMappingStrategy.DIRECT, description="The mapping strategy.")
+
+
+class RecipeNode(BaseNode):
+    """A node that executes another Recipe as a sub-graph.
+
+    Attributes:
+        type: The type of the node (must be 'recipe').
+        recipe_id: The ID of the recipe to execute.
+        input_mapping: How parent state maps to child inputs (parent_key -> child_key).
+        output_mapping: How child result maps back to parent state (child_key -> parent_key).
+    """
+
+    type: Literal["recipe"] = Field("recipe", description="Discriminator for RecipeNode.")
+    recipe_id: str = Field(..., description="The ID of the recipe to execute.")
+    input_mapping: Dict[str, Union[str, DataMapping]] = Field(
+        ..., description="Mapping of parent state keys to child input keys."
+    )
+    output_mapping: Dict[str, Union[str, DataMapping]] = Field(
+        ..., description="Mapping of child output keys to parent state keys."
+    )
+
+
+class MapNode(BaseNode):
+    """A node that spawns multiple parallel executions of a sub-branch.
+
+    Attributes:
+        type: The type of the node (must be 'map').
+        items_path: Dot-notation path to the list in the state.
+        processor_node_id: The node (or subgraph) to run for each item.
+        concurrency_limit: Max parallel executions.
+    """
+
+    type: Literal["map"] = Field("map", description="Discriminator for MapNode.")
+    items_path: str = Field(..., description="Dot-notation path to the list in the state.")
+    processor_node_id: str = Field(..., description="The node (or subgraph) to run for each item.")
+    concurrency_limit: int = Field(..., description="Max parallel executions.")
+
+
 # Discriminated Union for polymorphism
 Node = Annotated[
-    Union[AgentNode, HumanNode, LogicNode], Field(discriminator="type", description="Polymorphic node definition.")
+    Union[AgentNode, HumanNode, LogicNode, RecipeNode, MapNode],
+    Field(discriminator="type", description="Polymorphic node definition."),
 ]
 
 
-class Edge(BaseModel):
+class Edge(CoReasonBaseModel):
     """Represents a connection between two nodes.
 
     Attributes:
@@ -123,18 +244,98 @@ class Edge(BaseModel):
     condition: Optional[str] = Field(None, description="Optional Python expression for conditional branching.")
 
 
-class GraphTopology(BaseModel):
+RouterRef = Annotated[
+    str,
+    StringConstraints(
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$",
+        strip_whitespace=True,
+    ),
+]
+
+
+class RouterExpression(CoReasonBaseModel):
+    """A structured expression for routing logic (e.g., CEL or JSONLogic)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    operator: str = Field(..., description="The operator (e.g., 'eq', 'gt').")
+    args: List[Any] = Field(..., description="Arguments for the expression.")
+
+
+RouterDefinition = Annotated[
+    Union[RouterRef, RouterExpression],
+    Field(description="A reference to a python function or a logic expression."),
+]
+
+
+class ConditionalEdge(CoReasonBaseModel):
+    """Represents a dynamic routing connection from one node to multiple potential targets.
+
+    Attributes:
+        source_node_id: The ID of the source node.
+        router_logic: A reference to a python function or a logic expression that returns the next node ID.
+        mapping: A dictionary mapping the router's output (e.g., "approve", "reject") to target Node IDs.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_node_id: str = Field(..., description="The ID of the source node.")
+    router_logic: RouterDefinition = Field(
+        ..., description="A reference to a python function or logic expression that determines the path."
+    )
+    mapping: Dict[str, str] = Field(..., description="Map of router output values to target node IDs.")
+
+
+def validate_edge_integrity(
+    nodes: Sequence[Node],
+    edges: Sequence[Union[Edge, ConditionalEdge]],
+) -> None:
+    """Ensures that all edges point to valid nodes.
+
+    Args:
+        nodes: List of nodes in the graph.
+        edges: List of edges connecting the nodes.
+
+    Raises:
+        ValueError: If an edge points to a non-existent node.
+    """
+    node_ids = {node.id for node in nodes}
+
+    for edge in edges:
+        if edge.source_node_id not in node_ids:
+            raise ValueError(f"Edge source node '{edge.source_node_id}' not found in nodes.")
+
+        # ConditionalEdge mapping targets
+        if isinstance(edge, ConditionalEdge):
+            for target_id in edge.mapping.values():
+                if target_id not in node_ids:
+                    raise ValueError(f"ConditionalEdge target node '{target_id}' not found in nodes.")
+        else:
+            # Regular Edge
+            if edge.target_node_id not in node_ids:
+                raise ValueError(f"Edge target node '{edge.target_node_id}' not found in nodes.")
+
+
+class GraphTopology(CoReasonBaseModel):
     """The topology definition of the recipe.
 
     Attributes:
         nodes: List of nodes in the graph.
         edges: List of edges connecting the nodes.
+        state_schema: Optional schema definition for the graph state.
     """
 
     model_config = ConfigDict(extra="forbid")
 
     nodes: List[Node] = Field(..., description="List of nodes in the graph.")
-    edges: List[Edge] = Field(..., description="List of edges connecting the nodes.")
+    edges: List[Union[Edge, ConditionalEdge]] = Field(..., description="List of edges connecting the nodes.")
+    state_schema: Optional[StateDefinition] = Field(default=None, description="Schema definition for the graph state.")
+
+    @model_validator(mode="after")
+    def validate_graph_integrity(self) -> "GraphTopology":
+        """Ensures that all edges point to valid nodes."""
+        validate_edge_integrity(self.nodes, self.edges)
+        return self
 
 
 Topology = GraphTopology

coreason_manifest/recipes.py

@@ -1,3 +1,13 @@
+# 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
+
 # Copyright (c) 2025 CoReason, Inc.
 #
 # This software is proprietary and dual-licensed.
@@ -10,13 +20,30 @@
 
 from typing import Any, Dict, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import ConfigDict, Field
 
 from .definitions.agent import VersionStr
-from .definitions.topology import GraphTopology
+from .definitions.base import CoReasonBaseModel
+from .definitions.topology import GraphTopology, StateDefinition
+
+
+class RecipeInterface(CoReasonBaseModel):
+    """Defines the input/output contract for a Recipe.
+
+    Attributes:
+        inputs: JSON Schema defining valid entry arguments.
+        outputs: JSON Schema defining the guaranteed structure of the final result.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    inputs: Dict[str, Any] = Field(..., description="JSON Schema defining valid entry arguments.")
+    outputs: Dict[str, Any] = Field(
+        ..., description="JSON Schema defining the guaranteed structure of the final result."
+    )
 
 
-class RecipeManifest(BaseModel):
+class RecipeManifest(CoReasonBaseModel):
     """The executable specification for the MACO engine.
 
     Attributes:
@@ -24,8 +51,12 @@ class RecipeManifest(BaseModel):
         version: Version of the recipe.
         name: Human-readable name of the recipe.
         description: Detailed description of the recipe.
-        inputs: Schema defining global variables this recipe accepts.
-        graph: The topology definition of the workflow.
+        interface: Defines the input/output contract for the Recipe.
+        state: Defines the internal state (memory) of the Recipe.
+        parameters: Dictionary of build-time constants.
+        topology: The topology definition of the workflow.
+        integrity_hash: SHA256 hash of the canonical JSON representation of the topology.
+        metadata: Container for design-time data.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -34,5 +65,20 @@ class RecipeManifest(BaseModel):
     version: VersionStr = Field(..., description="Version of the recipe.")
     name: str = Field(..., description="Human-readable name of the recipe.")
     description: Optional[str] = Field(None, description="Detailed description of the recipe.")
-    inputs: Dict[str, Any] = Field(..., description="Schema defining global variables this recipe accepts.")
-    graph: GraphTopology = Field(..., description="The topology definition of the workflow.")
+    interface: RecipeInterface = Field(..., description="Defines the input/output contract for the Recipe.")
+    state: StateDefinition = Field(..., description="Defines the internal state (memory) of the Recipe.")
+    parameters: Dict[str, Any] = Field(..., description="Dictionary of build-time constants.")
+    topology: GraphTopology = Field(..., description="The topology definition of the workflow.")
+    integrity_hash: Optional[str] = Field(
+        default=None,
+        description=(
+            "SHA256 hash of the canonical JSON representation of the topology. "
+            "Enforced by Builder, verified by Runtime."
+        ),
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Container for design-time data (UI coordinates, resolution logs, draft status) to support re-hydration."
+        ),
+    )

coreason_manifest/schemas/__init__.py

@@ -1 +1,9 @@
-# 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