Metadata-Version: 2.5
Name: scitheory
Version: 0.1.0
Summary: Claim graphs from the scientific literature: explain contradictions between studies and rank research gaps.
Project-URL: Homepage, https://github.com/MarcoFerreiraRibeiro/scitheory
Project-URL: Issues, https://github.com/MarcoFerreiraRibeiro/scitheory/issues
Author: Marco Ferreira Ribeiro
License: MIT
License-File: LICENSE
Keywords: bibliometrics,knowledge graph,literature synthesis,research gaps,scientometrics
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.5
Provides-Extra: dev
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Description-Content-Type: text/markdown

# SciTheory

SciTheory turns empirical claims from scientific papers into a graph that keeps the context and
method of every claim. On that graph it does two things:

1. **Explains contradictions.** When studies disagree about the same relation, it tests whether
   context (country, period, sample) or method (design, estimator) accounts for the difference.
2. **Ranks research gaps.** It orders open questions by the expected value of new evidence, and
   separates "nobody has studied this" from "studying this would change what we know".

**Input scope: abstracts only.** SciTheory runs on titles and abstracts (from OpenAlex and similar
sources), not on full-text articles. This keeps it usable at corpus scale and independent of
publisher access, at the cost of less detail per paper: method and context fields are often
missing and stay optional in the schema.

> **Status: pre-alpha (0.1.0).** Only the claim schema exists so far. The modules for ingestion,
> extraction, normalisation, the graph, explanation and gaps are being built in the order set by
> the project plan.

## Install

```bash
git clone https://github.com/MarcoFerreiraRibeiro/scitheory.git
cd scitheory
python -m pip install -e ".[dev]"
pytest
```

Python 3.10 or later. Design decisions are recorded in [docs/decisions.md](docs/decisions.md).

## Claim schema (v0.1)

```python
import json
from scitheory import Claim

claim = Claim.model_validate(json.load(open("examples/claims_synthetic.json"))[0])
print(claim.relation.direction, claim.context.country)
```

The fields are described in [docs/schema.md](docs/schema.md). The examples in `examples/` are
synthetic and do not come from real papers.

## Layout

| Module | Purpose | Work package |
| --- | --- | --- |
| `scitheory.ingest` | Metadata and abstracts, with provenance | WP02 |
| `scitheory.extract` | Claim extraction | WP03 |
| `scitheory.normalize` | Merging equivalent constructs | WP04 |
| `scitheory.graph` | Aggregated claim graph | WP05 |
| `scitheory.explain` | Contradiction explanation | WP06 |
| `scitheory.gaps` | Gap ranking | WP07 |

## Related work

SciClaim (per-sentence claim graphs), THEORIZER (theory generation from literature), PaperQA2
(contradiction detection) and metaBUS (curated findings) cover parts of this space. SciTheory's
focus is explaining why studies diverge and valuing what is still unknown.

## Licence and citation

MIT. See [LICENSE](LICENSE). To cite, use [CITATION.cff](CITATION.cff).
