Skip to content

jharbieh-microsoft/az-ai-agentic-retrieval

BranchesTags

Repository files navigation

Multilingual Agentic Retrieval System

A comprehensive knowledge base system that supports multilingual document processing and intelligent query answering using Azure AI services and agentic retrieval capabilities.

🎯 Project Overview

This system enables users to upload documents in multiple formats (PDF, Word, Excel, PowerPoint, JPEG) and query them in both English and Korean. It leverages Azure's AI services and an agentic architecture for intelligent document processing and retrieval.

Key Features

  • ✅ Multilingual Support: English and Korean language processing
  • ✅ Multiple Document Formats: PDF, DOCX, XLSX, PPTX, JPEG
  • ✅ Agentic Retrieval: Intelligent multi-agent system for query processing
  • ✅ Hybrid Search: Combination of semantic and keyword search
  • ✅ Real-time Processing: Asynchronous document processing pipeline
  • ✅ Bilingual Responses: Generate answers in both languages simultaneously
  • ✅ Chat Interface: Interactive conversational UI with document upload
  • ✅ Scalable Architecture: Built on Azure cloud services

📚 Documentation

This repository contains comprehensive documentation to guide you through the entire project:

Core Documentation

  1. REQUIREMENTS.md

    • Business requirements and objectives
    • Technical capabilities and specifications
    • Technology stack requirements

  2. ARCHITECTURE.md

    • High-level system architecture
    • Detailed component diagrams
    • Agentic retrieval system design
    • Data flow and processing pipelines
    • Azure services integration
    • Security and scalability architecture
    • Technology stack mapping

  3. API_SPECIFICATION.md

    • Complete REST API documentation
    • WebSocket API specifications
    • Request/response schemas
    • Authentication and authorization
    • Error handling and rate limiting

  4. IMPLEMENTATION_GUIDE.md

    • Development environment setup
    • Step-by-step implementation instructions
    • Code examples and samples
    • Testing strategies
    • Best practices

  5. DEPLOYMENT_OPERATIONS_GUIDE.md

    • Azure resource provisioning
    • Deployment procedures
    • Monitoring and logging
    • Backup and disaster recovery
    • Scaling strategies
    • Security hardening
    • Troubleshooting guide

🏗️ Architecture At a Glance

┌─────────────────────────────────────────────────────────────┐
│                      React Frontend                          │
│          (Chat Interface + Document Management)              │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│              Azure API Management / Gateway                  │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ↓               ↓               ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Node.js API │ │Python Service│ │Azure Functions│
│   (Express)  │ │  (FastAPI)   │ │ (Serverless) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                 │
       └────────────────┼─────────────────┘
                        ↓
         ┌──────────────────────────────┐
         │   Agentic Orchestrator       │
         │  - Query Analyzer            │
         │  - Retrieval Coordinator     │
         │  - Context Builder           │
         │  - Response Generator        │
         └──────────────┬───────────────┘
                        │
        ┌───────────────┼───────────────┐
        ↓               ↓               ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│Azure OpenAI  │ │ AI Search    │ │Cognitive Svcs│
│   (GPT-4)    │ │(Hybrid Index)│ │ (OCR, Vision)│
└──────────────┘ └──────────────┘ └──────────────┘
                        │
        ┌───────────────┼───────────────┐
        ↓               ↓               ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│Blob Storage  │ │Cosmos DB     │ │PostgreSQL    │
│ (Documents)  │ │ (Metadata)   │ │(pgvector)    │
└──────────────┘ └──────────────┘ └──────────────┘

🚀 Quick Start

Prerequisites

  • Azure Subscription with required permissions
  • Node.js 20+ and npm/yarn
  • Python 3.11+
  • Docker Desktop
  • Git
  • Azure CLI
  • VS Code (recommended)

Installation

  1. Clone the repository

    git clone <repository-url>
cd az-ai-agentic-retrieval

  2. Set up environment variables

    cp .env.example .env
# Edit .env with your Azure credentials

  3. Install dependencies

    # Backend API
cd backend/api
npm install

# Python Processing Service
cd ../processing
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Frontend
cd ../../frontend
npm install

  4. Start development environment

    # Using Docker Compose (recommended)
docker-compose up -d

# Or start services individually
cd backend/api && npm run dev
cd backend/processing && uvicorn main:app --reload
cd frontend && npm start

  5. Access the application

🛠️ Technology Stack

Frontend

  • React 18+ with TypeScript
  • Redux Toolkit for state management
  • Material-UI / Ant Design for UI components
  • Socket.io for real-time updates

Backend

  • Node.js 20+ with Express
  • Python 3.11+ with FastAPI
  • Azure Functions for serverless compute
  • LangChain for LLM orchestration

Azure Services

  • Azure OpenAI (GPT-4, Embeddings)
  • Azure Cognitive Services (Vision, Language)
  • Azure AI Search (Hybrid search)
  • Azure Blob Storage (Document storage)
  • Azure Cosmos DB (NoSQL database)
  • Azure PostgreSQL with pgvector (Vector storage)
  • Azure Functions (Event-driven processing)
  • Azure API Management (API gateway)
  • Application Insights (Monitoring)

Development Tools

  • Docker for containerization
  • GitHub Actions for CI/CD
  • Jest for unit testing
  • Playwright for E2E testing
  • Bicep/Terraform for infrastructure as code

📦 Project Structure

az-ai-agentic-retrieval/
├── backend/
│   ├── api/                    # Node.js Express API
│   ├── processing/             # Python processing service
│   └── functions/              # Azure Functions
├── frontend/                   # React application
├── infrastructure/             # IaC templates (Bicep/Terraform)
├── tests/                      # Test suites
├── docs/                       # Additional documentation
├── .github/workflows/          # CI/CD pipelines
├── docker-compose.yml          # Local development setup
├── REQUIREMENTS.md             # Business requirements
├── ARCHITECTURE.md             # System architecture
├── API_SPECIFICATION.md        # API documentation
├── IMPLEMENTATION_GUIDE.md     # Implementation details
└── DEPLOYMENT_OPERATIONS_GUIDE.md  # Deployment procedures

🧪 Testing

Run Unit Tests

# Backend API
cd backend/api
npm test

# Python Service
cd backend/processing
pytest

# Frontend
cd frontend
npm test

Run Integration Tests

npm run test:integration

Run E2E Tests

npm run test:e2e

🚢 Deployment

Deploy to Azure

  1. Provision Azure Resources

    # Using Bicep
az deployment sub create \
  --location eastus \
  --template-file infrastructure/bicep/main.bicep \
  --parameters environment=production

# Or using Terraform
cd infrastructure/terraform
terraform init
terraform apply

  2. Deploy Applications

    # Deploy API
cd backend/api
npm run build
az webapp deployment source config-zip \
  --resource-group multilingual-kb-prd-rg \
  --name multilingual-prd-api \
  --src api.zip

# Deploy Functions
cd ../functions
func azure functionapp publish multilingual-prd-func

# Deploy Frontend
cd ../../frontend
npm run build
az staticwebapp deploy --name multilingual-prd-frontend

  3. Verify Deployment

    # Check health endpoints
curl https://api.multilingual-kb.azure.com/health

For detailed deployment instructions, see DEPLOYMENT_OPERATIONS_GUIDE.md.

📊 Monitoring & Observability

The system includes comprehensive monitoring:

  • Application Insights: Application performance monitoring
  • Log Analytics: Centralized logging
  • Azure Monitor: Infrastructure monitoring
  • Custom Dashboards: Business metrics and KPIs
  • Alerts: Proactive issue detection

Access dashboards:

  • Azure Portal → Application Insights → Dashboard
  • Grafana dashboards (if configured)

🔒 Security

Security features include:

  • Authentication: Azure AD B2C / OAuth 2.0
  • Authorization: Role-based access control (RBAC)
  • Data Encryption: At rest and in transit
  • Network Security: VNet integration, private endpoints
  • Secrets Management: Azure Key Vault
  • API Security: Rate limiting, request validation
  • Compliance: GDPR, SOC 2 ready

🔄 CI/CD Pipeline

Automated pipelines using GitHub Actions:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Code Push  │────▶│  Build & Test│────▶│   Deploy     │
│   (main)     │     │   - Lint     │     │   - Staging  │
│              │     │   - Unit     │     │   - Prod     │
└──────────────┘     │   - Integration     └──────────────┘
                     └──────────────┘

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 API Documentation

Complete API documentation is available at:

See API_SPECIFICATION.md for detailed specifications.

🐛 Troubleshooting

Common issues and solutions:

Issue: Document Processing Fails

Solution: Check Azure Function logs and verify file format support

Issue: Slow Query Response

Solution: Review cache configuration and database query optimization

Issue: Authentication Errors

Solution: Verify Azure AD configuration and token validity

For more troubleshooting tips, see DEPLOYMENT_OPERATIONS_GUIDE.md.

📈 Performance Targets

Metric Target Notes
Query Response < 3 seconds Cached/simple queries
Document Upload < 10 seconds Files up to 10MB
Document Processing < 2 minutes Complex multi-page docs
Concurrent Users 1000+ With auto-scaling
Availability 99.9% SLA target
Search Accuracy > 90% Top-5 relevance

🗺️ Roadmap

Phase 1: MVP (Current)

  • Basic document upload and processing
  • English and Korean language support
  • Simple query interface
  • Azure infrastructure setup

Phase 2: Enhanced Features

  • Additional language support (Japanese, Chinese)
  • Voice interface (speech-to-text)
  • Mobile applications
  • Advanced analytics dashboard

Phase 3: Enterprise Features

  • Multi-tenant support
  • Advanced collaboration features
  • Custom model fine-tuning
  • Enhanced security features

Phase 4: Innovation

  • Real-time collaborative querying
  • AI-powered content recommendations
  • Integration with external knowledge bases
  • Advanced visualization tools

📄 License

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

👥 Team & Support

🔗 Related Resources

📞 Getting Help

  • Documentation: Start with this README and linked guides
  • Issues: Create a GitHub issue for bugs
  • Discussions: Use GitHub Discussions for questions
  • Email: support@multilingual-kb.com

⭐ Acknowledgments

  • Microsoft Azure team for cloud services
  • OpenAI for GPT models
  • LangChain community for LLM orchestration tools
  • All contributors to this project

Built with ❤️ using Azure AI Services

Last Updated: February 13, 2026

About

An enterprise view into Agentic Retrieval for Multi-language usecases

Topics

ai agentic-retrieval-augmented-generation agentic-retrieval

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages