How climate-resilient-communities/climate-multilingual-chatbot works
Project Type and Purpose
• This is a full-stack, micro-service–style RAG chatbot application with both a Streamlit front end and a CLI mode.
• Its purpose is to let users ask climate-change questions in multiple languages, retrieve documents via Pinecone, rerank them with Cohere, generate responses with Amazon Bedrock Nova, enforce guardrails (hallucination checks, input validation), cache results in Redis, and display results with source citations.
File Structure
• Top-level “src/webui” → Streamlit app.
• “src/main_nova.py” → CLI entrypoint.
• “src/models” → RAG pipeline components (retrieval, rerank, generation, guardrails, caching).
• “src/data/config” → configuration modules (Azure, general).
• “src/utils” → cross-cutting utilities (env loading, logging, metrics, model downloads, system init).
• CI/CD workflows, Dockerfile, docker-compose.yml, Azure deployment scripts for containerized and cloud setups.
• Tests organized by unit, integration, system.
Extract Architectural Insights from the README
• Hybrid search uses Pinecone vector store and BGE-M3 embeddings.
• Reranking via Cohere.
• Generation via Amazon Bedrock Nova.
• Local fallback to HF ClimateBERT model.
• Redis caching layer.
• Asynchronous, pipeline-based processing.
• Streamlit front end with health checks, chat history, citations.
• Azure-ready with model-download script and env-based config.
a. User Interface
• Streamlit Web UI (src/webui/app_nova.py)
• Health Check endpoint (src/webui/health_check.py)
• CLI (src/main_nova.py)
b. Backend Pipeline
• Input Validation & Moderation (input_guardrail.py)
• Retrieval Module (retrieval.py) → Pinecone Vector Store
• Rerank Module (rerank.py) → Cohere API
• Generation Module (gen_response_nova.py) → Amazon Bedrock Nova
• Hallucination Guard (hallucination_guard.py)
• Caching Layer (redis_cache.py) → Redis
• System Messages & Prompts (system_messages.py)
c. Configuration & Utilities
• Env Loader & Config (env_loader.py, config.py, azure_config.py)
• Download Models (download_models.py) → local HF fallback
• Logging & Metrics (logging_config.py, analytics.py, metrics.py)
• System Init & Monitoring (system_init.py, system_monitor.py)
d. External Services & Data Stores
• Amazon Bedrock Nova (AWS)
• Pinecone Vector Store
• Cohere Reranking API
• Redis Server (optional)
• Optional Hugging Face local models
Relationships & Data Flow
1. User → (UI or CLI) → Input Validation
2. If validated → check Redis cache
• Cache hit → return cached response
• Cache miss → proceed
3. Retrieval → Pinecone → get top-k docs
4. Rerank → Cohere → reorder docs
5. Generation → Amazon Bedrock Nova (or local ClimateBERT fallback)
6. Hallucination Guard → enforce quality
7. Save response + citations to Redis
8. Return response to User + log metrics
Architectural Patterns & Design Principles
• Pipeline/Chain-of-Responsibility for RAG flow
• Layered separation: Presentation (UI/CLI), Application (validation, orchestration), Data (cache, vector store), External (LLM, reranker)
• Modular guardrails for safety
• Asynchronous I/O for performance
• Configuration via environment and config modules for portability (Docker, Azure)
Essential Elements to Capture
• All external integrations: Pinecone, Cohere, Amazon Bedrock, Redis, Hugging Face
• Configuration layers for AWS vs. Azure deployment
• Pipeline stages and guardrails
• Interfaces: Streamlit front end, CLI entrypoint