Metadata-Version: 2.4
Name: trugs
Version: 2.0.0
Summary: TRUGS — Traceable Recursive Universal Graph Specification (spec-only since 2.0; install `trugs-tools` for the `trug` language CLI)
License: Apache-2.0
Project-URL: Homepage, https://github.com/TRUGS-LLC/TRUGS
Project-URL: Documentation, https://github.com/TRUGS-LLC/TRUGS/blob/main/GETTING_STARTED.md
Project-URL: Source, https://github.com/TRUGS-LLC/TRUGS
Project-URL: Issues, https://github.com/TRUGS-LLC/TRUGS/issues
Project-URL: Changelog, https://github.com/TRUGS-LLC/TRUGS/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# TRUGS — Traceable Recursive Universal Graph Specification

[![PyPI](https://img.shields.io/pypi/v/trugs.svg)](https://pypi.org/project/trugs/)
[![Python](https://img.shields.io/pypi/pyversions/trugs.svg)](https://pypi.org/project/trugs/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![CI](https://github.com/TRUGS-LLC/TRUGS/actions/workflows/compliance.yml/badge.svg)](https://github.com/TRUGS-LLC/TRUGS/actions/workflows/compliance.yml)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19379454-blue.svg)](https://doi.org/10.5281/zenodo.19379454)

**Maintained by:** TRUGS LLC

## What is TRUGS?

TRUGS is a JSON graph specification for representing structured information. A TRUG is a JSON file with three components:

1. **Nodes** — typed things (functions, pages, chapters, tasks, parties)
2. **Edges** — named relationships between things (feeds, governs, depends_on)
3. **Hierarchy** — organization via parent/child containment using metric levels

**CORE + BRANCH = Complete TRUG.** CORE defines the universal structure every TRUG must satisfy. BRANCHES define domain-specific vocabularies.

```mermaid
flowchart LR
    S["TRUG/L sentence<br/>(233 words)"] <-->|compile/decompile| G["TRUG graph<br/>(nodes · edges · hierarchy)"]
    G -.validates against.-> C["CORE<br/>(7 boundaries · 16 rules)"]
    G -.extends.-> B["BRANCH<br/>(domain vocabulary)"]
```

The sentence IS the program. The graph IS the AST. Every valid TRUG/L sentence compiles to a graph losslessly, and every graph decompiles back to a sentence.

## Install

```bash
pip install trugs
```

**As of 2.0.0 (breaking), `trugs` ships the specification only — no CLIs.** Spec content (`CORE`, `TRL` vocabulary, reference papers) is packaged as data. The 2.0.0 release also adds 21 SI level prefixes (YOTTA…YOCTO) as a new part of speech for hierarchy transition markers — see [SPEC_vocabulary.md §9](TRUGS_LANGUAGE/SPEC_vocabulary.md#9-level-prefixes--hierarchy-transition-markers-21). For the `tg` CLI and all tooling, install the sibling package:

```bash
pip install trugs-tools    # provides the `tg` binary (36 operations)
tg --help
```

See [TRUGS-LLC/TRUGS-TOOLS](https://github.com/TRUGS-LLC/TRUGS-TOOLS) for the unified `tg` CLI — validation, memory, compliance, AAA protocol, and more.

**Migrating from `trugs` 1.x?** The pre-2.0 package shipped `tg validate`, `tg memory`, etc. as entry points. In 2.0.0 those move to `trugs-tools`. Migration is one additional install: `pip install trugs-tools` and every `tg <op>` command works identically.

## TRUGS Language

TRUGS includes a formalized subset of English — 233 words drawn from computation, law, and SI prefixes — where every valid sentence compiles to a TRUG graph and every graph decompiles back to a sentence. Losslessly.

```
PARTY system SHALL FILTER ALL ACTIVE RECORD
  THEN SORT RESULT
  THEN WRITE RESULT TO ENDPOINT output
  OR RETRY BOUNDED 3 WITHIN 60s.
```

Every word is from the vocabulary. The sentence IS the program. The graph IS the AST.

See [TRUGS_LANGUAGE/](TRUGS_LANGUAGE/) for the complete specification.

## Specification

| Document | Description |
|----------|-------------|
| [CORE.md](TRUGS_PROTOCOL/CORE.md) | 7 boundaries, 10 primitive classes (~131 primitives), 16 validation rules, composition type system |
| [BRANCHES.md](TRUGS_PROTOCOL/BRANCHES.md) | Domain-specific vocabularies (Python, Web, Writer, Knowledge, etc.) |
| [SPEC_fundamentals.md](TRUGS_PROTOCOL/SPEC_fundamentals.md) | Core concepts and structure |
| [SPEC_validation.md](TRUGS_PROTOCOL/SPEC_validation.md) | Validation rules with implementations |
| [SCHEMA.md](TRUGS_PROTOCOL/SCHEMA.md) | JSON schema reference |

## Language

| Document | Description |
|----------|-------------|
| [SPEC_vocabulary.md](TRUGS_LANGUAGE/SPEC_vocabulary.md) | 233 words, 9 parts of speech, formal definitions |
| [SPEC_grammar.md](TRUGS_LANGUAGE/SPEC_grammar.md) | BNF grammar, composition rules, 12 validation rules |
| [SPEC_examples.md](TRUGS_LANGUAGE/SPEC_examples.md) | 30 parsed examples across 13 patterns |
| [language.trug.json](TRUGS_LANGUAGE/language.trug.json) | The opening TRUG — the language defining itself |

## Tools — via `trugs-tools`

All operations below use the unified `tg` CLI from the sibling [`trugs-tools`](https://github.com/TRUGS-LLC/TRUGS-TOOLS) package (`pip install trugs-tools`). 36 operations under 21 top-level verbs + 3 sub-namespaces.

| Verb | Usage | Description |
|------|-------|-------------|
| `tg validate` | `tg validate <file>` | Enforces all 16 CORE rules |
| `tg validate` | `tg validate --all <dir>` | Batch validation |
| `tg get` | `tg get <file> <node_id>` | Read a node |
| `tg update` | `tg update <file> <node_id> --set key=value` | Update a node |
| `tg delete` | `tg delete <file> <node_id>` | Delete a node and its edges |
| `tg unlink` | `tg unlink <file> --from X --to Y` | Remove an edge |

See [`SPEC_cli.md`](https://github.com/TRUGS-LLC/TRUGS-TOOLS/blob/main/REFERENCE/SPEC_cli.md) in the trugs-tools repo for the full command surface.

**Legacy (trugs 1.2.x only):** the same operations are available as `python tools/validate.py`, `python tools/tget.py`, etc. in this repo's `tools/` directory. That directory disappears at `trugs` 2.0.0.

## Examples

The [EXAMPLES/](EXAMPLES/) directory contains sample TRUGs for 6 domains at varying complexity levels. All 19 examples pass validation.

## This repo, as a TRUG

This repository describes itself as a TRUG. [`folder.trug.json`](folder.trug.json) at the repo root is the machine-readable index — every top-level folder, every reference document, every public tool has a node, with typed edges to the specs and standards it implements or describes.

```bash
# What's in this repo?
tg ls folder.trug.json

# What does the compliance checker depend on?
tg get folder.trug.json tools_compliance_check --edges

# Does the graph match the filesystem?
tg check .
```

CI runs `tg check` on every PR — this README's section list, the spec index, the tool table above all correspond to nodes you can traverse programmatically. When the TRUG drifts from the prose or the filesystem, CI fails. We dogfood our own dogfood.

## Use It

**[TRUGS-AGENT](https://github.com/TRUGS-LLC/TRUGS-AGENT)** — copy one file into your project and your LLM speaks TRL, follows a 9-phase development protocol, tracks projects as graphs, and maintains persistent memory. Seven standalone components:

| Component | What It Does |
|-----------|-------------|
| FOLDER | Machine-readable filesystem index — one JSON graph per folder |
| AAA | 9-phase development protocol — plan before code, audit before ship |
| EPIC | Portfolio tracker as a traversable graph |
| MEMORY | Persistent context across sessions |
| TRUGGING | Methodology for describing a codebase with TRUGs and TRL |
| WEB_HUB | Curated web resource graph |
| NDA | Complete example — all systems applied to a mutual NDA |

## Building on TRUGS

**CORE and Language** are maintained by TRUGS LLC. The 233-word vocabulary, grammar, and validation rules are the specification — they don't change without a spec revision.

**Branches** are where the community builds. If your domain needs vocabulary that doesn't exist (medical, financial, legal, robotics, etc.), build a branch:

1. Define your domain's node types and edge relations
2. Use CORE primitives as your foundation
3. Add domain-specific words to your opening TRUG
4. Validate your TRUGs against CORE

You don't need permission. Build it, use it, share it. Once enough people are using a branch in the same domain, we'll work with the community to formalize it into the specification.

**Implementations** are welcome. Build tools that read, write, validate, or execute TRUGs in any language. The spec is the contract — implement it however you want.

## License

The TRUGS specification and reference tools are released under the [Apache License 2.0](LICENSE). Anyone may implement the standard.
