orion_core/
lib.rs

1//! orion-core: Agent harness for local LLM inference.
2//!
3//! Provides the agent loop, context pipeline, tool execution,
4//! and event system for building AI chat interfaces on top of
5//! local model backends (llama.cpp, MLX, etc.).
6//!
7//! # Architecture
8//!
9//! ```text
10//! User prompt
11//!   → Agent.prompt()
12//!     → Context pipeline (prune pairs + template format)
13//!       → LlmBackend.generate() (streaming tokens)
14//!         → Tool execution loop (parse calls → run tools → feed results back)
15//!           → AgentEvent stream → UI
16//! ```
17//!
18//! The crate is backend-agnostic. Implement [`backend::LlmBackend`]
19//! for your inference engine and the agent handles the rest.
20//!
21//! # Example
22//!
23//! Implement [`LlmBackend`] for your engine, then drive the agent. The mock
24//! backend below streams a canned reply so the whole loop runs end to end (a
25//! complete version lives in `examples/mock_backend.rs`):
26//!
27//! ```
28//! use std::sync::Arc;
29//! use std::sync::atomic::AtomicBool;
30//! use orion_core::{
31//!     Agent, AgentConfig, AgentEvent, CoreResult, GenerationResult,
32//!     InferenceParams, LlmBackend, TokenCallback,
33//! };
34//! use tokio::sync::mpsc;
35//!
36//! struct MockBackend;
37//! impl LlmBackend for MockBackend {
38//!     fn generate(
39//!         &self,
40//!         _prompt: &str,
41//!         _params: &InferenceParams,
42//!         _abort: Arc<AtomicBool>,
43//!         mut on_token: TokenCallback,
44//!     ) -> CoreResult<GenerationResult> {
45//!         on_token("Hi!", 1, 10.0);
46//!         Ok(GenerationResult {
47//!             text: "Hi!".into(),
48//!             tokens_generated: 1,
49//!             prompt_tokens: 0,
50//!             tokens_per_sec: 10.0,
51//!             time_to_first_token_ms: 1.0,
52//!             generation_time_ms: 1.0,
53//!         })
54//!     }
55//!     fn tokenize_count(&self, text: &str) -> CoreResult<u32> {
56//!         Ok(text.split_whitespace().count() as u32)
57//!     }
58//!     fn is_ready(&self) -> bool { true }
59//! }
60//!
61//! # fn main() {
62//! let rt = tokio::runtime::Runtime::new().unwrap();
63//! rt.block_on(async {
64//!     let mut agent = Agent::new(AgentConfig::default());
65//!     let backend: Arc<dyn LlmBackend> = Arc::new(MockBackend);
66//!     let (tx, mut rx) = mpsc::unbounded_channel::<AgentEvent>();
67//!
68//!     // Consume events concurrently while the agent generates.
69//!     let consumer = tokio::spawn(async move {
70//!         let mut reply = String::new();
71//!         while let Some(event) = rx.recv().await {
72//!             if let AgentEvent::MessageDelta { delta, .. } = event {
73//!                 reply.push_str(&delta);
74//!             }
75//!         }
76//!         reply
77//!     });
78//!
79//!     agent.prompt("Hello", backend, tx).await.unwrap();
80//!     assert_eq!(consumer.await.unwrap(), "Hi!");
81//! });
82//! # }
83//! ```
84
85#![deny(missing_docs)]
86#![deny(rustdoc::broken_intra_doc_links)]
87
88/// The [`Agent`] orchestrator and its configuration.
89pub mod agent;
90/// The [`LlmBackend`] trait and inference parameter/result types.
91pub mod backend;
92/// Context-window management: pruning, token budgeting, and prompt formatting.
93pub mod context;
94/// Error and result types for the crate.
95pub mod error;
96/// The [`AgentEvent`] stream emitted while the agent runs.
97pub mod events;
98/// Conversation data types: [`Message`], [`Role`], and tool call/result records.
99pub mod messages;
100/// Chat prompt templates for the supported model families.
101pub mod template;
102/// The `Tool` trait (feature `tools`), tool schemas, and tool-call parsing.
103pub mod tools;
104
105pub use agent::{Agent, AgentConfig};
106pub use backend::{GenerationResult, InferenceParams, LlmBackend, TokenCallback};
107pub use context::{plan_prune, ContextConfig, PreparedContext, PrunePlan, PruneStrategy};
108pub use error::{CoreError, CoreResult};
109pub use events::AgentEvent;
110pub use messages::{Message, Role, ToolCall, ToolResult};
111pub use template::{
112    detect_template, template_from_name, AlpacaTemplate, ChatMLTemplate, ChatTemplate,
113    CommandRTemplate, DeepSeekTemplate, GemmaTemplate, Llama2Template, Llama3Template,
114    MistralTemplate, Phi3Template, VicunaTemplate,
115};
116pub use tools::{parse_tool_calls, ParsedToolCall, ToolSchema};
117#[cfg(feature = "tools")]
118pub use tools::{Tool, ToolOutput, ToolUpdateCallback};
orion_core/lib.rs

orion_core/
lib.rs
