Crate aethellib 

aethellib

aethellib is a small Rust library for composable text generation over target-specific TOML corpora.

It focuses on three things:

• Loading typed documents into a single-target Corpus
• Generating text with composable rules and compiled plans
• Preserving source provenance for generated values so outputs remain traceable

Core Concepts

• corpus loads and validates documents, then builds pooled values grouped by section and field.
• engine validates and executes rule-based generation plans and stores prior outputs in a GenerationContext.
• prelude re-exports the most commonly used types for quick onboarding.

Why Provenance Matters

Generated text is more useful when you can explain where it came from. aethellib keeps provenance on pooled and composed values so you can:

• Debug generation outcomes quickly
• Audit content sources for pipelines and toolchains
• Build UI/UX that can show source attribution to users

Architecture

TOML Sources
    |
    v
corpus::Corpus::from_files / CorpusBuilder
    |
    v
Value Pools (section + field, with provenance)
    |
    v
engine::PlanBuilder + Rule
    |
    v
validate + compile
    |
    v
GenerationContext (named outputs + provenance)

Quick Start

use aethellib::engine::combinators;
use aethellib::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let corpus = Corpus::from_files(&["data/weapon_test_data.toml"], "weapon", None, None)?;
    let key = RuleKey::new("weapon_name")?;
    let prefix = PoolRef::new("name", "prefix")?;
    let kind = PoolRef::new("type", "type")?;

    let compiled = PlanBuilder::new(&corpus)
        .rule(
            &key,
            combinators::join([
                combinators::pick(prefix),
                combinators::lit(" "),
                combinators::pick(kind)
           ]),
        )
        .validate()?
        .compile()?;

    let mut rng = rand::rng();
    let ctx = compiled.generate(&mut rng)?;

    println!("{}", ctx.require(&key)?.value);

    Ok(())
}

For a fuller workflow (chance, recall, custom expressions), see examples/main.rs in the repository.

API At A Glance

• Corpus::from_files to load corpora from TOML sources
• PlanBuilder::new and PlanBuilder::rule to build typed plans
• combinators for rule helpers like pick, join, and weighted
• prelude for ergonomic imports in applications and examples

Stability

aethellib is currently pre-1.0. Public API naming and module layout may evolve as the crate approaches 1.0.0.

Modules

corpus

corpus module entrypoint.

engine

generation engine for rule-based planning and compiled execution.

prelude

Lightweight re-exports for common application-level usage.