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 typed plan, compile once, and generate.

use aethellib::engine::combinators::typed;
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(),
        typed::join([typed::pick(prefix), typed::lit(" "), typed::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/unified_api.rs and examples/main.rs.

Core Concepts

• Corpus: A loaded set of documents for one target such as weapon or person.
• Rule Expressions: Typed operations that read pools and compose generated text.
• Compiled Plan: Validated execution graph that runs in dependency order.
• 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