katalyst-core 0.1.1a1__tar.gz

katalyst_core-0.1.1a1/.gitignore

@@ -0,0 +1,123 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+# Not a Python build directory: Bard's SPA keeps shared helpers (utils.ts, download.ts) in
+# src/lib, and ignoring it left a fresh clone unable to build or test the SPA.
+!plugins/bard/web/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+*.local
+
+# Browser/Playwright state files
+browser-state-*.json
+
+# Agent harness scratch (run exhaust, never the design bundle)
+.opencode/sessions/
+.opencode/analysis/
+.opencode/package-lock.json
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/
+.worktrees/
+.plan-74-75-76-77.md
+.HANDOFF-scaffolding-wiring.md
+.HANDOFF-2-cicd-migration.md
+.HANDOFF-action-execution-fixes.md
+.HANDOFF-bdd-coverage.md
+.HANDOFF-*.md
+docs/superpowers/
+
+# Node dependencies — installed, never committed
+node_modules/

katalyst_core-0.1.1a1/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: katalyst-core
+Version: 0.1.1a1
+Summary: katalyst-core — the LinkML module every Katalyst schema module imports
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: linkml-map>=0.5.4
+Requires-Dist: linkml-runtime<2,>=1.12
+Requires-Dist: linkml<2,>=1.12
+Requires-Dist: pint<0.26,>=0.25
+Requires-Dist: pyoxigraph>=0.5.12
+Requires-Dist: pyshacl>=0.30
+Requires-Dist: pyyaml>=6
+Requires-Dist: rdflib>=7
+Description-Content-Type: text/markdown
+
+# katalyst-core
+
+The LinkML module every Katalyst schema module imports
+(`src/katalyst_core/schema/katalyst_core.yaml`):
+
+- `Node`: the base node. Identity (`id`, a URI under a declared prefix; core itself is `https://w3id.org/katalyst/core/`, prefix `kc:`), `kind`, `name`, `description`.
+- Lifecycle: `lifecycle_state` with a `retired` state, which is the default delete.
+- Provenance: `source`, `activity`, `derived_from`.
+- Two times: valid time (`valid_from`/`valid_to`) and recorded time (`recorded_from`/`recorded_to`).
+- `Relation`: a reified relationship (`subject`, `predicate`, `object`) with a `confidence`
+  and its own provenance and times.
+- The extension bag (`extensions`): data no loaded module defines, kept and never deleted.
+- `DeletePolicy` (block, cascade, detach, redirect): every relationship slot carries one
+  as its `delete_policy` annotation.
+
+A module imports it as `katalyst_core`:
+
+```yaml
+imports:
+  - linkml:types
+  - katalyst_core
+```
+
+The Python package defines no schema. It opens modules (`open_module`), holds them to the
+core contract (`contract.check_contract`, `kata core check`), and moves records between
+YAML and RDF (`graph.to_graph` / `graph.from_graph`, `kata core save` / `kata core load`).
+
+Lint the schema with the LinkML linter: `just core-lint`. The full `linkml` toolchain is a runtime dependency, so validation and linting are available wherever core is.

katalyst_core-0.1.1a1/README.md

@@ -0,0 +1,28 @@
+# katalyst-core
+
+The LinkML module every Katalyst schema module imports
+(`src/katalyst_core/schema/katalyst_core.yaml`):
+
+- `Node`: the base node. Identity (`id`, a URI under a declared prefix; core itself is `https://w3id.org/katalyst/core/`, prefix `kc:`), `kind`, `name`, `description`.
+- Lifecycle: `lifecycle_state` with a `retired` state, which is the default delete.
+- Provenance: `source`, `activity`, `derived_from`.
+- Two times: valid time (`valid_from`/`valid_to`) and recorded time (`recorded_from`/`recorded_to`).
+- `Relation`: a reified relationship (`subject`, `predicate`, `object`) with a `confidence`
+  and its own provenance and times.
+- The extension bag (`extensions`): data no loaded module defines, kept and never deleted.
+- `DeletePolicy` (block, cascade, detach, redirect): every relationship slot carries one
+  as its `delete_policy` annotation.
+
+A module imports it as `katalyst_core`:
+
+```yaml
+imports:
+  - linkml:types
+  - katalyst_core
+```
+
+The Python package defines no schema. It opens modules (`open_module`), holds them to the
+core contract (`contract.check_contract`, `kata core check`), and moves records between
+YAML and RDF (`graph.to_graph` / `graph.from_graph`, `kata core save` / `kata core load`).
+
+Lint the schema with the LinkML linter: `just core-lint`. The full `linkml` toolchain is a runtime dependency, so validation and linting are available wherever core is.

katalyst_core-0.1.1a1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "katalyst-core"
+version = "0.1.1a1"
+description = "katalyst-core — the LinkML module every Katalyst schema module imports"
+readme = "README.md"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    # The full toolchain at runtime: validation for CRUD and the linter. Licences of
+    # linkml and its dependencies (CC0, GPLv3+ rfc3987, W3C) are tracked by the owner.
+    "linkml>=1.12,<2",
+    "linkml-runtime>=1.12,<2",
+    # One validator for every check: SHACL shapes generated from the modules.
+    "pyshacl>=0.30",
+    "rdflib>=7",
+    "pyyaml>=6",
+    # Migrations between schema versions (LinkML-Map, Apache 2.0).
+    "linkml-map>=0.5.4",
+    # linkml-map's unit support (ucumvert 0.3.2) fails to load its UCUM definitions under
+    # pint 0.26 ("the alias i.U. is not a valid unit alias"); 0.25 is the newest that works.
+    "pint>=0.25,<0.26",
+    # The derived graph index below the query interface (MIT or Apache 2.0).
+    "pyoxigraph>=0.5.12",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_core"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

katalyst_core-0.1.1a1/src/katalyst_core/__init__.py

@@ -0,0 +1,178 @@
+"""katalyst-core — the LinkML module every Katalyst schema module imports.
+
+The schema itself is ``schema/katalyst_core.yaml``; nothing here defines a class or a
+slot. This package locates the module, opens LinkML modules that import it, holds them
+to the core contract (:mod:`katalyst_core.contract`) and moves records between their
+YAML form and their graph form (:mod:`katalyst_core.graph`).
+"""
+
+# linkml_runtime ships no type information.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false
+# pyright: reportUnknownVariableType=false, reportUnknownArgumentType=false
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from functools import cache
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+import yaml
+
+if TYPE_CHECKING:
+    # LinkML is imported where a view is opened, not with the package: a command that
+    # only reads definitions (from the schema cache) never pays for it.
+    from linkml_runtime.utils.schemaview import SchemaView
+
+__all__ = [
+    "CORE_IMPORT",
+    "MODULES_GROUP",
+    "SCHEMA_PATH",
+    "enum_values",
+    "installed_modules",
+    "kinds",
+    "local_modules",
+    "namespaces",
+    "open_installed",
+    "open_module",
+    "register_modules",
+]
+
+SCHEMA_PATH = Path(__file__).parent / "schema" / "katalyst_core.yaml"
+"""The katalyst-core LinkML module."""
+
+CORE_IMPORT = "katalyst_core"
+"""The name a module lists under ``imports:`` to import katalyst-core."""
+
+
+MODULES_GROUP = "katalyst_core.modules"
+"""Entry-point group a package registers its LinkML modules under.
+
+Each entry point loads to a mapping of module name (what an ``imports:`` line says) to
+the module's YAML file. A plugin ships its schema this way; core knows no plugin.
+"""
+
+
+_REGISTERED: dict[str, Path] = {}
+
+
+def register_modules(modules: Mapping[str, Path]) -> None:
+    """Add modules for this process: a LinkML schema bundle installed from a source."""
+    _REGISTERED.update({str(k): Path(v) for k, v in modules.items()})
+
+
+def installed_modules() -> dict[str, Path]:
+    """Every installed LinkML module by name, katalyst-core first.
+
+    Packages' modules (``katalyst_core.modules``), then any a schema bundle registered.
+    """
+    modules: dict[str, Path] = {CORE_IMPORT: SCHEMA_PATH, **_packaged_modules()}
+    modules.update(_REGISTERED)
+    return modules
+
+
+@cache
+def _packaged_modules() -> dict[str, Path]:
+    """The modules installed packages register (the entry points do not change in a process)."""
+    modules: dict[str, Path] = {}
+    for ep in sorted(entry_points(group=MODULES_GROUP), key=lambda e: e.name):
+        provided: Mapping[str, Any] = ep.load()
+        for name, path in provided.items():
+            modules[str(name)] = Path(path)
+    return modules
+
+
+def _importmap(modules: Mapping[str, Path]) -> dict[str, Any]:
+    return {name: str(path.with_suffix("")) for name, path in modules.items()}
+
+
+def local_modules(paths: Iterable[Path]) -> dict[str, Path]:
+    """Local module files (not installed) by name: the ``name`` each one declares.
+
+    Each is held to the rules for local modules first (:mod:`katalyst_core.local`): it
+    extends the installed baseline only by subtyping, against the version it pins.
+
+    Raises:
+        katalyst_core.local.LocalModuleError: A module breaks those rules.
+    """
+    from katalyst_core.local import check_local_module
+
+    found: dict[str, Path] = {}
+    baseline = installed_modules()
+    for path in paths:
+        raw: Any = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        name = str(raw.get("name") or path.stem) if isinstance(raw, dict) else path.stem
+        check_local_module(path, baseline)
+        found[name] = path.resolve()
+    return found
+
+
+def open_module(path: Path | None = None, extra: Mapping[str, Path] | None = None) -> SchemaView:
+    """Open a LinkML module (katalyst-core itself by default).
+
+    It may import katalyst-core (``katalyst_core``), any installed module and any module
+    in ``extra`` by name, wherever they live.
+    """
+    from linkml_runtime.utils.schemaview import SchemaView
+
+    importmap = _importmap({**installed_modules(), **(extra or {})})
+    return SchemaView(str(path or SCHEMA_PATH), importmap=importmap)
+
+
+def open_installed(extra: Mapping[str, Path] | None = None) -> SchemaView:
+    """Every installed module at once, and ``extra`` local ones: a view importing all."""
+    from linkml_runtime.linkml_model.meta import SchemaDefinition
+    from linkml_runtime.utils.schemaview import SchemaView
+
+    modules = {**installed_modules(), **(extra or {})}
+    root = SchemaDefinition(
+        id="https://w3id.org/katalyst/installed",
+        name="installed",
+        imports=["linkml:types", *modules],
+        prefixes=cast(Any, {"linkml": "https://w3id.org/linkml/"}),
+        default_prefix="linkml",
+    )
+    return SchemaView(root, importmap=_importmap(modules))
+
+
+def namespaces(sv: SchemaView) -> dict[str, str]:
+    """Every prefix declared by the module open in ``sv`` or by any module it imports.
+
+    ``SchemaView.namespaces()`` gives only the root module's. A compiled schema
+    (:mod:`katalyst_core.compiled`) holds them already.
+    """
+    compiled = getattr(sv, "compiled_namespaces", None)
+    if compiled is not None:
+        return dict(compiled())
+    merged: dict[str, str] = {}
+    for name in reversed(sv.imports_closure()):
+        schema: Any = (sv.schema_map or {}).get(name)
+        prefixes: dict[str, Any] = (schema.prefixes or {}) if schema else {}
+        for prefix in prefixes.values():
+            merged[str(prefix.prefix_prefix)] = str(prefix.prefix_reference)
+    merged.update({str(k): str(v) for k, v in sv.namespaces().items()})
+    return merged
+
+
+def enum_values(sv: SchemaView, name: str) -> list[str]:
+    """The permissible values of enum ``name``; empty when no loaded module defines it."""
+    enum: Any = sv.get_enum(name)
+    values: dict[str, Any] = (enum.permissible_values or {}) if enum else {}
+    return [str(v) for v in values]
+
+
+def kinds(sv: SchemaView) -> dict[str, str]:
+    """Node kind to class, for every class that declares a ``kind`` annotation."""
+    found: dict[str, str] = {}
+    for name in sv.all_classes():
+        cls: Any = sv.get_class(name)
+        annotations: Any = cls.annotations or {}
+        kind: Any = (
+            annotations.get("kind")
+            if isinstance(annotations, dict)
+            else getattr(annotations, "kind", None)
+        )
+        if kind is not None:
+            found[str(getattr(kind, "value", kind))] = str(name)
+    return found

katalyst_core-0.1.1a1/src/katalyst_core/cache.py

@@ -0,0 +1,153 @@
+"""What is built from the installed LinkML modules, kept on disk between processes.
+
+Opening the modules (LinkML's ``SchemaView``) and building from them takes about a second,
+and every command needs what they define. So what is built from them is kept as JSON in
+the active home's cache, keyed by a digest of everything it was built from:
+
+- the contents of every installed module (and every module a schema bundle registered),
+- the source of the code that built it (each builder names its own files), and
+- the builder's own key parts (the modules asked for, a format number), and
+- the versions of the libraries the build reads them with (LinkML, rdflib, katalyst-core).
+
+Any change to one of them gives a new key, so a stale entry is never read; writing the
+new entry removes the old ones of the same name and parts. An entry is written to a temporary file and
+renamed into place, so a reader never sees half of one; an entry that cannot be read is
+built again and replaced. Without a cache directory (no home, or one that cannot be
+written) everything is built in the process, as before.
+
+The runtime that owns the home says where the cache lives
+(:func:`set_cache_dir_provider`); katalyst-core knows no home.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from collections.abc import Callable, Iterable
+from functools import cache
+from pathlib import Path
+from typing import Any, TypeVar
+
+__all__ = ["cache_dir", "cached_json", "modules_digest", "set_cache_dir_provider"]
+
+_provider: Callable[[], Path | None] | None = None
+
+T = TypeVar("T")
+
+
+def _same(data: Any) -> Any:
+    return data
+
+
+def set_cache_dir_provider(provider: Callable[[], Path | None] | None) -> None:
+    """Say where the schema cache lives: a callable giving the directory, or ``None``."""
+    global _provider
+    _provider = provider
+
+
+def cache_dir() -> Path | None:
+    """The schema cache directory, or ``None`` when there is none to use."""
+    if _provider is None:
+        return None
+    try:
+        return _provider()
+    except Exception:  # no home resolves: build in the process instead
+        return None
+
+
+def modules_digest() -> str:
+    """A digest of every installed module's name and contents."""
+    from katalyst_core import installed_modules
+
+    modules = sorted(installed_modules().items())
+    stamp = tuple((name, str(path), *_stat(path)) for name, path in modules)
+    return _digest(stamp)
+
+
+def _stat(path: Path) -> tuple[int, int]:
+    info = path.stat()
+    return info.st_mtime_ns, info.st_size
+
+
+@cache
+def _digest(stamp: tuple[tuple[Any, ...], ...]) -> str:
+    """The contents' digest, read once per process for the same files (path, mtime, size)."""
+    digest = hashlib.sha256()
+    for name, path, *_ in stamp:
+        digest.update(str(name).encode())
+        digest.update(b"\0")
+        digest.update(Path(path).read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+#: Libraries whose version changes what is built from the same modules.
+_LIBRARIES = ("linkml-runtime", "linkml", "rdflib", "katalyst-core")
+
+
+@cache
+def _library_versions() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    found: list[str] = []
+    for name in _LIBRARIES:
+        try:
+            found.append(f"{name}={version(name)}")
+        except PackageNotFoundError:
+            found.append(f"{name}=")
+    return ";".join(found)
+
+
+def _key(kind: str, sources: Iterable[Path], parts: Iterable[str]) -> str:
+    digest = hashlib.sha256(kind.encode())
+    digest.update(_library_versions().encode())
+    digest.update(modules_digest().encode())
+    for source in sources:
+        digest.update(Path(source).read_bytes())
+    for part in parts:
+        digest.update(b"\0" + part.encode())
+    return digest.hexdigest()[:32]
+
+
+def cached_json(
+    kind: str,
+    build: Callable[[], Any],
+    *,
+    load: Callable[[Any], T] = _same,
+    sources: Iterable[Path] = (),
+    parts: Iterable[str] = (),
+    directory: Path | None = None,
+) -> T:
+    """``load(build())``, with what *build* returns (JSON data) kept in the cache.
+
+    *kind* names the entry (``definitions``, ``compiled``); *sources* are the files of
+    the code that builds it, *parts* any further key strings. An entry that cannot be
+    read or that *load* refuses is built again and replaced. *directory* overrides
+    :func:`cache_dir`.
+    """
+    where = directory if directory is not None else cache_dir()
+    if where is None:
+        return load(build())
+    parts = tuple(parts)
+    family = f"{kind}-{hashlib.sha256(chr(0).join(parts).encode()).hexdigest()[:8]}"
+    path = where / f"{family}-{_key(kind, sources, parts)}.json"
+    try:
+        return load(json.loads(path.read_text(encoding="utf-8")))
+    except Exception:  # absent, unreadable or refused: build it again
+        pass
+    data = build()
+    result = load(data)
+    try:
+        where.mkdir(parents=True, exist_ok=True)
+        fd, partial = tempfile.mkstemp(dir=where, prefix=f".{kind}-", suffix=".tmp")
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, separators=(",", ":"))
+        os.replace(partial, path)
+        for stale in where.glob(f"{family}-*.json"):
+            if stale != path:
+                stale.unlink(missing_ok=True)
+    except OSError:  # a cache that cannot be written is only slower
+        pass
+    return result