pub mod backend;
pub mod engine;
pub mod inference;
pub mod local;
pub mod query;
pub mod remote;
pub mod state;
pub mod tool_runtime;
use crate::error::{IronError, Result};
use crate::UnifiedMonitor;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
pub use backend::{BackendCapabilities, BackendConfig, BackendDiscovery, BackendType};
pub use engine::InferenceEngine;
pub use local::{
InferenceRequest, InferenceResponse, LocalInferenceClient, ModelInfo, OllamaClient,
};
pub use query::{Query, QueryType};
pub use remote::{RemoteClient, RemoteClientBuilder};
pub use state::SystemState;
pub const DEFAULT_OPENAI_MODEL: &str = "gpt-5.6-terra";
pub const DEFAULT_ANTHROPIC_MODEL: &str = "claude-sonnet-5";
#[deprecated(
since = "2.1.0",
note = "GitHub retired GitHub Models on 2026-07-30; no model id reaches it."
)]
pub const DEFAULT_GITHUB_MODEL: &str = "openai/gpt-4.1";
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
pub enum ModelSize {
Small,
#[default]
Medium,
Large,
}
impl ModelSize {
pub fn latency_estimate_ms(&self) -> u64 {
match self {
Self::Small => 75,
Self::Medium => 150,
Self::Large => 350,
}
}
pub fn memory_mb(&self) -> usize {
match self {
Self::Small => 200, Self::Medium => 1000, Self::Large => 2000, }
}
pub fn description(&self) -> &str {
match self {
Self::Small => "100M params - Fast responses, basic queries",
Self::Medium => "500M params - Balanced speed and reasoning",
Self::Large => "1B params - Advanced reasoning, slower",
}
}
}
impl std::fmt::Display for ModelSize {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Small => write!(f, "100M"),
Self::Medium => write!(f, "500M"),
Self::Large => write!(f, "1B"),
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentConfig {
pub model_size: ModelSize,
pub model_dir: PathBuf,
pub max_response_tokens: usize,
pub temperature: f32,
pub enable_caching: bool,
pub cache_size: usize,
pub timeout_seconds: u64,
pub backend: Option<BackendConfig>,
}
impl AgentConfig {
pub fn new(model_size: ModelSize) -> Self {
Self {
model_size,
model_dir: Self::default_model_dir(),
max_response_tokens: 256, temperature: 0.3, enable_caching: true,
cache_size: 100,
timeout_seconds: 5, backend: None, }
}
pub fn with_backend(backend: BackendConfig) -> Self {
Self {
model_size: ModelSize::Medium, model_dir: Self::default_model_dir(),
max_response_tokens: backend.max_tokens,
temperature: backend.temperature,
enable_caching: true,
cache_size: 100,
timeout_seconds: backend.timeout.as_secs(),
backend: Some(backend),
}
}
fn default_model_dir() -> PathBuf {
#[cfg(unix)]
{
let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
PathBuf::from(home).join(".cache/ironmon/models")
}
#[cfg(windows)]
{
let local_app_data =
std::env::var("LOCALAPPDATA").unwrap_or_else(|_| "C:\\Temp".to_string());
PathBuf::from(local_app_data).join("ironmon\\models")
}
}
pub fn with_model_dir(mut self, path: PathBuf) -> Self {
self.model_dir = path;
self
}
pub fn with_temperature(mut self, temp: f32) -> Self {
self.temperature = temp.clamp(0.0, 1.0);
self
}
pub fn with_max_tokens(mut self, tokens: usize) -> Self {
self.max_response_tokens = tokens;
self
}
pub fn without_caching(mut self) -> Self {
self.enable_caching = false;
self
}
pub fn with_caching(mut self, enabled: bool) -> Self {
self.enable_caching = enabled;
self
}
pub fn with_cache_size(mut self, size: usize) -> Self {
self.cache_size = size;
self
}
pub fn with_timeout(mut self, timeout: Duration) -> Self {
self.timeout_seconds = timeout.as_secs();
self
}
#[allow(deprecated)]
pub fn auto_detect() -> Result<Self> {
let discovery = BackendDiscovery::discover();
if discovery.available().is_empty() && discovery.configured().is_empty() {
return Err(IronError::Configuration(
"No AI backends available. Please install Ollama (https://ollama.com), \
configure an API key (OPENAI_API_KEY or GITHUB_TOKEN), or set up another backend."
.to_string(),
));
}
let backend_type = discovery.recommended();
let backend_config = match backend_type {
BackendType::IronWorks => {
BackendConfig::ironworks("default")
}
BackendType::Cli(provider) => BackendConfig::cli(provider, "default"),
BackendType::RemoteOpenAI => {
BackendConfig::openai(DEFAULT_OPENAI_MODEL, None) }
BackendType::RemoteAnthropic => {
BackendConfig::anthropic(DEFAULT_ANTHROPIC_MODEL, None) }
BackendType::RemoteOllama => {
BackendConfig::ollama("llama3.2:3b") }
BackendType::RemoteMlx => BackendConfig::mlx("default_model"),
BackendType::RemoteLMStudio => {
BackendConfig::lm_studio("local-model") }
BackendType::RemoteGitHub => {
BackendConfig::github_models(DEFAULT_GITHUB_MODEL, None) }
BackendType::RemoteVllm => {
BackendConfig::vllm("local-model") }
BackendType::RemoteTensorRT => {
BackendConfig::tensorrt("local-model") }
_ => {
return Err(IronError::Configuration(format!(
"Backend {} auto-detection not supported. Please configure manually.",
backend_type.display_name()
)));
}
};
backend_config.validate()?;
Ok(Self::with_backend(backend_config))
}
#[allow(deprecated)]
pub fn with_backend_type(backend_type: BackendType) -> Result<Self> {
let backend_config = match backend_type {
BackendType::IronWorks => BackendConfig::ironworks("default"),
BackendType::Cli(provider) => BackendConfig::cli(provider, "default"),
BackendType::RemoteOpenAI => BackendConfig::openai(DEFAULT_OPENAI_MODEL, None),
BackendType::RemoteAnthropic => BackendConfig::anthropic(DEFAULT_ANTHROPIC_MODEL, None),
BackendType::RemoteOllama => BackendConfig::ollama("llama3.2:3b"),
BackendType::RemoteMlx => BackendConfig::mlx("default_model"),
BackendType::RemoteLMStudio => BackendConfig::lm_studio("local-model"),
BackendType::RemoteGitHub => BackendConfig::github_models(DEFAULT_GITHUB_MODEL, None),
BackendType::RemoteVllm => BackendConfig::vllm("local-model"),
BackendType::RemoteTensorRT => BackendConfig::tensorrt("local-model"),
_ => {
return Err(IronError::Configuration(format!(
"Backend {} is not supported or requires manual configuration",
backend_type.display_name()
)));
}
};
backend_config.validate()?;
Ok(Self::with_backend(backend_config))
}
pub fn list_available_backends() -> Vec<BackendType> {
let discovery = BackendDiscovery::discover();
discovery.available().to_vec()
}
pub fn list_available_and_configured_backends() -> (Vec<BackendType>, Vec<BackendType>) {
let discovery = BackendDiscovery::discover();
(
discovery.available().to_vec(),
discovery.configured().to_vec(),
)
}
}
impl Default for AgentConfig {
fn default() -> Self {
Self::new(ModelSize::default())
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentResponse {
pub query: String,
pub response: String,
pub query_type: QueryType,
pub inference_time_ms: u64,
pub from_cache: bool,
pub timestamp: u64,
}
impl std::fmt::Display for AgentResponse {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.response)
}
}
impl AgentResponse {
pub fn is_error(&self) -> bool {
self.response.starts_with("Error:")
|| self.response.starts_with("Unable to")
|| self.response.contains("not available")
}
}
#[derive(Clone)]
pub struct Agent {
config: AgentConfig,
engine: Arc<Mutex<Option<InferenceEngine>>>,
cache: Arc<Mutex<lru::LruCache<String, (String, QueryType)>>>,
initialized: Arc<Mutex<bool>>,
}
impl Agent {
pub fn new(config: AgentConfig) -> Result<Self> {
let cache_size = if config.enable_caching {
std::num::NonZeroUsize::new(config.cache_size.max(1))
.expect("max(1) guarantees non-zero")
} else {
std::num::NonZeroUsize::new(1).expect("literal 1 is non-zero")
};
Ok(Self {
config,
engine: Arc::new(Mutex::new(None)),
cache: Arc::new(Mutex::new(lru::LruCache::new(cache_size))),
initialized: Arc::new(Mutex::new(false)),
})
}
pub fn config(&self) -> &AgentConfig {
&self.config
}
pub fn is_initialized(&self) -> bool {
*self.initialized.lock().unwrap()
}
fn initialize(&self) -> Result<()> {
let mut initialized = self.initialized.lock().unwrap();
if *initialized {
return Ok(());
}
let mut engine_lock = self.engine.lock().unwrap();
if engine_lock.is_none() {
let engine = InferenceEngine::new(&self.config)?;
*engine_lock = Some(engine);
}
*initialized = true;
Ok(())
}
pub fn ask(&mut self, question: &str, _monitor: &UnifiedMonitor) -> Result<AgentResponse> {
self.ask_with_control(question, &tool_runtime::RunControl::default())
}
pub fn ask_with_control(
&mut self,
question: &str,
control: &tool_runtime::RunControl,
) -> Result<AgentResponse> {
self.ask_run(
question,
control,
Duration::from_secs(self.config.timeout_seconds),
)
}
fn ask_run(
&mut self,
question: &str,
control: &tool_runtime::RunControl,
budget: Duration,
) -> Result<AgentResponse> {
self.ask_run_with_history(question, &[], control, budget)
}
pub fn ask_with_history_and_control(
&mut self,
question: &str,
history: &[tool_runtime::ConversationTurn],
control: &tool_runtime::RunControl,
) -> Result<AgentResponse> {
self.ask_run_with_history(
question,
history,
control,
Duration::from_secs(self.config.timeout_seconds),
)
}
fn ask_run_with_history(
&mut self,
question: &str,
history: &[tool_runtime::ConversationTurn],
control: &tool_runtime::RunControl,
budget: Duration,
) -> Result<AgentResponse> {
self.refuse_if_offline_and_offhost()?;
if control.is_cancelled() {
return Err(IronError::Agent("Agent run cancelled".into()));
}
if question.trim().is_empty() {
return Err(IronError::Agent("Question is empty".into()));
}
let start = Instant::now();
self.initialize()?;
let response_text = {
let engine_lock = self
.engine
.try_lock()
.map_err(|_| IronError::Agent("Agent is already running a query".into()))?;
let engine = engine_lock
.as_ref()
.ok_or_else(|| IronError::Agent("Agent not initialized".into()))?;
engine.generate_tool_response_with_history(
question,
history,
budget.saturating_sub(start.elapsed()),
control,
)?
};
Ok(AgentResponse {
query: question.to_string(),
response: response_text,
query_type: Query::parse(question).query_type,
inference_time_ms: start.elapsed().as_millis() as u64,
from_cache: false,
timestamp: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs(),
})
}
fn refuse_if_offline_and_offhost(&self) -> Result<()> {
if !crate::consent::is_offline_mode() {
return Ok(());
}
let Some(backend) = self.config.backend.as_ref() else {
return Ok(());
};
if backend.backend_type.runs_on_host() {
return Ok(());
}
Err(crate::error::IronError::Other(format!(
"refusing to query {:?} in offline mode: it would send this machine's \
hardware details off-host. Use a backend that runs locally (IronWorks, \
Ollama), or drop --offline if you intend the data to leave.",
backend.backend_type
)))
}
pub fn ask_with_timeout(
&mut self,
question: &str,
monitor: &UnifiedMonitor,
timeout: Duration,
) -> Result<AgentResponse> {
let _ = monitor;
self.ask_run(question, &tool_runtime::RunControl::default(), timeout)
}
pub fn clear_cache(&mut self) {
let mut cache = self.cache.lock().unwrap();
cache.clear();
}
pub fn cache_stats(&self) -> (usize, usize) {
let cache = self.cache.lock().unwrap();
(cache.len(), cache.cap().get())
}
pub fn cache_size(&self) -> usize {
let cache = self.cache.lock().unwrap();
cache.len()
}
pub fn preload(&mut self) -> Result<()> {
self.initialize()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_model_size_properties() {
assert_eq!(ModelSize::Small.latency_estimate_ms(), 75);
assert_eq!(ModelSize::Medium.latency_estimate_ms(), 150);
assert_eq!(ModelSize::Large.latency_estimate_ms(), 350);
assert_eq!(ModelSize::Small.memory_mb(), 200);
assert_eq!(ModelSize::Medium.memory_mb(), 1000);
assert_eq!(ModelSize::Large.memory_mb(), 2000);
}
#[test]
fn test_config_defaults() {
let config = AgentConfig::default();
assert_eq!(config.model_size, ModelSize::Medium);
assert!(config.enable_caching);
assert_eq!(config.temperature, 0.3);
assert_eq!(config.max_response_tokens, 256);
}
#[test]
fn test_config_builder() {
let config = AgentConfig::new(ModelSize::Large)
.with_temperature(0.7)
.with_max_tokens(512)
.without_caching();
assert_eq!(config.model_size, ModelSize::Large);
assert_eq!(config.temperature, 0.7);
assert_eq!(config.max_response_tokens, 512);
assert!(!config.enable_caching);
}
}
#[cfg(test)]
mod offline_enforcement_tests {
use super::*;
use crate::agent::backend::BackendConfig;
pub(super) static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
fn agent_with(backend: BackendConfig) -> Agent {
let config = AgentConfig::with_backend(backend);
Agent::new(config).expect("agent construction should not require a live backend")
}
#[test]
fn offline_refuses_a_backend_that_would_send_data_off_host() {
let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
std::env::set_var("IRONMON_OFFLINE", "1");
let agent = agent_with(BackendConfig::anthropic(
DEFAULT_ANTHROPIC_MODEL,
Some("test".into()),
));
let err = agent
.refuse_if_offline_and_offhost()
.expect_err("a hosted provider must be refused in offline mode");
let msg = err.to_string();
assert!(
msg.contains("offline mode"),
"the refusal should say why: {msg}"
);
assert!(
msg.contains("locally") || msg.contains("Ollama"),
"the refusal should name a way forward: {msg}"
);
std::env::remove_var("IRONMON_OFFLINE");
}
#[test]
fn offline_permits_a_backend_that_runs_on_this_machine() {
let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
std::env::set_var("IRONMON_OFFLINE", "1");
let agent = agent_with(BackendConfig::ironworks("test-model"));
assert!(
agent.refuse_if_offline_and_offhost().is_ok(),
"on-host inference must remain usable in offline mode, or the flag \
pushes users toward the hosted path it is meant to avoid"
);
std::env::remove_var("IRONMON_OFFLINE");
}
#[test]
fn without_offline_a_hosted_backend_is_permitted() {
let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
std::env::remove_var("IRONMON_OFFLINE");
let agent = agent_with(BackendConfig::anthropic(
DEFAULT_ANTHROPIC_MODEL,
Some("test".into()),
));
assert!(agent.refuse_if_offline_and_offhost().is_ok());
}
}