gmeow-gts 0.2.0

GTS (Graph Transport Substrate): a single-file CBOR transport for RDF 1.2 graphs — append-only log, BLAKE3 chain verification, deterministic fold, multi-segment cat-append composition.

gts — Graph Transport Substrate

A single-file, language-independent transport for an RDF 1.2 graph (statements and statement-level metadata) together with any content-addressed binary the graph references.

A GTS file is a CBOR Sequence of one or more segments, each an append-only log: a header followed by frames chained by BLAKE3 content-id. Composition is cat — concatenating valid GTS files yields a valid GTS file whose fold is the value-union of the segment graphs.

This package is the reference engine for the GTS specification: reader (fold, chain verification, opaque degradation, torn-append detection), writer, COSE signing and encryption, N-Quads projection, and the frozen language-neutral conformance corpus. GTS ships four independent, interoperable engines (Rust, Python, Go, TypeScript) that all gate against one frozen, byte-exact corpus — Python is the source of truth they are measured against.

Install

pip install gmeow-gts

The installed package name is gmeow-gts; the import name and CLI binary both remain gts, and GTS files keep the .gts extension. Optional extras: pip install 'gmeow-gts[rdf]' for rdflib interop and pip install 'gmeow-gts[db]' for the DuckDB/Parquet relational exports.

Library

Read a file (fold + verify the chain) and project to N-Quads, or build one with the writer:

from pathlib import Path

import gts

# Read + verify + fold, then project to N-Quads.
graph = gts.read(Path("package.gts").read_bytes())
print(gts.to_nquads(graph))

# Write a minimal graph.
w = gts.Writer(profile="dist")
w.add_terms([
    gts.Term(gts.TermKind.IRI, "https://example.org/Cat"),
    gts.Term(gts.TermKind.IRI, "http://www.w3.org/2000/01/rdf-schema#label"),
    gts.Term(gts.TermKind.LITERAL, "Cat", lang="en"),
])
w.add_quads([(0, 1, 2, None)])
Path("cat.gts").write_bytes(w.to_bytes())

Reading cat.gts back yields the expected statement:

<https://example.org/Cat> <http://www.w3.org/2000/01/rdf-schema#label> "Cat"@en .

gts.Term, gts.TermKind, gts.Writer, gts.read, and gts.to_nquads are the stable public surface; gts.from_nquads builds a graph from N-Quads text.

Command line

pip install gmeow-gts installs a gts binary whose verbs match the other engines (§14.1 of the spec — the engines are CLI-compatible by conformance test):

gts info <file>...            per-segment composition ledger
gts fold <file>               fold to N-Quads on stdout
gts from-nq <in.nq> -o <out>  build a GTS from N-Quads (inverse of fold; '-' = stdin)
gts verify <file>... [--key KID:HEXPUB]   verify chains + COSE signatures
gts extract-key <file>        print the embedded transport/verification key
gts cat -o <out> <file>...    validating composer: refuse degenerate inputs, then concatenate
gts ls <file>...              list inline blobs: digest, size, declared media type
gts pack <dir> -o <out>       package files/directories into a files-profile archive
gts unpack <file> -C <dir>    extract a files-profile archive (refuses path traversal)
gts extract <file> <digest>   write a single content-addressed blob
gts compact <file>            rewrite a segment into the streamable layout
gts diff <file> <directory>   compare a files-profile archive to a directory by digest
gts to-sqlite <file> <out>    export the folded graph to a SQLite database
gts to-duckdb <file> <out>    export to a DuckDB database (needs the [db] extra)
gts to-parquet <file> <dir>   export to Parquet, one file per table (needs the [db] extra)

Exit codes: 0 clean · 1 diagnostics or input refused · 2 usage/IO error.

cat output is the raw byte concatenation — validation added, transformation never. It refuses dirty inputs, contributes-nothing segments, and compositions whose suppressions hide every folded quad.

Signing, encryption, and key identity

GTS integrity is layered. Every frame carries an independent BLAKE3 self-hash and names its predecessor, so the head id transitively commits to all history. On top of that:

• COSE_Sign1 signatures (§9.2, RFC 9052) are optional and algorithm-agile; gts verify --key KID:HEXPUB checks them against a raw Ed25519 public key.
• COSE_Encrypt0 with AES-256-GCM (§9.3) encrypts payloads; a held-back key degrades a frame to an opaque node rather than failing the read.
• gts extract-key prints the embedded transport key's kid, OpenPGP fingerprint, emojihash, and armored public key. The emojihash is a human-readable visual fingerprint (the visual-hashing lineage, exposed as gts.emojihash.emojihash) so a person can eyeball that two files carry the same key. All four engines parse the embedded key to the identical fingerprint and emojihash.

Relational export

The folded graph can be projected into queryable stores via gts to-sqlite, gts to-duckdb, and gts to-parquet. SQLite export needs no extra; DuckDB and Parquet require the database extra:

pip install 'gmeow-gts[db]'
gts to-duckdb package.gts package.duckdb

GTS itself is not a database or query engine — these exports hand the graph off to a transform target for random-access query.

Example: grounded agent memory

The gts.examples.agent_memory module shows how to build a tiny claim store on top of GTS: every claim is a reified RDF 1.2 statement with confidence, standpoint, source, and timestamp; revision is supersession, never deletion; the file is always a valid, gts verify-able package.

pip install gmeow-gts
python -m gts.examples.agent_memory

from gts.examples.agent_memory import Memory

mem = Memory("assistant.gts")
mem.store(
    "Patrick prefers explicit error handling over exceptions-as-flow",
    source="conversation 2026-06-10",
    confidence=0.8,
    according_to="claude-fable-5",
)
print([c.text for c in mem.recall("error handling")])

This is the core motivation for GTS: portable, auditable, content-addressed agent memory that travels across sessions, models, and vendors as a signable, independently verifiable record.

Verifying the build

Wheels and sdists for gmeow-gts are built in GitHub Actions and signed with GitHub artifact attestations. After downloading a package from PyPI, verify it with:

gh attestation verify <path-to-wheel-or-sdist> --repo Blackcat-Informatics/gmeow-gts

An SPDX SBOM is also generated for each release and attached as a workflow artifact.

Contributing & security

Issues and pull requests are welcome — see CONTRIBUTING.md and the CODE_OF_CONDUCT.md. To report a vulnerability, follow SECURITY.md (do not open a public issue). The normative wire-format specification lives in docs/GTS-SPEC.md.

License

Triple-licensed: MIT OR Apache-2.0 OR proprietary — use under MIT or Apache-2.0 at your option; a proprietary license is also available (see LICENSING.md). © Blackcat Informatics® Inc.