Module retrieval 

Data structures for Retrieval-Augmented Generation (RAG).

This module provides core data structures for RAG integration. Retrieval and ingestion logic should be implemented as Agents, not as separate traits, allowing for better composability and integration with the agent ecosystem.

Design Philosophy

Instead of defining Retriever and Ingestor traits, implement retrieval and ingestion as regular agents:

Retrieval Pattern

Retrievers return Vec<Document> and can be composed with RetrievalAwareAgent:

// Retriever as Agent
impl Agent for MyVectorStore {
    type Output = Vec<Document>;
    async fn execute(&self, payload: Payload) -> Result<Vec<Document>, AgentError> {
        let query = payload.to_text();
        // Perform semantic search...
        Ok(documents)
    }
}

// Compose with RetrievalAwareAgent
let retriever = MyVectorStore::new();
let base_agent = MyLLMAgent::new();
let rag_agent = RetrievalAwareAgent::new(retriever, base_agent);

Ingestion Pattern

Ingest agent accept Attachments from payload and handle all implementation details (upload, store creation, metadata management) internally:

use llm_toolkit::attachment::Attachment;

// Gemini Files API style
struct GeminiIngestAgent {
    client: GeminiClient,
    store_name: String,  // Internal state
}

impl Agent for GeminiIngestAgent {
    type Output = IngestResult;  // Can be any type

    async fn execute(&self, payload: Payload) -> Result<IngestResult, AgentError> {
        let attachments = payload.attachments();
        let mut file_names = Vec::new();

        for attachment in attachments {
            // 1. Upload file
            let file = self.client.files.upload(attachment).await?;

            // 2. Import into store (internal detail)
            self.client.stores.import_file(&self.store_name, &file.name).await?;

            file_names.push(file.name);
        }

        Ok(IngestResult { file_names })
    }
}

// Usage - just pass files
let geminiIngestAgent = GeminiIngestAgent::new(client, "my-store");
let payload = Payload::attachment(Attachment::local("document.pdf"));
let result = geminiIngestAgent.execute(payload).await?;

Structs

Document

Represents a piece of retrieved content from a knowledge source.