Metadata-Version: 2.4
Name: coreason_episteme
Version: 0.1.0
Summary: coreason-episteme
License: # The Prosperity Public License 3.0.0
         
         Contributor: CoReason, Inc.
         
         Source Code: https://github.com/CoReason-AI/coreason_episteme
         
         ## 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: aiofiles (>=25.1.0,<26.0.0)
Requires-Dist: anyio (>=4.12.1,<5.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
Requires-Dist: pytest-asyncio (>=1.3.0,<2.0.0)
Requires-Dist: types-aiofiles (>=25.1.0.20251011,<26.0.0.0)
Project-URL: Documentation, https://github.com/CoReason-AI/coreason_episteme
Project-URL: Homepage, https://github.com/CoReason-AI/coreason_episteme
Project-URL: Repository, https://github.com/CoReason-AI/coreason_episteme
Description-Content-Type: text/markdown

# coreason-episteme

**Theorist / Hypothesis Engine**

[![License: Prosperity 3.0](https://img.shields.io/badge/license-Prosperity%203.0-blue)](https://github.com/CoReason-AI/coreason_episteme/blob/main/LICENSE)
[![CI/Status](https://github.com/CoReason-AI/coreason_episteme/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/CoReason-AI/coreason_episteme/actions/workflows/ci-cd.yml)
[![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)
[![Docs](https://img.shields.io/badge/docs-product__requirements-blue)](docs/product_requirements.md)

## Overview

**coreason-episteme** is the engine of **Scientific Intuition** within the CoReason platform. It acts as the "Theorist" that automates the "Eureka" moment by systematically scanning for "White Space" in the Knowledge Graph. It synthesizes weak signals from disparate papers into coherent, testable hypotheses (e.g., identifying a novel genetic target for a disease based on pathway adjacency).

Crucially, it implements a **"Null Hypothesis First"** architecture. Every generated hypothesis is treated as false until it survives a rigorous adversarial review process involving causal counterfactuals and patent whitespace analysis.

## Core Philosophy

"Identify the Void. Bridge the Gap. Propose the Novel."

1.  **Gap Scanning (Negative Space Analysis):** Identifies disconnected clusters in the Knowledge Graph that share high semantic similarity but lack connections.
2.  **Latent Bridging (The Leap):** Finds "Latent Bridges"—genes or proteins that are structurally or functionally connected to the conflict but rarely mentioned in the context of the specific disease.
3.  **Causal Simulation (The Test):** Runs a counterfactual simulation using `coreason-inference` to validate the hypothesis.
4.  **Adversarial Review (The Council):** Convenes a virtual "Review Board" (The Toxicologist, The Clinician, The IP Strategist) to attack the hypothesis for safety risks, clinical redundancy, or patent infringement.

## Installation

```bash
pip install coreason-episteme
```

## Features

*   **Gap Scanner:** Detects inconsistencies or missing links in the Knowledge Graph and literature.
*   **Bridge Builder:** Formulates novel hypotheses by exploring the "Neighborhood" of conflicting entities and proposing valid genetic targets.
*   **Causal Validator:** Validates proposed mechanisms using counterfactual simulations (A -> B -> C).
*   **Protocol Designer:** Designs the "Killer Experiment" (PICO) to prove or disprove the hypothesis in a wet lab.
*   **Adversarial Reviewer:** Critiques hypotheses using multi-perspective strategies (Toxicology, IP, Clinical, Scientific Skeptic).

For detailed requirements, see [Product Requirements](docs/product_requirements.md).

## Usage

```python
from typing import Any, Dict, List, Optional
from coreason_episteme.main import generate_hypothesis
from coreason_episteme.models import GeneticTarget, KnowledgeGap

# 1. Define Mock Clients (Simulate external services)
class MockClient:
    def find_disconnected_clusters(self, criteria: Dict[str, Any]) -> List[Dict[str, Any]]:
        return [{"cluster_a_id": "C1", "cluster_b_id": "C2", "cluster_a_name": "A", "cluster_b_name": "B"}]

    def find_latent_bridges(self, source: str, target: str) -> List[GeneticTarget]:
        return [GeneticTarget(symbol="GENE_X", ensembl_id="ENSG001", druggability_score=0.9, novelty_score=0.8)]

    def get_semantic_similarity(self, e1: str, e2: str) -> float: return 0.95
    def validate_target(self, symbol: str) -> Optional[GeneticTarget]:
        return GeneticTarget(symbol=symbol, ensembl_id="ENSG001", druggability_score=0.9, novelty_score=0.8)

    def find_literature_inconsistency(self, topic: str) -> List[KnowledgeGap]: return []
    def verify_citation(self, claim: str) -> bool: return True
    def check_patent_infringement(self, target: GeneticTarget, mech: str) -> List[str]: return []
    def find_disconfirming_evidence(self, sub: str, obj: str, act: str) -> List[str]: return []

    def check_druggability(self, target_id: str) -> float: return 0.9

    def run_counterfactual_simulation(self, mech: str, target: str) -> float: return 0.85
    def run_toxicology_screen(self, target: GeneticTarget) -> List[str]: return []
    def check_clinical_redundancy(self, mech: str, target: GeneticTarget) -> List[str]: return []

    def log_trace(self, h_id: str, trace: Dict[str, Any]) -> None: print(f"Logged trace for {h_id}")

# 2. Instantiate Clients
mock_client = MockClient()

# 3. Run the Engine
try:
    hypotheses = generate_hypothesis(
        disease_id="DOID:12345",
        graph_client=mock_client,      # type: ignore
        codex_client=mock_client,      # type: ignore
        search_client=mock_client,     # type: ignore
        prism_client=mock_client,      # type: ignore
        inference_client=mock_client,  # type: ignore
        veritas_client=mock_client     # type: ignore
    )

    for h in hypotheses:
        print(f"Hypothesis: {h.title}")
        print(f"Mechanism: {h.proposed_mechanism}")
        print(f"Confidence: {h.confidence}")

except Exception as e:
    print(f"Error generating hypotheses: {e}")
```

## License

This project is licensed under the **Prosperity Public License 3.0**.

