trugs-store

Graph storage backends for TRUGS specifications — InMemory, PostgreSQL, JSON file persistence.

trugs-store is the shared persistence layer for all TRUGS tooling. Every tool that reads or writes .trug.json files goes through this package. It supports JSON file storage for development and PostgreSQL for production scale.

As of 2.0.0, trugs-store natively supports TRUGS 2.0 (core_v2.0.0): vocabulary dispatch on a TRUG's declared capabilities.vocabularies, LEVEL_PREFIX hierarchy validation, inheritance stamping, and canonical re-emit on save. v1 TRUGs (core_v1.0.0, project_v1) load and save as before; since 2.2.0, validation also reports hierarchy cycles that 2.1.0 missed, in graphs of either version.

Install

pip install trugs-store

# With PostgreSQL support:
pip install trugs-store[postgres]

Quick Example

from trugs_store import InMemoryGraphStore, JsonFilePersistence

# Load a .trug.json file
persistence = JsonFilePersistence()
store = persistence.load("../folder.trug.json")

# Query
print(store.node_count())
print(store.find_nodes(type="FUNCTION"))

# Validate against TRUGS CORE rules
violations = store.validate_graph()
for v in violations:
    print(f"{v.severity}: {v.rule} — {v.message}")

Architecture

Basic Usage

Load and query a TRUG

from trugs_store import JsonFilePersistence

p = JsonFilePersistence()
store = p.load("../folder.trug.json")

# Find all FUNCTION nodes
functions = store.find_nodes(type="FUNCTION")

# Traverse outgoing edges from a node
for node, edge, depth in store.traverse("trugs_store_folder", direction="outgoing", max_depth=2):
    print(f"  {'  ' * depth}{node['id']} via {edge['relation']}")

Create a graph in memory

from trugs_store import InMemoryGraphStore

store = InMemoryGraphStore()
store.set_metadata("name", "my_graph")
store.set_metadata("version", "1.0.0")

store.add_node({"id": "root", "type": "FOLDER", "properties": {},
                "parent_id": None, "contains": [], "metric_level": "KILO_FOLDER",
                "dimension": "main"})
store.add_node({"id": "child", "type": "DOCUMENT", "properties": {},
                "parent_id": None, "contains": [], "metric_level": "BASE_DOCUMENT",
                "dimension": "main"}, parent_id="root")
store.add_edge({"from_id": "root", "to_id": "child", "relation": "REFERENCES"})

print(store.node_count())  # 2
print(store.get_children("root"))  # [child node]

Validate a graph

violations = store.validate_graph()
if violations:
    for v in violations:
        print(f"{v.severity}: {v.rule} on {v.node_id} — {v.message}")
else:
    print("Graph is valid.")

Documentation

• Package boundary: BOUNDARY.md — what STORE owns vs what TRUGS-TOOLS owns, and the deliberate two-validator split (structural vs CORE-16)
• TRUGS Specification: TRUGS-LLC/TRUGS — protocol, language, validator
• GraphStore Protocol: src/trugs_store/protocol.py — full PEP 544 interface (22 methods)
• TRUG Graph Index: folder.trug.json — machine-readable structure of this repo
• Dark Code Standard: TRUGS-LLC/TRUGS/REFERENCE/STANDARD_dark_code_compliance.md

Status

Version: 2.2.0 (TRUGS 2.0 native — core_v2.0.0 support) Phase: Beta License: Apache 2.0 — TRUGS LLC