Integrating helper agents(TitleAgent / PurposeAgent / DescriptionAgent) into a common interface

[grf53]

Ticket

#49

Summary

• Centralize provider configuration on ailoy's process-global default — main.rs populates it once at boot; helpers stop reading env directly.
• Lift the duplicated dispatch shell of TitleAgent / PurposeAgent / DescriptionAgent into a single HelperAgent trait with a fixed {"result": "<string>"} JSON contract.
• Pick the first registered model from a preference list per helper; fall back gracefully when no provider is registered.
• Scope all helper internals to module-private — Store is the sole public entry point for LLM-backed metadata.

Why

Helpers each called dotenvy::dotenv() + OPENAI_API_KEY and copy-pasted ~25 lines of agent setup / streaming / parsing. Without OPENAI_API_KEY — even with Anthropic or Gemini keys — Store::ingest and Store::describe died with "No provider found for model …".

What changes

• main.rs populates ailoy::agent::default_provider_mut once at boot; build_agent reads via default_provider().
• HelperAgent trait owns dispatch, streaming, JSON-field extraction, response-empty fallback, and model selection. Helpers declare only INSTRUCTION, build_query, fallback.
• MODELS defaults to ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5-20251001", "google/gemini-2.5-flash"] (override per helper if a different preference order is needed) and is checked against ailoy's registered glob patterns (openai/*, anthropic/claude-*, google/gemini-*); first match wins. Nothing registered → log::warn! + fallback without an LLM call.
• Response contract is {"result": "<string>"}; the trait extracts and substitutes fallback (logging the agent via std::any::type_name) on empty / malformed responses.

Adding a new helper

use ailoy::message::{Message, Part, Role};
use super::helper::HelperAgent;

struct SummaryAgent;

impl HelperAgent for SummaryAgent {
    type Input<'a> = &'a str;
    type Output = String;
    // const MODELS: &'static [&'static str] = &[...];  // override if needed
    const INSTRUCTION: &'static str = concat!(
        "Summarize the document in 3 sentences. ",
        "Return ONLY a JSON object: {\"result\": \"<string>\"}.",
    );
    fn build_query(&content: &&str) -> Message {
        Message::new(Role::User).with_contents([Part::text(content.to_string())])
    }
    fn fallback(_: &&str) -> String { String::new() }
}

// SummaryAgent::generate(content).await

MODELS, process, generate, agent identifier, model-availability check, and fallback path all come from trait defaults.

Test plan

• cargo build --workspace
• cargo test -p speedwagon --lib
• LLM round-trip: OPENAI_API_KEY=… cargo test -p speedwagon --lib -- --ignored describe_round_trips_against_pre_populated_index
• Manual: only ANTHROPIC_API_KEY (or only GEMINI_API_KEY) set → ingest succeeds via that provider.

[nuri-yoo]

Tested locally, clean. LGTM.