coreason-manifest 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

coreason_manifest/__init__.py

@@ -1,5 +1,22 @@
 # Prosperity-3.0
-from .engine import ManifestConfig, ManifestEngine
+"""Coreason Manifest Package.
+
+This package provides the core functionality for the Coreason Manifest system,
+including loading, validation, policy enforcement, and integrity checking of
+agent definitions.
+
+The `coreason-manifest` package serves as the definitive source of truth for
+Asset definitions in the CoReason-AI ecosystem.
+
+Usage:
+    from coreason_manifest import ManifestEngine, ManifestConfig
+
+    config = ManifestConfig(policy_path="./policies/gx_compliant.rego")
+    engine = ManifestEngine(config)
+    agent_def = engine.load_and_validate("agent.yaml", "./src")
+"""
+
+from .engine import ManifestConfig, ManifestEngine, ManifestEngineAsync
 from .errors import (
     IntegrityCompromisedError,
     ManifestError,
@@ -30,6 +47,7 @@ __all__ = [
     "IntegrityCompromisedError",
     "ManifestConfig",
     "ManifestEngine",
+    "ManifestEngineAsync",
     "ManifestError",
     "ManifestLoader",
     "ManifestSyntaxError",

coreason_manifest/engine.py

@@ -1,24 +1,38 @@
 # Prosperity-3.0
+"""Engine for the Coreason Manifest system.
+
+This module provides the main entry point for verifying and loading Agent Manifests.
+It coordinates schema validation, policy enforcement, and integrity checking.
+"""
+
 from __future__ import annotations
 
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Optional, Union
+from typing import Any, List, Optional, Union, cast
+
+import anyio
+import anyio.to_thread
 
 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."""
+    """Configuration for the ManifestEngine.
+
+    Attributes:
+        policy_path: Path to the Rego policy file.
+        opa_path: Path to the OPA executable. Defaults to "opa".
+        tbom_path: Optional path to the Trusted Bill of Materials.
+        extra_data_paths: Additional data paths to load into OPA.
+    """
 
     policy_path: Union[str, Path]
     opa_path: str = "opa"
@@ -26,14 +40,19 @@ class ManifestConfig:
     extra_data_paths: List[Union[str, Path]] = field(default_factory=list)
 
 
-class ManifestEngine:
-    """
-    The main entry point for verifying and loading Agent Manifests.
+class ManifestEngineAsync:
+    """The async core for verifying and loading Agent Manifests.
+
+    This class coordinates the validation process, including:
+    1.  Loading raw YAML.
+    2.  Validating against JSON Schema.
+    3.  Converting to AgentDefinition Pydantic model (Normalization).
+    4.  Enforcing Policy (Rego).
+    5.  Verifying Integrity (Hash check).
     """
 
     def __init__(self, config: ManifestConfig) -> None:
-        """
-        Initialize the ManifestEngine.
+        """Initialize the ManifestEngineAsync.
 
         Args:
             config: Configuration including policy path and OPA path.
@@ -52,56 +71,57 @@ class ManifestEngine:
             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.
+    async def __aenter__(self) -> ManifestEngineAsync:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        # Clean up resources if necessary.
+        pass
+
+    async def validate_manifest_dict(self, raw_data: dict[str, Any]) -> AgentDefinition:
+        """Validates an Agent Manifest dictionary in memory.
+
+        Performs:
+        1. Normalization (stripping version prefixes)
+        2. Schema Validation
+        3. Model Conversion
+        4. Policy Enforcement
 
-        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).
+        Does NOT perform Integrity Check (hashing).
 
         Args:
-            manifest_path: Path to the agent.yaml file.
-            source_dir: Path to the source code directory.
+            raw_data: The raw dictionary of the manifest.
 
         Returns:
-            AgentDefinition: The fully validated and verified agent definition.
+            AgentDefinition: The fully validated 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)
+        # 1. Normalization (ensure version string is clean before schema/model validation)
+        # We access the static method on ManifestLoader.
+        ManifestLoader._normalize_data(raw_data)
 
         # 2. Schema Validation
         logger.debug("Running Schema Validation...")
         self.schema_validator.validate(raw_data)
 
-        # 3. Model Conversion (Normalization)
+        # 3. Model Conversion (Normalization) (CPU bound)
         logger.debug("Converting to AgentDefinition...")
-        agent_def = ManifestLoader.load_from_dict(raw_data)
+        agent_def = await anyio.to_thread.run_sync(ManifestLoader.load_from_dict, raw_data)
         logger.info(f"Validating Agent {agent_def.metadata.id} v{agent_def.metadata.version}")
 
-        # 4. Policy Enforcement
+        # 4. Policy Enforcement (Subprocess / Blocking)
         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)
+            # PolicyEnforcer.evaluate is synchronous and runs subprocess.run, so we wrap it.
+            await anyio.to_thread.run_sync(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:
@@ -109,9 +129,94 @@ class ManifestEngine:
             logger.info(f"Policy Check: Fail - {duration_ms:.2f}ms")
             raise
 
-        # 5. Integrity Check
+        return cast(AgentDefinition, agent_def)
+
+    async def load_and_validate(self, manifest_path: Union[str, Path], source_dir: Union[str, Path]) -> AgentDefinition:
+        """Loads, validates, and verifies an Agent Manifest asynchronously.
+
+        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 (I/O)
+        raw_data = await ManifestLoader.load_raw_from_file_async(manifest_path)
+
+        # 2. Validate Manifest Dict (Schema, Model, Policy)
+        agent_def = await self.validate_manifest_dict(raw_data)
+
+        # 5. Integrity Check (Heavy I/O and CPU)
         logger.debug("Verifying Integrity...")
-        IntegrityChecker.verify(agent_def, source_dir, manifest_path=manifest_path)
+        # IntegrityChecker.verify is synchronous and does heavy IO, so we wrap it.
+        await anyio.to_thread.run_sync(IntegrityChecker.verify, agent_def, source_dir, manifest_path)
 
         logger.info("Agent validation successful.")
         return agent_def
+
+
+class ManifestEngine:
+    """The Sync Facade for ManifestEngineAsync.
+
+    Allows synchronous usage of the async core via anyio.run.
+    """
+
+    def __init__(self, config: ManifestConfig) -> None:
+        """Initialize the ManifestEngine facade.
+
+        Args:
+            config: Configuration including policy path and OPA path.
+        """
+        self._async = ManifestEngineAsync(config)
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the async engine instance.
+
+        This ensures backward compatibility for accessing attributes like
+        'config', 'schema_validator', and 'policy_enforcer'.
+        """
+        return getattr(self._async, name)
+
+    def __enter__(self) -> ManifestEngine:
+        """Context manager entry."""
+        anyio.run(self._async.__aenter__)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        anyio.run(self._async.__aexit__, exc_type, exc_val, exc_tb)
+
+    def load_and_validate(self, manifest_path: Union[str, Path], source_dir: Union[str, Path]) -> AgentDefinition:
+        """Loads, validates, and verifies an Agent Manifest synchronously.
+
+        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.
+        """
+        return cast(AgentDefinition, anyio.run(self._async.load_and_validate, manifest_path, source_dir))
+
+    def validate_manifest_dict(self, raw_data: dict[str, Any]) -> AgentDefinition:
+        """Validates an Agent Manifest dictionary synchronously.
+
+        Args:
+            raw_data: The raw dictionary of the manifest.
+
+        Returns:
+            AgentDefinition: The fully validated agent definition.
+        """
+        return cast(AgentDefinition, anyio.run(self._async.validate_manifest_dict, raw_data))

coreason_manifest/errors.py

@@ -1,4 +1,9 @@
 # Prosperity-3.0
+"""Exceptions for the Coreason Manifest system.
+
+This module defines the hierarchy of exceptions raised by the package.
+"""
+
 from __future__ import annotations
 
 
@@ -9,20 +14,40 @@ class ManifestError(Exception):
 
 
 class ManifestSyntaxError(ManifestError):
-    """Raised when the manifest YAML is invalid or missing required fields."""
+    """Raised when the manifest YAML is invalid or missing required fields.
+
+    This includes YAML parsing errors and JSON Schema validation failures.
+    """
 
     pass
 
 
 class PolicyViolationError(ManifestError):
-    """Raised when the agent violates a compliance policy."""
+    """Raised when the agent violates a compliance policy.
+
+    This error indicates that the manifest is structurally valid but fails
+    business rules or compliance checks (e.g., banned libraries).
+
+    Attributes:
+        violations: A list of specific policy violation messages.
+    """
 
     def __init__(self, message: str, violations: list[str] | None = None) -> None:
+        """Initialize PolicyViolationError.
+
+        Args:
+            message: The error message.
+            violations: Optional list of detailed violation strings.
+        """
         super().__init__(message)
         self.violations = violations or []
 
 
 class IntegrityCompromisedError(ManifestError):
-    """Raised when the source code hash does not match the manifest."""
+    """Raised when the source code hash does not match the manifest.
+
+    This indicates that the source code may have been tampered with or changed
+    without updating the manifest's integrity hash.
+    """
 
     pass

coreason_manifest/integrity.py

@@ -1,4 +1,11 @@
 # Prosperity-3.0
+"""Integrity checking functionality.
+
+This module provides the `IntegrityChecker` class, which is responsible for
+calculating deterministic hashes of source code directories and verifying
+them against the expected hash in the agent manifest.
+"""
+
 from __future__ import annotations
 
 import hashlib
@@ -11,8 +18,7 @@ from coreason_manifest.models import AgentDefinition
 
 
 class IntegrityChecker:
-    """
-    Component D: IntegrityChecker (The Notary).
+    """Component D: IntegrityChecker (The Notary).
 
     Responsibility:
       - Calculate the SHA256 hash of the source code directory.
@@ -23,8 +29,7 @@ class IntegrityChecker:
 
     @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.
+        """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.
@@ -34,7 +39,8 @@ class IntegrityChecker:
 
         Args:
             source_dir: The directory containing source code.
-            exclude_files: Optional set of file paths (absolute or relative to CWD) to exclude from hashing.
+            exclude_files: Optional set of file paths (absolute or relative to CWD)
+                to exclude from hashing.
 
         Returns:
             The hex digest of the SHA256 hash.
@@ -113,8 +119,7 @@ class IntegrityChecker:
         source_dir: Union[Path, str],
         manifest_path: Optional[Union[Path, str]] = None,
     ) -> None:
-        """
-        Verifies the integrity of the source code against the manifest.
+        """Verifies the integrity of the source code against the manifest.
 
         Args:
             agent_def: The AgentDefinition containing the expected hash.

coreason_manifest/loader.py

@@ -1,9 +1,16 @@
 # Prosperity-3.0
+"""Manifest Loader.
+
+This module is responsible for loading the agent manifest from YAML files or
+dictionaries, normalizing the data, and converting it into Pydantic models.
+"""
+
 from __future__ import annotations
 
 from pathlib import Path
 from typing import Any, Union
 
+import aiofiles
 import yaml
 from pydantic import ValidationError
 
@@ -12,8 +19,7 @@ from coreason_manifest.models import AgentDefinition
 
 
 class ManifestLoader:
-    """
-    Component A: ManifestLoader (The Parser).
+    """Component A: ManifestLoader (The Parser).
 
     Responsibility:
       - Load YAML safely.
@@ -23,8 +29,7 @@ class ManifestLoader:
 
     @staticmethod
     def load_raw_from_file(path: Union[str, Path]) -> dict[str, Any]:
-        """
-        Loads the raw dict from a YAML file.
+        """Loads the raw dict from a YAML file.
 
         Args:
             path: The path to the agent.yaml file.
@@ -48,15 +53,42 @@ class ManifestLoader:
             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
+    async def load_raw_from_file_async(path: Union[str, Path]) -> dict[str, Any]:
+        """Loads the raw dict from a YAML file asynchronously.
+
+        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}")
+
+            async with aiofiles.open(path_obj, "r", encoding="utf-8") as f:
+                content = await f.read()
+                data = yaml.safe_load(content)
+
+            if not isinstance(data, dict):
+                raise ManifestSyntaxError(f"Invalid YAML content in {path}: must be a dictionary.")
 
             ManifestLoader._normalize_data(data)
 
@@ -71,8 +103,7 @@ class ManifestLoader:
 
     @staticmethod
     def load_from_file(path: Union[str, Path]) -> AgentDefinition:
-        """
-        Loads the agent manifest from a YAML file.
+        """Loads the agent manifest from a YAML file.
 
         Args:
             path: The path to the agent.yaml file.
@@ -89,8 +120,7 @@ class ManifestLoader:
 
     @staticmethod
     def load_from_dict(data: dict[str, Any]) -> AgentDefinition:
-        """
-        Converts a dictionary into an AgentDefinition model.
+        """Converts a dictionary into an AgentDefinition model.
 
         Args:
             data: The raw dictionary.
@@ -115,11 +145,14 @@ class ManifestLoader:
 
     @staticmethod
     def _normalize_data(data: dict[str, Any]) -> None:
-        """
-        Normalizes the data dictionary in place.
-        Specifically strips 'v' or 'V' from version strings.
+        """Normalizes the data dictionary in place.
+
+        Specifically strips 'v' or 'V' from version strings recursively until clean.
         """
         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:]
+            if isinstance(version, str):
+                # Recursively strip leading 'v' or 'V'
+                while version and version[0] in ("v", "V"):
+                    version = version[1:]
+                data["metadata"]["version"] = version

coreason_manifest/main.py

@@ -1,16 +1,17 @@
-# 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
+# Prosperity-3.0
+"""Main module for coreason_manifest.
+
+This module is primarily used for testing and demonstration purposes.
+"""
 
 from coreason_manifest.utils.logger import logger
 
 
 def hello_world() -> str:
+    """Returns a hello world string.
+
+    Returns:
+        "Hello World!" string.
+    """
     logger.info("Hello World!")
     return "Hello World!"

coreason_manifest/models.py

@@ -1,4 +1,10 @@
 # Prosperity-3.0
+"""Pydantic models for the Coreason Manifest system.
+
+These models define the structure and validation rules for the Agent Manifest
+(OAS). They represent the source of truth for Agent definitions.
+"""
+
 from __future__ import annotations
 
 from datetime import datetime
@@ -27,7 +33,14 @@ SEMVER_REGEX = (
 
 
 def normalize_version(v: str) -> str:
-    """Normalize version string by recursively stripping 'v' or 'V' prefix."""
+    """Normalize version string by recursively stripping 'v' or 'V' prefix.
+
+    Args:
+        v: The version string to normalize.
+
+    Returns:
+        The normalized version string without 'v' prefix.
+    """
     while v.lower().startswith("v"):
         v = v[1:]
     return v
@@ -56,7 +69,15 @@ StrictUri = Annotated[
 
 
 class AgentMetadata(BaseModel):
-    """Metadata for the Agent."""
+    """Metadata for the Agent.
+
+    Attributes:
+        id: Unique Identifier for the Agent (UUID).
+        version: Semantic Version of the Agent.
+        name: Name of the Agent.
+        author: Author of the Agent.
+        created_at: Creation timestamp (ISO 8601).
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -68,7 +89,12 @@ class AgentMetadata(BaseModel):
 
 
 class AgentInterface(BaseModel):
-    """Interface definition for the Agent."""
+    """Interface definition for the Agent.
+
+    Attributes:
+        inputs: Typed arguments the agent accepts (JSON Schema).
+        outputs: Typed structure of the result.
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -77,7 +103,12 @@ class AgentInterface(BaseModel):
 
 
 class Step(BaseModel):
-    """A single step in the execution graph."""
+    """A single step in the execution graph.
+
+    Attributes:
+        id: Unique identifier for the step.
+        description: Description of the step.
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -86,7 +117,12 @@ class Step(BaseModel):
 
 
 class ModelConfig(BaseModel):
-    """LLM Configuration parameters."""
+    """LLM Configuration parameters.
+
+    Attributes:
+        model: The LLM model identifier.
+        temperature: Temperature for generation.
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -95,7 +131,12 @@ class ModelConfig(BaseModel):
 
 
 class AgentTopology(BaseModel):
-    """Topology of the Agent execution."""
+    """Topology of the Agent execution.
+
+    Attributes:
+        steps: A directed acyclic graph (DAG) of execution steps.
+        llm_config: Specific LLM parameters.
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -105,7 +146,17 @@ class AgentTopology(BaseModel):
     @field_validator("steps")
     @classmethod
     def validate_unique_step_ids(cls, v: Tuple[Step, ...]) -> Tuple[Step, ...]:
-        """Ensure all step IDs are unique."""
+        """Ensure all step IDs are unique.
+
+        Args:
+            v: The tuple of steps to validate.
+
+        Returns:
+            The validated tuple of steps.
+
+        Raises:
+            ValueError: If duplicate step IDs are found.
+        """
         ids = [step.id for step in v]
         if len(ids) != len(set(ids)):
             # Find duplicates
@@ -120,7 +171,12 @@ class AgentTopology(BaseModel):
 
 
 class AgentDependencies(BaseModel):
-    """External dependencies for the Agent."""
+    """External dependencies for the Agent.
+
+    Attributes:
+        tools: List of MCP capability URIs required.
+        libraries: List of Python packages required (if code execution is allowed).
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -133,7 +189,15 @@ class AgentDependencies(BaseModel):
 
 
 class AgentDefinition(BaseModel):
-    """The Root Object for the CoReason Agent Manifest."""
+    """The Root Object for the CoReason Agent Manifest.
+
+    Attributes:
+        metadata: Metadata for the Agent.
+        interface: Interface definition for the Agent.
+        topology: Topology of the Agent execution.
+        dependencies: External dependencies for the Agent.
+        integrity_hash: SHA256 hash of the source code.
+    """
 
     model_config = ConfigDict(
         extra="forbid",

coreason_manifest/policy.py

@@ -1,4 +1,10 @@
 # Prosperity-3.0
+"""Policy enforcement functionality using Open Policy Agent (OPA).
+
+This module provides the `PolicyEnforcer` class, which interacts with OPA to
+evaluate agent definitions against compliance policies defined in Rego.
+"""
+
 from __future__ import annotations
 
 import json
@@ -11,8 +17,7 @@ from coreason_manifest.errors import PolicyViolationError
 
 
 class PolicyEnforcer:
-    """
-    Component C: PolicyEnforcer (The Compliance Officer).
+    """Component C: PolicyEnforcer (The Compliance Officer).
 
     Responsibility:
       - Evaluate the agent against the compliance.rego policy file using OPA.
@@ -24,13 +29,15 @@ class PolicyEnforcer:
         opa_path: str = "opa",
         data_paths: Optional[List[str | Path]] = None,
     ) -> None:
-        """
-        Initialize the PolicyEnforcer.
+        """Initialize the PolicyEnforcer.
 
         Args:
             policy_path: Path to the Rego policy file.
             opa_path: Path to the OPA executable. Defaults to "opa" (expected in PATH).
             data_paths: List of paths to data files (e.g. JSON/YAML) to be loaded by OPA.
+
+        Raises:
+            FileNotFoundError: If OPA, policy file, or data files are not found.
         """
         self.policy_path = Path(policy_path)
         self.data_paths = [Path(p) for p in data_paths] if data_paths else []
@@ -38,15 +45,15 @@ class PolicyEnforcer:
         # Validate OPA executable
         # If opa_path is a simple name (like "opa"), use shutil.which to find it
         if "/" not in str(opa_path) and "\\" not in str(opa_path):
-            resolved_opa = shutil.which(opa_path)
+            resolved_opa: Optional[str] = shutil.which(opa_path)
             if not resolved_opa:
                 raise FileNotFoundError(f"OPA executable not found in PATH: {opa_path}")
-            self.opa_path = resolved_opa
+            self.opa_path: str = resolved_opa
         else:
             # If it's a path, check existence
             if not Path(opa_path).exists():
                 raise FileNotFoundError(f"OPA executable not found at: {opa_path}")
-            self.opa_path = opa_path
+            self.opa_path = str(opa_path)
 
         if not self.policy_path.exists():
             raise FileNotFoundError(f"Policy file not found: {self.policy_path}")
@@ -56,8 +63,7 @@ class PolicyEnforcer:
                 raise FileNotFoundError(f"Data file not found: {path}")
 
     def evaluate(self, agent_data: dict[str, Any]) -> None:
-        """
-        Evaluates the agent data against the policy.
+        """Evaluates the agent data against the policy.
 
         Args:
             agent_data: The dictionary representation of the AgentDefinition.

coreason_manifest/schemas/agent.schema.json

@@ -2,7 +2,7 @@
   "$defs": {
     "AgentDependencies": {
       "additionalProperties": false,
-      "description": "External dependencies for the Agent.",
+      "description": "External dependencies for the Agent.\n\nAttributes:\n    tools: List of MCP capability URIs required.\n    libraries: List of Python packages required (if code execution is allowed).",
       "properties": {
         "tools": {
           "description": "List of MCP capability URIs required.",
@@ -28,7 +28,7 @@
     },
     "AgentInterface": {
       "additionalProperties": false,
-      "description": "Interface definition for the Agent.",
+      "description": "Interface definition for the Agent.\n\nAttributes:\n    inputs: Typed arguments the agent accepts (JSON Schema).\n    outputs: Typed structure of the result.",
       "properties": {
         "inputs": {
           "additionalProperties": true,
@@ -52,7 +52,7 @@
     },
     "AgentMetadata": {
       "additionalProperties": false,
-      "description": "Metadata for the Agent.",
+      "description": "Metadata for the Agent.\n\nAttributes:\n    id: Unique Identifier for the Agent (UUID).\n    version: Semantic Version of the Agent.\n    name: Name of the Agent.\n    author: Author of the Agent.\n    created_at: Creation timestamp (ISO 8601).",
       "properties": {
         "id": {
           "description": "Unique Identifier for the Agent (UUID).",
@@ -97,7 +97,7 @@
     },
     "AgentTopology": {
       "additionalProperties": false,
-      "description": "Topology of the Agent execution.",
+      "description": "Topology of the Agent execution.\n\nAttributes:\n    steps: A directed acyclic graph (DAG) of execution steps.\n    llm_config: Specific LLM parameters.",
       "properties": {
         "steps": {
           "description": "A directed acyclic graph (DAG) of execution steps.",
@@ -121,7 +121,7 @@
     },
     "ModelConfig": {
       "additionalProperties": false,
-      "description": "LLM Configuration parameters.",
+      "description": "LLM Configuration parameters.\n\nAttributes:\n    model: The LLM model identifier.\n    temperature: Temperature for generation.",
       "properties": {
         "model": {
           "description": "The LLM model identifier.",
@@ -145,7 +145,7 @@
     },
     "Step": {
       "additionalProperties": false,
-      "description": "A single step in the execution graph.",
+      "description": "A single step in the execution graph.\n\nAttributes:\n    id: Unique identifier for the step.\n    description: Description of the step.",
       "properties": {
         "id": {
           "description": "Unique identifier for the step.",

coreason_manifest/server.py

@@ -0,0 +1,123 @@
+from contextlib import asynccontextmanager
+from importlib import resources
+from pathlib import Path
+from typing import AsyncIterator, List, Optional, Union
+
+from fastapi import FastAPI, HTTPException, Request, status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from coreason_manifest.engine import ManifestConfig, ManifestEngineAsync
+from coreason_manifest.errors import ManifestSyntaxError, PolicyViolationError
+
+
+# Response Model
+class ValidationResponse(BaseModel):
+    valid: bool
+    agent_id: Optional[str] = None
+    version: Optional[str] = None
+    policy_violations: List[str] = Field(default_factory=list)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    # Locate policies
+    policy_path: Optional[Path] = None
+    tbom_path: Optional[Path] = None
+
+    # 1. Check local directory (Docker runtime with COPY or relative dev path)
+    # In Docker we will COPY to /app/policies/ or ./policies/ relative to WORKDIR
+    # We'll check common locations.
+    possible_dirs = [
+        Path("policies"),
+        Path("/app/policies"),
+        Path("src/coreason_manifest/policies"),  # Dev from root
+    ]
+
+    for d in possible_dirs:
+        if (d / "compliance.rego").exists():
+            policy_path = d / "compliance.rego"
+            if (d / "tbom.json").exists():
+                tbom_path = d / "tbom.json"
+            break
+
+    # 2. Fallback to package resources
+    resource_context = None
+    if not policy_path:
+        try:
+            # Check if it exists as a resource
+            ref = resources.files("coreason_manifest.policies").joinpath("compliance.rego")
+            if ref.is_file():
+                resource_context = resources.as_file(ref)
+                policy_path = resource_context.__enter__()
+                # Check for TBOM in same dir if possible, or ignore for fallback
+        except Exception:
+            pass
+
+    # If still not found, fail.
+    if not policy_path:
+        raise RuntimeError("Could not locate compliance.rego policy file.")
+
+    config = ManifestConfig(
+        policy_path=policy_path,
+        tbom_path=tbom_path,
+        opa_path="opa",  # Assumes OPA is in PATH (installed via Dockerfile)
+    )
+
+    engine = ManifestEngineAsync(config)
+
+    try:
+        async with engine:
+            app.state.engine = engine
+            yield
+    finally:
+        if resource_context:
+            resource_context.__exit__(None, None, None)
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/validate", response_model=ValidationResponse)  # type: ignore[misc]
+async def validate_manifest(request: Request) -> Union[ValidationResponse, JSONResponse]:
+    engine: ManifestEngineAsync = app.state.engine
+
+    try:
+        raw_body = await request.json()
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid JSON body") from None
+
+    try:
+        agent_def = await engine.validate_manifest_dict(raw_body)
+        return ValidationResponse(
+            valid=True,
+            agent_id=str(agent_def.metadata.id),
+            version=agent_def.metadata.version,
+            policy_violations=[],
+        )
+    except ManifestSyntaxError as e:
+        # Return 422 with the error
+        resp = ValidationResponse(valid=False, policy_violations=[f"Syntax Error: {str(e)}"])
+        return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=resp.model_dump())
+    except PolicyViolationError as e:
+        resp = ValidationResponse(valid=False, policy_violations=e.violations)
+        return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=resp.model_dump())
+
+
+@app.get("/health")  # type: ignore[misc]
+async def health_check() -> dict[str, str]:
+    engine: ManifestEngineAsync = app.state.engine
+    policy_version = "unknown"
+    try:
+        import hashlib
+
+        # policy_path is guaranteed to exist by lifespan check
+        policy_path = Path(engine.config.policy_path)
+        if policy_path.exists():
+            with open(policy_path, "rb") as f:
+                digest = hashlib.sha256(f.read()).hexdigest()[:8]
+            policy_version = digest
+    except Exception:
+        pass
+
+    return {"status": "active", "policy_version": policy_version}

coreason_manifest/validator.py

@@ -1,4 +1,10 @@
 # Prosperity-3.0
+"""Schema validation functionality.
+
+This module provides the `SchemaValidator` class, which uses JSON Schema to
+validate the structure and types of agent definitions.
+"""
+
 from __future__ import annotations
 
 import json
@@ -11,8 +17,7 @@ from coreason_manifest.errors import ManifestSyntaxError
 
 
 class SchemaValidator:
-    """
-    Component B: SchemaValidator (The Structural Engineer).
+    """Component B: SchemaValidator (The Structural Engineer).
 
     Responsibility:
       - Validate the dictionary against the Master JSON Schema.
@@ -24,7 +29,14 @@ class SchemaValidator:
         self.schema = self._load_schema()
 
     def _load_schema(self) -> dict[str, Any]:
-        """Loads the JSON schema from the package resources."""
+        """Loads the JSON schema from the package resources.
+
+        Returns:
+            The JSON schema dictionary.
+
+        Raises:
+            ManifestSyntaxError: If the schema file cannot be loaded or is invalid.
+        """
         try:
             schema_path = files("coreason_manifest.schemas").joinpath("agent.schema.json")
             with schema_path.open("r", encoding="utf-8") as f:
@@ -36,14 +48,13 @@ class SchemaValidator:
             raise ManifestSyntaxError(f"Failed to load agent schema: {e}") from e
 
     def validate(self, data: dict[str, Any]) -> bool:
-        """
-        Validates the given dictionary against the agent schema.
+        """Validates the given dictionary against the agent schema.
 
         Args:
             data: The raw dictionary to validate.
 
         Returns:
-            bool: True if validation passes.
+            True if validation passes.
 
         Raises:
             ManifestSyntaxError: If validation fails.

{coreason_manifest-0.2.0.dist-info → coreason_manifest-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coreason_manifest
-Version: 0.2.0
+Version: 0.4.0
 Summary: This package is the definitive source of truth. If it isn't in the manifest, it doesn't exist. If it violates the manifest, it doesn't run.
 License: # The Prosperity Public License 3.0.0
          
@@ -67,48 +67,74 @@ Requires-Python: >=3.11
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: OS Independent
+Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
+Requires-Dist: anyio (>=4.3.0,<5.0.0)
+Requires-Dist: fastapi (>=0.111.0,<0.112.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
 Requires-Dist: jsonschema (>=4.25.1,<5.0.0)
 Requires-Dist: loguru (>=0.7.2,<0.8.0)
 Requires-Dist: pydantic (>=2.12.5,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: uvicorn (>=0.30.1,<0.31.0)
 Project-URL: Documentation, https://github.com/CoReason-AI/coreason_manifest
 Project-URL: Homepage, https://github.com/CoReason-AI/coreason_manifest
 Project-URL: Repository, https://github.com/CoReason-AI/coreason_manifest
 Description-Content-Type: text/markdown
 
-# coreason-manifest
+# Coreason Manifest
 
-This package is the definitive source of truth. If it isn't in the manifest, it doesn't exist. If it violates the manifest, it doesn't run.
+The definitive source of truth for CoReason-AI Asset definitions. "The Blueprint."
 
-[![CI](https://github.com/CoReason-AI/coreason_manifest/actions/workflows/ci.yml/badge.svg)](https://github.com/CoReason-AI/coreason_manifest/actions/workflows/ci.yml)
+[![License: Prosperity 3.0](https://img.shields.io/badge/license-Prosperity%203.0-blue)](https://github.com/CoReason-AI/coreason-manifest)
+[![Build Status](https://github.com/CoReason-AI/coreason-manifest/actions/workflows/ci.yml/badge.svg)](https://github.com/CoReason-AI/coreason-manifest/actions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Documentation](https://img.shields.io/badge/docs-product_requirements-informational)](docs/product_requirements.md)
 
-## Getting Started
+## Overview
 
-### Prerequisites
+`coreason-manifest` acts as the validator for the "Agent Development Lifecycle" (ADLC). It ensures that every Agent produced meets strict GxP and security standards. If it isn't in the manifest, it doesn't exist. If it violates the manifest, it doesn't run.
 
-- Python 3.12+
-- Poetry
+## Features
 
-### Installation
+*   **Open Agent Specification (OAS) Validation:** Parses and validates agent definitions against a strict schema.
+*   **Compliance Enforcement:** Uses Open Policy Agent (OPA) / Rego to enforce complex business rules and allowlists.
+*   **Integrity Verification:** Calculates and verifies SHA256 hashes of the agent's source code to prevent tampering.
+*   **Dependency Pinning:** Enforces strict version pinning for all library dependencies.
+*   **Trusted Bill of Materials (TBOM):** Validates libraries against an approved list.
+*   **Compliance Microservice:** Can be run as a standalone API server (Service C) for centralized validation.
 
-1.  Clone the repository:
-    ```sh
-    git clone https://github.com/example/example.git
-    cd my_python_project
-    ```
-2.  Install dependencies:
-    ```sh
-    poetry install
-    ```
+## Installation
 
-### Usage
+```bash
+pip install coreason-manifest
+```
 
--   Run the linter:
-    ```sh
-    poetry run pre-commit run --all-files
-    ```
--   Run the tests:
-    ```sh
-    poetry run pytest
-    ```
+## Usage
+
+`coreason-manifest` supports two modes: **Library (CLI)** and **Server (Microservice)**.
+
+### 1. Library Usage
+
+Use the python library to validate local agent files and verify source integrity.
+
+```python
+from coreason_manifest import ManifestEngine, ManifestConfig
+
+# Initialize and Validate
+config = ManifestConfig(policy_path="./policies/compliance.rego")
+engine = ManifestEngine(config)
+agent_def = engine.load_and_validate("agent.yaml", "./src")
+```
+
+### 2. Server Mode
+
+Run the package as a FastAPI server to provide a centralized compliance API.
+
+```bash
+uvicorn coreason_manifest.server:app --host 0.0.0.0 --port 8000
+```
+
+For full details, see the [Usage Documentation](docs/usage.md).
+
+For detailed requirements and architecture, please refer to the [Product Requirements](docs/product_requirements.md) or [Requirements](docs/requirements.md).
 

coreason_manifest-0.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+coreason_manifest/__init__.py,sha256=R07xUHw9RWdWQPh7OWbpMT8kkzkEWfEI5hizu_5UNck,1528
+coreason_manifest/engine.py,sha256=ENAkRuGFd1uY_5u4EYEsTZUMrqw5HgijKtkF9lk-E-c,8199
+coreason_manifest/errors.py,sha256=CKFWSucncoPLYUJcsuXtLIfneyr2d89oHRTiWPT4psU,1437
+coreason_manifest/integrity.py,sha256=CMBaa2A8DpC9hDSO-aj-YOzss6if1CajaeLEmTC703c,5344
+coreason_manifest/loader.py,sha256=cc1iV-yKfH3gyPaB-P_7AaTaPYkgj1NoDsJz4PReTgo,5479
+coreason_manifest/main.py,sha256=YQO98w2wxkfNs-DpSLmiDTs9DtUeGsC48GEfbElXVPk,357
+coreason_manifest/models.py,sha256=pJIuEtCiiXcxxi2zRwken4ph2GFa66YHnOqHyySR5sU,6828
+coreason_manifest/policies/compliance.rego,sha256=-drMuno6YkGOXKjvdLWawCZWK8iUxY7OcXpoXa_9Oyo,3035
+coreason_manifest/policies/tbom.json,sha256=rSn4V44_IdFqCC86J3Jc31qQKTV4J5BdmyO0CI4iOu0,167
+coreason_manifest/policy.py,sha256=vvEivq5HSjv-bMSrZ5VMM3eTomYFp39SBtuFajG9RU4,5009
+coreason_manifest/schemas/__init__.py,sha256=9TMs6jWKCIewAKkj-u0tq9c6N_-0CU6b5s9q6MTS6v4,17
+coreason_manifest/schemas/agent.schema.json,sha256=wdNYmpyCUEKR1UgMmRV4ZSQOm7xvnmSg5lvhQ3JKvSg,6368
+coreason_manifest/server.py,sha256=kHrReqoEx4sL5k5GQN7yNwLgvfnOl1kZf-dQehseuO4,4251
+coreason_manifest/utils/__init__.py,sha256=Q9gXiBtX3mD9GTu4z0JDHSHkbXC-MRHagrOaOmRH_1Q,435
+coreason_manifest/utils/logger.py,sha256=A7E6Hd_Jk1XDUajNEJQl-WtUv9M2LT76b4_TsbxnILw,1227
+coreason_manifest/validator.py,sha256=v33EzKroRwLEjZeuRRpTB7cqB38op3DV2EZpZhJ80a0,2240
+coreason_manifest-0.4.0.dist-info/METADATA,sha256=aQdNN6nn8Fi4g_eSj17mKrtf_SkO4l0XembzP85TXlE,7229
+coreason_manifest-0.4.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+coreason_manifest-0.4.0.dist-info/licenses/LICENSE,sha256=3tYb7ZQe7sVXcbNmX22fDESFjOSIlCZodUGpZMkuSlk,3063
+coreason_manifest-0.4.0.dist-info/licenses/NOTICE,sha256=tqzUyP9VTCGxoHLgBI0AC1i0G7m_PSyESFL8Jwuw0dA,610
+coreason_manifest-0.4.0.dist-info/RECORD,,

{coreason_manifest-0.2.0.dist-info → coreason_manifest-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: poetry-core 2.3.0
 Root-Is-Purelib: true
 Tag: py3-none-any

coreason_manifest-0.2.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-coreason_manifest/__init__.py,sha256=NeRYnUf8mbcBbAwplVfpqHv1LN9ElFbrGck0ZdGj0kA,897
-coreason_manifest/engine.py,sha256=kY4TrtvHANvAK8yvB0CNjg9ZT5wjMrubykF6InYjujw,4212
-coreason_manifest/errors.py,sha256=B3fEYR3jxR3iZulu4qeS3UzHFsZDTImBTQWZUvUQkKM,684
-coreason_manifest/integrity.py,sha256=AYprazGTey4EY1tjH7774-pdL8trmc6jOPWf1atGV-8,5104
-coreason_manifest/loader.py,sha256=5MGrlb9QYhV1-ovfGT5UdCW-t6Ar1HPUV6cHCSkSx6U,4670
-coreason_manifest/main.py,sha256=2pj9LX91WQFvbsykANCSc0-5PP4peBYfIcxa8IMUiaA,549
-coreason_manifest/models.py,sha256=C73chpjgUuvDxglEj0FURPoNhMoyVlyZpput7QAg1rk,5110
-coreason_manifest/policies/compliance.rego,sha256=-drMuno6YkGOXKjvdLWawCZWK8iUxY7OcXpoXa_9Oyo,3035
-coreason_manifest/policies/tbom.json,sha256=rSn4V44_IdFqCC86J3Jc31qQKTV4J5BdmyO0CI4iOu0,167
-coreason_manifest/policy.py,sha256=Tu_FL1DwNfKky_Nash7KqzVs1oV8oZCgS4ppUV7tQbs,4687
-coreason_manifest/schemas/__init__.py,sha256=9TMs6jWKCIewAKkj-u0tq9c6N_-0CU6b5s9q6MTS6v4,17
-coreason_manifest/schemas/agent.schema.json,sha256=OqJlTp2_GocK05kPAfpyK807NELOQPDikfwn1yfl3kI,5561
-coreason_manifest/utils/__init__.py,sha256=Q9gXiBtX3mD9GTu4z0JDHSHkbXC-MRHagrOaOmRH_1Q,435
-coreason_manifest/utils/logger.py,sha256=A7E6Hd_Jk1XDUajNEJQl-WtUv9M2LT76b4_TsbxnILw,1227
-coreason_manifest/validator.py,sha256=OzLLjqRHLxXfKQeOwEVj16fHWfdif8of5r4b_mCOR8g,1919
-coreason_manifest-0.2.0.dist-info/METADATA,sha256=1eiB1e0RnGDKF4YFy0wQgoGgOGegxyvyEBABDYSAIr4,5238
-coreason_manifest-0.2.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-coreason_manifest-0.2.0.dist-info/licenses/LICENSE,sha256=3tYb7ZQe7sVXcbNmX22fDESFjOSIlCZodUGpZMkuSlk,3063
-coreason_manifest-0.2.0.dist-info/licenses/NOTICE,sha256=tqzUyP9VTCGxoHLgBI0AC1i0G7m_PSyESFL8Jwuw0dA,610
-coreason_manifest-0.2.0.dist-info/RECORD,,