Distinction Tree Storage (DTS)

Overview

DTS (Distinction Tree Storage) is Braid's AI-native knowledge graph memory system. It stores facts as a directed tree of distinction nodes (subject → predicate → object triples) with epistemic weighting, domain isolation, and embedding-based neural integration. DTS serves as the long-term memory backbone for the Braid AI runtime, enabling RAG pipelines, anti-hallucination, contradiction detection, and knowledge-augmented generation.

DTS is exposed to Braid code via std.dts (declared in braid-lang/lib/std/dts.bd) and backed by native C implementations in braid-lang/src/runtime/.

Core API

import std.dts

fn main() {
    # Analyze natural language into a distinction tree
    let tree = dts.analyze("The Earth orbits the Sun")

    # Store the tree in a namespace
    dts.store(tree, "astronomy")

    # Persist to disk
    dts.save(tree, "knowledge.dts")

    # Load from disk
    let loaded = dts.load("knowledge.dts")

    # Debug print the tree structure
    dts.debug(loaded)
}

ML Integration

DTS trees can be trained on natural language text and used for next-word prediction via the distinction graph.

import std.dts

fn main() {
    let tree = dts.analyze("")
    dts.train(tree, "The cat sat on the mat")
    dts.train(tree, "The dog ran in the park")

    # Predict next word given prefix
    let next = dts.predict(tree, "The")
    io.println(next)

    # Train from a file
    dts.train_file(tree, "corpus.txt")
}

Knowledge Operations

Bind logical axioms and verify the consistency of stored knowledge.

import std.dts

fn main() {
    let tree = dts.analyze("")

    # Bind an axiom with a truth value
    dts.bind_axiom(tree, "gravity_exists", 1)

    # Verify knowledge consistency
    let valid = dts.verify(tree)
    io.println(valid)
}

Neural Bridge — Embeddings & RAG

The DTS neural bridge (dts_neural_bridge.c) converts distinction subgraphs into tensor embeddings for integration with Braid's ML pipelines.

# C-level API (accessed via native bindings)
let emb = dts_to_embedding("gravity", 64)
let ctx = dts_query_context("Earth orbits Sun", 16, 64)
dts_train_from_text("The Earth orbits the Sun", "astronomy")

The dts_rag_query() function retrieves relevant facts from the DTS knowledge graph given a natural language query:

# RAG query — returns string of matching facts
let facts = dts_rag_query("What orbits the Sun?", 10, "astronomy")
# Returns: "Fact: Earth orbits Sun.\nFact: Jupiter orbits Sun.\n..."

Anti-Hallucination

Two functions bias generation logits toward tokens that are consistent with stored knowledge, and penalize tokens that contradict it.

# Bias logits toward knowledge-consistent tokens
let biased = dts_bias_logits(logits, "The Earth", 0.5)

# Penalize hallucinated tokens
let safe = dts_anti_hallucinate(logits, "The Earth", 0.3)

Contradiction Detection

The contradiction detector (dts_contradiction.c) checks whether a statement conflicts with stored knowledge using SPO (subject-predicate-object) extraction and graph traversal.

# Returns 1 if contradiction found, confidence in out param
let is_contra = dts_detect_contradiction("The Earth is flat", "astronomy")
if is_contra {
    io.println("Contradiction detected!")
}

Fact Extraction

The neural fact extractor (neural_fact_extractor.c) splits text into sentences, extracts subject-predicate-object triples, and stores them into the DTS graph.

# Extract facts from natural language
let facts = extract_facts("The Sun is a star. Earth has a moon.", "astronomy")
store_facts_in_dts(facts, "astronomy")
extracted_facts_free(facts)

RAG Pipeline Example

A complete Retrieval-Augmented Generation pipeline using DTS:

import std.dts

fn build_knowledge_base() {
    let tree = dts.analyze("")
    dts.train(tree, "Python is a programming language")
    dts.train(tree, "Python was created by Guido van Rossum")
    dts.train(tree, "Python supports object-oriented programming")
    dts.store(tree, "programming")
    dts.save(tree, "python_kb.dts")
}

fn query_knowledge(query: string) {
    let tree = dts.load("python_kb.dts")
    # Predict gives us DTS-guided completion
    let facts = dts.analyze(query)
    let result = dts.predict(facts, query)
    io.println(result)
    dts.debug(tree)
}

fn main() {
    build_knowledge_base()
    query_knowledge("Python")
}

Knowledge-Augmented Generation Example

import std.dts

fn generate_with_context(topic: string, context: string) {
    let tree = dts.analyze(context)
    dts.train(tree, context)

    # Bind grounding axioms
    dts.bind_axiom(tree, topic, 1)
    dts.bind_axiom(tree, "factual", 1)

    let generated = dts.predict(tree, topic)
    io.print("Generated: ")
    io.println(generated)
}

Architecture

The DTS system is composed of several C modules under braid-lang/src/runtime/:

• dts_neural_bridge.c — Embeddings, query context, training, and neural integration
• dts_rag.c — Retrieval-Augmented Generation query execution
• dts_guided_gen.c — Logit biasing and anti-hallucination for guided generation
• dts_contradiction.c — Contradiction detection via graph comparison
• neural_fact_extractor.c — Natural language SPO triple extraction and storage

The header braid-lang/include/dts_neural.h exposes the full C API, while diameter_train.h extends DTS with dialectical reasoning capabilities (see the Diameter Reasoning page).