Crate neuron_types 

neuron-types

Foundation crate for the neuron ecosystem. Defines the core types, traits, and error enums that every other neuron crate depends on. Contains zero logic – only data structures, trait definitions, and serde implementations. This is the equivalent of serde’s core: traits live here, implementations live in satellite crates.

Installation

cargo add neuron-types

Key Types

• Message – a conversation message with a Role and Vec<ContentBlock>. Convenience constructors: Message::user(), Message::assistant(), Message::system().
• Role – User, Assistant, or System
• ContentBlock – text, thinking, tool use/result, image, document, or server-side compaction summary
• CompletionRequest – full LLM request: model, messages, system prompt, tools, temperature, thinking config, context management
• CompletionResponse – LLM response: message, token usage, stop reason
• ToolDefinition – tool name, description, and JSON Schema for input
• ToolOutput – tool execution result with content items and optional structured JSON
• ToolContext – runtime context (cwd, session ID, environment, cancellation token). Implements Default for zero-config construction.
• TokenUsage – input/output/cache/reasoning token counts
• UsageIteration – per-iteration token breakdown (during server-side compaction)
• ContextManagement, ContextEdit – server-side context management configuration
• StopReason – why the model stopped: EndTurn, ToolUse, MaxTokens, StopSequence, ContentFilter, Compaction
• EmbeddingRequest – embedding model request: model, input texts, optional dimensions
• EmbeddingResponse – embedding model response: vectors, usage
• EmbeddingUsage – token counts for an embedding request
• UsageLimits – token usage budget constraints (request tokens, response tokens, total tokens) enforced by the agentic loop

Key Traits

• Provider – LLM provider with complete() and complete_stream() (RPITIT, not object-safe)
• EmbeddingProvider – embedding model provider with embed() (RPITIT, separate from Provider)
• Tool – strongly typed tool with NAME, Args, Output, Error associated types
• ToolDyn – type-erased tool for heterogeneous registries (blanket-implemented for all Tool impls)
• ContextStrategy – context compaction: should_compact(), compact(), token_estimate()
• ObservabilityHook – logging/metrics/telemetry hooks returning a HookAction:
  • Continue — proceed normally
  • Skip — reject the tool call and return the reason as a tool result so the model can adapt
  • Terminate — halt the loop immediately
• DurableContext – wraps side effects for durable execution engines (Temporal, Restate)
• PermissionPolicy – tool call permission checks returning:
  • Allow — permit the call
  • Deny(reason) — block the call
  • Ask(question) — prompt the user for confirmation

Usage

use neuron_types::{Message, CompletionRequest};

// Construct a message with convenience constructor
let message = Message::user("What is 2 + 2?");

// Build a completion request (only specify what you need)
let request = CompletionRequest {
    model: "claude-sonnet-4-20250514".into(),
    messages: vec![message],
    system: Some("You are a calculator.".into()),
    max_tokens: Some(1024),
    temperature: Some(0.0),
    ..Default::default()
};

Implementing the Provider trait (Rust 2024 native async, no #[async_trait]). This example is marked ignore because it’s an abstract skeleton — a real implementation would make HTTP calls to an LLM API:

use neuron_types::*;

struct MyProvider { /* ... */ }

impl Provider for MyProvider {
    fn complete(&self, request: CompletionRequest)
        -> impl Future<Output = Result<CompletionResponse, ProviderError>> + Send
    {
        async { todo!() }
    }

    fn complete_stream(&self, request: CompletionRequest)
        -> impl Future<Output = Result<StreamHandle, ProviderError>> + Send
    {
        async { todo!() }
    }
}

Part of neuron

This crate is part of neuron, a composable building-blocks library for AI agents in Rust.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

Re-exports

pub use error::*;

pub use stream::*;

pub use traits::*;

pub use types::*;

pub use wasm::*;

Modules

error

Error types for all neuron crates.

stream

Streaming event types for incremental LLM responses.

traits

Core traits: Provider, Tool, ToolDyn, ContextStrategy, ObservabilityHook, DurableContext.

types

Core message and request/response types.

wasm

WASM compatibility shims.