coreason-manifest 0.2.0__tar.gz → 0.4.0__tar.gz

{coreason_manifest-0.2.0 → coreason_manifest-0.4.0}/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,56 @@
+# Coreason Manifest
+
+The definitive source of truth for CoReason-AI Asset definitions. "The Blueprint."
+
+[![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)
+
+## Overview
+
+`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.
+
+## Features
+
+*   **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.
+
+## Installation
+
+```bash
+pip install coreason-manifest
+```
+
+## 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.2.0 → coreason_manifest-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "coreason_manifest"
-version = "0.2.0"
+version = "0.4.0"
 description = "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."
 authors = ["Gowtham A Rao <gowtham.rao@coreason.ai>"]
 license = "Prosperity-3.0"
@@ -13,6 +13,11 @@ loguru = "^0.7.2"
 pydantic = "^2.12.5"
 jsonschema = "^4.25.1"
 pyyaml = "^6.0.3"
+anyio = "^4.3.0"
+httpx = "^0.27.0"
+aiofiles = "^23.2.1"
+fastapi = "^0.111.0"
+uvicorn = "^0.30.1"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.2.2"
@@ -23,6 +28,8 @@ mkdocs = "^1.6.0"
 mkdocs-material = "^9.5.26"
 pydantic = "^2.12.5"
 mypy = "^1.19.1"
+types-aiofiles = "^23.2.0"
+pytest-asyncio = "^0.23.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -30,7 +37,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "coreason_manifest"
-version = "0.2.0"
+version = "0.4.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -66,6 +73,7 @@ plugins = ["pydantic.mypy"]
 [tool.pytest.ini_options]
 addopts = "--cov=src --cov-report=term-missing --cov-fail-under=100"
 testpaths = ["tests"]
+asyncio_mode = "auto"
 
 [tool.coverage.run]
 omit = ["tests/*", "/tmp/*"]

{coreason_manifest-0.2.0 → coreason_manifest-0.4.0}/src/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-0.4.0/src/coreason_manifest/engine.py

@@ -0,0 +1,222 @@
+# 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 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
+from coreason_manifest.utils.logger import logger
+from coreason_manifest.validator import SchemaValidator
+
+
+@dataclass
+class ManifestConfig:
+    """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"
+    tbom_path: Optional[Union[str, Path]] = None
+    extra_data_paths: List[Union[str, Path]] = field(default_factory=list)
+
+
+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 ManifestEngineAsync.
+
+        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,
+        )
+
+    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
+
+        Does NOT perform Integrity Check (hashing).
+
+        Args:
+            raw_data: The raw dictionary of the manifest.
+
+        Returns:
+            AgentDefinition: The fully validated agent definition.
+
+        Raises:
+            ManifestSyntaxError: If structure or schema is invalid.
+            PolicyViolationError: If business rules are violated.
+        """
+        # 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) (CPU bound)
+        logger.debug("Converting to AgentDefinition...")
+        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 (Subprocess / Blocking)
+        logger.debug("Enforcing Policies...")
+        # We assume policy is checked against the Normalized data (model dumped back to dict)
+        normalized_data = agent_def.model_dump(mode="json")
+        start_time = time.perf_counter()
+        try:
+            # 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:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            logger.info(f"Policy Check: Fail - {duration_ms:.2f}ms")
+            raise
+
+        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 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-0.4.0/src/coreason_manifest/errors.py

@@ -0,0 +1,53 @@
+# Prosperity-3.0
+"""Exceptions for the Coreason Manifest system.
+
+This module defines the hierarchy of exceptions raised by the package.
+"""
+
+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.
+
+    This includes YAML parsing errors and JSON Schema validation failures.
+    """
+
+    pass
+
+
+class PolicyViolationError(ManifestError):
+    """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.
+
+    This indicates that the source code may have been tampered with or changed
+    without updating the manifest's integrity hash.
+    """
+
+    pass

{coreason_manifest-0.2.0 → coreason_manifest-0.4.0}/src/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.