coreason-manifest 0.1.0__py3-none-any.whl

coreason_manifest/__init__.py

@@ -0,0 +1,41 @@
+# Prosperity-3.0
+from .engine import ManifestConfig, ManifestEngine
+from .errors import (
+    IntegrityCompromisedError,
+    ManifestError,
+    ManifestSyntaxError,
+    PolicyViolationError,
+)
+from .integrity import IntegrityChecker
+from .loader import ManifestLoader
+from .models import (
+    AgentDefinition,
+    AgentDependencies,
+    AgentInterface,
+    AgentMetadata,
+    AgentTopology,
+    ModelConfig,
+    Step,
+)
+from .policy import PolicyEnforcer
+from .validator import SchemaValidator
+
+__all__ = [
+    "AgentDefinition",
+    "AgentDependencies",
+    "AgentInterface",
+    "AgentMetadata",
+    "AgentTopology",
+    "IntegrityChecker",
+    "IntegrityCompromisedError",
+    "ManifestConfig",
+    "ManifestEngine",
+    "ManifestError",
+    "ManifestLoader",
+    "ManifestSyntaxError",
+    "ModelConfig",
+    "PolicyEnforcer",
+    "PolicyViolationError",
+    "SchemaValidator",
+    "Step",
+]

coreason_manifest/engine.py

@@ -0,0 +1,117 @@
+# Prosperity-3.0
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Union
+
+from coreason_manifest.integrity import IntegrityChecker
+from coreason_manifest.loader import ManifestLoader
+from coreason_manifest.models import AgentDefinition
+from coreason_manifest.policy import PolicyEnforcer
+
+# Import logger from utils to ensure configuration is applied
+from coreason_manifest.utils.logger import logger
+from coreason_manifest.validator import SchemaValidator
+
+
+@dataclass
+class ManifestConfig:
+    """Configuration for the ManifestEngine."""
+
+    policy_path: Union[str, Path]
+    opa_path: str = "opa"
+    tbom_path: Optional[Union[str, Path]] = None
+    extra_data_paths: List[Union[str, Path]] = field(default_factory=list)
+
+
+class ManifestEngine:
+    """
+    The main entry point for verifying and loading Agent Manifests.
+    """
+
+    def __init__(self, config: ManifestConfig) -> None:
+        """
+        Initialize the ManifestEngine.
+
+        Args:
+            config: Configuration including policy path and OPA path.
+        """
+        self.config = config
+        self.schema_validator = SchemaValidator()
+
+        # Collect data paths
+        data_paths = list(config.extra_data_paths)
+        if config.tbom_path:
+            data_paths.append(config.tbom_path)
+
+        self.policy_enforcer = PolicyEnforcer(
+            policy_path=config.policy_path,
+            opa_path=config.opa_path,
+            data_paths=data_paths,
+        )
+
+    def load_and_validate(self, manifest_path: Union[str, Path], source_dir: Union[str, Path]) -> AgentDefinition:
+        """
+        Loads, validates, and verifies an Agent Manifest.
+
+        Steps:
+        1. Load raw YAML.
+        2. Validate against JSON Schema.
+        3. Convert to AgentDefinition Pydantic model (Normalization).
+        4. Enforce Policy (Rego).
+        5. Verify Integrity (Hash check).
+
+        Args:
+            manifest_path: Path to the agent.yaml file.
+            source_dir: Path to the source code directory.
+
+        Returns:
+            AgentDefinition: The fully validated and verified agent definition.
+
+        Raises:
+            ManifestSyntaxError: If structure or schema is invalid.
+            PolicyViolationError: If business rules are violated.
+            IntegrityCompromisedError: If source code hash does not match.
+            FileNotFoundError: If files are missing.
+        """
+        manifest_path = Path(manifest_path)
+        source_dir = Path(source_dir)
+
+        logger.info(f"Validating Agent Manifest: {manifest_path}")
+
+        # 1. Load Raw YAML
+        raw_data = ManifestLoader.load_raw_from_file(manifest_path)
+
+        # 2. Schema Validation
+        logger.debug("Running Schema Validation...")
+        self.schema_validator.validate(raw_data)
+
+        # 3. Model Conversion (Normalization)
+        logger.debug("Converting to AgentDefinition...")
+        agent_def = ManifestLoader.load_from_dict(raw_data)
+        logger.info(f"Validating Agent {agent_def.metadata.id} v{agent_def.metadata.version}")
+
+        # 4. Policy Enforcement
+        logger.debug("Enforcing Policies...")
+        # We assume policy is checked against the Normalized data (model dumped back to dict)
+        # or raw data? Standard practice: Check against normalized data to prevent bypasses.
+        # dump mode='json' converts UUIDs/Dates to strings which is what OPA expects usually.
+        normalized_data = agent_def.model_dump(mode="json")
+        start_time = time.perf_counter()
+        try:
+            self.policy_enforcer.evaluate(normalized_data)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            logger.info(f"Policy Check: Pass - {duration_ms:.2f}ms")
+        except Exception:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            logger.info(f"Policy Check: Fail - {duration_ms:.2f}ms")
+            raise
+
+        # 5. Integrity Check
+        logger.debug("Verifying Integrity...")
+        IntegrityChecker.verify(agent_def, source_dir, manifest_path=manifest_path)
+
+        logger.info("Agent validation successful.")
+        return agent_def

coreason_manifest/errors.py

@@ -0,0 +1,28 @@
+# Prosperity-3.0
+from __future__ import annotations
+
+
+class ManifestError(Exception):
+    """Base exception for coreason_manifest errors."""
+
+    pass
+
+
+class ManifestSyntaxError(ManifestError):
+    """Raised when the manifest YAML is invalid or missing required fields."""
+
+    pass
+
+
+class PolicyViolationError(ManifestError):
+    """Raised when the agent violates a compliance policy."""
+
+    def __init__(self, message: str, violations: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.violations = violations or []
+
+
+class IntegrityCompromisedError(ManifestError):
+    """Raised when the source code hash does not match the manifest."""
+
+    pass

coreason_manifest/integrity.py

@@ -0,0 +1,136 @@
+# Prosperity-3.0
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import List, Optional, Set, Union
+
+from coreason_manifest.errors import IntegrityCompromisedError
+from coreason_manifest.models import AgentDefinition
+
+
+class IntegrityChecker:
+    """
+    Component D: IntegrityChecker (The Notary).
+
+    Responsibility:
+      - Calculate the SHA256 hash of the source code directory.
+      - Compare it against the integrity_hash defined in the manifest.
+    """
+
+    IGNORED_DIRS = frozenset({".git", "__pycache__", ".venv", ".env", ".DS_Store"})
+
+    @staticmethod
+    def calculate_hash(source_dir: Union[Path, str], exclude_files: Optional[Set[Union[Path, str]]] = None) -> str:
+        """
+        Calculates a deterministic SHA256 hash of the source code directory.
+
+        It walks the directory using os.walk to efficiently prune ignored directories.
+        Sorts files by relative path, hashes each file, and then hashes the sequence.
+
+        Ignores hidden directories/files in IGNORED_DIRS.
+        Rejects symbolic links for security.
+
+        Args:
+            source_dir: The directory containing source code.
+            exclude_files: Optional set of file paths (absolute or relative to CWD) to exclude from hashing.
+
+        Returns:
+            The hex digest of the SHA256 hash.
+
+        Raises:
+            FileNotFoundError: If source_dir does not exist.
+            IntegrityCompromisedError: If a symlink is found.
+        """
+        path_obj = Path(source_dir)
+        if path_obj.is_symlink():
+            raise IntegrityCompromisedError(f"Symbolic links are forbidden: {path_obj}")
+
+        source_path = path_obj.resolve()
+        if not source_path.exists():
+            raise FileNotFoundError(f"Source directory not found: {source_path}")
+
+        # Normalize excluded files to absolute paths
+        excludes = set()
+        if exclude_files:
+            for ex_path in exclude_files:
+                excludes.add(Path(ex_path).resolve())
+
+        sha256 = hashlib.sha256()
+        file_paths: List[Path] = []
+
+        # Use os.walk for efficient traversal and pruning
+        for root, dirs, files in os.walk(source_path, topdown=True):
+            root_path = Path(root)
+
+            # Check for symlinks in directories before pruning
+            for d_name in dirs:
+                d_path = root_path / d_name
+                if d_path.is_symlink():
+                    raise IntegrityCompromisedError(f"Symbolic links are forbidden: {d_path}")  # pragma: no cover
+
+            # Prune directories efficiently using slice assignment
+            dirs[:] = [d for d in dirs if d not in IntegrityChecker.IGNORED_DIRS]
+
+            # Collect files
+            for f_name in files:
+                f_path = root_path / f_name
+
+                if f_path.is_symlink():
+                    raise IntegrityCompromisedError(f"Symbolic links are forbidden: {f_path}")
+
+                if f_name in IntegrityChecker.IGNORED_DIRS:
+                    continue
+
+                # Use resolved path for exclusion checking and inclusion
+                f_path_abs = f_path.resolve()
+                if f_path_abs in excludes:
+                    continue
+
+                file_paths.append(f_path_abs)
+
+        # Sort to ensure deterministic order
+        # Use as_posix() to ensure ASCII sorting (case-sensitive) on all platforms (Windows vs Linux)
+        file_paths.sort(key=lambda p: p.relative_to(source_path).as_posix())
+
+        for path in file_paths:
+            # Update hash with relative path to ensure structure matters
+            # Use forward slashes for cross-platform consistency
+            rel_path = path.relative_to(source_path).as_posix().encode("utf-8")
+            sha256.update(rel_path)
+
+            # Update hash with file content
+            with open(path, "rb") as f:
+                while chunk := f.read(8192):
+                    sha256.update(chunk)
+
+        return sha256.hexdigest()
+
+    @staticmethod
+    def verify(
+        agent_def: AgentDefinition,
+        source_dir: Union[Path, str],
+        manifest_path: Optional[Union[Path, str]] = None,
+    ) -> None:
+        """
+        Verifies the integrity of the source code against the manifest.
+
+        Args:
+            agent_def: The AgentDefinition containing the expected hash.
+            source_dir: The directory containing source code.
+            manifest_path: Optional path to the manifest file to exclude from hashing.
+
+        Raises:
+            IntegrityCompromisedError: If the hash does not match or is missing.
+            FileNotFoundError: If source_dir does not exist.
+        """
+        exclude_files = {manifest_path} if manifest_path else None
+
+        # agent_def.integrity_hash is now required by Pydantic model
+        calculated = IntegrityChecker.calculate_hash(source_dir, exclude_files=exclude_files)
+
+        if calculated != agent_def.integrity_hash:
+            raise IntegrityCompromisedError(
+                f"Integrity check failed. Expected {agent_def.integrity_hash}, got {calculated}"
+            )

coreason_manifest/loader.py

@@ -0,0 +1,125 @@
+# Prosperity-3.0
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+from pydantic import ValidationError
+
+from coreason_manifest.errors import ManifestSyntaxError
+from coreason_manifest.models import AgentDefinition
+
+
+class ManifestLoader:
+    """
+    Component A: ManifestLoader (The Parser).
+
+    Responsibility:
+      - Load YAML safely.
+      - Convert raw data into a Pydantic AgentDefinition model.
+      - Normalization: Ensure all version strings follow SemVer and all IDs are canonical UUIDs.
+    """
+
+    @staticmethod
+    def load_raw_from_file(path: Union[str, Path]) -> dict[str, Any]:
+        """
+        Loads the raw dict from a YAML file.
+
+        Args:
+            path: The path to the agent.yaml file.
+
+        Returns:
+            dict: The raw dictionary content.
+
+        Raises:
+            ManifestSyntaxError: If YAML is invalid.
+            FileNotFoundError: If the file does not exist.
+        """
+        try:
+            path_obj = Path(path)
+            if not path_obj.exists():
+                raise FileNotFoundError(f"Manifest file not found: {path}")
+
+            with open(path_obj, "r", encoding="utf-8") as f:
+                # safe_load is recommended for untrusted input
+                data = yaml.safe_load(f)
+
+            if not isinstance(data, dict):
+                raise ManifestSyntaxError(f"Invalid YAML content in {path}: must be a dictionary.")
+
+            # Normalization logic is now centralized in load_from_dict
+            # But we perform it here too if we return the raw dict, or we delegate.
+            # However, standardizing on load_from_dict doing the normalization is cleaner.
+            # But for backward compatibility with callers who use raw dict, we keep the logic here too?
+            # Or we call a shared helper. For now, we replicate or keep it.
+            # Actually, the requirement is "explicitly strip ... before they reach Pydantic models".
+            # If load_raw returns data, and then user calls load_from_dict, load_from_dict must do it.
+            # If load_raw returns data with 'v', the caller sees 'v'. That's fine for raw.
+            # But let's apply it here too for consistency.
+
+            ManifestLoader._normalize_data(data)
+
+            return data
+
+        except yaml.YAMLError as e:
+            raise ManifestSyntaxError(f"Failed to parse YAML file {path}: {str(e)}") from e
+        except OSError as e:
+            if isinstance(e, FileNotFoundError):
+                raise
+            raise ManifestSyntaxError(f"Error reading file {path}: {str(e)}") from e
+
+    @staticmethod
+    def load_from_file(path: Union[str, Path]) -> AgentDefinition:
+        """
+        Loads the agent manifest from a YAML file.
+
+        Args:
+            path: The path to the agent.yaml file.
+
+        Returns:
+            AgentDefinition: The validated Pydantic model.
+
+        Raises:
+            ManifestSyntaxError: If YAML is invalid or Pydantic validation fails.
+            FileNotFoundError: If the file does not exist.
+        """
+        data = ManifestLoader.load_raw_from_file(path)
+        return ManifestLoader.load_from_dict(data)
+
+    @staticmethod
+    def load_from_dict(data: dict[str, Any]) -> AgentDefinition:
+        """
+        Converts a dictionary into an AgentDefinition model.
+
+        Args:
+            data: The raw dictionary.
+
+        Returns:
+            AgentDefinition: The validated Pydantic model.
+
+        Raises:
+            ManifestSyntaxError: If Pydantic validation fails.
+        """
+        try:
+            # Ensure normalization happens before Pydantic validation
+            # We work on a copy to avoid side effects if possible, but deep copy is expensive.
+            # The input 'data' might be modified in place.
+            ManifestLoader._normalize_data(data)
+
+            return AgentDefinition.model_validate(data)
+        except ValidationError as e:
+            # Convert Pydantic ValidationError to ManifestSyntaxError
+            # We assume "normalization" happens via Pydantic validators (e.g. UUID, SemVer checks)
+            raise ManifestSyntaxError(f"Manifest validation failed: {str(e)}") from e
+
+    @staticmethod
+    def _normalize_data(data: dict[str, Any]) -> None:
+        """
+        Normalizes the data dictionary in place.
+        Specifically strips 'v' or 'V' from version strings.
+        """
+        if "metadata" in data and isinstance(data["metadata"], dict):
+            version = data["metadata"].get("version")
+            if isinstance(version, str) and version.lower().startswith("v"):
+                data["metadata"]["version"] = version[1:]

coreason_manifest/main.py

@@ -0,0 +1,16 @@
+# 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 coreason_manifest.utils.logger import logger
+
+
+def hello_world() -> str:
+    logger.info("Hello World!")
+    return "Hello World!"

coreason_manifest/models.py

@@ -0,0 +1,156 @@
+# Prosperity-3.0
+from __future__ import annotations
+
+from datetime import datetime
+from types import MappingProxyType
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+from uuid import UUID
+
+from pydantic import (
+    AfterValidator,
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    Field,
+    PlainSerializer,
+    field_validator,
+)
+from typing_extensions import Annotated
+
+# SemVer Regex pattern (simplified for standard SemVer)
+# Modified to accept optional 'v' or 'V' prefix (multiple allowed) for input normalization
+SEMVER_REGEX = (
+    r"^[vV]*(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
+    r"(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+)
+
+
+def normalize_version(v: str) -> str:
+    """Normalize version string by recursively stripping 'v' or 'V' prefix."""
+    while v.lower().startswith("v"):
+        v = v[1:]
+    return v
+
+
+# Annotated type that validates SemVer regex (allowing multiple v) then normalizes to strict SemVer (no v)
+VersionStr = Annotated[
+    str,
+    Field(pattern=SEMVER_REGEX),
+    AfterValidator(normalize_version),
+]
+
+# Reusable immutable dictionary type
+ImmutableDict = Annotated[
+    Mapping[str, Any],
+    AfterValidator(lambda x: MappingProxyType(x)),
+    PlainSerializer(lambda x: dict(x), return_type=Dict[str, Any]),
+]
+
+
+# Strict URI type that serializes to string
+StrictUri = Annotated[
+    AnyUrl,
+    PlainSerializer(lambda x: str(x), return_type=str),
+]
+
+
+class AgentMetadata(BaseModel):
+    """Metadata for the Agent."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: UUID = Field(..., description="Unique Identifier for the Agent (UUID).")
+    version: VersionStr = Field(..., description="Semantic Version of the Agent.")
+    name: str = Field(..., min_length=1, description="Name of the Agent.")
+    author: str = Field(..., min_length=1, description="Author of the Agent.")
+    created_at: datetime = Field(..., description="Creation timestamp (ISO 8601).")
+
+
+class AgentInterface(BaseModel):
+    """Interface definition for the Agent."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    inputs: ImmutableDict = Field(..., description="Typed arguments the agent accepts (JSON Schema).")
+    outputs: ImmutableDict = Field(..., description="Typed structure of the result.")
+
+
+class Step(BaseModel):
+    """A single step in the execution graph."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: str = Field(..., min_length=1, description="Unique identifier for the step.")
+    description: Optional[str] = Field(None, description="Description of the step.")
+
+
+class ModelConfig(BaseModel):
+    """LLM Configuration parameters."""
+
+    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.")
+
+
+class AgentTopology(BaseModel):
+    """Topology of the Agent execution."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    steps: Tuple[Step, ...] = Field(..., description="A directed acyclic graph (DAG) of execution steps.")
+    llm_config: ModelConfig = Field(..., alias="model_config", description="Specific LLM parameters.")
+
+    @field_validator("steps")
+    @classmethod
+    def validate_unique_step_ids(cls, v: Tuple[Step, ...]) -> Tuple[Step, ...]:
+        """Ensure all step IDs are unique."""
+        ids = [step.id for step in v]
+        if len(ids) != len(set(ids)):
+            # Find duplicates
+            seen = set()
+            dupes = set()
+            for x in ids:
+                if x in seen:
+                    dupes.add(x)
+                seen.add(x)
+            raise ValueError(f"Duplicate step IDs found: {', '.join(dupes)}")
+        return v
+
+
+class AgentDependencies(BaseModel):
+    """External dependencies for the Agent."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    # Use AnyUrl to enforce strictly valid URIs
+    # Changed to List[StrictUri] to strictly enforce valid URI formatting and string serialization
+    tools: List[StrictUri] = Field(default_factory=list, description="List of MCP capability URIs required.")
+    libraries: Tuple[str, ...] = Field(
+        default_factory=tuple, description="List of Python packages required (if code execution is allowed)."
+    )
+
+
+class AgentDefinition(BaseModel):
+    """The Root Object for the CoReason Agent Manifest."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        title="CoReason Agent Manifest",
+        json_schema_extra={
+            "$id": "https://coreason.ai/schemas/agent.schema.json",
+            "description": "The definitive source of truth for CoReason Agent definitions.",
+        },
+    )
+
+    metadata: AgentMetadata
+    interface: AgentInterface
+    topology: AgentTopology
+    dependencies: AgentDependencies
+    integrity_hash: str = Field(
+        ...,
+        pattern=r"^[a-fA-F0-9]{64}$",
+        description="SHA256 hash of the source code.",
+    )