aethellib 0.8.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.

## Status

- Current version: 0.8.2
- Under active development

## Installation

```bash
cargo add aethellib
```

## Quick Start

Load a corpus and generate one composed weapon name.

```rust
use aethellib::engine::combinators::{concat, lit, pick};
use aethellib::prelude::*;

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

let ctx = Engine::new(&corpus, rand::rng())
	// with_rule is chainable
    .with_rule(concat(
        "weapon_name",
        pick("prefix", "name".to_string(), "prefix".to_string()),
        concat(
            "type_part",
            lit(" "),
            pick("type", "name".to_string(), "type".to_string()),
        ),
    ))
    .generate()?;

let name = ctx.get_previous("weapon_name").unwrap().value.as_str();
println!("Generated weapon: {name}");
```

For a fuller reference workflow, see [examples/main.rs](examples/main.rs).

## Core Concepts

- Corpus: A loaded set of documents for one target such as `weapon` or `person`.
- Rules: Composable operations that read pooled values and return generated text.
- Engine: Runs rules in order and stores prior outputs in generation context.
- 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