Metadata-Version: 2.4
Name: coreason_validator
Version: 0.5.1
Summary: Enforces structural integrity across the entire CoReason ecosystem
License: # The Prosperity Public License 3.0.0
         
         Contributor: CoReason, Inc.
         
         Source Code: https://github.com/CoReason-AI/coreason_validator
         
         ## Purpose
         
         This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
         
         ## Agreement
         
         In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
         
         ## Notices
         
         Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
         
         ## Commercial Trial
         
         Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
         
         ## Contributions Back
         
         Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
         
         ## Personal Uses
         
         Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
         
         ## Noncommercial Organizations
         
         Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
         
         ## Defense
         
         Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
         
         ## Copyright
         
         The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
         
         ## Patent
         
         The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
         
         ## Reliability
         
         The contributor can't revoke this license.
         
         ## Excuse
         
         You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
         
         ## No Liability
         
         ***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***
License-File: LICENSE
License-File: NOTICE
Author: Gowtham A Rao
Author-email: gowtham.rao@coreason.ai
Requires-Python: >=3.11
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Dist: anyio (>=4.12.1,<5.0.0)
Requires-Dist: coreason-identity
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: jsonschema (>=4.26.0,<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)
Project-URL: Documentation, https://github.com/CoReason-AI/coreason_validator
Project-URL: Homepage, https://github.com/CoReason-AI/coreason_validator
Project-URL: Repository, https://github.com/CoReason-AI/coreason_validator
Description-Content-Type: text/markdown

# coreason-validator

[![CI](https://github.com/CoReason-AI/coreason_validator/actions/workflows/ci.yml/badge.svg)](https://github.com/CoReason-AI/coreason_validator/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Prosperity%203.0-blue.svg)](https://prosperitylicense.com/versions/3.0.0)
[![Python](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue)](https://www.python.org/)
[![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)
[![codecov](https://codecov.io/gh/CoReason-AI/coreason_validator/graph/badge.svg?token=placeholder)](https://codecov.io/gh/CoReason-AI/coreason_validator)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

Enforces structural integrity across the entire CoReason ecosystem.

## Overview

`coreason-validator` acts as the **Single Source of Truth** for all data structures (Agents, Tests, Topologies, Messages). It provides "Schemas-as-Code" definitions and validation logic to check assets *before* they are processed, ensuring structural soundness.

In a GxP environment, "Implicit Trust" is a vulnerability. Component A must never assume Component B sent valid data. This library ensures that what *is about to happen* is structurally sound.

## Key Features

*   **Schema Registry**: A collection of immutable Pydantic Models defining valid assets.
*   **Static Analyzer**: A validation engine that runs on static files (JSON/YAML) with rich error reporting.
*   **Runtime Guard**: A lightweight validation function for dynamic payloads with microsecond latency.
*   **Integrity Hasher**: Provides canonical hashing to ensure file integrity and GxP compliance.
*   **Frontend Bridge**: Exports JSON Schemas to keep the UI in sync with the backend.

## Documentation

For detailed documentation, please refer to the `docs/` directory or the hosted site:

-   [Usage Guide](docs/usage.md)
-   [Architecture](docs/architecture.md)
-   [Product Requirements](docs/requirements.md)

## Architecture

The library implements the **Define-Check-Hash Loop**:
1.  **Define**: Schemas as strict Python classes (Pydantic V2).
2.  **Check**: Shift-left validation locally and at runtime.
3.  **Hash**: Canonical hashing of the validated structure for GxP integrity.

See [Architecture](docs/architecture.md) for more details.

## Getting Started

### Prerequisites

- Python 3.12+
- Poetry

### Installation

1.  Clone the repository:
    ```sh
    git clone https://github.com/CoReason-AI/coreason_validator.git
    cd coreason_validator
    ```
2.  Install dependencies:
    ```sh
    poetry install
    ```

## Usage

### CLI Quick Start

The package exposes a CLI tool `coreason-val` for validation and schema operations.

#### Validate a File

To validate a YAML or JSON file against its schema (schema type is auto-detected):

```sh
poetry run coreason-val check path/to/file.yaml
```

**Example:**
```sh
poetry run coreason-val check samples/agent_config.yaml
```

#### Export JSON Schemas

To export the canonical JSON Schemas for use in other systems (e.g., Frontend forms):

```sh
poetry run coreason-val export ./schemas_out
```

This will generate `agent.schema.json`, `bec.schema.json`, etc., in the specified directory.

### Python API

For deep integration, import `coreason_validator` directly.

```python
from coreason_validator import validate_file, validate_object

# Validate a file
result = validate_file("path/to/agent.yaml")
if result.is_valid:
    print("Valid!")
else:
    print(f"Errors: {result.errors}")

# Validate an object (Runtime)
data = {"name": "my-agent", "version": "1.0.0"}
try:
    model = validate_object(data, "agent")
    print(f"Canonical Hash: {model.canonical_hash()}")
except Exception as e:
    print(f"Validation failed: {e}")
```

## Development

-   Run the linter:
    ```sh
    poetry run pre-commit run --all-files
    ```
-   Run the tests:
    ```sh
    poetry run pytest
    ```
-   Build documentation:
    ```sh
    poetry run mkdocs build
    ```

