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

coreason_manifest/utils/logger.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.

coreason_manifest/v2/__init__.py

@@ -0,0 +1 @@
+# Coreason Manifest V2

coreason_manifest/v2/governance.py

@@ -0,0 +1,144 @@
+# 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
+
+"""Governance logic for V2 Manifests."""
+
+from typing import List
+from urllib.parse import urlparse
+
+from coreason_manifest.common import ToolRiskLevel
+from coreason_manifest.governance import (
+    ComplianceReport,
+    ComplianceViolation,
+    GovernanceConfig,
+)
+from coreason_manifest.v2.spec.definitions import (
+    LogicStep,
+    ManifestV2,
+    SwitchStep,
+    ToolDefinition,
+)
+
+
+def _risk_score(level: ToolRiskLevel) -> int:
+    """Convert risk level to integer score for comparison."""
+    if level == ToolRiskLevel.SAFE:
+        return 0
+    if level == ToolRiskLevel.STANDARD:
+        return 1
+    if level == ToolRiskLevel.CRITICAL:
+        return 2
+    return 3  # Unknown is highest risk
+
+
+def check_compliance_v2(manifest: ManifestV2, config: GovernanceConfig) -> ComplianceReport:
+    """Enforce policy on V2 Manifest before compilation.
+
+    Args:
+        manifest: The V2 manifest to check.
+        config: The governance policy configuration.
+
+    Returns:
+        A ComplianceReport detailing violations.
+    """
+    violations: List[ComplianceViolation] = []
+
+    # 1. Check Tools in Definitions
+    for _, definition in manifest.definitions.items():
+        if isinstance(definition, ToolDefinition):
+            # Check Risk Level
+            if config.max_risk_level:
+                tool_score = _risk_score(definition.risk_level)
+                max_score = _risk_score(config.max_risk_level)
+                if tool_score > max_score:
+                    violations.append(
+                        ComplianceViolation(
+                            rule="risk_level_restriction",
+                            message=(
+                                f"Tool '{definition.name}' risk level '{definition.risk_level.value}' "
+                                f"exceeds allowed maximum '{config.max_risk_level.value}'."
+                            ),
+                            component_id=definition.id,
+                        )
+                    )
+
+            # Check Allowed Domains
+            if config.allowed_domains is not None:
+                try:
+                    parsed_uri = urlparse(str(definition.uri))
+                    hostname = parsed_uri.hostname
+
+                    if not hostname:
+                        violations.append(
+                            ComplianceViolation(
+                                rule="domain_restriction",
+                                message=(f"Tool '{definition.name}' URI '{definition.uri}' has no hostname."),
+                                component_id=definition.id,
+                            )
+                        )
+                    else:
+                        # Normalize hostname
+                        hostname = hostname.lower()
+                        if hostname.endswith("."):
+                            hostname = hostname[:-1]
+
+                        # Prepare allowed set
+                        if config.strict_url_validation:
+                            allowed_set = {d.lower() for d in config.allowed_domains if d}
+                        else:
+                            allowed_set = set(config.allowed_domains)
+
+                        if hostname not in allowed_set:
+                            violations.append(
+                                ComplianceViolation(
+                                    rule="domain_restriction",
+                                    message=(
+                                        f"Tool '{definition.name}' URI host '{hostname}' "
+                                        f"is not in allowed domains: {config.allowed_domains}"
+                                    ),
+                                    component_id=definition.id,
+                                )
+                            )
+                except Exception as e:
+                    violations.append(
+                        ComplianceViolation(
+                            rule="domain_restriction",
+                            message=f"Failed to parse tool URI '{definition.uri}': {e}",
+                            component_id=definition.id,
+                        )
+                    )
+
+    # 2. Check Workflow Steps for Custom Logic
+    if not config.allow_custom_logic:
+        for step_id, step in manifest.workflow.steps.items():
+            if isinstance(step, LogicStep):
+                violations.append(
+                    ComplianceViolation(
+                        rule="custom_logic_restriction",
+                        message="LogicStep containing custom code is not allowed by policy.",
+                        component_id=step_id,
+                    )
+                )
+            elif isinstance(step, SwitchStep):
+                # Flag complex conditions (function calls, imports, internals) as custom logic.
+                for condition in step.cases.keys():
+                    if "(" in condition or "import " in condition or "__" in condition:
+                        violations.append(
+                            ComplianceViolation(
+                                rule="custom_logic_restriction",
+                                message=(
+                                    f"SwitchStep '{step_id}' contains complex condition '{condition}' "
+                                    "which is flagged as custom logic."
+                                ),
+                                component_id=step_id,
+                            )
+                        )
+
+    return ComplianceReport(passed=len(violations) == 0, violations=violations)

coreason_manifest/v2/io.py

@@ -0,0 +1,132 @@
+# 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
+
+"""I/O module for loading and dumping V2 Manifests."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Set, Union
+
+import yaml
+
+from coreason_manifest.v2.resolver import ReferenceResolver
+from coreason_manifest.v2.spec.definitions import ManifestV2
+
+
+def _load_recursive(path: Path, resolver: ReferenceResolver, visited_paths: Set[Path]) -> Dict[str, Any]:
+    """
+    Recursively load YAML data, resolving $ref in definitions.
+
+    Handles cycle detection to prevent infinite recursion and uses the
+    ReferenceResolver to ensure secure path resolution.
+    """
+    if path in visited_paths:
+        raise RecursionError(f"Circular dependency detected: {path}")
+
+    visited_paths.add(path)
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML in {path}: {e}") from e
+
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected a dictionary in {path}, got {type(data).__name__}")
+
+    # Resolve references in definitions
+    definitions = data.get("definitions", {})
+    if definitions:
+        for key, value in definitions.items():
+            if isinstance(value, dict) and "$ref" in value:
+                ref_path_str = value["$ref"]
+                # Resolve the path
+                abs_path = resolver.resolve(path, ref_path_str)
+
+                # Recursively load
+                loaded_obj = _load_recursive(abs_path, resolver, visited_paths)
+
+                # Merge Strategy:
+                # Replace the $ref dict with the loaded data.
+                definitions[key] = loaded_obj
+
+    visited_paths.remove(path)
+    return data
+
+
+def load_from_yaml(
+    path: Union[str, Path],
+    root_dir: Optional[Union[str, Path]] = None,
+    recursive: bool = True,
+) -> ManifestV2:
+    """Load a V2 manifest from a YAML file.
+
+    Args:
+        path: Path to the YAML file.
+        root_dir: The allowed root directory for references. Defaults to path's parent.
+        recursive: Whether to resolve $ref recursively.
+
+    Returns:
+        The validated ManifestV2 object.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValidationError: If the manifest is invalid.
+        yaml.YAMLError: If the YAML is invalid.
+        RecursionError: If a cyclic dependency is detected.
+        ValueError: If a security violation occurs or YAML is invalid.
+    """
+    p = Path(path).resolve()
+    if not p.exists():
+        raise FileNotFoundError(f"Manifest file not found: {path}")
+
+    if root_dir is None:
+        root_dir = p.parent
+
+    if recursive:
+        resolver = ReferenceResolver(root_dir)
+        visited_paths: Set[Path] = set()
+        data = _load_recursive(p, resolver, visited_paths)
+    else:
+        with p.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+    return ManifestV2.model_validate(data)
+
+
+def dump_to_yaml(manifest: ManifestV2) -> str:
+    """Dump a V2 manifest to a YAML string.
+
+    Ensures that apiVersion, kind, and metadata appear at the top.
+
+    Args:
+        manifest: The ManifestV2 object to dump.
+
+    Returns:
+        The YAML string representation.
+    """
+    # Serialize to dict, using aliases (e.g., x-design) and excluding None
+    data = manifest.model_dump(by_alias=True, exclude_none=True)
+
+    # Reorder keys to ensure human readability
+    # Priority keys: apiVersion, kind, metadata
+    ordered_keys = ["apiVersion", "kind", "metadata"]
+    ordered_data = {}
+
+    # 1. Add priority keys
+    for key in ordered_keys:
+        if key in data:
+            ordered_data[key] = data.pop(key)
+
+    # 2. Add remaining keys
+    ordered_data.update(data)
+
+    # Dump using PyYAML, preserving key order (sort_keys=False)
+    # allow_unicode=True ensures proper string representation
+    return yaml.dump(ordered_data, sort_keys=False, allow_unicode=True)

coreason_manifest/v2/resolver.py

@@ -0,0 +1,67 @@
+# 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
+
+"""Resolver module for secure file reference handling."""
+
+from pathlib import Path
+from typing import Union
+
+
+class ReferenceResolver:
+    """
+    Resolves file references with security constraints (Jail).
+
+    This class enforces strict security boundaries to prevent Path Traversal attacks.
+    All resolved paths must be contained within the specified root directory.
+    """
+
+    def __init__(self, root_dir: Union[str, Path]):
+        """
+        Initialize the resolver with a root directory.
+
+        Args:
+            root_dir: The allowed jail directory. All resolved paths must be within this directory.
+        """
+        self.root_dir = Path(root_dir).resolve()
+
+    def resolve(self, base_file: Path, ref_path: str) -> Path:
+        """
+        Resolve a reference relative to a base file, ensuring it stays within the root directory.
+
+        Args:
+            base_file: The file containing the reference.
+            ref_path: The relative path string to resolve.
+
+        Returns:
+            The absolute resolved Path.
+
+        Raises:
+            ValueError: If the resolved path escapes the root directory.
+            FileNotFoundError: If the referenced file does not exist.
+        """
+        # Ensure base_file is absolute
+        base_file = base_file.resolve()
+
+        # Combine base_file parent with ref_path
+        # We assume ref_path is relative to the base_file's location
+        target_path = (base_file.parent / ref_path).resolve()
+
+        # Security Check: Jail
+        try:
+            target_path.relative_to(self.root_dir)
+        except ValueError:
+            raise ValueError(
+                f"Security Error: Reference '{ref_path}' escapes the root directory '{self.root_dir}'."
+            ) from None
+
+        if not target_path.exists():
+            raise FileNotFoundError(f"Referenced file not found: {target_path}")
+
+        return target_path

coreason_manifest/v2/spec/__init__.py

@@ -0,0 +1 @@
+# Coreason Manifest V2 Spec Definitions

coreason_manifest/v2/spec/contracts.py

@@ -0,0 +1,34 @@
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class InterfaceDefinition(BaseModel):
+    """Defines the input/output contract."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    inputs: Dict[str, Any] = Field(default_factory=dict, description="JSON Schema definitions for arguments.")
+    outputs: Dict[str, Any] = Field(default_factory=dict, description="JSON Schema definitions for return values.")
+
+
+class StateDefinition(BaseModel):
+    """Defines the conversation memory/context structure."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    schema_: Dict[str, Any] = Field(
+        default_factory=dict, alias="schema", description="The structure of the conversation memory/context."
+    )
+    backend: Optional[str] = Field(None, description="Backend storage type (e.g., 'redis', 'memory').")
+
+
+class PolicyDefinition(BaseModel):
+    """Defines execution policy and governance rules."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_steps: Optional[int] = Field(None, description="Execution limit on number of steps.")
+    max_retries: int = Field(3, description="Maximum number of retries.")
+    timeout: Optional[int] = Field(None, description="Timeout in seconds.")
+    human_in_the_loop: bool = Field(False, description="Whether to require human approval.")

coreason_manifest/v2/spec/definitions.py

@@ -0,0 +1,196 @@
+from typing import Annotated, Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from coreason_manifest.common import StrictUri, ToolRiskLevel
+from coreason_manifest.v2.spec.contracts import InterfaceDefinition, PolicyDefinition, StateDefinition
+
+
+class DesignMetadata(BaseModel):
+    """UI-specific metadata for the visual builder."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    x: float = Field(..., description="X coordinate on the canvas.")
+    y: float = Field(..., description="Y coordinate on the canvas.")
+    icon: Optional[str] = Field(None, description="Icon name or URL.")
+    color: Optional[str] = Field(None, description="Color code (hex/name).")
+    label: Optional[str] = Field(None, description="Display label.")
+    zoom: Optional[float] = Field(None, description="Zoom level.")
+    collapsed: bool = Field(False, description="Whether the node is collapsed in UI.")
+
+
+class ToolDefinition(BaseModel):
+    """Definition of an external tool."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    type: Literal["tool"] = "tool"
+    id: str = Field(..., description="Unique ID for the tool within the manifest.")
+    name: str = Field(..., description="Name of the tool.")
+    uri: StrictUri = Field(..., description="The MCP endpoint URI.")
+    risk_level: ToolRiskLevel = Field(..., description="Risk level (safe, standard, critical).")
+    description: Optional[str] = Field(None, description="Description of the tool.")
+
+
+class AgentDefinition(BaseModel):
+    """Definition of an Agent."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    type: Literal["agent"] = "agent"
+    id: str = Field(..., description="Unique ID for the agent.")
+    name: str = Field(..., description="Name of the agent.")
+    role: str = Field(..., description="The persona/job title.")
+    goal: str = Field(..., description="Primary objective.")
+    backstory: Optional[str] = Field(None, description="Backstory or directives.")
+    model: Optional[str] = Field(None, description="LLM identifier.")
+    tools: List[str] = Field(default_factory=list, description="List of Tool IDs or URI references.")
+    knowledge: List[str] = Field(default_factory=list, description="List of file paths or knowledge base IDs.")
+
+
+class GenericDefinition(BaseModel):
+    """Fallback for unknown definitions."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class BaseStep(BaseModel):
+    """Base attributes for all steps."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    id: str = Field(..., description="Unique identifier for the step.")
+    inputs: Dict[str, Any] = Field(default_factory=dict, description="Input arguments for the step.")
+    design_metadata: Optional[DesignMetadata] = Field(None, alias="x-design", description="UI metadata.")
+
+
+class AgentStep(BaseStep):
+    """A step that executes an AI Agent."""
+
+    type: Literal["agent"] = "agent"
+    agent: str = Field(..., description="Reference to an Agent definition (by ID or name).")
+    next: Optional[str] = Field(None, description="ID of the next step to execute.")
+    system_prompt: Optional[str] = Field(None, description="Optional override for system prompt.")
+
+
+class LogicStep(BaseStep):
+    """A step that executes custom logic."""
+
+    type: Literal["logic"] = "logic"
+    code: str = Field(..., description="Python code or reference to logic to execute.")
+    next: Optional[str] = Field(None, description="ID of the next step to execute.")
+
+
+class CouncilStep(BaseStep):
+    """A step that involves multiple voters/agents."""
+
+    type: Literal["council"] = "council"
+    voters: List[str] = Field(..., description="List of voters (Agent IDs).")
+    strategy: str = Field("consensus", description="Voting strategy (e.g., consensus, majority).")
+    next: Optional[str] = Field(None, description="ID of the next step to execute.")
+
+
+class SwitchStep(BaseStep):
+    """A step that routes execution based on conditions."""
+
+    type: Literal["switch"] = "switch"
+    cases: Dict[str, str] = Field(..., description="Dictionary of condition expressions to Step IDs.")
+    default: Optional[str] = Field(None, description="Default Step ID if no cases match.")
+    # Note: 'next' is deliberately excluded for SwitchStep in favor of cases/default.
+
+
+Step = Annotated[
+    Union[AgentStep, LogicStep, CouncilStep, SwitchStep],
+    Field(discriminator="type", description="Polymorphic step definition."),
+]
+
+
+class Workflow(BaseModel):
+    """Defines the execution topology."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    start: str = Field(..., description="ID of the starting step.")
+    steps: Dict[str, Step] = Field(..., description="Dictionary of all steps indexed by ID.")
+
+
+class ManifestMetadata(BaseModel):
+    """Metadata for the manifest."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    name: str = Field(..., description="Human-readable name of the workflow/agent.")
+    design_metadata: Optional[DesignMetadata] = Field(None, alias="x-design", description="UI metadata.")
+
+
+class ManifestV2(BaseModel):
+    """Root object for Coreason Manifest V2."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    apiVersion: Literal["coreason.ai/v2"] = Field("coreason.ai/v2", description="API Version.")
+    kind: Literal["Recipe", "Agent"] = Field(..., description="Kind of the object.")
+    metadata: ManifestMetadata = Field(..., description="Metadata including name and design info.")
+    interface: InterfaceDefinition = Field(default_factory=InterfaceDefinition)
+    state: StateDefinition = Field(default_factory=StateDefinition)
+    policy: PolicyDefinition = Field(default_factory=PolicyDefinition)
+    definitions: Dict[
+        str,
+        Union[
+            Annotated[Union[ToolDefinition, AgentDefinition], Field(discriminator="type")],
+            GenericDefinition,
+        ],
+    ] = Field(default_factory=dict, description="Reusable definitions.")
+    workflow: Workflow = Field(..., description="The main workflow topology.")
+
+    @model_validator(mode="after")
+    def validate_integrity(self) -> "ManifestV2":
+        """Validate referential integrity of the manifest."""
+        steps = self.workflow.steps
+
+        # 1. Validate Start Step
+        if self.workflow.start not in steps:
+            raise ValueError(f"Start step '{self.workflow.start}' not found in steps.")
+
+        for step in steps.values():
+            # 2. Validate 'next' pointers (AgentStep, LogicStep, CouncilStep)
+            if hasattr(step, "next") and step.next:
+                if step.next not in steps:
+                    raise ValueError(f"Step '{step.id}' references missing next step '{step.next}'.")
+
+            # 3. Validate SwitchStep targets
+            if isinstance(step, SwitchStep):
+                for target in step.cases.values():
+                    if target not in steps:
+                        raise ValueError(f"SwitchStep '{step.id}' references missing step '{target}' in cases.")
+                if step.default and step.default not in steps:
+                    raise ValueError(f"SwitchStep '{step.id}' references missing step '{step.default}' in default.")
+
+            # 4. Validate Definition References
+            if isinstance(step, AgentStep):
+                if step.agent not in self.definitions:
+                    raise ValueError(f"AgentStep '{step.id}' references missing agent '{step.agent}'.")
+
+                # Check type
+                agent_def = self.definitions[step.agent]
+                if not isinstance(agent_def, AgentDefinition):
+                    raise ValueError(
+                        f"AgentStep '{step.id}' references '{step.agent}' which is not an AgentDefinition "
+                        f"(got {type(agent_def).__name__})."
+                    )
+
+            if isinstance(step, CouncilStep):
+                for voter in step.voters:
+                    if voter not in self.definitions:
+                        raise ValueError(f"CouncilStep '{step.id}' references missing voter '{voter}'.")
+
+                    # Check type
+                    agent_def = self.definitions[voter]
+                    if not isinstance(agent_def, AgentDefinition):
+                        raise ValueError(
+                            f"CouncilStep '{step.id}' references voter '{voter}' which is not an AgentDefinition "
+                            f"(got {type(agent_def).__name__})."
+                        )
+
+        return self

coreason_manifest/v2/validator.py

@@ -0,0 +1,48 @@
+# 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
+
+"""Validation logic for V2 Manifests."""
+
+from typing import List
+
+from coreason_manifest.v2.spec.definitions import (
+    ManifestV2,
+    SwitchStep,
+)
+
+
+def validate_loose(manifest: ManifestV2) -> List[str]:
+    """Validate "Draft" manifests for structural sanity only.
+
+    Checks:
+    - Unique Step IDs.
+    - SwitchStep case syntax (basic).
+
+    Args:
+        manifest: The V2 manifest to validate.
+
+    Returns:
+        List of warning messages (empty if clean).
+    """
+    warnings: List[str] = []
+
+    # 1. Check unique Step IDs
+    for step_id, step in manifest.workflow.steps.items():
+        if step.id != step_id:
+            warnings.append(f"Step key '{step_id}' does not match step.id '{step.id}'.")
+
+    # 2. Check SwitchStep cases
+    for step_id, step in manifest.workflow.steps.items():
+        if isinstance(step, SwitchStep):
+            for condition in step.cases.keys():
+                if not isinstance(condition, str) or not condition.strip():
+                    warnings.append(f"SwitchStep '{step_id}' has invalid condition: {condition}")
+
+    return warnings