Metadata-Version: 2.4
Name: tablassert
Version: 8.2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Database
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Framework :: Pydantic
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Environment :: Console
Requires-Dist: biolink-model>=4.4.3
Requires-Dist: loguru>=0.7.3
Requires-Dist: polars>=1.39.0
Requires-Dist: rapidfuzz>=3.14.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: cyclopts>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fastexcel>=0.20.2
Requires-Dist: smolagents>=1.26.0 ; extra == 'agent'
Requires-Dist: litellm>=1.93.0 ; extra == 'agent'
Requires-Dist: pdfminer-six>=20221105 ; extra == 'agent'
Requires-Dist: dspy>=3.2.1 ; extra == 'optimize'
Requires-Dist: scikit-learn>=1.8.0 ; extra == 'qc'
Requires-Dist: sentence-transformers>=5.3.0 ; extra == 'qc'
Requires-Dist: polars[rtcompat]>=1.40.1 ; extra == 'rt'
Provides-Extra: agent
Provides-Extra: optimize
Provides-Extra: qc
Provides-Extra: rt
License-File: LICENSE
Summary: Extract knowledge assertions from tabular data into NCATS Translator-compliant KGX NDJSON — declaratively, with entity resolution and quality control built in.
Keywords: knowledge graph,bioinformatics,entity resolution,ner,ncats translator,kgx,yaml configuration,table mining,declarative pipeline,data quality control,tablassert
Author-email: Skye Lane Goetz <sgoetz@isbscience.org>
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://skyeav.github.io/Tablassert/
Project-URL: Homepage, https://github.com/SkyeAv/Tablassert
Project-URL: Source, https://github.com/SkyeAv/Tablassert

# Tablassert

[![PyPI](https://img.shields.io/pypi/v/tablassert.svg)](https://pypi.org/project/tablassert/)
[![Python](https://img.shields.io/pypi/pyversions/tablassert.svg)](https://pypi.org/project/tablassert/)
[![CI](https://github.com/SkyeAv/Tablassert/actions/workflows/ci.yml/badge.svg)](https://github.com/SkyeAv/Tablassert/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/tablassert.svg)](https://github.com/SkyeAv/Tablassert/blob/main/LICENSE)
[![Docs](https://img.shields.io/github/deployments/SkyeAv/Tablassert/github-pages?label=docs)](https://skyeav.github.io/Tablassert/)

> Extract knowledge assertions from tabular data into NCATS Translator-compliant KGX NDJSON —
> declaratively, with entity resolution built in and optional quality control.

Tablassert turns biomedical spreadsheets (Excel, CSV, TSV) into knowledge graphs ready for NCATS
Translator. Declare how your columns map to subject–predicate–object statements in YAML; Tablassert
resolves free text to standard CURIEs, attaches provenance and statistical annotations, and emits
KGX-compliant nodes and edges.

**[Full Documentation](https://skyeav.github.io/Tablassert/)** — installation guides, tutorial,
configuration reference, and API docs.

## Quick Start

```bash
pip install tablassert
```

Given a CSV of gene–disease associations with p-values and sample sizes, declare the mapping in a
table config (`table.yaml`):

```yaml
template:
  source:
    kind: text
    local: ./gene-disease.csv
    url: https://example.com/data.csv
    row_slice: [1, auto]
    delimiter: ","
  statement:
    subject: { method: column, encoding: A, prioritize: [Gene] }
    predicate: associated_with
    object: { method: column, encoding: B, prioritize: [Disease] }
  provenance: { repo: PMID, publication: "12345678" }
  annotations:
    - { annotation: p_value, method: column, encoding: C }
    - { annotation: supporting_study_size, method: column, encoding: D }
```

Wrap it in a graph config (`graph.yaml`) pointing at your fullmap entity-resolution database:

```yaml
name: MY_KG
version: 1.0.0
description: Gene–disease associations extracted from tabular sources.
tables:
  - ./table.yaml
fullmap: /path/to/fullmap
```

Build the knowledge graph:

```bash
tablassert build-kg graph.yaml
```

Output is one JSON object per line — nodes with Biolink categories, edges with annotations:

```json
{"id":"HGNC:11998","name":"TP53","category":["biolink:Gene"],"taxon":"NCBITaxon:9606"}
{"id":"MONDO:0008903","name":"lung cancer","category":["biolink:Disease"]}
```

```json
{"subject":"HGNC:11998","predicate":"biolink:associated_with","object":"MONDO:0008903","p_value":"1.0000e-03","supporting_study_size":"450"}
```

See the [Tutorial](https://skyeav.github.io/Tablassert/tutorial/) for the full walkthrough.

## Key Features

- **Declarative YAML configuration** — define data transformations without writing code
- **Built-in entity resolution** — map free text to genes, diseases, and chemicals with standard
  CURIEs, taxonomic filtering, and provenance, backed by an embedded redb database
- **Optional quality control** — a three-stage audit (exact → fuzzy → BioBERT embeddings) flags
  low-confidence mappings
- **KGX compliance** — emits NCATS Translator-compatible node/edge NDJSON with Biolink categories
  and predicates
- **Autonomous agent** — `tablassert agent` derives, builds, and refines configs for whole papers
- **Performance & reproducibility** — lazy Polars pipelines and a deterministic UV-based
  development environment

## Installation

```bash
pip install tablassert
```

Or with uv: `uv tool install tablassert`. The base install builds knowledge graphs from
CSV/TSV/Excel sources; optional extras add runtime and pipeline capabilities:

| Extra | Adds | Install |
| ----- | ---- | ------- |
| `rt` | CPU-compatible Polars runtime | `pip install "tablassert[rt]"` |
| `qc` | three-stage QC audit (exact → fuzzy → BioBERT embeddings) | `pip install "tablassert[qc]"` |
| `agent` | autonomous agent (smolagents, litellm, PDF context) | `pip install "tablassert[agent]"` |
| `optimize` | GEPA prompt optimization for `agent --optimize` (dspy) | `pip install "tablassert[optimize]"` |

QC is opt-in at build time (`build-kg --qc`). See the
[Installation guide](https://skyeav.github.io/Tablassert/installation/) for the full matrix and the
[CLI Reference](https://skyeav.github.io/Tablassert/cli/) for every flag.

## Entity Resolution API

```python
from pathlib import Path
from tablassert.lib import resolve_many

results = resolve_many(
    col="gene",
    entities=["TP53", "BRCA1"],
    fullmap=Path("/path/to/fullmap"),
    taxon="9606",
)
# [{"original_gene": "TP53", "gene": "HGNC:11998", "gene_name": "TP53", ...}, ...]
```

Point `resolve_many()` at a fullmap database to resolve any iterable of entity strings to CURIEs —
no LazyFrame setup or NLP preprocessing required. See the
[Batch Resolution API](https://skyeav.github.io/Tablassert/api/lib/) for the full reference.

## Documentation

- **[Installation](https://skyeav.github.io/Tablassert/installation/)** — install methods, extras, and development setup
- **[Tutorial](https://skyeav.github.io/Tablassert/tutorial/)** — step-by-step example with synthetic data
- **[CLI Reference](https://skyeav.github.io/Tablassert/cli/)** — complete command-line flag reference
- **[Use Case Gallery](https://skyeav.github.io/Tablassert/examples/)** — real-world configuration patterns
- **[Configuration](https://skyeav.github.io/Tablassert/configuration/graph/)** — graph and table configuration reference
- **[Agent](https://skyeav.github.io/Tablassert/agent/)** — the autonomous agent pipeline
- **[API Reference](https://skyeav.github.io/Tablassert/api/fullmap/)** — core functions documentation

## Developing

```bash
uv sync --group dev --extra qc
uv run maturin develop --manifest-path rust/Cargo.toml
make check
```

See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full development loop, quality gates, and pull
request guidelines.

## Citation

If you use Tablassert, please cite it as described in [CITATION.cff](CITATION.cff). The approach is
described in:

> Skye Lane Goetz, Alex K. Glen, and Gwênlyn Glusman. “MicrobiomeKG: bridging microbiome research
> and host health through knowledge graphs.” *Frontiers in Systems Biology* 5 (2025).
> [doi:10.3389/fsysb.2025.1544432](https://doi.org/10.3389/fsysb.2025.1544432)

## License

[Apache License 2.0](LICENSE)

## Contributors

- [Skye Lane Goetz](mailto:sgoetz@isbscience.org) — Institute for Systems Biology
- [Gwênlyn Glusman](mailto:gglusman@isbscience.org) — Institute for Systems Biology
- Jared C. Roach — Institute for Systems Biology

