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

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.
@@ -9,28 +19,32 @@
 # Source Code: https://github.com/CoReason-AI/coreason_maco
 
 from enum import Enum
-from typing import Annotated, Any, Dict, List, Literal, Optional, Union
+from typing import Annotated, Any, Dict, List, Literal, Optional, Sequence, Union
+
+from pydantic import ConfigDict, Field, StringConstraints, model_validator
 
-from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+from coreason_manifest.definitions.base import CoReasonBaseModel
 
 
-class StateSchema(BaseModel):
-    """Defines the structure and persistence of the graph state.
+class StateDefinition(CoReasonBaseModel):
+    """Defines the internal state (memory) of the Recipe.
 
     Attributes:
-        data_schema: A JSON Schema or Pydantic definition describing the state structure.
-        persistence: Configuration for how state is checkpointed.
+        schema: JSON Schema of the keys available in the shared memory.
+        persistence: Configuration for state durability.
     """
 
     model_config = ConfigDict(extra="forbid")
 
-    data_schema: Dict[str, Any] = Field(
-        ..., description="A JSON Schema or Pydantic definition describing the state structure."
+    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."
     )
-    persistence: str = Field(..., description="Configuration for how state is checkpointed (e.g., 'memory', 'redis').")
 
 
-class CouncilConfig(BaseModel):
+class CouncilConfig(CoReasonBaseModel):
     """Configuration for 'Architectural Triangulation'.
 
     Attributes:
@@ -44,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:
@@ -64,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")
@@ -80,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):
@@ -88,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):
@@ -126,7 +176,7 @@ class DataMappingStrategy(str, Enum):
     LITERAL = "literal"
 
 
-class DataMapping(BaseModel):
+class DataMapping(CoReasonBaseModel):
     """Defines how to transform data between parent and child."""
 
     model_config = ConfigDict(extra="forbid")
@@ -178,7 +228,7 @@ Node = Annotated[
 ]
 
 
-class Edge(BaseModel):
+class Edge(CoReasonBaseModel):
     """Represents a connection between two nodes.
 
     Attributes:
@@ -203,7 +253,7 @@ RouterRef = Annotated[
 ]
 
 
-class RouterExpression(BaseModel):
+class RouterExpression(CoReasonBaseModel):
     """A structured expression for routing logic (e.g., CEL or JSONLogic)."""
 
     model_config = ConfigDict(extra="forbid")
@@ -218,7 +268,7 @@ RouterDefinition = Annotated[
 ]
 
 
-class ConditionalEdge(BaseModel):
+class ConditionalEdge(CoReasonBaseModel):
     """Represents a dynamic routing connection from one node to multiple potential targets.
 
     Attributes:
@@ -236,7 +286,37 @@ class ConditionalEdge(BaseModel):
     mapping: Dict[str, str] = Field(..., description="Map of router output values to target node IDs.")
 
 
-class GraphTopology(BaseModel):
+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:
@@ -249,7 +329,13 @@ class GraphTopology(BaseModel):
 
     nodes: List[Node] = Field(..., description="List of nodes in the graph.")
     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.")
+    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.
@@ -8,15 +18,16 @@
 #
 # Source Code: https://github.com/CoReason-AI/coreason_maco
 
-from typing import Any, Dict, Literal, Optional
+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(BaseModel):
+class RecipeInterface(CoReasonBaseModel):
     """Defines the input/output contract for a Recipe.
 
     Attributes:
@@ -32,25 +43,7 @@ class RecipeInterface(BaseModel):
     )
 
 
-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):
+class RecipeManifest(CoReasonBaseModel):
     """The executable specification for the MACO engine.
 
     Attributes:
@@ -62,6 +55,8 @@ class RecipeManifest(BaseModel):
         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")
@@ -74,3 +69,16 @@ class RecipeManifest(BaseModel):
     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

coreason_manifest/schemas/agent.schema.json

@@ -7,7 +7,14 @@
         "tools": {
           "description": "List of MCP tool requirements.",
           "items": {
-            "$ref": "#/$defs/ToolRequirement"
+            "anyOf": [
+              {
+                "$ref": "#/$defs/ToolRequirement"
+              },
+              {
+                "$ref": "#/$defs/InlineToolDefinition"
+              }
+            ]
           },
           "title": "Tools",
           "type": "array"
@@ -109,7 +116,7 @@
     },
     "AgentNode": {
       "additionalProperties": false,
-      "description": "A node that calls a specific atomic agent.\n\nAttributes:\n    type: The type of the node (must be 'agent').\n    agent_name: The name of the atomic agent to call.",
+      "description": "A node that calls a specific atomic agent.\n\nAttributes:\n    type: The type of the node (must be 'agent').\n    agent_name: The name of the atomic agent to call.\n    system_prompt: Overrides the registry default prompt. Required for ad-hoc/optimized agents.\n    config: Runtime-specific configuration (e.g., model parameters, temperature). Merged with registry defaults.\n    overrides: Runtime overrides for the agent (e.g., temperature, prompt_template_vars).",
       "properties": {
         "id": {
           "description": "Unique identifier for the node.",
@@ -140,6 +147,12 @@
           "default": null,
           "description": "Visual metadata for the UI."
         },
+        "metadata": {
+          "additionalProperties": true,
+          "description": "Generic metadata for operational context (e.g. cost tracking, SLAs).",
+          "title": "Metadata",
+          "type": "object"
+        },
         "type": {
           "const": "agent",
           "default": "agent",
@@ -151,6 +164,47 @@
           "description": "The name of the atomic agent to call.",
           "title": "Agent Name",
           "type": "string"
+        },
+        "system_prompt": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Overrides the registry default prompt. Required for ad-hoc/optimized agents.",
+          "title": "System Prompt"
+        },
+        "config": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Runtime-specific configuration (e.g., model parameters, temperature). Merged with registry defaults.",
+          "title": "Config"
+        },
+        "overrides": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Runtime overrides for the agent (e.g., temperature, prompt_template_vars).",
+          "title": "Overrides"
         }
       },
       "required": [
@@ -208,19 +262,37 @@
           "type": "array"
         },
         "entry_point": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "The ID of the starting node.",
-          "title": "Entry Point",
-          "type": "string"
+          "title": "Entry Point"
         },
         "model_config": {
           "$ref": "#/$defs/ModelConfig",
           "description": "Specific LLM parameters."
+        },
+        "system_prompt": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The global system prompt/instruction for the agent.",
+          "title": "System Prompt"
         }
       },
       "required": [
-        "nodes",
-        "edges",
-        "entry_point",
         "model_config"
       ],
       "title": "AgentRuntimeConfig",
@@ -350,6 +422,12 @@
           "default": null,
           "description": "Visual metadata for the UI."
         },
+        "metadata": {
+          "additionalProperties": true,
+          "description": "Generic metadata for operational context (e.g. cost tracking, SLAs).",
+          "title": "Metadata",
+          "type": "object"
+        },
         "type": {
           "const": "human",
           "default": "human",
@@ -377,6 +455,42 @@
       "title": "HumanNode",
       "type": "object"
     },
+    "InlineToolDefinition": {
+      "additionalProperties": false,
+      "description": "Definition of an inline tool.\n\nAttributes:\n    name: Name of the tool.\n    description: Description of the tool.\n    parameters: JSON Schema of parameters.\n    type: The type of the tool (must be 'function').",
+      "properties": {
+        "name": {
+          "description": "Name of the tool.",
+          "title": "Name",
+          "type": "string"
+        },
+        "description": {
+          "description": "Description of the tool.",
+          "title": "Description",
+          "type": "string"
+        },
+        "parameters": {
+          "additionalProperties": true,
+          "description": "JSON Schema of parameters.",
+          "title": "Parameters",
+          "type": "object"
+        },
+        "type": {
+          "const": "function",
+          "default": "function",
+          "description": "The type of the tool (must be 'function').",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "description",
+        "parameters"
+      ],
+      "title": "InlineToolDefinition",
+      "type": "object"
+    },
     "LogicNode": {
       "additionalProperties": false,
       "description": "A node that executes pure Python logic.\n\nAttributes:\n    type: The type of the node (must be 'logic').\n    code: The Python logic code to execute.",
@@ -410,6 +524,12 @@
           "default": null,
           "description": "Visual metadata for the UI."
         },
+        "metadata": {
+          "additionalProperties": true,
+          "description": "Generic metadata for operational context (e.g. cost tracking, SLAs).",
+          "title": "Metadata",
+          "type": "object"
+        },
         "type": {
           "const": "logic",
           "default": "logic",
@@ -463,6 +583,12 @@
           "default": null,
           "description": "Visual metadata for the UI."
         },
+        "metadata": {
+          "additionalProperties": true,
+          "description": "Generic metadata for operational context (e.g. cost tracking, SLAs).",
+          "title": "Metadata",
+          "type": "object"
+        },
         "type": {
           "const": "map",
           "default": "map",
@@ -497,7 +623,7 @@
     },
     "ModelConfig": {
       "additionalProperties": false,
-      "description": "LLM Configuration parameters.\n\nAttributes:\n    model: The LLM model identifier.\n    temperature: Temperature for generation.",
+      "description": "LLM Configuration parameters.\n\nAttributes:\n    model: The LLM model identifier.\n    temperature: Temperature for generation.\n    system_prompt: The default system prompt/persona for the agent.\n    persona: The full persona definition (name, description, directives).",
       "properties": {
         "model": {
           "description": "The LLM model identifier.",
@@ -510,6 +636,31 @@
           "minimum": 0.0,
           "title": "Temperature",
           "type": "number"
+        },
+        "system_prompt": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The default system prompt/persona for the agent.",
+          "title": "System Prompt"
+        },
+        "persona": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Persona"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The full persona definition (name, description, directives)."
         }
       },
       "required": [
@@ -550,6 +701,37 @@
       "title": "ObservabilityConfig",
       "type": "object"
     },
+    "Persona": {
+      "additionalProperties": false,
+      "description": "Definition of an Agent Persona.\n\nAttributes:\n    name: Name of the persona.\n    description: Description of the persona.\n    directives: List of specific instructions or directives.",
+      "properties": {
+        "name": {
+          "description": "Name of the persona.",
+          "title": "Name",
+          "type": "string"
+        },
+        "description": {
+          "description": "Description of the persona.",
+          "title": "Description",
+          "type": "string"
+        },
+        "directives": {
+          "description": "List of specific instructions or directives.",
+          "items": {
+            "type": "string"
+          },
+          "title": "Directives",
+          "type": "array"
+        }
+      },
+      "required": [
+        "name",
+        "description",
+        "directives"
+      ],
+      "title": "Persona",
+      "type": "object"
+    },
     "PolicyConfig": {
       "additionalProperties": false,
       "description": "Governance policy configuration.\n\nAttributes:\n    budget_caps: Dictionary defining budget limits (e.g., {\"total_cost\": 10.0, \"total_tokens\": 1000}).\n    human_in_the_loop: List of Node IDs that require human approval.\n    allowed_domains: List of allowed domains for external access.",
@@ -615,6 +797,12 @@
           "default": null,
           "description": "Visual metadata for the UI."
         },
+        "metadata": {
+          "additionalProperties": true,
+          "description": "Generic metadata for operational context (e.g. cost tracking, SLAs).",
+          "title": "Metadata",
+          "type": "object"
+        },
         "type": {
           "const": "recipe",
           "default": "recipe",
@@ -830,6 +1018,20 @@
       "default": null,
       "description": "Observability configuration."
     },
+    "custom_metadata": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Container for arbitrary metadata extensions without breaking validation.",
+      "title": "Custom Metadata"
+    },
     "integrity_hash": {
       "description": "SHA256 hash of the source code.",
       "pattern": "^[a-fA-F0-9]{64}$",