convez.ai
AgenteDados & AnalyticsAvançado
sarthakshirsatai-lab

FreightIQ — Agent de Inteligência de Taxas de Frete

sarthakshirsatai-lab/freightiq-freight-rate-intelligence

IA agentic para decisões de frete spot em segundos vs 2-3 horas

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema agentic de dois agentes que ingere cotações de frete em PDF e responde perguntas sobre taxas em linguagem natural usando RAG com Pinecone. Automatiza decisões de frete spot que levam 2-3 horas manualmente, extraindo dados estruturados, detectando surcharges ocultos e alertando sobre prazos de validade.

Instalação

$npx convez-ai sarthakshirsatai-lab/freightiq-freight-rate-intelligence

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar análise de cotações de frete spot em múltiplos formatos PDF
  • Encontrar taxas mais baratas com cálculo all-in incluindo surcharges ocultos
  • Comparar validade de cotações e alertar sobre expiração próxima
  • Reduzir tempo de decisão em operações de logística e forwarding

Veredito

Projeto maduro e bem documentado com arquitetura agentic real (dois agentes distintos com loops de autocorreção). A implementação mostra domínio de RAG, Pinecone e orquestração Claude, com resultados práticos validados (15/15 PDFs ingeridos, 5/5 perguntas respondidas). Ideal para explorar patterns agentic em negócios reais de logística.

README

A tradução para o português deste README ainda está na fila.

FreightIQ — Freight Rate Intelligence Agent

A personal learning project — building an agentic AI system that enables faster decision making with fragmented data in freight forwarding, using Pinecone Vector DB and Retrieval Augmented Generation (RAG).

Built with Claude Code | Python | Pinecone Vector DB | Anthropic Claude API | PyMuPDF


What This Is

A two-agent Agentic AI System for freight rate intelligence. Logistics operations managers receive spot freight quotes in multiple PDF formats from different forwarders — with surcharges buried in footnotes and validity dates expiring. Comparing them manually takes 2-3 hours per shipment decision.

FreightIQ ingests those PDFs into a Pinecone Vector DB and answers plain English rate questions in seconds.

20-25% of ocean freight shipments are booked on spot quotes in 2026. For a mid-size importer doing 200 containers a year — that's 40-50 manual rate decisions annually. (Source: Freightos Ocean Freight Procurement Report, 2026)


Architecture

FreightIQ Architecture


The Two Agents

Agent 1 — Quote Ingester

Perceives PDF freight quotes, decides on data structure and quality, acts by storing in Pinecone Vector DB, loops until all quotes are ingested or confirmed unrecoverable.

3-round agentic loop:

  • Round 1: Extract text via PyMuPDF → Claude structures JSON → validate → embed → upsert to Pinecone
  • Round 2: Automatic retry on all failures with stricter prompt
  • Round 3: Final validation — confirms vector count matches expected ingestion count

Self-corrections on Run 1: 2 automatic fixes

  • Pinecone metadata type constraint (floats → strings)
  • LOCODE extraction from filename vs Claude extraction

Agent 2 — Rate Advisor

Perceives plain English questions, decides on retrieval strategy, acts by returning recommendations, loops until answer is complete and confident.

4-loop agentic architecture:

  • Loop 1: Input validation — confirms route and intent before searching
  • Loop 2: 3-attempt retrieval — progressively broader search if no results found
  • Loop 3: Quality enrichment — recalculates true all-in cost, flags buried surcharges, flags expiry within 7 days
  • Loop 4: Completeness check — Claude reviews its own answer before returning it

RAG Pipeline

Plain English question ↓ Pinecone semantic search — finds quotes by meaning, not keywords ↓ Expired quotes filtered out automatically ↓ Retrieved quotes passed to Claude as context ↓ Claude reasons across quotes — not from memory ↓ Plain English answer with surcharge breakdown and expiry warning

RAG = Retrieval Augmented Generation — the AI answers from your documents, not from its training data.


Sample Output

Q: "What is the cheapest all-in rate from Mumbai to Rotterdam this week?"

A: Maersk at $2,150 all-in — cheapest, but expires in 4 days. Switch to MSC at $2,610 valid till July 15.

Q: "What hidden surcharges should I watch out for on the Shanghai to Mumbai route?"

A: Hapag-Lloyd quote has BAF + CAF + THC + PSS = $320 buried on top of $580 base rate — 55% hidden markup.


Run 1 Results

MetricResult
PDFs ingested15/15
Questions answered5/5
Self-corrections2
Hidden markup caught55%
Formats handled3 different PDF layouts

Simulated Data

15 freight quotes across 3 PDF formats covering:

Routes: Mumbai→Rotterdam · Mumbai→Hamburg · Shanghai→Mumbai · Mumbai→Dubai · Delhi→London

Carriers: Maersk · MSC · CMA CGM · Hapag-Lloyd

Quote mix:

  • 5 quotes: all-in rate clearly stated
  • 5 quotes: base rate + buried surcharges, total not stated
  • 3 quotes: validity already expired
  • 2 quotes: expiring within 7 days

All quotes labelled: "Simulated data for prototype demonstration only. No affiliation with named carriers."


Tech Stack

🔹 Language: Python 🔹 Vector DB: Pinecone (llama-text-embed-v2 · 1024 dimensions) 🔹 AI Layer: Anthropic Claude API (claude-sonnet-4-5) 🔹 PDF Extraction: PyMuPDF 🔹 PDF Generation: fpdf2 🔹 Built with: Claude Code — plain English prompts only


Production Note

In this prototype, the database schema is shared with the AI to generate queries. In production, companies would deploy this on AWS Bedrock or Azure AI — so nothing leaves the enterprise environment. The logic is the same. The infrastructure is what changes.


Roadmap

  • ✅ Run 1: Two-agent MVP — terminal only
  • 🔄 Run 2: Eval framework — accuracy, hallucination rate
  • 🔄 Run 3: Flask frontend — interactive demo with pre-loaded sample quotes

Built By

Sarthak Shirsat Founder, Acharooz | Ex-Movam | Ex Tolaram Group | IIM Mumbai MBA 9.5 years across fleet management, last mile logistics, B2B logistics SaaS and D2C brand building.

LinkedIn AI Logistics Control Tower


Disclaimer

All freight quote data is simulated. Maersk, MSC, CMA CGM and Hapag-Lloyd are referenced for simulation realism only — no affiliation. Built with Claude Code.

Ver o original no GitHub

Bom para

Relacionados