<div align="center">

🧠 ASTRA

Autonomous Store Trading & Resource Agent

A production-grade multi-agent AI system for grocery retail — combining 5 specialized frameworks on Google Cloud Platform

<br/>

<br/>

<br/>

Architecture · Features · Quick Start · Tech Stack · Interactive Diagram

</div>

---

📋 Overview

Large grocery retailers juggle thousands of daily customer queries, real-time pricing decisions across 50,000+ SKUs, and complex supply chain logistics — all requiring instant, accurate, context-aware responses.

ASTRA solves this by deploying the right AI framework for each job:

| Framework | Role | Why This Framework | Model | |-----------|------|--------------------|-------| | 🎯 Google ADK | Orchestrator — routes messages, manages sessions | Native GCP integration, Vertex AI deployment path | Gemini 2.0 Flash | | 🔄 LangGraph | Customer support — 6-node state machine with HITL | Stateful workflows, conditional routing, interrupt/resume | Gemini 2.5 Flash | | 👥 CrewAI | Pricing analysis — 3 specialist agents collaborate | Multi-agent delegation, role-based reasoning | Gemini 2.5 Pro | | 📚 LlamaIndex | Knowledge retrieval — 4 specialized RAG indexes | Production RAG, structured metadata filtering | text-embedding-005 | | 🛡️ NeMo Guardrails | Safety layer — input/output validation | Programmable safety rules via Colang, injection defense | Gemini 2.0 Flash |

Why 5 frameworks instead of 1? Each framework excels at a specific pattern. LangGraph handles stateful workflows better than CrewAI. CrewAI handles multi-agent collaboration better than LangGraph. LlamaIndex handles RAG better than both. ADK provides the GCP deployment path. NeMo provides programmable safety. Using the right tool for each job produces better results than forcing one framework to do everything.

---

🏗 Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        NeMo Guardrails (Safety Layer)                │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                   Google ADK Orchestrator                      │  │
│  │                                                                │  │
│  │   User Message → Intent Router → Session Manager               │  │
│  │          │        (3-tier: keyword → pattern → LLM)            │  │
│  │          ▼                                                     │  │
│  │   ┌──────────────────┬──────────────────┬───────────────────┐  │  │
│  │   │    LangGraph     │     CrewAI       │    LlamaIndex     │  │  │
│  │   │    Customer      │     Pricing      │    Knowledge      │  │  │
│  │   │    Support       │     Crew         │    Base           │  │  │
│  │   │                  │                  │                   │  │  │
│  │   │  6 Nodes:        │  3 Agents:       │  4 Indexes:       │  │  │
│  │   │  · intake        │  · Analyst       │  · products       │  │  │
│  │   │  · classify      │  · Forecaster    │  · policies       │  │  │
│  │   │  · retrieve      │  · Strategist    │  · pricing_rules  │  │  │
│  │   │  · resolve       │                  │  · faqs           │  │  │
│  │   │  · escalate      │  6 Tools         │                   │  │  │
│  │   │  · feedback      │                  │  ChromaDB         │  │  │
│  │   └──────────────────┴──────────────────┴───────────────────┘  │  │
│  │                                                                │  │
│  │   MCP Servers: [Inventory] [Competitor] [Logistics]            │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                ↕                    ↕                  ↕              │
│     ┌──────────────┐    ┌──────────────┐    ┌──────────────┐        │
│     │  Cloud Run   │    │  BigQuery    │    │ Cloud Trace  │        │
│     │  (API)       │    │  (Analytics) │    │ (Tracing)    │        │
│     └──────────────┘    └──────────────┘    └──────────────┘        │
└──────────────────────────────────────────────────────────────────────┘

🎯 Three-Tier Intent Router

The routing layer uses a cost-optimized cascade — saving ~80% of LLM routing costs:

| Tier | Method | Coverage | Latency | Cost | |------|--------|----------|---------|------| | 1 | Keyword matching | ~50% of messages | <1ms | Free | | 2 | Entity/pattern boosting | ~30% of messages | ~5ms | Free | | 3 | LLM classification (Gemini 2.0 Flash) | ~20% of messages | ~200ms | ~$0.0001/call |

---

🔥 Key Features

Customer Support — LangGraph State Machine

• 6-node workflow: intake → classify → retrieve → resolve → escalate → feedback
• Conditional routing based on issue type and LLM confidence scores
• Human-in-the-loop escalation with interrupt_after — graph pauses for human review and resumes exactly where it stopped
• Automated actions: refunds, vouchers, redelivery scheduling
• CSAT prediction for every interaction

Customer: "My order ORD-2025-1042 arrived with spoiled milk!"
    │
    ▼
[NeMo] → Input validated ✓
    │
[ADK]  → Intent: "customer_support" (keyword match, confidence: 0.92)
    │
[LangGraph]
    ├─ INTAKE    → Extract: order_id, issue=quality_complaint, sentiment=very_negative
    ├─ CLASSIFY  → Category: quality_complaint, needs_retrieval=true
    ├─ RETRIEVE  → LlamaIndex: "Spoiled perishables qualify for full refund..."
    ├─ RESOLVE   → Confidence: 0.88 → process_refund(£34.50) + issue_voucher(£5)
    └─ FEEDBACK  → Predicted CSAT: 4.0 → Trajectory logged to BigQuery

Pricing Optimization — CrewAI Sequential Crew

• Market Analyst → competitive intelligence via Vertex AI Search + BigQuery
• Demand Forecaster → sales trends, stock levels, seasonality analysis
• Pricing Strategist → margin-aware recommendations with business rule validation
• Context chaining: each agent builds on the previous agent's output

Employee: "Optimize dairy pricing — clear excess yoghurt stock"
    │
[CrewAI Sequential]
    ├─ MARKET ANALYST    → "ASTRA is 4.2% above market on yoghurt, Tesco promoting..."
    ├─ DEMAND FORECASTER → "Yoghurt overstocked at 4.2 weeks cover, waste risk flagged"
    └─ PRICING STRATEGIST→ Structured pricing report with margin-safe recommendations

Knowledge Layer — LlamaIndex RAG

| Index | Contents | Query Example | |-------|----------|---------------| | products | 50 products with prices, categories, stock | "Is organic milk in stock?" | | policies | Return, refund, delivery, loyalty policies | "Can I return frozen items?" | | pricing_rules | Margin guidelines, approval thresholds | "Minimum margin for dairy?" | | faqs | 30+ frequently asked questions | "How does loyalty work?" |

• Intelligent query routing across indexes by domain
• Hybrid search with metadata filtering (e.g., category=dairy)
• Embedding model: Google text-embedding-005 (768 dimensions)

Safety & Compliance — NeMo Guardrails

• Input rails: Prompt injection detection, off-topic blocking, message validation
• Output rails: Internal data redaction, price bounds enforcement, brand voice compliance
• Topical rails: Scope enforcement (no medical, legal, or financial advice)
• Colang rules: Version-controlled, testable, auditable

Observability & Monitoring

• Trajectory tracking: Every agent decision logged with full context to BigQuery
• Distributed tracing: OpenTelemetry → Cloud Trace across all frameworks
• Custom metrics: Latency, CSAT, escalation rate, error rate, token usage
• Alert policies: Auto-fires on P95 latency >30s, CSAT <3.5, error rate >5%

---

🎨 Interactive Architecture Diagram

This repository includes an interactive React component (ASTRA_Architecture.jsx) that visualizes the complete system architecture with four navigable tabs:

| Tab | Description | |-----|-------------| | Architecture | Nested layer diagram — click any framework to explore its responsibilities | | Data Flows | Step-by-step Customer Support and Pricing flows with agent attribution | | Timeline | 4-week MVP implementation plan breakdown | | Tools & Models | Complete model assignments and tool inventory |

▶️ View It Live

Open architecture/index.html in any browser — no build step needed. It renders the JSX component using React CDN.

# On any OS — just open the file:
open architecture/index.html        # macOS
start architecture/index.html       # Windows
xdg-open architecture/index.html    # Linux

💡 For Developers: The JSX component can also be imported directly into any React project:

import ASTRAArchitecture from './ASTRA_Architecture';

---

📂 Project Structure

astra-multi-agent-ai/
├── src/
│   ├── api/                        # FastAPI REST layer
│   │   └── app.py                  # Endpoints: /chat, /health, /escalation, /sessions
│   ├── orchestrator/               # Google ADK orchestrator
│   │   ├── agent.py                # Main entry point — intent routing & delegation
│   │   ├── router.py               # 3-tier intent classification
│   │   └── session.py              # Multi-turn session management
│   ├── customer_support/           # LangGraph state machine
│   │   ├── graph.py                # Graph definition + compilation
│   │   ├── state.py                # TypedDict state with reducers
│   │   ├── prompts.py              # Centralized LLM prompts
│   │   ├── tools.py                # Order/customer/action tools
│   │   └── nodes/                  # 6 graph nodes
│   │       ├── intake.py           # Entity extraction, order lookup
│   │       ├── classify.py         # Issue categorization
│   │       ├── retrieve.py         # LlamaIndex context retrieval
│   │       ├── resolve.py          # Response generation + actions
│   │       ├── escalate.py         # HITL checkpoint
│   │       └── feedback.py         # CSAT prediction + logging
│   ├── pricing/                    # CrewAI pricing crew
│   │   ├── crew.py                 # Crew orchestration
│   │   ├── agents.py               # 3 specialist agents
│   │   ├── tasks.py                # Task definitions with context chains
│   │   └── tools.py                # 6 pricing tools
│   ├── knowledge/                  # LlamaIndex RAG
│   │   ├── indexer.py              # 4 specialized indexes
│   │   ├── query_engine.py         # Intelligent query routing
│   │   ├── sample_data.py          # Test data generator
│   │   └── data/                   # Products, policies, FAQs, rules
│   ├── guardrails/                 # NeMo Guardrails
│   │   ├── config.yml              # Model + instruction config
│   │   ├── rails/                  # Colang dialog flows
│   │   └── actions.py              # Custom validation actions
│   ├── tools/
│   │   └── mcp_servers/            # 3 MCP data servers
│   └── common/                     # Shared config, models, logging, tracing
│       ├── config.py               # Pydantic settings
│       ├── models.py               # Shared data models
│       ├── logging.py              # Structured logging
│       └── tracing.py              # OpenTelemetry setup
├── tests/                          # Unit + integration tests
│   ├── test_router.py              # Intent router tests
│   ├── test_tools_and_session.py   # Tool + session tests
│   └── test_monitoring.py          # Metrics + alert tests
├── notebooks/                      # Weekly development notebooks
│   ├── 01_week1_knowledge_layer.ipynb
│   ├── 02_week2_agent_workflows.ipynb
│   ├── 03_week3_integration.ipynb
│   └── 04_week4_deployment_monitoring.ipynb
├── deploy/
│   ├── Dockerfile                  # Multi-stage production build
│   ├── cloudbuild.yaml             # GCP CI/CD pipeline
│   ├── deploy_cloudrun.sh          # One-command Cloud Run deploy
│   ├── cleanup.sh                  # Resource cleanup
│   └── terraform/
│       └── main.tf                 # Infrastructure as Code (all GCP resources)
├── monitoring/
│   ├── metrics.py                  # Interaction metrics collector
│   ├── tracing.py                  # Distributed tracing
│   ├── alerts/                     # Alert rules and thresholds
│   └── dashboards/                 # BigQuery queries for Looker Studio
├── architecture/
│   └── index.html                  # Interactive architecture viewer (open in browser)
├── ASTRA_Architecture.jsx          # React component — interactive system diagram
├── ASTRA_PROJECT_REPORT.md         # Detailed project lifecycle report
├── PROJECT_DESCRIPTION.md          # Project description & skills breakdown
├── pyproject.toml                  # Python project config
├── requirements.txt                # Production dependencies
├── setup.bat                       # Windows dependency installer
├── .env.example                    # Environment variable template
└── .gitignore

---

⚡ Tech Stack

| Layer | Technology | Purpose | |-------|-----------|---------| | Orchestration | Google ADK | Intent routing, session management, Vertex AI deployment | | Customer Workflow | LangGraph | 6-node stateful graph with HITL interrupts | | Pricing Analysis | CrewAI | 3-agent sequential collaboration with context chaining | | Knowledge / RAG | LlamaIndex + ChromaDB | 4-index retrieval with metadata filtering | | Safety | NeMo Guardrails (Colang) | Input/output validation, injection defense | | Models | Gemini 2.0 Flash, 2.5 Flash, 2.5 Pro | Tiered by cost and capability | | Embeddings | text-embedding-005 | 768-dimensional vectors for RAG | | Real-time Data | MCP Protocol | 3 servers: inventory, competitor, logistics | | API | FastAPI + Uvicorn | REST endpoints with OpenAPI documentation | | Data Warehouse | BigQuery | Trajectories, interaction metrics, analytics | | Storage | Cloud Storage | Knowledge documents, model artifacts | | Deployment | Cloud Run (Docker) | Containerized, auto-scaling, serverless | | CI/CD | Cloud Build | Automated test → build → deploy pipeline | | Infrastructure | Terraform | Infrastructure as Code for all GCP resources | | Tracing | OpenTelemetry → Cloud Trace | Distributed tracing across all frameworks | | Monitoring | Cloud Monitoring | Latency, CSAT, error rate, escalation rate alerts | | Logging | Cloud Logging + Rich | Structured logs with agent prefixes |

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Google AI Studio API key (for local development)
• GCP project with billing enabled (for deployment)

Setup

# Clone the repository
git clone https://github.com/vsundar95/astra-multi-agent-ai.git
cd astra-multi-agent-ai

# Install dependencies (Windows)
setup.bat

# Configure environment
cp .env.example .env
# Edit .env — only 2 values needed for local dev:
#   GOOGLE_API_KEY=your-ai-studio-key
#   GCP_PROJECT_ID=your-project-id

Run

# Generate sample data for RAG indexes
python -m src.knowledge.sample_data

# Run the test suite
pytest tests/ -v

# Start the API server
uvicorn src.api.app:app --reload --port 8080

# Open development notebooks
jupyter notebook notebooks/

Deploy to Production (GCP)

# One-command Cloud Run deployment
./deploy/deploy_cloudrun.sh YOUR_PROJECT_ID

# Or use Terraform for full infrastructure
cd deploy/terraform
terraform init && terraform apply

---

📊 Project Statistics

| Metric | Value | |--------|-------| | Python source files | ~45+ | | Lines of code | ~8,000+ | | Agent frameworks | 5 (ADK, LangGraph, CrewAI, LlamaIndex, NeMo) | | LangGraph nodes | 6 (intake → classify → retrieve → resolve → escalate → feedback) | | CrewAI agents | 3 (Market Analyst, Demand Forecaster, Pricing Strategist) | | LlamaIndex indexes | 4 (products, policies, pricing_rules, FAQs) | | MCP servers | 3 (inventory, competitor, logistics) | | API endpoints | 5 (/chat, /health, /escalation, /sessions, /) | | Custom tools | 20+ | | Test files | 7 | | Gemini models | 3 (2.0 Flash, 2.5 Flash, 2.5 Pro) | | GCP services | 10+ | | Development notebooks | 4 (weekly sprints) |

---

🧩 Design Decisions

<details> <summary><strong>Why 5 frameworks instead of 1?</strong></summary>

Each framework excels at a specific pattern. LangGraph handles stateful workflows better than CrewAI. CrewAI handles multi-agent collaboration better than LangGraph. LlamaIndex handles RAG better than both. ADK provides the GCP deployment path. NeMo provides programmable safety. Using the right tool for each job produces better results than forcing one framework to do everything.

</details> <details> <summary><strong>Why keyword routing before LLM routing?</strong></summary>

The 3-tier router (keywords → patterns → LLM) saves ~80% of LLM routing costs. Most messages contain obvious signals ("order", "refund", "pricing") that don't need AI to classify. The LLM fallback only fires for genuinely ambiguous messages.

</details> <details> <summary><strong>Why separate customer/internal APIs?</strong></summary>

Customer support and pricing optimization serve different users with different security requirements. Customers should never see cost prices, margins, or competitor strategies. Separating at the API layer (not just the prompt layer) provides defense in depth.

</details> <details> <summary><strong>Why MCP for real-time data?</strong></summary>

The Model Context Protocol provides standardized tool discovery and invocation. Any MCP-compatible agent can connect to the inventory, competitor, or logistics servers without custom integration code. It's the "USB port" for AI tools.

</details> <details> <summary><strong>Why Cloud Run over Vertex AI Agent Engine?</strong></summary>

Full control over the 5-framework stack, custom Docker images, independent scaling, and no pickle serialization constraints. Agent Engine is great for single-framework agents but doesn't support the heterogeneous architecture ASTRA requires.

</details>

---

🎓 Skills Demonstrated

AI / ML Engineering

• Multi-agent system design with 5 specialized frameworks
• Retrieval-Augmented Generation (RAG) with 4 domain-specific indexes
• Prompt engineering for entity extraction, classification, and response generation
• Human-in-the-loop (HITL) workflow implementation
• Agent trajectory tracking and CSAT prediction
• Programmable AI safety guardrails (Colang)
• Cost-optimized model selection (tiered Gemini models)

Software Engineering

• Production Python architecture (async, Pydantic, type hints, factory patterns)
• FastAPI REST API design with OpenAPI documentation
• Multi-stage Docker builds for optimized container images
• Model Context Protocol (MCP) server implementation
• Comprehensive test suites (unit + integration)

Cloud Engineering (GCP)

• Cloud Run containerized deployment with auto-scaling
• BigQuery data warehousing and analytics
• Cloud Build CI/CD pipelines
• Terraform Infrastructure as Code
• OpenTelemetry distributed tracing → Cloud Trace
• Cloud Monitoring alerting and custom dashboards
• IAM role-based access control
• Artifact Registry container image management

---

🗂 Additional Documentation

| Document | Description | |----------|-------------| | ASTRA_PROJECT_REPORT.md | Complete project lifecycle report — genesis, team structure, sprint-by-sprint build, challenges, production deployment, monitoring, and lessons learned | | PROJECT_DESCRIPTION.md | Concise project description with architecture diagrams, data flows, and skills breakdown | | ASTRA_Architecture.jsx | Interactive React component for the system architecture visualization |

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

<div align="center">

Built by Sundar Paul — demonstrating enterprise multi-agent AI architecture on Google Cloud Platform.

If you found this project interesting, consider giving it a ⭐

</div>