coreason-manifest 0.9.0__tar.gz → 0.10.0__tar.gz

{coreason_manifest-0.9.0 → coreason_manifest-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coreason_manifest
-Version: 0.9.0
+Version: 0.10.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
          
@@ -87,17 +87,31 @@ The definitive source of truth for CoReason-AI Asset definitions. "The Blueprint
 
 ## 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.
+`coreason-manifest` serves as the **Shared Kernel** for the Coreason ecosystem. It contains the canonical Pydantic definitions, schemas, and data structures for Agents, Workflows (Recipes), and Auditing.
+
+It provides the **"Blueprint"** that all other services (Builder, Engine, Simulator) rely on. It focuses on strict typing, schema validation, and serialization, ensuring that if it isn't in the manifest, it doesn't exist.
 
 ## 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.
-*   **Automatic Schema Generation:** Inspects Python functions to generate Agent Interfaces, automatically handling `UserContext` injection.
-*   **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.
+*   **Open Agent Specification (OAS):** Strict Pydantic models for Agent definitions (`AgentDefinition`).
+*   **Strict Typing:** Enforces type safety and immutable structures for critical interfaces.
+*   **Enhanced Serialization:** Includes `CoReasonBaseModel` to ensure consistent JSON serialization of complex types like `UUID` and `datetime`.
+*   **Event Protocol:** Defines the `GraphEvent` and `CloudEvent` structures for real-time communication.
+*   **Simulation Schemas:** Provides standard models for `SimulationScenario`, `AdversaryProfile`, and `SimulationTrace`.
+*   **Audit & Compliance:** Defines the `AuditLog` structure for tamper-evident record keeping.
+*   **Ergonomic Factory Methods:** Simplified construction of `ChatMessage` and `GenAIOperation`.
+*   **Token Arithmetic:** Support for `+` and `+=` operators on `GenAITokenUsage`.
+*   **Flexible Tooling:** `ToolCallRequestPart` accepts JSON strings with automatic parsing.
+*   **Enhanced Tracing:** `ReasoningTrace` includes flexible metadata for execution state.
+
+## Serialization & Base Model
+
+All core definitions (`AgentDefinition`, `RecipeManifest`, `GraphTopology`, `AuditLog`) inherit from `CoReasonBaseModel`. This provides a consistent interface for serialization, solving common Pydantic v2 issues with `UUID` and `datetime`.
+
+*   Use `.dump()` to get a JSON-compatible dictionary (where UUIDs/datetimes are strings).
+*   Use `.to_json()` to get a JSON string.
+
+For a detailed rationale, see [docs/coreason_base_model_rationale.md](docs/coreason_base_model_rationale.md).
 
 ## Installation
 
@@ -107,30 +121,78 @@ 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.
+This library is used to define and validate Agent configurations programmatically.
 
 ```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
+import uuid
+from datetime import datetime, timezone
+from coreason_manifest.definitions.agent import (
+    AgentDefinition,
+    AgentMetadata,
+    AgentInterface,
+    AgentRuntimeConfig,
+    ModelConfig,
+    AgentDependencies,
+    ToolRequirement,
+    ToolRiskLevel,
+    PolicyConfig,
+    ObservabilityConfig,
+    TraceLevel
+)
+
+# 1. Define Metadata
+metadata = AgentMetadata(
+    id=uuid.uuid4(),
+    version="1.0.0",  # Strict SemVer
+    name="Research Agent",
+    author="Coreason AI",
+    created_at=datetime.now(timezone.utc)
+)
+
+# 2. Instantiate Agent
+agent = AgentDefinition(
+    metadata=metadata,
+    interface=AgentInterface(
+        inputs={"topic": {"type": "string"}},
+        outputs={"summary": {"type": "string"}}
+    ),
+    config=AgentRuntimeConfig(
+        model_config=ModelConfig(
+            model="gpt-4",
+            temperature=0.0,
+            system_prompt="You are a helpful assistant."
+        )
+    ),
+    dependencies=AgentDependencies(
+        tools=[
+            ToolRequirement(
+                uri="mcp://search-service/google",
+                hash="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",  # Valid SHA256
+                scopes=["search:read"],
+                risk_level=ToolRiskLevel.STANDARD
+            )
+        ],
+        libraries=("pandas==2.0.0",)
+    ),
+    policy=PolicyConfig(
+        budget_caps={"total_cost": 5.0}
+    ),
+    observability=ObservabilityConfig(
+        trace_level=TraceLevel.FULL,
+        retention_policy="90_days"
+    ),
+    # Mandatory Integrity Hash
+    integrity_hash="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+)
+
+print(f"Agent '{agent.metadata.name}' definition created and validated.")
 ```
 
 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).
+## Documentation
+
+*   [Frontend Integration](docs/frontend_integration.md): Communicating with the Coreason Engine.
+*   [Simulation Architecture](docs/simulation_architecture.md): Details on ATIF compatibility and GAIA scenarios.
+*   [Audit & Compliance](docs/audit_compliance.md): Details on EU AI Act compliance, Chain of Custody, and Integrity Hashing.
 

coreason_manifest-0.10.0/README.md

@@ -0,0 +1,119 @@
+# 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` serves as the **Shared Kernel** for the Coreason ecosystem. It contains the canonical Pydantic definitions, schemas, and data structures for Agents, Workflows (Recipes), and Auditing.
+
+It provides the **"Blueprint"** that all other services (Builder, Engine, Simulator) rely on. It focuses on strict typing, schema validation, and serialization, ensuring that if it isn't in the manifest, it doesn't exist.
+
+## Features
+
+*   **Open Agent Specification (OAS):** Strict Pydantic models for Agent definitions (`AgentDefinition`).
+*   **Strict Typing:** Enforces type safety and immutable structures for critical interfaces.
+*   **Enhanced Serialization:** Includes `CoReasonBaseModel` to ensure consistent JSON serialization of complex types like `UUID` and `datetime`.
+*   **Event Protocol:** Defines the `GraphEvent` and `CloudEvent` structures for real-time communication.
+*   **Simulation Schemas:** Provides standard models for `SimulationScenario`, `AdversaryProfile`, and `SimulationTrace`.
+*   **Audit & Compliance:** Defines the `AuditLog` structure for tamper-evident record keeping.
+*   **Ergonomic Factory Methods:** Simplified construction of `ChatMessage` and `GenAIOperation`.
+*   **Token Arithmetic:** Support for `+` and `+=` operators on `GenAITokenUsage`.
+*   **Flexible Tooling:** `ToolCallRequestPart` accepts JSON strings with automatic parsing.
+*   **Enhanced Tracing:** `ReasoningTrace` includes flexible metadata for execution state.
+
+## Serialization & Base Model
+
+All core definitions (`AgentDefinition`, `RecipeManifest`, `GraphTopology`, `AuditLog`) inherit from `CoReasonBaseModel`. This provides a consistent interface for serialization, solving common Pydantic v2 issues with `UUID` and `datetime`.
+
+*   Use `.dump()` to get a JSON-compatible dictionary (where UUIDs/datetimes are strings).
+*   Use `.to_json()` to get a JSON string.
+
+For a detailed rationale, see [docs/coreason_base_model_rationale.md](docs/coreason_base_model_rationale.md).
+
+## Installation
+
+```bash
+pip install coreason-manifest
+```
+
+## Usage
+
+This library is used to define and validate Agent configurations programmatically.
+
+```python
+import uuid
+from datetime import datetime, timezone
+from coreason_manifest.definitions.agent import (
+    AgentDefinition,
+    AgentMetadata,
+    AgentInterface,
+    AgentRuntimeConfig,
+    ModelConfig,
+    AgentDependencies,
+    ToolRequirement,
+    ToolRiskLevel,
+    PolicyConfig,
+    ObservabilityConfig,
+    TraceLevel
+)
+
+# 1. Define Metadata
+metadata = AgentMetadata(
+    id=uuid.uuid4(),
+    version="1.0.0",  # Strict SemVer
+    name="Research Agent",
+    author="Coreason AI",
+    created_at=datetime.now(timezone.utc)
+)
+
+# 2. Instantiate Agent
+agent = AgentDefinition(
+    metadata=metadata,
+    interface=AgentInterface(
+        inputs={"topic": {"type": "string"}},
+        outputs={"summary": {"type": "string"}}
+    ),
+    config=AgentRuntimeConfig(
+        model_config=ModelConfig(
+            model="gpt-4",
+            temperature=0.0,
+            system_prompt="You are a helpful assistant."
+        )
+    ),
+    dependencies=AgentDependencies(
+        tools=[
+            ToolRequirement(
+                uri="mcp://search-service/google",
+                hash="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",  # Valid SHA256
+                scopes=["search:read"],
+                risk_level=ToolRiskLevel.STANDARD
+            )
+        ],
+        libraries=("pandas==2.0.0",)
+    ),
+    policy=PolicyConfig(
+        budget_caps={"total_cost": 5.0}
+    ),
+    observability=ObservabilityConfig(
+        trace_level=TraceLevel.FULL,
+        retention_policy="90_days"
+    ),
+    # Mandatory Integrity Hash
+    integrity_hash="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+)
+
+print(f"Agent '{agent.metadata.name}' definition created and validated.")
+```
+
+For full details, see the [Usage Documentation](docs/usage.md).
+
+## Documentation
+
+*   [Frontend Integration](docs/frontend_integration.md): Communicating with the Coreason Engine.
+*   [Simulation Architecture](docs/simulation_architecture.md): Details on ATIF compatibility and GAIA scenarios.
+*   [Audit & Compliance](docs/audit_compliance.md): Details on EU AI Act compliance, Chain of Custody, and Integrity Hashing.

{coreason_manifest-0.9.0 → coreason_manifest-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "coreason_manifest"
-version = "0.9.0"
+version = "0.10.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"
@@ -32,7 +32,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "coreason_manifest"
-version = "0.9.0"
+version = "0.10.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.12"

coreason_manifest-0.10.0/src/coreason_manifest/__init__.py

@@ -0,0 +1,98 @@
+# 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 .definitions.agent import AgentDefinition, Persona
+from .definitions.audit import AuditLog
+from .definitions.events import (
+    ArtifactGenerated,
+    CloudEvent,
+    CouncilVote,
+    EdgeTraversed,
+    GraphEvent,
+    GraphEventArtifactGenerated,
+    GraphEventCouncilVote,
+    GraphEventEdgeActive,
+    GraphEventError,
+    GraphEventNodeDone,
+    GraphEventNodeInit,
+    GraphEventNodeRestored,
+    GraphEventNodeSkipped,
+    GraphEventNodeStart,
+    GraphEventNodeStream,
+    NodeCompleted,
+    NodeInit,
+    NodeRestored,
+    NodeSkipped,
+    NodeStarted,
+    NodeStream,
+    WorkflowError,
+    migrate_graph_event_to_cloud_event,
+)
+from .definitions.simulation import (
+    SimulationMetrics,
+    SimulationScenario,
+    SimulationStep,
+    SimulationTrace,
+    StepType,
+)
+from .definitions.simulation_config import AdversaryProfile, ChaosConfig, SimulationRequest
+from .definitions.topology import (
+    AgentNode,
+    Edge,
+    GraphTopology,
+    Node,
+    StateDefinition,
+    Topology,
+)
+from .recipes import RecipeManifest
+
+__all__ = [
+    "AgentDefinition",
+    "Persona",
+    "Topology",
+    "GraphTopology",
+    "Node",
+    "AgentNode",
+    "Edge",
+    "StateDefinition",
+    "GraphEvent",
+    "CloudEvent",
+    "GraphEventNodeInit",
+    "GraphEventNodeStart",
+    "GraphEventNodeDone",
+    "GraphEventNodeStream",
+    "GraphEventNodeSkipped",
+    "GraphEventNodeRestored",
+    "GraphEventEdgeActive",
+    "GraphEventCouncilVote",
+    "GraphEventError",
+    "GraphEventArtifactGenerated",
+    "NodeInit",
+    "NodeStarted",
+    "NodeCompleted",
+    "NodeStream",
+    "NodeSkipped",
+    "NodeRestored",
+    "WorkflowError",
+    "CouncilVote",
+    "ArtifactGenerated",
+    "EdgeTraversed",
+    "migrate_graph_event_to_cloud_event",
+    "SimulationScenario",
+    "SimulationTrace",
+    "SimulationStep",
+    "SimulationMetrics",
+    "StepType",
+    "AdversaryProfile",
+    "ChaosConfig",
+    "SimulationRequest",
+    "AuditLog",
+    "RecipeManifest",
+]

{coreason_manifest-0.9.0 → coreason_manifest-0.10.0}/src/coreason_manifest/definitions/__init__.py

@@ -1,4 +1,14 @@
-from .agent import AgentDefinition, AgentRuntimeConfig
+# 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 .agent import AgentDefinition, AgentRuntimeConfig, Persona
 from .events import (
     ArtifactGenerated,
     ArtifactGeneratedPayload,
@@ -26,6 +36,7 @@ from .events import (
 __all__ = [
     "AgentRuntimeConfig",
     "AgentDefinition",
+    "Persona",
     "GraphEvent",
     "NodeInit",
     "NodeStarted",

{coreason_manifest-0.9.0 → coreason_manifest-0.10.0}/src/coreason_manifest/definitions/agent.py

@@ -1,4 +1,13 @@
-# Prosperity-3.0
+# Copyright (c) 2025 CoReason, Inc.
+#
+# This software is proprietary and dual-licensed.
+# Licensed under the Prosperity Public License 3.0 (the "License").
+# A copy of the license is available at https://prosperitylicense.com/versions/3.0.0
+# For details, see the LICENSE file.
+# Commercial use beyond a 30-day trial requires a separate license.
+#
+# Source Code: https://github.com/CoReason-AI/coreason-manifest
+
 """Pydantic models for the Coreason Manifest system.
 
 These models define the structure and validation rules for the Agent Manifest
@@ -10,13 +19,12 @@ from __future__ import annotations
 from datetime import datetime
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Dict, List, Mapping, Optional, Tuple
+from typing import Any, Dict, List, Literal, Mapping, Optional, Tuple, Union
 from uuid import UUID
 
 from pydantic import (
     AfterValidator,
     AnyUrl,
-    BaseModel,
     ConfigDict,
     Field,
     PlainSerializer,
@@ -25,7 +33,8 @@ from pydantic import (
 )
 from typing_extensions import Annotated
 
-from coreason_manifest.definitions.topology import Edge, Node
+from coreason_manifest.definitions.base import CoReasonBaseModel
+from coreason_manifest.definitions.topology import Edge, Node, validate_edge_integrity
 
 # SemVer Regex pattern (simplified for standard SemVer)
 # Modified to accept optional 'v' or 'V' prefix (multiple allowed) for input normalization
@@ -72,7 +81,7 @@ StrictUri = Annotated[
 ]
 
 
-class AgentMetadata(BaseModel):
+class AgentMetadata(CoReasonBaseModel):
     """Metadata for the Agent.
 
     Attributes:
@@ -93,7 +102,23 @@ class AgentMetadata(BaseModel):
     requires_auth: bool = Field(default=False, description="Whether the agent requires user authentication.")
 
 
-class AgentInterface(BaseModel):
+class Persona(CoReasonBaseModel):
+    """Definition of an Agent Persona.
+
+    Attributes:
+        name: Name of the persona.
+        description: Description of the persona.
+        directives: List of specific instructions or directives.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(..., description="Name of the persona.")
+    description: str = Field(..., description="Description of the persona.")
+    directives: List[str] = Field(..., description="List of specific instructions or directives.")
+
+
+class AgentInterface(CoReasonBaseModel):
     """Interface definition for the Agent.
 
     Attributes:
@@ -108,21 +133,25 @@ class AgentInterface(BaseModel):
     injected_params: List[str] = Field(default_factory=list, description="List of parameters injected by the system.")
 
 
-class ModelConfig(BaseModel):
+class ModelConfig(CoReasonBaseModel):
     """LLM Configuration parameters.
 
     Attributes:
         model: The LLM model identifier.
         temperature: Temperature for generation.
+        system_prompt: The default system prompt/persona for the agent.
+        persona: The full persona definition (name, description, directives).
     """
 
     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.")
+    system_prompt: Optional[str] = Field(None, description="The default system prompt/persona for the agent.")
+    persona: Optional[Persona] = Field(None, description="The full persona definition (name, description, directives).")
 
 
-class AgentRuntimeConfig(BaseModel):
+class AgentRuntimeConfig(CoReasonBaseModel):
     """Configuration of the Agent execution.
 
     Attributes:
@@ -134,10 +163,36 @@ class AgentRuntimeConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    nodes: List[Node] = Field(..., description="A collection of execution units.")
-    edges: List[Edge] = Field(..., description="Directed connections defining control flow.")
-    entry_point: str = Field(..., description="The ID of the starting node.")
+    nodes: List[Node] = Field(default_factory=list, description="A collection of execution units.")
+    edges: List[Edge] = Field(default_factory=list, description="Directed connections defining control flow.")
+    entry_point: Optional[str] = Field(None, description="The ID of the starting node.")
     llm_config: ModelConfig = Field(..., alias="model_config", description="Specific LLM parameters.")
+    system_prompt: Optional[str] = Field(None, description="The global system prompt/instruction for the agent.")
+
+    @model_validator(mode="after")
+    def validate_topology_or_atomic(self) -> AgentRuntimeConfig:
+        """Ensure valid configuration: either a Graph or an Atomic Agent."""
+        has_nodes = len(self.nodes) > 0
+        has_entry = self.entry_point is not None
+
+        if has_nodes:
+            if not has_entry:
+                raise ValueError("Graph execution requires an 'entry_point'.")
+        else:
+            # Atomic Agent: Must have a system prompt (either global or in model_config)
+            has_global_prompt = self.system_prompt is not None
+            has_model_prompt = self.llm_config.system_prompt is not None
+
+            if not (has_global_prompt or has_model_prompt):
+                raise ValueError("Atomic Agents require a system_prompt (global or in model_config).")
+
+        return self
+
+    @model_validator(mode="after")
+    def validate_topology_integrity(self) -> AgentRuntimeConfig:
+        """Ensure that edges connect existing nodes."""
+        validate_edge_integrity(self.nodes, self.edges)
+        return self
 
     @field_validator("nodes")
     @classmethod
@@ -174,7 +229,7 @@ class ToolRiskLevel(str, Enum):
     CRITICAL = "critical"
 
 
-class ToolRequirement(BaseModel):
+class ToolRequirement(CoReasonBaseModel):
     """Requirement for an MCP tool.
 
     Attributes:
@@ -194,7 +249,25 @@ class ToolRequirement(BaseModel):
     risk_level: ToolRiskLevel = Field(..., description="The risk level of the tool.")
 
 
-class AgentDependencies(BaseModel):
+class InlineToolDefinition(CoReasonBaseModel):
+    """Definition of an inline tool.
+
+    Attributes:
+        name: Name of the tool.
+        description: Description of the tool.
+        parameters: JSON Schema of parameters.
+        type: The type of the tool (must be 'function').
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(..., description="Name of the tool.")
+    description: str = Field(..., description="Description of the tool.")
+    parameters: Dict[str, Any] = Field(..., description="JSON Schema of parameters.")
+    type: Literal["function"] = Field("function", description="The type of the tool (must be 'function').")
+
+
+class AgentDependencies(CoReasonBaseModel):
     """External dependencies for the Agent.
 
     Attributes:
@@ -204,13 +277,15 @@ class AgentDependencies(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    tools: List[ToolRequirement] = Field(default_factory=list, description="List of MCP tool requirements.")
+    tools: List[Union[ToolRequirement, InlineToolDefinition]] = Field(
+        default_factory=list, description="List of MCP tool requirements."
+    )
     libraries: Tuple[str, ...] = Field(
         default_factory=tuple, description="List of Python packages required (if code execution is allowed)."
     )
 
 
-class PolicyConfig(BaseModel):
+class PolicyConfig(CoReasonBaseModel):
     """Governance policy configuration.
 
     Attributes:
@@ -234,7 +309,7 @@ class TraceLevel(str, Enum):
     NONE = "none"
 
 
-class ObservabilityConfig(BaseModel):
+class ObservabilityConfig(CoReasonBaseModel):
     """Observability configuration.
 
     Attributes:
@@ -250,7 +325,7 @@ class ObservabilityConfig(BaseModel):
     encryption_key_id: Optional[str] = Field(None, description="Optional ID of the key used for log encryption.")
 
 
-class AgentDefinition(BaseModel):
+class AgentDefinition(CoReasonBaseModel):
     """The Root Object for the CoReason Agent Manifest.
 
     Attributes:
@@ -277,6 +352,9 @@ class AgentDefinition(BaseModel):
     dependencies: AgentDependencies
     policy: Optional[PolicyConfig] = Field(None, description="Governance policy configuration.")
     observability: Optional[ObservabilityConfig] = Field(None, description="Observability configuration.")
+    custom_metadata: Optional[Dict[str, Any]] = Field(
+        None, description="Container for arbitrary metadata extensions without breaking validation."
+    )
     integrity_hash: str = Field(
         ...,
         pattern=r"^[a-fA-F0-9]{64}$",