Crate neuromance 

neuromance

A Rust library for controlling and orchestrating LLM interactions.

Neuromance provides high-level abstractions for building LLM-powered applications, including conversation management, tool calling, and interaction orchestration.

Quick Start

use neuromance::{Conversation, Message, Core, CoreEvent, ToolApproval};

// Create a conversation
let mut conversation = Conversation::new().with_title("My Chat");

// Add messages
let user_msg = Message::user(conversation.id, "Hello!");
let assistant_msg = Message::assistant(conversation.id, "Hi there!");

conversation.add_message(user_msg).expect("Failed to add message");
conversation.add_message(assistant_msg).expect("Failed to add message");

// Core uses event-driven architecture for streaming and monitoring
let core = Core::new(client)
    .with_streaming()
    .with_event_callback(|event| async move {
        match event {
            CoreEvent::Streaming(chunk) => print!("{}", chunk),
            CoreEvent::ToolResult { name, .. } => println!("Tool executed: {}", name),
            CoreEvent::Usage(usage) => println!("Tokens: {}", usage.total_tokens),
        }
    })
    .with_tool_approval_callback(|tool_call| {
        let tool_call = tool_call.clone();
        async move {
            println!("Approve {}?", tool_call.function.name);
            ToolApproval::Approved // Or prompt user
        }
    });

Features

• Conversation Management: Track multi-turn conversations with metadata and status
• Message Handling: Support for system, user, assistant, and tool messages
• Tool Calling: Define and execute function calls from LLM responses
• Serialization: Full serde support for all types

Re-exports

pub use core::Core;

pub use events::CoreEvent;

pub use events::EventCallback;

pub use events::ToolApprovalCallback;

Modules

agents

Agent state management and context types.

chat

Chat conversation and message types.

client

Client configuration and request/response types.

core

error

events

Event types for Core orchestration

generic

mcp

openai

OpenAI API types and client implementation.

tools

Tool calling and function execution types.

Structs

AgentContext

Context describing the agent’s current task and environment.

AgentMemory

Memory storage for agents.

AgentResponse

Response from agent execution.

AgentState

Complete state of an agent.

AgentStats

Execution statistics for monitoring agent performance.

BooleanTool

A tool that returns a boolean result based on the agent’s analysis Used for binary decisions like goal verification

ChatRequest

A request for a chat completion from an LLM.

ChatResponse

A response from a chat completion request.

Config

Configuration for an LLM client.

Conversation

Represents a conversation thread containing multiple messages.

Function

Describes a function that can be called by an LLM.

FunctionCall

Represents an invocation of a function with arguments.

Message

A single message in a conversation.

NoRetryPolicy

A retry policy for SSE streams that never retries.

OpenAIClient

Client for OpenAI-compatible APIs.

Parameters

Defines the parameter schema for a function using JSON Schema conventions.

Property

Describes a single property in a function parameter schema.

RetryConfig

Configuration for exponential backoff retry behavior.

ThinkTool

A tool that allows the agent to record thoughts and reasoning Used for making the agent’s thinking process visible in the context

TodoReadTool

Tool for reading the current todo list

TodoWriteTool

Tool for writing/updating the todo list

Tool

Represents a tool available to the LLM, typically wrapping a function.

ToolCall

Represents a complete tool call from an LLM, including ID and function details.

ToolExecutor

ToolRegistry

Usage

Token usage statistics for a completion request.

Enums

AgentMessage

Messages that can be sent to or from an agent.

ClientError

Errors that can occur when interacting with LLM APIs.

ConversationStatus

The lifecycle status of a conversation.

FinishReason

Indicates why the model stopped generating tokens.

MessageRole

Represents the role of a message sender in a conversation.

ToolApproval

Represents the approval status of a tool call.

ToolChoice

Controls how the model selects which tool to call, if any.

Traits

LLMClient

Trait for LLM client implementations.

ToolImplementation

Functions

create_todo_tools

Create a pair of TodoRead and TodoWrite tools that share the same storage