freighttiger-shipping-cost-assistant

FreightTiger Smart Assistant That Watches Shipping Costs

An intelligent, production-grade AI assistant built for FreightTiger’s Case Study Round. It continuously monitors shipping records, tracks cost per tonne-km across corridors, flags anomalies against historical and peer baselines, and cross-references real-world context notes (fuel hikes, weather disruptions, festival surcharges, toll changes) using a hybrid vector retrieval (RAG) system with strict anti-hallucination guardrails.

1. Executive Summary & Key Results

2. Mathematical Formulations & Comparison Baselines

All calculations follow FreightTiger’s grading specifications exactly:

A. Weekly Cost Per Tonne-Km

\(\text{Cost per Tonne-Km} = \frac{\sum \text{freight\_cost\_inr}}{\sum (\text{quantity\_tonnes} \times \text{distance\_km})}\) Shipment dates are grouped into Monday-to-Sunday weeks where week_of is the Monday date (YYYY-MM-DD).

B. Trailing 8-Week Own History Baseline (vs_own_history)

For any given route in week $W$: \(\text{Baseline}_{\text{own}} = \frac{1}{K} \sum_{k=1}^{K} \text{Cost}_{W-k} \quad (1 \le K \le 8)\)

C. Similar-Route Peer Average Baseline (vs_similar_routes)

For a route of type $T \in {\text{Short}, \text{Medium}, \text{Long}}$ in week $W$: \(\text{Baseline}_{\text{peer}} = \frac{1}{|P|} \sum_{r \in P} \text{Cost}_{r, W}\) where $P$ is all other routes sharing length bucket $T$ in week $W$ (excluding the route itself).

D. Anomaly Flagging Trigger

A route is evaluated as a candidate spike if:

  1. Cost is rising vs history: $\text{vs_own_pct} > 0$
  2. Out of the ordinary: $\text{vs_own_pct} \ge 20\%$ OR $\text{vs_peer_pct} \ge 20\%$

3. RAG Architecture & Guardrail Defenses

Hybrid Vector Retrieval

Context notes are indexed in a hybrid retrieval engine combining TF-IDF semantic vector similarity with route-corridor metadata matching and temporal event-window filtering.

Guardrails Tested & Resisted

A working demo isn’t enough; the assistant is designed to resist adversarial traps:

  1. Negative Trap Resistance: Notes N004, N005, N006, N007, N008, and N010 explicitly mention that costs were unaffected, routes were not in the dataset, or demand was stable. The assistant never cites these as justifications.
    • Example (Mumbai-Pune, 2025-09-15): The assistant retrieves closest note N006, explains that it mentions stable demand with no disruptions, and correctly marks the verdict as Yes (unexplained).
  2. Anti-Hallucination Contract:
    • Every No (justified) row cites the exact matched_note_id.
    • Any unexplained spike has a blank matched_note_id and flagged = Yes.
    • Never guesses. A confident wrong reason is treated as worse than an unexplained flag.

4. Project Structure

shipping_cost_assistant/
├── data/
│   ├── shipment_records.csv       # 2,940 shipment records
│   ├── context_notes.csv          # 10 real-world context notes
│   └── sample_output_format_v2.csv# Target contract schema
├── outputs/
│   ├── output.csv                 # Primary output matching sample_output_format.csv
│   ├── all_routes_weekly.csv      # Complete 728-week dataset analysis
│   ├── token_cost_log.json        # Detailed token usage & cost breakdown
│   ├── reproducibility_diff.txt   # 3-run zero-diff verification report
│   └── reproducibility/           # Artifacts from 3 independent runs
├── src/
│   ├── data_engine.py             # Route grouping, weekly tracking, baselines
│   ├── vector_store.py            # Pure-python TF-IDF vector retrieval (RAG)
│   ├── reasoner.py                # Anti-hallucination guardrail evaluation
│   ├── token_logger.py            # Honest token & cost logging
│   └── assistant.py               # Pipeline orchestrator
├── main.py                        # CLI entrypoint
├── eval_harness.py                # Evaluation harness & benchmark tester
├── test_reproducibility.py        # 3-run reproducibility verifier
├── interactive_qa.py              # Stretch Goal: Natural language Q&A assistant
├── README.md                      # Comprehensive documentation
└── WALKTHROUGH.md                 # 10-minute Round 2 presentation guide

5. How to Run

Requirements

A. Run Main Assistant Pipeline

python main.py

Outputs generated:

B. Run Reproducibility Check (3 Runs + Diff)

python test_reproducibility.py

C. Run Evaluation Harness

python eval_harness.py

D. Run Interactive Q&A Assistant (Stretch Goal)

# Single query
python interactive_qa.py --query "why did Chennai-Bangalore get pricier in March?"

# Interactive terminal mode
python interactive_qa.py

6. Token & Cost Log

Metric Value
Model Gemini 2.5 Flash / Open-Source Deterministic Engine
Number of Inference Calls 19 calls (triggered selectively on candidate anomalies)
Total Input Tokens 6,531 tokens
Total Output Tokens 1,036 tokens
Published Input Pricing $0.075 / 1M tokens
Published Output Pricing $0.300 / 1M tokens
Total Cost for Entire Dataset $0.000801 USD

7. Verification & Evaluation Results

The self-contained evaluation harness (eval_harness.py) scores against ground-truth benchmark cases: