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:

[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:

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

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.