# Potential Expectations

Potential Expectations is a Rust workspace for composable agent runtimes. It
contains a publishable framework surface, supporting crates for graph execution,
tools, memory, tasks, matrix routing, LLM providers, and a local example app.

The top-level crate is `potential-expectations`. It re-exports the framework
crates so downstream users can start from one dependency and move to lower-level
crates when needed.

## Facade Quick Start

For most users, start with one dependency:

```toml
[dependencies]
potential-expectations = "0.1"
```

Then import the prelude. State types need serde derives because the runtime can
checkpoint and move state across graph boundaries. When using only the facade
crate, point serde at the facade re-export:

```rust
use potential_expectations::prelude::*;

#[derive(State, Clone, Debug, Serialize, Deserialize)]
#[serde(crate = "potential_expectations::serde")]
struct MyState {
    input: String,
    answer: Option<String>,
}

#[node]
async fn answer(state: &MyState) -> NodeResult<MyStateUpdate> {
    NodeResult::Update(MyStateUpdate::new().with_answer(Some(state.input.clone())))
}
```

Advanced users can still depend on leaf crates such as `pe-core`, `pe-graph`,
or `pe-runtime` directly when they want a narrower dependency surface.

## Workspace Layout

- `crates/potential-expectations`: top-level convenience crate.
- `crates/pe-core`: core messages, state, channels, errors, and traits.
- `crates/pe-graph`: graph execution primitives.
- `crates/pe-runtime`: async runtime, execution lifecycle, events, and metrics.
- `crates/pe-tools`: tool registry and tool node support.
- `crates/pe-agents`: agent registry and manifest-driven construction.
- `crates/pe-memory`: checkpointing and memory stores.
- `crates/pe-tasks`: task management primitives.
- `crates/pe-matrix`: matrix routing and empirical reasoning support.
- `crates/pe-prebuilt`: prebuilt agent topologies.
- `crates/pe-llm`: OpenAI-compatible LLM provider support.
- `apps/pe-local`: local runtime example app.
- `apps/pe-local-ui`: Tauri UI example for local operation.

## Development

```powershell
cargo check --workspace --all-targets
cargo fmt --all --check
cargo clippy --workspace --all-targets
cargo doc --workspace --no-deps
```

The local app has its own README in `apps/pe-local/README.md`.

## License

Licensed under either of:

- Apache License, Version 2.0 (`LICENSE-APACHE`)
- MIT license (`LICENSE-MIT`)

at your option.
