Metadata-Version: 2.5
Name: ontology-quality-suite
Version: 0.25.0
Summary: Ontology Quality Suite -- assess OWL2 DL/RL/QL ontologies, TARQL/oxi-gen CONSTRUCT-query sketches, and the RDF data graphs they triplify -- structural, logical, documentation, efficiency, style, data quality, OWL2 profile membership, and reasoner-based consistency -- plus ontology-version and TARQL/ontology consistency checking with suggested repair diffs, locally or against a live Fuseki triplestore.
Project-URL: Repository, https://github.com/pwin/consolidated-ontology-quality-suite-python
Project-URL: Issues, https://github.com/pwin/consolidated-ontology-quality-suite-python/issues
Author-email: pwin <pw@inbox.lv>
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Keywords: linked-data,ontology,owl,rdf,semantic-web,shacl,sparql,tarql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: holosdb>=0.24
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: owlready2>=0.51
Requires-Dist: owlrl>=6.0.2
Requires-Dist: pandas>=2.0.0
Requires-Dist: rdflib>=7.6.0
Requires-Dist: shacl<0.4,>=0.3.3
Requires-Dist: tabulate>=0.9.0
Provides-Extra: native-shacl
Provides-Extra: reasoner
Requires-Dist: owlready2>=0.47; extra == 'reasoner'
Description-Content-Type: text/markdown

# Ontology Quality Suite

Python tools for checking that an OWL2 ontology stays internally consistent
across versions, and that TARQL/oxi-gen CONSTRUCT-query transformation files
stay aligned with the ontology(ies) they triplify against -- namespaces,
class/property usage -- with **suggested diffs for automated repair**,
either against local files or a live Fuseki (SPARQL 1.1 Protocol)
triplestore.

This package carries forward the full `ontology_suite` pipeline from the
sibling `consolidated_ontology_suite` checkout (OntoQA/OQuaRE metrics,
SHACL+SPARQL registry checks, OWL2 profile/reasoner-backed consistency,
docgen -- the same logic is also ported to TypeScript in
`consolidated_ontology_suite_webapp`, the VS Code extension) and adds three
things that didn't exist in Python before:

- **Ontology-version consistency + rename detection**
  (`ontology_suite.versioning.rename_detection`) -- pairs up a version
  diff's removed/added classes and properties into probable renames, using
  either an explicit `owl:equivalentClass`/`dcterms:isReplacedBy`
  migration annotation (high confidence) or local-name similarity
  (fallback).
- **Automated repair suggestions** (`ontology_suite.repair`,
  `ontology_suite.checks.repair`) -- turns a TARQL/ontology misalignment or
  a registry-check finding into a concrete unified diff: a `PREFIX` line
  fix, an IRI-rename substitution across a query file, an ontology
  declaration stub, or a real SPARQL 1.1 Update -- reviewable as a
  `.patch` file, or applied directly.
- **Live triplestore support** (`ontology_suite.remote`) -- runs the same
  checks against a Fuseki (or any SPARQL 1.1 Protocol) dataset, named-graph
  aware: diff two ontology *versions* held as separate named graphs, run
  the existing registry `.rq` checks scoped to exactly the graphs they
  should see, or three-way check a live triplified named graph against its
  ontology graph *and* its local TARQL source file.

Every `--ontology`/`--data`/query-source argument throughout accepts a
local file, an http(s) URL, or either gzip-compressed, transparently (see
`ontology_suite/io_utils.py` and `docs/ARCHITECTURE.md`'s "Loading files"
section).

**New here? Start with `docs/PRIMER.md`** -- a task-oriented guide to which
command answers which question, worked examples for every major use case
(auditing an ontology, validating a CSV-to-RDF pipeline, releasing a new
version, auto-repairing drift, taxonomy governance, live-triplestore
checks, CI wiring), and a suggested adoption path. New to RDF/OWL? It opens
with a short, plain-language glossary. Prefer running things over reading
them? `docs/primer.ipynb` is a Jupyter notebook covering most of the same
ground with live, executable cells against this repo's own `examples/`
fixtures (validated on every push by `.github/workflows/notebook.yml`).

See `docs/CONSISTENCY_AND_REPAIR.md` for the local-file workflow,
`docs/FUSEKI.md` for the live-triplestore one, `docs/ARCHITECTURE.md` for
the inherited pipeline this all sits on top of, and
`docs/UPSTREAM_README.md` for that pipeline's own original README.

Got a run's output and want to know which file to open? `docs/REPORTS.md`
covers what each one is for, why `findings.txt` is the one to start with,
where its `file:line` positions come from and when it declines to guess one,
and how `--themes` groups the findings under questions in your own words
instead of under check ids.

Working on TARQL/oxi-gen queries? `docs/TESTING_TARQL.md` is the guide to
testing a query folder: what goes wrong in a `CONSTRUCT` query, which check
catches each thing, what none of them catch, and a review order that puts the
cheapest checks first. `ontology-quality-suite sketch --queries ...` needs no
ontology and no CSV to run the BIND review half of it. It also covers writing
your own query-source checks: the run publishes what it parsed as
`bind-facts.ttl`, so a TARQL check is a `.rq` file and a registry entry --
which can live in your project rather than in this package.

Want to know what the suite actually checks, and how to add checks of your
own? `docs/check-registry.html` is a standalone, self-contained page
covering all the registered checks -- what each one asserts, its severity
and remediation, and whether it is implemented in SPARQL, SHACL or native
Python -- plus the result contract a new check has to satisfy and how to
run a project-local panel via `--registry`/`--shapes`/`--sparql`. It is
generated from `registry.json` by `docs/generate_check_registry.py`, so it
cannot drift from the suite; `tests/test_check_registry_doc.py` fails if
the committed copy goes stale. `docs/CHECKS.md` is the terser Markdown
reference over the same registry.

`registry.json`, the shapes, the queries and the repair templates are shared
data rather than this package's private tables: the same files ship inside the
VS Code extension, which loads them at runtime and can be pointed at a checkout
of this repo instead (`ontologySuite.checksRegistryPath`). So the registry
declares every check *any* implementation produces -- three of them the CLI
cannot run, marked as such in `docs/CHECKS.md` -- and
`tests/test_shared_registry_parity.py` fails if the two copies stop agreeing,
whenever a machine has both checked out.

Want to add checks of your own without editing anything the suite ships?
`examples/riverside_library/README.md` is a runnable worked example: four
invented checks over an invented catalogue, keeping the standard 61 and
adding to them. It gives every command in full and quotes only measured
output. `docs/EXTENDING.md` has the mechanics behind it, and
`docs/PRIMER.md` §13 the summary.

Need the same checks read differently at different points in a project --
permissive while sketching, strict at a release? `--severity-policy` takes a
JSON file of check ids and the severity your project wants them reported at,
optionally per named stage selected with `--stringency`. The stage names are
yours, it covers your own checks as well as the shipped ones, and because it
is applied to finished findings rather than to any check file, every
re-mapping is printed and recorded rather than quietly baked in.
See `docs/SEVERITY_POLICY.md`.

Want one continuous, realistic worked example instead of task-by-task
fixtures? `docs/ACME_ROBOTICS_WALKTHROUGH.md` runs nearly every stage above
against a single small org chart built on two real external vocabularies
(W3C Organization Ontology, FOAF) -- with two companion notebooks,
`docs/acme_robotics_lifecycle.ipynb` and
`docs/acme_robotics_data_pipeline.ipynb` (also validated on every push).

## Quick start

```bash
uv sync
uv run ontology-quality-suite consistency --new domain-v2.ttl --old domain-v1.ttl --queries queries/
```

```python
from ontology_suite import consistency

report = consistency.check_consistency(
    "domain-v2.ttl", old_ontology="domain-v1.ttl", tarql_sources=["queries/"],
)
print(consistency.format_consistency_report(report))
consistency.apply_repairs(report.repairs, min_confidence=0.7)
```

## CLI

```
ontology-quality-suite ontology            --ontology domain.ttl
ontology-quality-suite checks              --ontology domain.ttl [--data data.ttl]
ontology-quality-suite sketch              --queries queries/ [--ontology domain.ttl]
ontology-quality-suite triplify            --csv-dir csv/ --queries queries/
ontology-quality-suite data                data.ttl [more.ttl ...] [--ontology domain.ttl]
ontology-quality-suite docgen              --ontology domain.ttl
ontology-quality-suite run                 whichever of --ontology/--queries/--csv-dir/--data apply
ontology-quality-suite version-diff        old.ttl new.ttl
ontology-quality-suite consistency         --new domain.ttl [--old domain-v1.ttl] [--queries queries/] [--apply-repairs]
ontology-quality-suite consistency-remote  --query-endpoint URL --manifest graphs.json
```

## Tests

```bash
uv run pytest
```
