aethellib 0.9.4

# 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

```bash
cargo add aethellib
```

## Quick Start

Load a corpus, build a typed plan, compile once, and generate.

```rust
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](examples/unified_api.rs) and [examples/main.rs](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:

```bash
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