Add Maritime/Logistics support assistant with safety/eval layer

RAG + multi-agent (retrieval, policy-compliance, drafting) support
assistant for a fictional shipping company, built in Rust with Qdrant
for vector storage and a hand-rolled Anthropic tool-calling client
(no Rust pydantic-ai equivalent exists). A deterministic supervisor
orchestrates the agents and runs every response through a rule-based
guardrail pipeline with an append-only audit log.

Includes a 44-example golden dataset (normal/injection/policy-
violation/hallucination-bait/out-of-scope) and a regression harness
that scores retrieval, generation, and guardrail correctness
separately, plus a write-up of the failure modes and trade-offs.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

src/retrieval/chunking.rs

@@ -0,0 +1,76 @@
+//! Naive but predictable text chunking for the knowledge base documents.
+//!
+//! Splits on paragraph boundaries first and packs paragraphs into
+//! `chunk_size`-ish chunks with a small overlap, rather than cutting mid
+//! sentence — the documents here are short policy pages, not novels, so
+//! this stays simple on purpose.
+
+pub fn chunk_text(text: &str, chunk_size: usize, overlap: usize) -> Vec<String> {
+    let paragraphs: Vec<&str> = text
+        .split("\n\n")
+        .map(str::trim)
+        .filter(|p| !p.is_empty())
+        .collect();
+
+    if paragraphs.is_empty() {
+        return Vec::new();
+    }
+
+    let mut chunks = Vec::new();
+    let mut current = String::new();
+
+    for paragraph in &paragraphs {
+        if !current.is_empty() && current.len() + paragraph.len() + 2 > chunk_size {
+            chunks.push(current.clone());
+            current = tail(&current, overlap);
+        }
+        if !current.is_empty() {
+            current.push_str("\n\n");
+        }
+        current.push_str(paragraph);
+    }
+    if !current.trim().is_empty() {
+        chunks.push(current);
+    }
+
+    chunks
+}
+
+/// Returns the last `overlap` characters of `s`, snapped to a char boundary.
+fn tail(s: &str, overlap: usize) -> String {
+    if s.len() <= overlap {
+        return s.to_string();
+    }
+    let start = s.len() - overlap;
+    let boundary = (start..s.len())
+        .find(|&i| s.is_char_boundary(i))
+        .unwrap_or(s.len());
+    s[boundary..].to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn splits_long_text_into_multiple_chunks() {
+        let text = "Paragraph one is here.\n\nParagraph two is here.\n\nParagraph three is here.\n\nParagraph four is here.";
+        let chunks = chunk_text(text, 50, 10);
+        assert!(chunks.len() > 1, "expected multiple chunks, got {chunks:?}");
+        for chunk in &chunks {
+            assert!(!chunk.is_empty());
+        }
+    }
+
+    #[test]
+    fn keeps_short_text_as_a_single_chunk() {
+        let text = "Just one short paragraph.";
+        let chunks = chunk_text(text, 500, 50);
+        assert_eq!(chunks, vec!["Just one short paragraph.".to_string()]);
+    }
+
+    #[test]
+    fn empty_input_produces_no_chunks() {
+        assert!(chunk_text("   \n\n  ", 100, 10).is_empty());
+    }
+}

src/retrieval/mod.rs

@@ -0,0 +1,7 @@
+pub mod chunking;
+pub mod reference_extractor;
+pub mod retriever;
+pub mod vector_store;
+
+pub use retriever::DocumentRetriever;
+pub use vector_store::VectorStore;

src/retrieval/reference_extractor.rs

@@ -0,0 +1,65 @@
+//! Deterministic extraction of shipment identifiers from free text.
+//!
+//! Pulled out as its own unit (rather than a method on `DocumentRetriever`)
+//! purely so it's testable without spinning up a Qdrant connection.
+
+use regex::Regex;
+
+pub struct ReferenceExtractor {
+    booking_reference_re: Regex,
+    container_number_re: Regex,
+}
+
+impl ReferenceExtractor {
+    pub fn new() -> Self {
+        Self {
+            booking_reference_re: Regex::new(r"\bMSL-[A-Z0-9]{7}\b").expect("valid regex"),
+            container_number_re: Regex::new(r"\b[A-Z]{4}\d{7}\b").expect("valid regex"),
+        }
+    }
+
+    /// Preferred over asking the LLM to do this: it's cheap, exact, and
+    /// never hallucinates a reference that wasn't actually typed.
+    pub fn extract(&self, query: &str) -> Option<String> {
+        let upper = query.to_uppercase();
+        self.booking_reference_re
+            .find(&upper)
+            .or_else(|| self.container_number_re.find(&upper))
+            .map(|m| m.as_str().to_string())
+    }
+}
+
+impl Default for ReferenceExtractor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extracts_booking_reference_case_insensitively() {
+        let r = ReferenceExtractor::new();
+        assert_eq!(
+            r.extract("where is msl-4b7k921 right now?"),
+            Some("MSL-4B7K921".to_string())
+        );
+    }
+
+    #[test]
+    fn extracts_container_number() {
+        let r = ReferenceExtractor::new();
+        assert_eq!(
+            r.extract("container MSCU1234567 status please"),
+            Some("MSCU1234567".to_string())
+        );
+    }
+
+    #[test]
+    fn returns_none_when_no_reference_present() {
+        let r = ReferenceExtractor::new();
+        assert_eq!(r.extract("what are your office hours?"), None);
+    }
+}

src/retrieval/retriever.rs

@@ -0,0 +1,31 @@
+//! Deterministic half of retrieval: vector search plus reference
+//! extraction. The LLM-based relevance filtering on top of this lives in
+//! `agents::retrieval_agent`, which owns a `DocumentRetriever`.
+
+use anyhow::Result;
+
+use crate::models::agent_io::RetrievedPassage;
+use crate::retrieval::reference_extractor::ReferenceExtractor;
+use crate::retrieval::vector_store::VectorStore;
+
+pub struct DocumentRetriever {
+    store: VectorStore,
+    reference_extractor: ReferenceExtractor,
+}
+
+impl DocumentRetriever {
+    pub fn new(store: VectorStore) -> Self {
+        Self {
+            store,
+            reference_extractor: ReferenceExtractor::new(),
+        }
+    }
+
+    pub async fn search(&self, query: &str, limit: u64) -> Result<Vec<RetrievedPassage>> {
+        self.store.search(query, limit).await
+    }
+
+    pub fn extract_reference(&self, query: &str) -> Option<String> {
+        self.reference_extractor.extract(query)
+    }
+}

src/retrieval/vector_store.rs

@@ -0,0 +1,127 @@
+//! Thin wrapper around the Qdrant gRPC client.
+//!
+//! Constructed explicitly (see `cli.rs`) and handed to a `DocumentRetriever`
+//! by reference -- there is no global client instance anywhere in this
+//! crate.
+
+use std::sync::Arc;
+
+use anyhow::Result;
+use qdrant_client::qdrant::{
+    CreateCollectionBuilder, Distance, PointStruct, QueryPointsBuilder, UpsertPointsBuilder,
+    VectorParamsBuilder,
+};
+use qdrant_client::{Payload, Qdrant};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::embeddings::EmbeddingProvider;
+use crate::knowledge::loader::DocumentRecord;
+use crate::models::agent_io::RetrievedPassage;
+use crate::retrieval::chunking::chunk_text;
+
+const CHUNK_SIZE: usize = 700;
+const CHUNK_OVERLAP: usize = 100;
+
+#[derive(Debug, Serialize, Deserialize)]
+struct ChunkPayload {
+    source: String,
+    text: String,
+}
+
+pub struct VectorStore {
+    client: Qdrant,
+    collection_name: String,
+    embeddings: Arc<dyn EmbeddingProvider>,
+}
+
+impl VectorStore {
+    pub fn new(
+        url: &str,
+        collection_name: impl Into<String>,
+        embeddings: Arc<dyn EmbeddingProvider>,
+    ) -> Result<Self> {
+        let client = Qdrant::from_url(url).build()?;
+        Ok(Self {
+            client,
+            collection_name: collection_name.into(),
+            embeddings,
+        })
+    }
+
+    /// Creates the collection if it doesn't already exist. Idempotent.
+    pub async fn ensure_collection(&self) -> Result<()> {
+        if self.client.collection_exists(&self.collection_name).await? {
+            return Ok(());
+        }
+        self.client
+            .create_collection(CreateCollectionBuilder::new(&self.collection_name).vectors_config(
+                VectorParamsBuilder::new(self.embeddings.dimension() as u64, Distance::Cosine),
+            ))
+            .await?;
+        Ok(())
+    }
+
+    /// Chunks and embeds every document, then upserts the chunks as points.
+    /// Returns the number of chunks indexed.
+    pub async fn index_documents(&self, documents: &[DocumentRecord]) -> Result<usize> {
+        let mut chunk_texts = Vec::new();
+        let mut sources = Vec::new();
+        for doc in documents {
+            for chunk in chunk_text(&doc.text, CHUNK_SIZE, CHUNK_OVERLAP) {
+                sources.push(doc.source.clone());
+                chunk_texts.push(chunk);
+            }
+        }
+        if chunk_texts.is_empty() {
+            return Ok(0);
+        }
+
+        let vectors = self.embeddings.embed(chunk_texts.clone()).await?;
+        let points: Vec<PointStruct> = vectors
+            .into_iter()
+            .zip(chunk_texts)
+            .zip(sources)
+            .map(|((vector, text), source)| {
+                let payload = ChunkPayload { source, text };
+                let payload_value = serde_json::to_value(payload).expect("payload serializes");
+                PointStruct::new(
+                    Uuid::new_v4().to_string(),
+                    vector,
+                    Payload::try_from(payload_value).expect("payload is a JSON object"),
+                )
+            })
+            .collect();
+
+        let count = points.len();
+        self.client
+            .upsert_points(UpsertPointsBuilder::new(&self.collection_name, points))
+            .await?;
+        Ok(count)
+    }
+
+    /// Embeds `query` and returns the `limit` nearest chunks.
+    pub async fn search(&self, query: &str, limit: u64) -> Result<Vec<RetrievedPassage>> {
+        let vector = self.embeddings.embed_one(query).await?;
+        let response = self
+            .client
+            .query(
+                QueryPointsBuilder::new(&self.collection_name)
+                    .query(vector)
+                    .limit(limit)
+                    .with_payload(true),
+            )
+            .await?;
+
+        let mut passages = Vec::with_capacity(response.result.len());
+        for point in response.result {
+            let payload: ChunkPayload = Payload::from(point.payload).deserialize()?;
+            passages.push(RetrievedPassage {
+                source: payload.source,
+                text: payload.text,
+                score: point.score,
+            });
+        }
+        Ok(passages)
+    }
+}