archy/core/archipelago/src/assistant/backends/mod.rs

//! The `Backend` trait — the wire-format-agnostic seam every model backend
//! (Ollama, Claude, Routstr) implements once. The loop and every tool are
//! written against this trait only; wire-format differences live entirely
//! inside each adapter.

use std::path::Path;

use anyhow::Result;
use async_trait::async_trait;

use super::tools::{ChatMessage, ToolCall, ToolDef};

pub mod claude;
pub mod ollama;
#[cfg(test)]
pub mod scripted;

pub enum BackendTurn {
    Text(String),
    ToolCalls(Vec<ToolCall>),
}

#[async_trait]
pub trait Backend: Send + Sync {
    async fn send(
        &self,
        system: &str,
        tools: &[ToolDef],
        history: &[ChatMessage],
    ) -> Result<BackendTurn>;
}

/// D-04's identified backends — used for tracing which backend answered a
/// given turn. Grows a `Routstr` variant once 13-13 lands it. Deliberately
/// NOT carried into `ChatMessage`/`history.rs` (outside this plan's file
/// scope; per-turn backend attribution in the persisted transcript is a
/// natural follow-up, not required by any of 13-10's behaviors).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BackendId {
    Ollama,
    Claude,
}

impl std::fmt::Display for BackendId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            BackendId::Ollama => write!(f, "ollama"),
            BackendId::Claude => write!(f, "claude"),
        }
    }
}

/// D-04's per-call fallback: try `primary`'s `send()`, and on a transport
/// error fall through to `secondary` for that SAME call rather than
/// failing the whole turn — a local model that answers earlier turns and
/// then drops off mid-loop (Ollama restarted, OOM-killed, network blip)
/// still completes the turn via Claude instead of surfacing an error to
/// the user. Generic over both legs so tests can exercise the fallthrough
/// with lightweight stub backends instead of a live network leg.
struct FallbackChain {
    primary: Box<dyn Backend>,
    primary_id: BackendId,
    secondary: Box<dyn Backend>,
}

#[async_trait]
impl Backend for FallbackChain {
    async fn send(
        &self,
        system: &str,
        tools: &[ToolDef],
        history: &[ChatMessage],
    ) -> Result<BackendTurn> {
        match self.primary.send(system, tools, history).await {
            Ok(turn) => Ok(turn),
            Err(e) => {
                tracing::warn!(
                    backend = %self.primary_id,
                    error = %e,
                    "D-04: backend transport error mid-turn — falling through to the next backend rather than failing this turn"
                );
                self.secondary.send(system, tools, history).await
            }
        }
    }
}

/// Pure decision logic for D-04's leading leg — whether Ollama should be
/// selected given the two facts `select_backend` gathers from live probes
/// (`detect_ollama()`/`ollama::model_supports_tools()`). Extracted so the
/// decision table itself is directly testable without faking a network
/// seam for both probes.
fn ollama_is_selectable(detected: bool, tool_capable: bool) -> bool {
    detected && tool_capable
}

/// D-04's backend chain: local Ollama first (node data never leaves the
/// node when a local model is available and tool-capable), then Claude.
/// The Routstr slot (13-13) inserts as a third leg without changing the
/// `Backend` trait or this function's shape — the architectural commitment
/// the 13-01 tracer proved and this plan fills the first real leg of.
///
/// Reuses `detect_ollama()` — the SAME probe `mesh.assistant-status`
/// reports — rather than writing a second one. Ollama being unreachable OR
/// its configured model being reachable-but-not-tool-capable both fall
/// through to Claude, each with a logged reason — never a silent,
/// tools-free degrade.
pub async fn select_backend(data_dir: &Path) -> (Box<dyn Backend>, BackendId) {
    let (detected, _models) = crate::api::rpc::mesh::assistant::detect_ollama().await;
    let model = ollama::OLLAMA_DEFAULT_MODEL;
    let tool_capable = if detected {
        ollama::model_supports_tools(ollama::OLLAMA_BASE_URL, model).await
    } else {
        false
    };

    if ollama_is_selectable(detected, tool_capable) {
        tracing::info!(
            model,
            "D-04: local Ollama selected — node data stays on-node this turn"
        );
        let primary =
            ollama::OllamaBackend::new(ollama::OLLAMA_BASE_URL.to_string(), model.to_string());
        let secondary = claude::ClaudeBackend::new(data_dir.to_path_buf());
        let chain = FallbackChain {
            primary: Box::new(primary),
            primary_id: BackendId::Ollama,
            secondary: Box::new(secondary),
        };
        return (Box::new(chain), BackendId::Ollama);
    }

    if !detected {
        tracing::info!("D-04: Ollama not detected — falling through to Claude");
    } else {
        tracing::info!(
            model,
            "D-04: Ollama detected but the configured model is not tool-capable — falling through to Claude"
        );
    }
    (
        Box::new(claude::ClaudeBackend::new(data_dir.to_path_buf())),
        BackendId::Claude,
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::assistant::tools::{ChatMessage, ToolDef};

    struct ErroringBackend;
    #[async_trait]
    impl Backend for ErroringBackend {
        async fn send(
            &self,
            _system: &str,
            _tools: &[ToolDef],
            _history: &[ChatMessage],
        ) -> Result<BackendTurn> {
            anyhow::bail!("stub transport error")
        }
    }

    struct OkBackend(&'static str);
    #[async_trait]
    impl Backend for OkBackend {
        async fn send(
            &self,
            _system: &str,
            _tools: &[ToolDef],
            _history: &[ChatMessage],
        ) -> Result<BackendTurn> {
            Ok(BackendTurn::Text(self.0.to_string()))
        }
    }

    /// Behavior: an Ollama transport error falls through to the next
    /// backend rather than failing the turn.
    #[tokio::test]
    async fn ollama_transport_error_falls_through_to_next_backend() {
        let chain = FallbackChain {
            primary: Box::new(ErroringBackend),
            primary_id: BackendId::Ollama,
            secondary: Box::new(OkBackend("answered by claude")),
        };
        let result = chain
            .send("sys", &[], &[])
            .await
            .expect("falls through, does not fail the turn");
        assert!(matches!(result, BackendTurn::Text(t) if t == "answered by claude"));
    }

    #[tokio::test]
    async fn healthy_primary_never_reaches_secondary() {
        let chain = FallbackChain {
            primary: Box::new(OkBackend("answered by ollama")),
            primary_id: BackendId::Ollama,
            secondary: Box::new(ErroringBackend),
        };
        let result = chain.send("sys", &[], &[]).await.expect("primary answers");
        assert!(matches!(result, BackendTurn::Text(t) if t == "answered by ollama"));
    }

    /// Behavior: `select_backend` returns Ollama when reachable and
    /// tool-capable; falls through to Claude when unreachable, and also
    /// when reachable but not tool-capable.
    #[test]
    fn ollama_is_selectable_truth_table() {
        assert!(
            ollama_is_selectable(true, true),
            "reachable + tool-capable => selectable"
        );
        assert!(
            !ollama_is_selectable(false, true),
            "unreachable => falls through to Claude"
        );
        assert!(
            !ollama_is_selectable(true, false),
            "reachable but not tool-capable => falls through to Claude"
        );
        assert!(
            !ollama_is_selectable(false, false),
            "neither => falls through to Claude"
        );
    }
}