Domain Tree Intake Nouns for riff

What it is

This project serves as a business-component precursor for riff's intake substrate. It manages vertical content as JSON tree data, enforces a strict Tree DSL via validation, and transforms locked hierarchical trees into flat capability dictionaries. These dictionaries define intake forms with branching logic, field phases (problem, triage, identity), and alias resolution maps, enabling structured data ingestion into the riff runtime.

Features

• Validates hierarchical JSON trees against a strict DSL schema
• Compiles locked trees into flat capability dictionaries with branching logic
• Generates draft domain trees using LLM prompts for rapid authoring
• Supports alias resolution maps for robust entity extraction
• Enforces conversation-order contracts (problem, triage, identity phases)
• Integrates with verification tools like SMS code and USPS address validation

Quickstart

.venv/bin/pytest -q
.venv/bin/python scripts/build_dist.py
.venv/bin/python -m intake_trees.tree_gen --domain plumbing --persona "experienced residential plumber" --out trees/plumbing.draft.json

Architecture

flowchart TD
    Author[Human Author]
    LLM[LLM Service]
    TreeGen[tree_gen.py]
    LockedTree[Locked JSON Tree]
    Validator[tree_schema.py]
    Compiler[tree_to_schema.py]
    Capability[Capability JSON]
    Riff[riff Runtime]
    Author -->|Prunes Draft| LockedTree
    LLM -->|Draft Tree| TreeGen
    TreeGen -->|Draft JSON| Author
    LockedTree -->|Validates| Validator
    Validator -->|Pass| Compiler
    Compiler -->|Compiles| Capability
    Capability -->|Ingests| Riff

How it's built

The core logic is implemented in pure Python using only the standard library. It consists of three main modules: tree_schema.py for DSL validation, tree_gen.py for LLM-assisted draft generation, and tree_to_schema.py for compiling locked trees into flat schemas. The build process is managed by scripts/build_dist.py, which reads locked JSON trees from the trees/ directory and outputs compiled capability JSON files to dist/.

How it runs

sequenceDiagram
    participant User as Human Author
    participant CLIGen as tree_gen CLI
    participant LLM as LLM Service
    participant TreeFile as Locked JSON Tree
    participant Compiler as tree_to_schema
    participant Dist as dist capability JSON
    participant Riff as riff Runtime
    User->>CLIGen: Run draft generation
    CLIGen->>LLM: Request domain nouns/questions
    LLM-->>CLIGen: Return draft JSON
    CLIGen-->>User: Save draft file
    User->>TreeFile: Prune and lock status
    User->>Compiler: Run build_dist script
    Compiler->>TreeFile: Read locked tree
    Compiler->>Compiler: Validate and compile
    Compiler->>Dist: Write capability JSON
    Riff->>Dist: Load capability JSON
    Riff->>Riff: Ingest intake schema

How to apply & reuse

Use this repository to author and validate domain-specific intake forms. Generate draft trees using the CLI, manually prune and lock them, then compile them into capability JSONs. Ingest these JSONs into the riff runtime by copying them into riff/intake_schemas.py or loading them directly. The resulting schemas drive the conversation flow, alias resolution, and field validation within the riff application.

At a glance