Metadata-Version: 2.4
Name: coreason-protocol
Version: 0.1.0
Summary: Design and Governance Engine for high-stakes research.
License-File: LICENSE
License-File: NOTICE
Author: Gowtham A Rao
Author-email: gowtham.rao@coreason.ai
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiofiles (>=23.0,<24.0)
Requires-Dist: anyio (>=4.0,<5.0)
Requires-Dist: boolean-py (>=4.0,<5.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: loguru (>=0.7.0,<0.8.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Description-Content-Type: text/markdown

# coreason-protocol

The **Design and Governance Engine** for high-stakes research.

[![Organization](https://img.shields.io/badge/org-CoReason--AI-blue)](https://github.com/CoReason-AI)
[![License](https://img.shields.io/badge/license-Prosperity%203.0-blue)](https://github.com/CoReason-AI/coreason-protocol/blob/main/LICENSE)
[![Build Status](https://github.com/CoReason-AI/coreason-protocol/actions/workflows/build.yml/badge.svg)](https://github.com/CoReason-AI/coreason-protocol/actions)
[![Code Style: 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.md-blue)](docs/product_requirements.md)

## Description

`coreason-protocol` transforms natural language intent into a **Rigorous, Audited, and Executable Search Protocol**. It acts as the "Study Director" or Design Plane, ensuring that research protocols are designed with rigor, validated with logic (PRESS guidelines), and approved with authority before execution.

Unlike simple RAG retrieval, this package enforces a scientific workflow:
1.  **AI Draft:** Generates PICO blocks and expands terms using ontologies (via `coreason-codex`).
2.  **Human Governance:** Allows experts to override or inject terms.
3.  **Strict Validation:** Checks structural integrity and PRESS guidelines.
4.  **Immutable Registration:** Locks and registers approved protocols (via `coreason-veritas`).

## Installation

```bash
pip install coreason-protocol
```

Or using poetry:

```bash
poetry add coreason-protocol
```

## Features

*   **PICO Architecture:** Structuring of research intent into Population, Intervention, Comparator, and Outcome.
*   **Ontology Expansion:** Integration with `coreason-codex` for term hydration (Concept IDs).
*   **Strategy Compilation:** Translation of PICO models into executable queries for:
    *   PubMed/Ovid (Boolean strings with MeSH/TiAb mapping).
    *   LanceDB (Vector embeddings + metadata filters).
    *   Graph (Cypher queries).
*   **HITL Governance:** Support for human review with `override_term` and `inject_term` capabilities.
*   **Audit Fidelity:** Soft-deletion of terms to maintain a complete history of design decisions.
*   **Multi-Format Rendering:** Export to HTML (visual diff), PRISMA-S text, and JSON-LD.

## Usage

```python
from coreason_protocol import ProtocolDefinition, PicoBlock, TermOrigin, OntologyTerm

# Initialize a new Protocol Definition
protocol = ProtocolDefinition(
    id="prot-123",
    title="Statins for CVD Prevention",
    research_question="Do statins reduce CVD risk in elderly patients?",
    pico_structure={},
    status="DRAFT"
)

# Example: Adding a PICO block (programmatically or via AI expansion)
term = OntologyTerm(
    id="term-001",
    label="Statins",
    vocab_source="MeSH",
    code="D019821",
    origin=TermOrigin.USER_INPUT
)

protocol.pico_structure["I"] = PicoBlock(
    block_type="I",
    description="Intervention",
    terms=[term]
)

# Render the protocol for review
html_output = protocol.render(format="html")
print(html_output)
```

## Documentation

For detailed product requirements and architectural philosophy, see [docs/product_requirements.md](docs/product_requirements.md).

