<div align="center">

🚚 freight-voice-agents

AI Contact Center for Freight & Logistics — integrated with OpenCall.ai

LangGraph orchestrator · CrewAI specialist crews · Hybrid RAG · Fine-tuned intent classifier

🇧🇷 Leia em Português · 🇬🇧 Read in English

</div>

---

TL;DR

When a customer calls the freight company's OpenCall number, a LangGraph state machine transcribes, classifies the intent (via a fine-tuned LoRA on Llama-3.2-3B), and routes the call to a specialist CrewAI crew (quote, tracking, complaint, pickup). The crew grounds its response with hybrid RAG (BM25 + dense + reranker) over ANTT-based freight policies and rate tables served from Qdrant. Every step is traced in Langfuse; the whole stack runs with docker compose up.

Quando um cliente liga no número OpenCall da transportadora, uma máquina de estados LangGraph transcreve, classifica a intenção (via LoRA fine-tuned em Llama-3.2-3B) e roteia a chamada para uma crew especialista do CrewAI (cotação, rastreamento, reclamação, coleta). A crew fundamenta sua resposta com RAG híbrido (BM25 + denso + reranker) sobre políticas e tabelas de frete baseadas na ANTT, servidas pelo Qdrant. Cada passo é rastreado no Langfuse; todo o stack sobe com docker compose up.

---

🏗️ Architecture

flowchart LR
    Caller([📞 Caller]) -->|phone| OC[OpenCall.ai]
    OC -->|webhook| API[FastAPI<br/>webhook receiver]
    API --> Orch{LangGraph<br/>Orchestrator}

    Orch -->|audio| STT[Transcribe]
    STT --> Intent[Intent Classifier<br/>LoRA on Llama-3.2-3B]

    Intent -->|cotação| Quote[Quote Crew<br/>CrewAI]
    Intent -->|rastreio| Track[Tracking Crew]
    Intent -->|reclamação| Comp[Complaint Crew]
    Intent -->|coleta| Pick[Pickup Crew]
    Intent -->|fallback| Human[Human Handoff]

    Quote & Track & Comp & Pick --> RAG[(Hybrid RAG<br/>Qdrant + BM25 + Reranker)]
    Quote & Track & Comp & Pick --> Tools[Tools<br/>freight_calc · CRM · tracking]

    Quote & Track & Comp & Pick --> Resp[Response<br/>Composer]
    Resp -->|voice reply| OC
    Resp -->|actions| Actions[OpenCall Actions<br/>transfer · SMS · end_call]
    Actions --> OC

    Orch -.->|checkpoint| PG[(Postgres)]
    Orch -.->|trace| LF[Langfuse]

    style OC fill:#f9d71c,color:#000
    style Intent fill:#a3e4d7,color:#000
    style RAG fill:#d7bde2,color:#000

Full C4 breakdown in docs/architecture.md. Architectural decisions documented as ADRs.

---

⚡ Quickstart

git clone https://github.com/caiu-c/freight-voice-agents.git
cd freight-voice-agents
cp .env.example .env                          # preencha ANTHROPIC_API_KEY
make bootstrap                                # uv sync + docker compose + seed
make demo                                     # roda uma chamada simulada E2E

| Service | URL | |---|---| | FastAPI Swagger | http://localhost:8000/docs | | Langfuse (traces) | http://localhost:3000 | | Qdrant dashboard | http://localhost:6333/dashboard | | Dagster UI | http://localhost:3001 |

---

🧩 What this repo demonstrates

| Skill (from job spec) | Where to look | |---|---| | Agent architecture | apps/orchestrator/src/orchestrator/graph.py — LangGraph StateGraph with conditional routing, Postgres checkpointing, guardrails | | LangGraph | Same as above — explicit state machine with retry/fallback branches | | CrewAI | agents/crews/quote_crew/ — role/goal/backstory/tools for a pricing crew | | LangChain | agents/tools/ + init_chat_model abstraction for multi-provider LLMs | | Vector DB + RAG | rag/retrievers/hybrid.py — Qdrant + BM25 + BGE reranker, metadata filters | | Fine-tuning | finetuning/train_intent_lora.py — LoRA on Llama-3.2-3B, before/after metrics in finetuning/results/ | | Data engineering | rag/ingest/dagster_pipeline.py — Dagster job for PDF/CSV/HTML ingestion and chunking | | Deployment | docker-compose.yml + infra/k8s/helm/ + .github/workflows/ | | OpenCall integration | integrations/opencall/ — Pydantic schemas, client, replay tool, fixtures | | RAG evals | rag/evals/run_ragas.py + CI gate in .github/workflows/evals.yml |

---

📁 Project layout

apps/               # FastAPI API · LangGraph orchestrator · arq workers
agents/             # CrewAI crews · shared tools · versioned prompts
rag/                # Ingest (Dagster) · retrievers · RAGAS evals
finetuning/         # LoRA training · synthetic data gen · eval
integrations/       # OpenCall webhook contract + replay tool
infra/              # docker-compose · Helm · Terraform (example)
data/seed/          # ANTT-based freight policies, rate tables, FAQ
docs/               # C4 architecture · ADRs · runbook

---

📚 Deep dives

• 📐 Architecture (C4)
• 🔌 OpenCall integration contract
• 📜 Architecture Decision Records
• 🎯 Fine-tuning walkthrough
• 🛠️ Operational runbook

---

📄 License

MIT — see LICENSE.

---

<div align="center"> _{Built by <a href="https://github.com/caiu-c">@caiu-c</a> · Portfolio project targeting AI Architect / Agent Engineer roles.} </div>