Docs Getting started

Installation

An application depends on one crate, turnframe, and turns on the parts it uses with feature flags. The rest of the family comes in behind them.

Add the dependency #

shell

cargo add turnframe --features openai

or, in Cargo.toml:

toml

[dependencies]turnframe = { version = "0.1", features = ["openai", "postgres", "telemetry"] }tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

To follow the repository between releases, depend on it instead:

shell

cargo add turnframe --git https://github.com/turnframe-rs/turnframe --features openai

Requirements #

Rust 1.88 or newer. The workspace uses the 2024 edition.
Tokio. The runtime is asynchronous and runs on it; the core crate has no async runtime of its own.
A model provider for real turns: OpenAI, Azure OpenAI or a compatible endpoint, Anthropic, Gemini or Vertex AI, AWS Bedrock, or a local Ollama daemon. The examples and the test kit need none.
PostgreSQL only if you choose the reference store. The in-memory store needs nothing, and any database can back the store traits.

Feature flags #

None is on by default, and none changes the runtime's safety semantics.

Feature	What it turns on
`openai`	`provider::openai`: OpenAI, Azure OpenAI and OpenAI-compatible endpoints
`anthropic`	`provider::anthropic`: the Anthropic Messages API
`gemini`	`provider::gemini`: Google Gemini and Vertex AI
`bedrock`	`provider::bedrock`: AWS Bedrock Converse
`ollama`	`provider::ollama`: a local Ollama daemon
`all-providers`	every adapter above
`postgres`	`store::postgres`: the PostgreSQL reference store, its migrations and its expected-revision transactions
`prompts`	the prompt sources in `prompt`: prompts compiled in from your own repository, and a bounded cache. No network
`langfuse`	`prompts`, plus `prompt::langfuse`: prompts fetched from a Langfuse project over the Langfuse v4 API. A runtime dependency on a remote service
`telemetry`	`telemetry`: the `turnframe.*` metrics observer, tracing spans and the dashboard description
`otel`	`telemetry`, plus the OpenTelemetry bridge and the baggage-copying span processor
`test-kit`	`testing`: scripted providers and tasks, fake stores, workflow exploration and three sample domains
`eval`	`evaluation`: the model evaluation harness
`full`	`all-providers`, `postgres`, `prompts`, `telemetry`, `test-kit` and `eval`

The crate family #

Each crate can be used on its own, but the facade is the supported way in: its modules are named for what an adopter writes (flow, turn, interaction, command, event, response, provider, store, runtime), and every public module of the runtime appears under runtime, which the facade's own tests check.

Crate	Role	Feature
`turnframe`	Facade re-exporting the family behind feature flags	included
`turnframe-core`	Pure types and the deterministic Flow Map projector; no async runtime, HTTP or database	included
`turnframe-tasks`	Small verified model tasks: repairs, in-place retries, votes, escalation, budgets, records	included
`turnframe-understand`	The understanding pipeline over those tasks	included
`turnframe-runtime`	Turn orchestration: reduction, interactions, commands, events, the reply, tracing, replay	included
`turnframe-provider`	Provider-neutral model interfaces, capability routing, fallback policy, conformance suite	included
`turnframe-provider-openai`	OpenAI, Azure OpenAI and OpenAI-compatible endpoints (profiles)	`openai`
`turnframe-provider-anthropic`	Anthropic Messages API	`anthropic`
`turnframe-provider-gemini`	Google Gemini and Vertex AI	`gemini`
`turnframe-provider-bedrock`	AWS Bedrock Converse	`bedrock`
`turnframe-provider-ollama`	Ollama	`ollama`
`turnframe-store`	Object-safe persistence traits and the deterministic in-memory store	included
`turnframe-store-postgres`	PostgreSQL reference store with migrations and expected-revision transactions	`postgres`
`turnframe-prompt`	Prompt sources: prompts compiled in from your own repository, a bounded cache, an optional Langfuse v4 adapter	`prompts, langfuse`
`turnframe-test`	Test kit: scripted providers and tasks, fake stores, sample workflows, workflow exploration	`test-kit`
`turnframe-eval`	Evaluation harness, scored per turn and per understanding task	`eval`
`turnframe-telemetry`	Tracing spans, turnframe.* metrics, optional OpenTelemetry bridge	`telemetry, otel`

turnframe-macros is reserved. No macros ship in the 0.1 series, by policy: a domain is plain Rust types and trait implementations.

A provider #

Each adapter is a builder that ends in a ModelProvider. This is the OpenAI one, as the console example builds it from the environment:

rust

use std::sync::Arc; use turnframe::provider::openai::OpenAiProvider;use turnframe::provider::provider::ModelProvider;use turnframe::provider::secret::ApiKey; let provider: Arc<dyn ModelProvider> = Arc::new(    OpenAiProvider::openai()        .api_key(ApiKey::new(std::env::var("OPENAI_API_KEY")?))        .model("gpt-5.4-mini")        .build()?,);

The provider goes into a ProviderPool, which routes each task to a model that declares the capabilities it needs. How routing, fallback and each adapter work is in provider adapters.

Next #

The quickstart runs one turn end to end with the test kit, which is the fastest way to see every piece in place. Turn on the test-kit feature to run it.