maritime-logistics/README.md

Maritime/Logistics Support Assistant

A RAG + multi-agent support assistant for a fictional shipping company (Meridian Sea Logistics), built with a safety/eval layer as the headline feature rather than an afterthought. Written in Rust.

Why this exists

This is a portfolio piece modeled on real maritime-logistics support work, scoped to be publishable: its own fictional company, own documents, own IP. The interesting part isn't the RAG pipeline (that's table stakes) -- it's the guardrail and regression-eval layer wrapped around it, and the trade-offs documented in docs/SAFETY_WRITEUP.md.

Architecture

Three narrow agents behind a deterministic supervisor -- the supervisor is plain Rust control flow, not another LLM call, so what's allowed through is never itself something the model can be talked out of:

query -> guardrail.pre_check (rule-based, blocks prompt injection)
      -> RetrievalAgent   (Qdrant vector search -> LLM relevance filter)
      -> DraftingAgent     (tool-calling: lookup_shipment, escalate_to_human)
      -> PolicyAgent        (LLM compliance check against acceptable_use.md)
      -> guardrail.post_check (rule-based PII/injection scan + policy verdict)
      -> answer, audit record

Every LLM call asks for a schema-validated structured output (via a forced tool-call, see src/llm/client.rs) rather than free text -- there's no Rust equivalent of pydantic-ai, so this is a small hand-rolled agent loop against the raw Anthropic Messages API.

The crate is organized as a dependency-injected module tree (see src/cli.rs, the composition root) -- no global/static singletons anywhere; every component is constructed explicitly and passed to its collaborators through the constructor.

src/
  config.rs        Settings, loaded once in cli.rs
  models/          domain types + structured agent I/O + eval types
  knowledge/       the fictional company's markdown knowledge base
  data/            seed shipment records
  embeddings/      EmbeddingProvider trait + local fastembed impl
  retrieval/       chunking, Qdrant wrapper, reference extraction
  tools/           shipment lookup + human escalation (as LLM tools)
  llm/             Anthropic client, tool trait, agentic loop
  agents/          retrieval / policy / drafting agents + supervisor
  guardrails/      rule-based scanner, audit log, decision pipeline
  eval/            golden dataset loader, scoring, regression harness
  cli.rs           composition root + subcommands

Running it

Requires a Qdrant instance and an Anthropic API key. Embeddings run locally via fastembed (ONNX Runtime) -- the model downloads once on first use, then runs fully offline.

docker run -p 6334:6334 qdrant/qdrant
cp .env.example .env   # fill in ANTHROPIC_API_KEY

cargo run -- ingest              # chunk + embed + index the knowledge base
cargo run -- ask "Where is my container MSCU7654321?"
cargo run -- eval                # run the golden dataset, print the report

Testing

cargo test      # pure-logic unit + integration tests, no network required
cargo clippy --all-targets

The eval command exercises the live model and Qdrant; cargo test deliberately does not, so CI-style checks don't need API keys.

The safety/eval layer

• Golden dataset (data/golden_dataset.jsonl, 44 examples): normal queries, prompt-injection attempts, policy-violation requests, hallucination bait (asking about shipments that don't exist), and out-of-scope requests.
• Regression harness (src/eval/harness.rs): scores retrieval accuracy, generation accuracy, and guardrail correctness separately per example and per category, so a failing run points at where the failure originated instead of just "test 17 failed."
• Guardrail pipeline (src/guardrails/): a fast rule-based scan runs before and after the LLM agents, independent of what the policy agent concludes, and every decision -- allow or block -- is written to an append-only audit log.

See docs/SAFETY_WRITEUP.md for the failure modes this was designed for, the trade-offs made, and what would need to change for real production scale.