Metadata-Version: 2.4
Name: CifQL
Version: 0.2.0
Summary: CifQL - mmCIF and ModelCIF files as one queryable relational database.
Author-email: Bienchen <stefan.bienert@unibas.ch>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=6.1.2
Requires-Dist: gemmi>=0.7.5
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: dev
Requires-Dist: black>=26.10.1; extra == "dev"
Requires-Dist: CifQL[rtd]; extra == "dev"
Requires-Dist: mcp>=2.3.0; extra == "dev"
Requires-Dist: pylint>=4.1.3; extra == "dev"
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=2.3.0; extra == "mcp"
Provides-Extra: rtd
Requires-Dist: sphinx-argparse==0.6.1; extra == "rtd"
Requires-Dist: sphinx==9.1.1; extra == "rtd"
Requires-Dist: sphinx_rtd_theme==3.1.0; extra == "rtd"
Dynamic: license-file

<!--  Copyright 2026 SIB - Swiss Institute of Bioinformatics and Biozentrum -
University of Basel
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
-->

# CifQL - mmCIF and ModelCIF files as one queryable relational database

CifQL reads many mmCIF or ModelCIF files into one relational database, one
table per CIF category, so that questions across a whole archive become
database queries: "which entries have a heme group bound", "which human
proteins are there as kinases".

The database schema is not designed manually. `cifql dic2orm` generates it from
the CIF dictionary itself, as Django models, with keys, links between
categories, types, enumerations and descriptions taken from the dictionary.
Django then creates and manages the database. CifQL runs on SQLite so far,
PostgreSQL is planned.

CifQL holds what describes a structure, not its atoms: atom coordinates,
polymer sequences and per-residue data are left out on purpose.

## Installation

```sh
pip install CifQL
# with the MCP server for language models
pip install "CifQL[mcp]"
```

CifQL needs Python 3.12 or newer. The ORM for PDBx/mmCIF 5.417 comes with the
package.

## Configuration

The database connection is a YAML file in Django's `DATABASES` format:

```yaml
DATABASES:
  default:
    ENGINE: django.db.backends.sqlite3
    NAME: /data/pdb.sqlite3
```

The tools read the file given by `--config`, else the one in
`$CIFQL_CONFIG_YAML`, else `~/.cifqlconfig.yaml`.

## Usage

Read files into the database, a directory is searched for `.cif` and
`.cif.gz`:

```sh
cifql cif2db --config pdb.yaml --dic mmcif_pdbx/v5_417 --source PDB \
    --entry-link 'https://www.rcsb.org/structure/{ID}' /data/pdb/mmCIF/
```

`cifql cif2db --list-dics` lists the ORMs available. For an archive of another
layout, `--loader` takes a Python file that walks it, see `cifql.loader`. A
run started again skips files already loaded. Every record is validated
against the dictionary while reading, `--no-validate` skips that and saves
some time.

On SQLite, `cifql cif2db` also builds a full-text index over titles,
descriptions, names and organisms. This needs an SQLite with FTS5, without
one `cifql cif2db` stops before the first file.

### Querying

The database is plain SQL, reading it needs neither CifQL nor Django. Tables
are named `<ORM version>_<category>`, with the underscores of the category
dropped (`_chem_comp` is `v5_417_chemcomp`):

```sql
SELECT d.name, e.pdbx_description
FROM v5_417_entity e
JOIN v5_417_datablock d ON d.id = e.datablock_id
WHERE e.pdbx_description LIKE '%hexokinase%';
```

### Language models (MCP)

`cifql mcp` hands the database to a language model as tools: search the
dictionary, describe a category, query with filters across linked categories
(full-text search included) and plain SQL. It serves streamable HTTP on
`127.0.0.1:8000/mcp`, or talks over stdin/stdout with `--stdio`:

```sh
cifql mcp --config pdb.yaml --dic mmcif_pdbx/v5_417 --port 8765
claude mcp add --transport http cifql http://localhost:8765/mcp
```

### Other dictionaries

`cifql dic2orm` generates the ORM for another dictionary or version.
`cifql dic-usage --dump-json` counts which categories a set of files actually
uses and writes the unused ones as an exclusion list for
`cifql dic2orm --exclude-json`:

```sh
cifql dic2json --dump-json mmcif_ma.json mmcif_ma.dic
cifql dic-usage --dump-json exclude.json mmcif_ma.json /data/models/
mkdir -p /data/orms/my_orm
cifql dic2orm --exclude-json exclude.json --output-dir /data/orms/my_orm \
    mmcif_ma.dic
cifql cif2db --config models.yaml --dic /data/orms/my_orm /data/models/
```

`cifql dic-usage` reads the dictionary as JSON, as `cifql dic2json` dumps it.

### Tab completion

In Bash, Tab completes sub-commands, options and file names after this:

```sh
eval "$(cifql completion bash)"
```

## Development

```sh
pip install -e ".[dev]"
black --check cifql doc/source tests
pylint --disable=fixme cifql doc/source tests
pytest --cov=cifql
```

- tools go in as their own Python file
- once per clone, activate the release tag check of `hooks/pre-push`:
  `git config core.hooksPath hooks`
- an ORM generated into the package (`cifql dic2orm` without `--output-dir`)
  needs a `black` run before it is committed

<!--  LocalWords:  CifQL ModelCIF mmCIF PDBx ORM ORMs argparser
 -->
