Crate nanocodex 

Nanocodex

The batteries-included façade for the Nanocodex frontier-agent building blocks.

This crate contains no second runtime implementation. It re-exports the owned agent lifecycle and gives the lower-level crates stable, named module paths. Depending on nanocodex-agent directly creates the same agent.

Quick start

Build one owned agent, keep its cheap cloneable handle, and await typed turn results. The independent event stream is optional:

use nanocodex::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions(
        "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
    )
    .workspace(std::env::current_dir()?)
    .build()?;

let turn = agent
    .prompt("Explain the cause of the failing parser test.")
    .await?;
let result = turn.await?;

println!("{}", result.final_message());
agent.shutdown().await?;

Awaiting prompt means the private driver accepted and ordered the turn. Awaiting the returned Turn waits for its complete TurnResult; it does not wait for the turn’s optional event stream to be consumed. Follow-on prompts reuse the same retained context and transport without asking the caller to manage response IDs or history.

gpt-5.6-sol is the default; .model(Model::Terra) and .model(Model::Luna) select the other supported models when creating the agent. The selected model remains fixed for the thread so follow-on turns can continue from the provider checkpoint without replaying the complete retained context.

Usage and USD estimates

Every completed turn reports aggregate provider usage. Cost remains explicit: Nanocodex automatically applies the selected model’s published standard or priority rates. Terra and Luna use their documented rates rather than Sol’s higher rates.

use nanocodex::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions("Answer concisely and preserve exact identifiers.")
    .build()?;

let result = agent.prompt("Explain the identifier req_7f3.").await?.await?;
if let Some(cost) = result.usage().estimated_cost() {
    println!("estimated {}", cost.amount());
} else {
    println!("cost unavailable: {}", result.usage().cost_status().as_str());
}
agent.shutdown().await?;

Progressive disclosure

The root exports only the golden-path types. Reach for a named module when an embedding needs more control:

• agent — lifecycle policy, events, input, sessions, usage, and rollout
• oai — managed Responses sessions and the concrete Tower boundary
• tools — tool contracts, built-ins, Code Mode, and MCP
• observability — native tracing and OTLP setup when the default-off observability feature is enabled
• prelude — common imports for the owned-agent path

Detailed items retain the documentation from their owning crate. Each lower crate also includes its own focused guide and can be documented or consumed without the facade.

Canonical imports

Use the crate root for the common agent path and the module that owns a concept when reaching for its detailed API:

use nanocodex::{Nanocodex, OpenAi};
use nanocodex::agent::{events::AgentEvent, session::SessionSnapshot};
use nanocodex::oai::tower::ResponsesAttempt;
use nanocodex::tools::mcp::Mcp;

The root convenience path and its owning module name the same type; for example, OpenAi and oai::OpenAi are identical. The agent module intentionally does not repeat sibling convenience exports: provider configuration belongs under oai, tool implementation belongs under tools, and lifecycle state belongs under agent. Applications that need only one component can depend on its package directly and use nanocodex_oai_api, nanocodex_tools, or nanocodex_agent.

Modules

agent

Owned agent lifecycle, builders, turns, branching, and snapshots.

oai

Tower-native OpenAI Responses client, sessions, protocol, and transport.

observabilityobservability and non-target_family=wasm

Application-owned tracing and OpenTelemetry setup.

prelude

Common imports for the golden owned-agent path.

tools

Tool registry, built-ins, MCP, tool search, and Code Mode.

Structs

AgentEvents

The receiving half of an agent’s typed event stream.

AgentSessionContext

Read-only model context exposed to session adapters.

EstimatedUsdCost

Exact estimated USD cost for provider-reported token usage.

Nanocodex

Cheap, cloneable command handle for an owned agent driver.

NanocodexBuilder

Builder for one owned agent lifecycle.

OpenAi

Configured, cloneable OpenAI client recipe.

Tools

Declarative selection of the built-in tools installed for an agent.

Turn

Completion handle for an accepted turn.

TurnControl

Cheap cloneable control capability for one accepted turn.

TurnResult

Final result of a completed turn.

TurnUsage

Exact token accounting for every Responses call in one logical agent turn.

UsdAmount

An exact non-negative amount of United States dollars.

Enums

CostStatus

Availability of the automatic local USD estimate.

Model

Supported models in the GPT-5.6 coding-model family.

NanocodexError

Error returned by the Nanocodex library boundary.

PromptRoute

Outcome of routing live user input into an agent session.

ReasoningMode

Responses reasoning execution mode for the supported GPT-5.6 model family.

ServiceTier

OpenAI service tiers supported by Nanocodex.

Thinking

Requested model reasoning effort.

Traits

Tool

A caller-defined model-visible tool.

Attribute Macros

toolNon-target_family=wasm

Defines a typed JSON function tool from an async Rust function.