Metadata-Version: 2.4
Name: linkml-runtime-rust
Version: 0.5.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: OSI Approved :: Apache Software License
Summary: Rust-backed LinkML runtime for Python: schema loading, instance validation, diff/patch, Turtle import/export
Keywords: linkml,rdf,turtle,schema,validation
Author: Jonny Saunders
Author-email: Frank Dekervel <frank@kapernikov.com>
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/Kapernikov/rust-linkml-core#readme
Project-URL: Repository, https://github.com/Kapernikov/rust-linkml-core

# linkml-core

core linkml schema operations written in rust

## Showcase

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Kapernikov/rust-linkml-core/blob/main/notebooks/showcase.ipynb)

The [showcase notebook](notebooks/showcase.ipynb) demonstrates the Python bindings (`linkml-runtime-rust` on PyPI): schema loading without I/O, multi-schema namespace support with cross-schema slot disambiguation, instance loading/validation, diffing & patching, and Turtle export.

## Crates

- linkml_meta (`src/metamodel`): Autogenerated LinkML metamodel types and helpers. Optional Serde/PyO3 features for serialization and Python interop.
- schemaview (`src/schemaview`): Schema loading, CURIE/URI conversion, resolution (feature-gated), and view utilities: `SchemaView`, `ClassView`, `SlotView`, `EnumView`.
- linkml_runtime (`src/runtime`): Core runtime: `LinkMLInstance` parsing (YAML/JSON), basic validation, diff/patch, and Turtle serialization. Pure Rust library.
- linkml_tools (`src/tools`): CLI tools wrapping the runtime and schemaview:
  - `linkml-validate`, `linkml-convert`, `linkml-diff`, `linkml-patch`, `linkml-schema-validate`.
- linkml_runtime_python (`src/python`): PyO3 bindings and Python package (`linkml_runtime_rust._native`) exposing SchemaView and LinkMLInstance to Python; includes small Python helpers.
- linkml_wasm (`src/wasm`): WASM build target (experimental).

### SchemaView snapshots

`SchemaView` instances can be serialized into a **snapshot**—a self-contained YAML payload that carries
every loaded schema definition along with the resolved-import lineage and primary-schema pointer. The
snapshot can be reconstructed into an equivalent `SchemaView` without contacting remote import targets,
making it ideal for building views server-side and shipping them to Python, WASM, or browser clients.

- Rust: `SchemaView::to_snapshot_yaml()` / `SchemaView::from_snapshot_yaml(...)`
- Python: `SchemaView.to_snapshot_yaml()`, `SchemaView.from_snapshot_yaml(...)`
- WASM/JS: `JsSchemaView::toSnapshotYaml()`, `schemaview_from_snapshot_yaml(...)`

## Regenerating the metamodel

`src/metamodel` (the `linkml_meta` crate) is generated and must never be edited by hand.
The generator is `gen-rust`, which lives in a [linkml](https://github.com/linkml/linkml)
checkout rather than in this repo; the input schema is `src/schemaview/tests/data/meta.yaml`.

* Put a linkml checkout at `../linkml` on a branch carrying the rust generator, or point
  `LINKML_DIR` at one. Recreate its venv with `cd ../linkml && uv sync` if it is missing.
* Regenerate in place: `./regen.sh`
* Check reproducibility: `./regen.sh --check` — regenerates into a temp dir, formats it the
  same way, and diffs against the committed crate without writing anything.

An empty `--check` diff means the committed crate is exactly what that generator emits. A
non-empty one means either the checkout is on a different revision than the crate was built
from, or something was hand-edited into generated code — and a regen would silently revert
it. That has happened before (a per-key map merge strategy), which is why the check exists.

### Keeping regeneration reproducible

`./regen.sh` stamps `src/metamodel/GENERATED_FROM` with the generator revision it used and
with every generator change it needed that is not in `linkml/main`, each resolved to the pull
request carrying it. That list is the reproduction recipe: apply those PRs on top of
`linkml/main` and re-run the script.

So a generator fix does **not** have to be merged upstream before the regenerated crate lands
here — it has to be *identifiable*. Push it and open the PR, so the stamp can name something a
reader can fetch instead of a sha that only exists on your disk. (`LINKML_PR_REPO` overrides
which repo is searched for the PR; it defaults to `linkml/linkml`.)

Each such PR gets a tracking issue here, so they can be closed off one by one as they merge
upstream and drop out of the stamp.

## Development on the Python bindings

1. Create a virtual env and activate it
2. Install maturin (pip install maturin)
3. From repo root, run: `maturin develop -m src/python/Cargo.toml` (or use your venv: `../env/bin/maturin develop -m src/python/Cargo.toml`)

Now the `linkml_runtime_rust` module should be accessible.

## Building and testing

- Build all crates: `cargo build --workspace`
- Run all tests: `cargo test --workspace`
- Format: `cargo fmt --all` (check: `cargo fmt --all -- --check`)
- Lint: `cargo clippy --workspace --all-targets --all-features --exclude linkml_meta -- -D warnings --no-deps` (excludes autogenerated `linkml_meta`)

