AgenticOptioRS

Command. Coordinate. Execute.

AgenticOptioRS is a disciplined AI agent library built for reliable multi-model orchestration. Named after the Roman military Optio—the trusted second-in-command who coordinated formations, supervised operations, and stepped in as acting commander—this framework embodies the same principles of tactical coordination, operational resilience, and execution discipline.

This is the Rust implementation of AgenticOptio, providing high-performance, type-safe AI agent coordination.

Why "Optio"? In Roman legions, an Optio was the backbone of military precision—responsible for coordination, training supervision, and maintaining formation integrity. They were the reliable officers who transformed strategic vision into flawless tactical execution. AgenticOptio brings this same operational excellence to AI agent coordination.

Features

Current (v0.1.0)

OllamaChat: Chat with local Ollama models
OllamaEmbedding: Generate embeddings using local Ollama models
Async Support: Full async/await support using Tokio
Streaming: Real-time streaming responses
Type Safety: Rust's type system ensures correctness at compile time
Zero-cost Abstractions: High performance with minimal overhead

Coming Soon

OpenAI Integration: GPT-4, GPT-3.5-turbo support
Anthropic Claude: Claude 3.5 Sonnet and other models
Google Gemini: Gemini Pro and Flash models
Groq: Fast inference with Llama and Mixtral
Tool Support: Function calling capabilities

Installation

Add to your Cargo.toml:

[dependencies]
agentic_optio_rs = "0.1"
tokio = { version = "1", features = ["full"] }

Requirements: Rust 1.70+

Prerequisites

For Ollama (Current)

Install and run Ollama
Pull a model: ollama pull llama3.2

Quick Start

Basic Chat

use agentic_optio_rs::{OllamaChat, Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create chat model
    let llm = OllamaChat::new("llama3.2");
    
    // Send a message
    let messages = vec![Message::user("Hello!")];
    let response = llm.invoke(&messages).await?;
    println!("{}", response.content);
    
    Ok(())
}

Streaming Responses

use agentic_optio_rs::{OllamaChat, Message};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OllamaChat::new("llama3.2");
    let messages = vec![Message::user("Tell me a story")];
    
    let mut stream = llm.stream(&messages).await?;
    
    while let Some(result) = stream.next().await {
        if let Ok(chunk) = result {
            print!("{}", chunk.content);
        }
    }
    
    Ok(())
}

Embeddings

use agentic_optio_rs::OllamaEmbedding;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let embedder = OllamaEmbedding::new("nomic-embed-text");
    
    // Embed multiple texts
    let texts = vec!["Hello world".to_string(), "How are you?".to_string()];
    let embeddings = embedder.embed(&texts).await?;
    
    println!("Generated {} embeddings", embeddings.len());
    println!("Embedding dimension: {}", embeddings[0].len());
    
    Ok(())
}

Configuration

Custom Ollama Host

use agentic_optio_rs::OllamaChat;

let llm = OllamaChat::builder("llama3.2")
    .host("http://192.168.1.100:11434")
    .temperature(0.7)
    .max_tokens(1000)
    .build();

Environment Variables

OLLAMA_HOST: Default Ollama host URL (default: http://localhost:11434)

API Reference

OllamaChat

// Create with defaults
let llm = OllamaChat::new("llama3.2");

// Create with builder
let llm = OllamaChat::builder("llama3.2")
    .host("http://localhost:11434")
    .temperature(0.0)
    .max_tokens(1000)
    .timeout(Duration::from_secs(60))
    .max_retries(2)
    .build();

// Invoke
let response = llm.invoke(&messages).await?;

// Stream
let stream = llm.stream(&messages).await?;

OllamaEmbedding

// Create with defaults
let embedder = OllamaEmbedding::new("nomic-embed-text");

// Create with builder
let embedder = OllamaEmbedding::builder("nomic-embed-text")
    .host("http://localhost:11434")
    .batch_size(100)
    .timeout(Duration::from_secs(60))
    .build();

// Embed multiple texts
let embeddings = embedder.embed(&texts).await?;

// Embed single query
let embedding = embedder.embed_query("Hello").await?;

Examples

Run the examples:

# Basic usage
cargo run --example basic_usage

# Streaming
cargo run --example streaming_example

Roadmap

v0.2.0 - Strategic Alliance

OpenAI GPT integration (GPT-4o, GPT-4o-mini, GPT-3.5-turbo)
OpenAI embedding support
Unified deployment protocols

v0.3.0 - Allied Forces

Anthropic Claude integration
Google Gemini coordination
Groq rapid response units

v0.4.0 - Advanced Tactics

Standardized tool/function calling protocols
Enhanced streaming capabilities
Batch processing for large-scale deployments
Intelligent rate limiting and resilience patterns

v1.0.0 - Battle Ready

Full test coverage
Comprehensive documentation
Performance optimizations
Production stability guarantees

The Optio Advantage

In Roman legions, the Optio was the disciplined officer who transformed strategy into flawless execution. AgenticOptio brings this same operational excellence to AI:

Command Structure

Unified Command: Single interface governing all model providers
Type Safety: Rust's type system prevents errors at compile time
Tactical Flexibility: Adapt to any model or provider seamlessly

Operational Discipline

Reliability First: Battle-tested patterns with comprehensive error handling
Resource Management: Efficient coordination of compute and memory
Zero-cost Abstractions: High performance without runtime overhead

Strategic Readiness

Multi-Theater Operations: Local models (Ollama) and cloud APIs in unified formation
Rapid Deployment: Minimal dependencies for quick battlefield setup
Scalable Command: From single agents to complex multi-agent orchestrations

Comparison with Python Version

Feature	Python	Rust
Type Safety	Runtime	Compile-time
Performance	Good	Excellent
Memory Safety	GC	Ownership
Async	asyncio	Tokio
Dependencies	Minimal	Minimal
Ease of Use	Very Easy	Easy

License

MIT License

agentic_optio_rs 0.1.1