aethellib

aethellib is a Rust library for composable text generation from target-specific TOML corpora with source provenance tracking.

What It Does

• Loads and validates attributed TOML documents into a single-target corpus.
• Pools values by section and field for rule-based generation.
• Runs composable generation rules through an execution engine.
• Preserves value provenance so outputs can be traced to source data.

Installation

cargo add aethellib

Quick Start

Load a corpus, build a rule-based plan, compile once, and generate.

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

let prefix = PoolRef::new("name", "prefix")?;
let kind = PoolRef::new("type", "type")?;
let weapon_name = RuleKey::new("weapon_name")?;

let corpus = Corpus::from_files(
    &["path_to_file.toml"],
    "weapon",
    None, // options
    None, // validator
)?;

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

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

let name = ctx.require(weapon_name)?.value;
println!("Generated weapon: {name}");

For full reference workflows, see examples/main.rs.

Core Concepts

• Corpus: A loaded set of documents for one target such as weapon or person.
• Rules: Executable operations that read pools and compose generated text.
• Compiled Plan: Validated execution graph that runs in dependency order.
• Combinators: Built-in rules for picks, unique picks, choices, fallback, joins, and transforms.
• Provenance: Generated values carry source metadata for traceability.

Design Philosophy

• Keep the core focused on single-target corpus loading and generation primitives.
• Prefer composable building blocks over a rigid generation DSL.
• Treat provenance as first-class so generated outputs remain explainable.
• Keep dependencies minimal and behavior explicit.

Contributing

Contributions are welcome.

Before opening a pull request, run:

cargo fmt
cargo clippy
cargo test

If you change API behavior, include updates to examples and tests in the same PR.

License

Apache License 2.0.

Author

Arad Fadaei