knowledge-graph-rdbms 0.1.0__tar.gz

knowledge_graph_rdbms-0.1.0/.claude/skills/kg-compose/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: kg-compose
+description: Decompose documents or pasted context into a queryable kgrdbms ontology — extract entities and typed relationships, mint stable CURIE ids, and write them gated+logged into a named ontology via the `kg` CLI. Use when the user hands over source material (notes, docs, transcripts, research, pasted text) and wants it turned into a knowledge graph they can query, or says things like "compose this into an ontology", "build a KG from this", "extract the entities and relationships", "turn these notes into a graph".
+---
+
+# kg-compose — document → ontology
+
+Turn unstructured source material into structured, queryable graph facts in a
+named kgrdbms ontology. You are the extraction engine; the ontology supplies the
+*opinion* (how aggressive to be), and every write is gated and logged so a wrong
+call is reversible, not permanent.
+
+## The one idea
+
+**You are mechanism; the ontology is policy.** Don't impose a house style — read
+the target ontology's `stance` and honor it. A `literal` legal-notes ontology and
+an `inferential` research-notes ontology get *different* graphs from the same
+paragraph, on purpose.
+
+## Procedure
+
+### 0. Resolve the target ontology
+- If the user named one, use it. If not, propose a short kebab-case name from the
+  material and confirm.
+- Check whether it exists: `kg --json ontology list`. If absent, create it:
+  `kg ontology create NAME --stance <literal|inferential> --description "…"`.
+  If present, **do not recreate it** — read its existing `stance`/`path` from the
+  list output and honor them.
+
+### 1. Read the ontology's opinion
+From the registry entry: `stance` (free-text extraction guidance — see *Stance*
+below), `allowed_kinds` (if non-empty, prefer those kinds; extract others but
+flag that they're outside the ontology's allowlist), `id_convention` (default
+CURIE `prefix:slug`). These are the guidance you compose within.
+
+### 2. Decompose the source into a `{nodes, edges}` model
+- **Nodes** = the *things*. Each: `id` (a CURIE — see *Id rules*), `kind` (a
+  TitleCase type like `Person`, `Company`, `Method`), `name` (display string),
+  `labels` (set memberships), `properties` (JSON facts).
+- **Edges** = the *relationships*. Each: `from`, `to`, `type` (UPPER_SNAKE verb
+  like `FOUNDED`, `MADE_WITH`, `REPORTS_TO`), and optional `properties` (facts
+  about the relationship itself — `year`, `confidence`, `source`).
+- Let the **stance** govern how far past the literal text you go.
+
+### 3. Write it (bulk, gated, logged — ONE call, not N)
+Write the whole `{nodes, edges}` model in a single bulk operation. **Do not emit
+dozens of individual upsert calls** — use the bulk path:
+
+- **Over MCP:** call `kg_import(nodes=[...], edges=[...], ontology="NAME")` once.
+- **Over the CLI:** `kg --ontology NAME import /tmp/compose.json --actor kg-compose`.
+
+Both run the same gated + logged path inside one transaction — fast *and* fully
+recorded, so it survives replay. Every node/edge is still individually gated and
+reversible; bulk only collapses the commit, not the gate. Re-running on
+overlapping sources is safe: stable CURIE ids make re-imports **merge**, never
+duplicate. For a very large source, chunk into a few `kg_import` calls rather
+than one per entity.
+
+### 4. Verify and hand back the receipt
+- `kg --ontology NAME stats` — what landed.
+- `kg --ontology NAME path A B` (or a `neighbors`/`out` query) — show it's
+  actually connected, not just a pile of nodes.
+- `kg --ontology NAME events -n 10` — the audit trail of this composition.
+- Summarize in prose: counts, the key entities/relationships, and anything you
+  inferred (so the user can see and revert it).
+
+## Id rules (CURIEs)
+- `id = prefix:reference`. `prefix` is a short stable lowercase type token
+  (`person`, `company`, `paper`); `reference` is the slugged name.
+- Mint with the slug discipline: "Ada Lovelace" → `person:ada-lovelace`. Two
+  spellings that slug the same **must** get the same id — that's how the same
+  entity across two documents becomes one node.
+- The id is an **address, not a record**: identity goes in the id, mutable facts
+  go in `properties`. Never bake `status=active` into an id.
+
+## Stance: the ontology's extraction guidance
+
+`stance` is **free-text guidance the ontology carries about how to extract** — a
+dial, not a switch, and not a fixed enum. Read it and apply judgment; the
+ontology's own words win. Common values, just to convey the range (not a menu to
+pick from):
+
+- **`literal`** — assert only what the text states outright: entities only if
+  named, relationships only if stated, never guess two mentions are the same.
+  Fits legal, technical, contractual sources.
+- **`inferential`** — also assert what's clearly implied, resolve aliases
+  ("Ada" / "Lovelace" / "the Countess" → one node), normalize and enrich. Fits
+  research notes, brainstorming, exploratory reading.
+- …or whatever the ontology actually says — `"conservative; medical terms must
+  be exact"`, `"connect aggressively, this is ideation"`. Honor the intent, not
+  a keyword.
+
+**The floor (always, regardless of stance):** when you assert something the
+source didn't state outright, mark it — add `{"inferred": true}` (and a `source`
+snippet when useful) to that node/edge's properties. An inference is always
+visible and revertible, never laundered into a stated fact. This isn't a stance
+choice; it's the one non-negotiable.
+
+## Guardrails
+- **Reversible, so don't freeze up.** Every write is logged; a bad edge is one
+  `kg --ontology NAME revert <event-id>` away. Compose confidently, then review.
+- **Respect `allowed_kinds`.** If the ontology constrains kinds, stay inside them
+  or surface what you'd have to add.
+- **Don't put data in ids.** (See *Id rules*.)
+- **One ontology per coherent domain.** If the source clearly spans two unrelated
+  domains, ask whether to split into two ontologies rather than blending them.
+
+## Anti-patterns
+- Minting ids by hand that bypass slug discipline (`person:Ada` vs
+  `person:ada-lovelace`) — breaks cross-document dedup.
+- Inventing relationships under `literal` stance.
+- Encoding a whole sentence as a node `name` instead of extracting the entity.
+- Emitting one write per entity — dozens of `kg_node_upsert`/`kg node add` calls —
+  when a single `kg_import` (MCP) or `kg import` (CLI) does the whole batch in one
+  gated, logged, atomic transaction. This is the most common mistake; don't.

knowledge_graph_rdbms-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Test / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local graph databases
+*.db
+*.db-wal
+*.db-shm
+
+# Scratch / generated artifacts (benchmark JSON, charts).
+# Promote a chart worth keeping into assets/ and commit that explicitly.
+temp/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

knowledge_graph_rdbms-0.1.0/CLAUDE.md

@@ -0,0 +1,110 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A label property graph (nodes, typed directed edges, labels, JSON properties) stored in SQLite. The core library has **zero third-party dependencies** — everything is stdlib + SQLite. Three front doors (Python library, `kg` CLI, MCP server) sit on one gated + logged engine, and a **control plane** (`resolver.py` + the `backends/` package) lets all three address *many named ontologies* — each its own file (or, eventually, its own engine) — through one interface. See `README.md` for the full design narrative.
+
+## Commands
+
+```bash
+uv venv && uv pip install -e ".[dev]"   # set up dev env (installs pytest + mcp)
+
+pytest                                   # run all tests (~62)
+pytest tests/test_graph.py               # one file
+pytest tests/test_graph.py::test_name    # one test
+pytest -k events                         # by keyword
+
+python bench/benchmark.py                # perf, full p50–p99 distributions
+python bench/charts.py                   # render assets/*.png from bench data (needs [charts])
+python bench/runtimes/compare.py         # CPython vs Node vs Bun SQLite comparison
+
+kg stats                                 # default ontology (~/.kgrdbms/graph.db)
+kg ontology list                         # the registry (the "db of dbs")
+kg ontology create coffee --stance inferential   # register a named ontology
+kg --ontology coffee node add drink:latte --kind Drink   # route to it (resolver)
+kg --db /tmp/x.db node add a:1 --kind T  # raw escape hatch: exact file, no registry
+kg serve                                 # run the MCP server (needs [mcp] extra)
+```
+
+There is no linter/formatter configured — match the surrounding style (type hints, `from __future__ import annotations`, dataclasses).
+
+## Architecture: the load-bearing ideas
+
+**Two write paths, and the distinction is the whole point.**
+
+- **Direct path** — `graph.py` methods (`g.add_node`, `g.add_nodes`, `g.batch()`). Writes go straight to the SQLite projection. Fast, but **not gated and not logged** — `replay()` will not reproduce them. Use for bulk loading raw data.
+- **Logged path** — everything in `service.py` (used by the CLI and MCP server). Each mutation is gated, then applied, then appended to the `graph_events` log. Audited, reversible, replayable.
+
+When you add or change a mutation, decide which path it belongs to. A new gated operation must go through `service.py`, not directly on `Graph`.
+
+**The graph is a projection; the event log is the source of truth.** `events.py` holds an append-only log. `replay(graph, events, genesis=...)` rebuilds the projection from an optional declarative seed + the log, optionally `upto_ts=` for time travel. Undo is `compensate()` — it appends the *inverse* event, never deletes a row. If you add a new logged operation, you must also make it replayable and compensatable in `events.py` (add an `OP_*` constant + apply/compensate handling).
+
+**The two-layer mutation gate, in order.** `service.guard()` runs `invariants.enforce()` **before** `policy.mutation_check()`:
+
+- `invariants.py` = mechanism. Compiled-in, no off switch, changing one is a code change. Default: no-op.
+- `policy.py` = configuration. A single `mutation_check(ctx) -> Decision`. Default: permissive (allow all). The file has commented example policies at the bottom.
+
+Order matters: a permissive or compromised policy can never re-open something an invariant sealed. Failures raise `InvariantViolation` (invariant) vs `PermissionError` (policy) — keep these distinct.
+
+**Hooks resolve through their modules at call time.** `guard()` calls `invariants.enforce` / `policy.mutation_check` via the module, not a captured reference — so editing policy (or monkeypatching it in a test) takes effect across all three front doors at once. Don't `from policy import mutation_check` into the service and call it directly; that would break this.
+
+## Control plane: ontologies, the resolver, the backend registry
+
+The engine above (`graph.py` + `service.py` + the log + the gate) operates on **one** graph. The control plane lets the three front doors address **many named ontologies** through that same engine, without any of them knowing where an ontology physically lives.
+
+**`resolver.py` maps an ontology *name* → a `Resolved(backend, events, entry)` bundle.** Callers say `resolve("coffee")`; the resolver looks the name up in an **index** (itself a kg — `<root>/index.db`, nodes of kind `Ontology`), opens the right backend, pairs it with an event log, and hands back the bundle. The front doors then call the *same* `service.*` functions as before — the gate and the log didn't move, only *which* `(graph, events)` pair gets passed in. That's why multi-tenancy was a small change: the single write path was already the choke point.
+
+- **The default ontology is the legacy file.** `resolver._default_db_path` special-cases the default name → `<root>/graph.db`, so omitting `--ontology` / the `ontology` arg behaves exactly as the pre-resolver code did. Backward-compat lives in that one function; both front doors inherit it. Don't scatter default-path logic elsewhere.
+- **Isolation is filesystem-shaped, not code-shaped.** Each named ontology is its own SQLite file under `<root>/ontologies/<slug>/graph.db`, with its own event log. No tenant-id columns, no row filtering — "coffee doesn't know Ada" because they're different files.
+
+**`backends/` is the pluggable data plane (engine registry).** An engine is a factory `(*, location, **opts) -> GraphBackend` registered with `@backend("name")`. Adding one = write a module + decorate its factory + add one import line in `backends/__init__.py`. **No switch to edit** — `resolver._open_backend` does `get_backend(entry.backend)(location=...)` and never knows which engines exist.
+
+- `backends/base.py` — the `GraphBackend` Protocol (the finite method surface `service.py` + reads depend on; `Graph` satisfies it *structurally*, zero changes to `graph.py`) and `_StubBackend` (raising skeleton so a half-built engine is still a routable, fail-loud `GraphBackend`).
+- `sqlite.py` and `postgres.py` are **live**; `neo4j.py` is a **stub** (routes and fails per-call with what's missing; its docstring is the ADR for how it'd be built). `postgres.py` is the scale-up: same five-table model + query shapes ported to psycopg (`%s`, `ON CONFLICT`, `jsonb` properties, `= ANY(%s)`, the recursive-CTE `descendants`, BFS traversals reused verbatim). It needs the `postgres` extra (`psycopg`), imported lazily so `import kgrdbms.backends` works without it; a missing driver raises `NotImplementedError`. `location` for postgres is a DSN, not a file path — `register()` requires it for any non-sqlite backend.
+- **The event log is decoupled from the backend.** `EventLog(store, projection=None)`: *store* is the SQLite that holds the log rows; *projection* is the `GraphBackend` that `compensate()`/replay apply to. They coincide for sqlite (`EventLog(graph)` — projection defaults to store, unchanged). For postgres the store is `resolver._ControlPlaneLogStore` (a `<root>/ontologies/<slug>/events.db` sidecar) and the projection is the `PostgresGraph` — so audit/replay/undo keep working with graph data in Postgres and history in SQLite. `apply_event` only calls `GraphBackend` methods, so it drives any backend. This store↔projection split is the seam to respect for *any* non-sqlite engine (neo4j next).
+- **New failure class:** routing to a stub engine raises `NotImplementedError`. Every front door's error handling must account for it (the CLI's `main()` already maps it to `unavailable: …` / exit 1).
+
+## Layout
+
+```
+kgrdbms/
+├── graph.py        # the LPG over SQLite — imports nothing internal; usable standalone
+├── events.py       # append-only event log: OP_* constants, record, compensate, replay
+├── policy.py       # configurable mutation policy (edit mutation_check)
+├── invariants.py   # compiled-in invariants, run before policy (no-op default)
+├── service.py      # the shared gated + logged write path (all front doors use this)
+├── resolver.py     # control plane: name → (backend, events, entry); the ontology index
+├── backends/       # pluggable data plane (engine registry)
+│   ├── base.py     #   GraphBackend Protocol + _StubBackend
+│   ├── __init__.py #   registry: @backend(name), get_backend, available_backends
+│   ├── sqlite.py   #   live engine (adapter over Graph)
+│   ├── postgres.py #   live engine (psycopg; jsonb + recursive CTEs); needs [postgres] extra
+│   └── neo4j.py    #   stub (deep-traversal escalation)
+├── cli.py          # the `kg` command (stdlib argparse) — `--ontology` / `--db` / `kg ontology …`
+└── mcp_server.py   # MCP server, kg_-prefixed tools, each with optional `ontology=` (optional [mcp] extra)
+```
+
+`graph.py` has no internal dependencies — everything else layers on top of it. Dependency direction: `graph` ← `events`/`backends` ← `resolver` ← `service`-callers (`cli`, `mcp_server`). `service.py` depends only on the `GraphBackend` surface, never a concrete engine. Public API is re-exported from `__init__.py`.
+
+## Node id convention (CURIEs)
+
+Node ids follow `prefix:reference` — `person:ada-lovelace`, `company:apple`, `card:abc123`. This is deliberately a **CURIE** (a compact URI: the prefix is shorthand that expands to a full IRI through a lookup table you only need the day you publish to the RDF/linked-data world). Adopting the shape now keeps interop a cheap, additive option later; until then a CURIE stands alone as a plain string. Three rules:
+
+1. **`prefix`** is a short, stable, lowercase type word (`person`, `company`, `card`, `device`) — not the `kind` field's exact casing, just a stable token.
+2. **`reference`** is slugged. Mint ids with `slug(name, prefix="person")` → `person:ada-lovelace`. **`slug()` is the CURIE constructor and the dedup mechanism** — but `add_node` does *not* auto-slug the id it's handed, so an id minted by hand (`"person:Ada"`) will *not* collapse with `slug()`-minted ones. Always go through `slug()` when the local part comes from natural language.
+3. **The id is an address, not a record.** Put identity in the id (`company/apple`), never mutable attributes (`status=active`) — those are node *properties*. Mental model: the id is a URL's *path* (stable), properties are its *query string* (changeable). Baking a changeable fact into an id breaks identity when the fact changes.
+
+**Namespacing is free and you don't type it.** Each ontology is its own file with its own registry name, so "which world a node came from" is already known — the ontology *is* the namespace. If two ontologies are ever merged, qualify by ontology name; you don't pre-encode it in the id. An ontology that genuinely needs strict global identity sets its `id_convention` on the registry entry (currently descriptive metadata; the per-ontology enforcement seam, not yet wired to a validator) and adopts fuller CURIE/IRI discipline without affecting the others.
+
+**No RDF stack.** This is the *only* RDF idea adopted (identity, because it's the one expensive-to-retrofit decision). No OWL, no SPARQL, no triplestore-as-storage. Interop (Turtle/JSON-LD) and vocabulary borrowing (SKOS, PROV-O) are deferred until a real external consumer exists — both are additive at the boundary, store LPG inside.
+
+## Conventions that bite
+
+- **Edges are unique on `(from_node, type, to_node)`.** Re-adding the same triple updates properties rather than duplicating — mutations are idempotent by construction. Tests rely on this.
+- **`slug()` deduplicates natural-language ids** — two strings that slugify the same collapse to one node id (see *Node id convention* above; `add_node` does not auto-slug).
+- **Properties round-trip as JSON.** Storage is `value_json`; ints/bools/lists/objects come back as their JSON type. CLI `--prop key=value` parses value as JSON when possible, else keeps it as a string.
+- **Per-call writes each commit (one fsync).** Wrapping work in `batch()` / using `add_nodes` / `add_edges` collapses to one transaction (~10× faster). Don't add a per-row commit inside a bulk loop.
+- **Reads are not in `service.py`** by design — callers hit `Graph` directly. Don't route reads through the gate.
+- **CLI exit codes are contractual:** `0` ok, `1` not found / bad input, `2` policy denial, `3` invariant violation. Preserve these.

knowledge_graph_rdbms-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+## The short version
+
+Be kind, be constructive, assume good faith. This is a small project and a
+welcoming one — technical disagreement is good, personal hostility is not.
+
+## Expected behavior
+
+- Be respectful of differing viewpoints and experience levels.
+- Give and accept constructive feedback gracefully.
+- Focus on what's best for the project and its users.
+- Show empathy toward other community members.
+
+## Unacceptable behavior
+
+Harassment, discriminatory or derogatory comments, personal or political attacks,
+publishing others' private information, or other conduct that would reasonably be
+considered inappropriate in a professional setting.
+
+## Scope
+
+Applies in all project spaces — issues, pull requests, discussions — and when
+representing the project in public spaces.
+
+## Enforcement
+
+Report unacceptable behavior privately to the maintainer via GitHub (see
+`SECURITY.md` for the private-contact route). Reports will be reviewed and
+handled in good faith; the maintainer may remove, edit, or reject contributions
+and comments that violate this code, and may ban contributors for behavior they
+deem inappropriate.
+
+This Code of Conduct is adapted in spirit from the
+[Contributor Covenant](https://www.contributor-covenant.org/).

knowledge_graph_rdbms-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for your interest. This is a small, opinionated project — the goal is a
+knowledge graph you can hold in your head, so contributions that keep it legible
+are worth more than ones that add surface area.
+
+## Setup
+
+```bash
+git clone https://github.com/cunicopia-dev/knowledge-graph-rdbms
+cd knowledge-graph-rdbms
+uv venv && uv pip install -e ".[dev]"     # pytest + mcp
+pytest                                     # should be all green
+```
+
+The Postgres backend and its tests are optional — they need the `postgres` extra
+and a reachable Postgres (`pip install -e ".[dev,postgres]"`); the suite skips
+those tests cleanly when no database is available.
+
+## The rules that matter here
+
+These aren't style nits — they're the load-bearing invariants the design depends
+on. A change that breaks one of these will be asked to change, no matter how nice
+it looks.
+
+1. **The core stays zero-dependency.** `kgrdbms` (the library, CLI, engine) imports
+   only the standard library + SQLite. Third-party deps live behind extras
+   (`mcp`, `postgres`, `charts`) and are imported lazily. Don't add a hard
+   dependency to the core.
+
+2. **Mutations go through the gate.** Any new *logged* operation must go through
+   `service.py` (which runs `invariants.enforce` then `policy.mutation_check`,
+   then records the event) — not directly on a backend. The direct `Graph`
+   methods are the unlogged fast path, on purpose; know which one you're adding to.
+
+3. **A new logged op must be replayable and reversible.** If you add an operation
+   to the event log, add its `OP_*` constant plus `apply_event` and `compensate`
+   handling in `events.py`. "Every mutation can be replayed and undone" is a
+   guarantee, not a nice-to-have.
+
+4. **Backends register; they don't get switched on.** A new engine is a module in
+   `backends/` with a factory decorated `@backend("name")` and one import line in
+   `backends/__init__.py`. It implements the `GraphBackend` protocol. No `if
+   engine == ...` ladders anywhere.
+
+5. **Node ids are CURIEs** (`prefix:reference`, minted via `slug()`). See the
+   convention in `CLAUDE.md` / the README before inventing id shapes.
+
+6. **CLI exit codes are contractual:** `0` ok · `1` not found / bad input · `2`
+   policy denial · `3` invariant violation · (`unavailable`/1 for an unbuilt
+   backend). Preserve them.
+
+`CLAUDE.md` documents the architecture in more depth — it's worth a read before a
+non-trivial change.
+
+## Style
+
+There's no linter or formatter configured — match the surrounding code:
+`from __future__ import annotations`, type hints, dataclasses, clear names over
+clever ones. Reads are not gated; writes are. Keep tests close to the behavior
+they describe.
+
+## Pull requests
+
+- Keep the diff focused; one idea per PR.
+- Add or update tests — `pytest` should pass, and new behavior should be covered.
+- If you change a public behavior, update the README and `CLAUDE.md` to match.
+- Describe *why*, not just *what*, in the PR body.
+
+Small fixes and docs improvements are very welcome. For larger changes (a new
+backend, a new logged operation, a change to the gate), open an issue first so we
+can agree on the shape before you build it.

knowledge_graph_rdbms-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Cunic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.