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

coreason_manifest/definitions/topology.py

@@ -8,9 +8,26 @@
 #
 # 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, Union
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+
+class StateSchema(BaseModel):
+    """Defines the structure and persistence of the graph state.
+
+    Attributes:
+        data_schema: A JSON Schema or Pydantic definition describing the state structure.
+        persistence: Configuration for how state is checkpointed.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    data_schema: Dict[str, Any] = Field(
+        ..., description="A JSON Schema or Pydantic definition describing the state structure."
+    )
+    persistence: str = Field(..., description="Configuration for how state is checkpointed (e.g., 'memory', 'redis').")
 
 
 class CouncilConfig(BaseModel):
@@ -101,9 +118,63 @@ 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(BaseModel):
+    """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."),
 ]
 
 
@@ -123,18 +194,62 @@ class Edge(BaseModel):
     condition: Optional[str] = Field(None, description="Optional Python expression for conditional branching.")
 
 
+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(BaseModel):
+    """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(BaseModel):
+    """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.")
+
+
 class GraphTopology(BaseModel):
     """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[StateSchema] = Field(None, description="Schema definition for the graph state.")
 
 
 Topology = GraphTopology

coreason_manifest/recipes.py

@@ -8,7 +8,7 @@
 #
 # Source Code: https://github.com/CoReason-AI/coreason_maco
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Literal, Optional
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -16,6 +16,40 @@ from .definitions.agent import VersionStr
 from .definitions.topology import GraphTopology
 
 
+class RecipeInterface(BaseModel):
+    """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 StateDefinition(BaseModel):
+    """Defines the internal state (memory) of the Recipe.
+
+    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 RecipeManifest(BaseModel):
     """The executable specification for the MACO engine.
 
@@ -24,8 +58,10 @@ 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.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -34,5 +70,7 @@ 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.")