# Multilingual Support AI [](https://github.com/Ous39/multilingual-support-ai/actions/workflows/ci.yml) [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](LICENSE) A production-minded reference implementation of a grounded customer-support assistant for English, French, and Wolof. It demonstrates retrieval, citations, multilingual responses, PII redaction, prompt-injection handling, confidence-based human escalation, evaluation, monitoring, and deployment. The repository uses entirely synthetic support information. It contains no customer data, employer code, private endpoints, or client materials. ## Why this project exists Customer-support automation in emerging markets must work across languages, unreliable connectivity, limited training data, and high-risk financial workflows. This project focuses on a practical principle: the assistant should answer only when it has relevant support information and should escalate safely when it does not. ## Features - English, French, and Wolof knowledge content and responses - Lightweight BM25 retrieval with source citations - Automatic language detection with an explicit language override - Local extractive mode that runs without an API key - Optional OpenAI-compatible LLM provider - Confidence-based escalation to human support - PII and credential redaction before retrieval or generation - Basic prompt-injection detection - Golden-set evaluation endpoint and command-line runner - Prometheus-compatible operational metrics - FastAPI interactive documentation - Docker, health checks, tests, linting, and GitHub Actions CI ## Architecture ```mermaid flowchart TD A[Customer message] --> B[Language detection] B --> C[Safety and PII filter] C -->|Blocked| H[Human escalation] C -->|Safe| D[BM25 retrieval] D --> E{Enough context?} E -->|No| H E -->|Yes| F[Answer generator] F --> G[Response safety check] G -->|Pass| I[Answer with citations] G -->|Fail| H ``` The default `extractive` provider is deterministic and uses no external service. Setting `LLM_PROVIDER=openai` enables an OpenAI-compatible chat-completions endpoint while keeping retrieval, redaction, citations, and escalation in the application layer. ## Quick start ### Local Python ```bash git clone https://github.com/Ous39/multilingual-support-ai.git cd multilingual-support-ai python -m venv .venv source .venv/bin/activate python -m pip install -r requirements-dev.txt uvicorn app.main:app --reload ``` Open: - API documentation: `http://localhost:8000/docs` - Health check: `http://localhost:8000/health` - Metrics: `http://localhost:8000/metrics` ### Docker ```bash docker compose up --build ``` ## API example ```bash curl -X POST http://localhost:8000/v1/chat \ -H 'Content-Type: application/json' \ -d '{ "message": "My cash withdrawal is still pending. What should I do?", "language": "en", "session_id": "demo-001" }' ``` Example response: ```json { "answer": "Based on the support information available: If a cash withdrawal is pending...", "language": "en", "confidence": 0.89, "citations": [ { "document_id": "cashout-001", "title": "Cash withdrawal pending", "score": 0.89 } ], "escalated": false, "escalation_reason": null, "pii_redacted": false, "latency_ms": 3 } ``` The exact score and latency depend on the query and environment. ## Optional LLM mode Copy the environment template and configure your provider: ```bash cp .env.example .env ``` ```dotenv LLM_PROVIDER=openai LLM_MODEL=gpt-4.1-mini LLM_BASE_URL=https://api.openai.com/v1 LLM_API_KEY=replace_me ``` Never commit `.env` or a real API key. The application defaults to API-key-free extractive mode. ## Evaluation Start the API, then run: ```bash python evaluation/run.py ``` The golden set checks: - whether retrieval finds an expected source - whether the response contains citations or escalates safely - whether the response passes the output safety check - request latency Add new JSON Lines cases to `evaluation/golden_set.jsonl`: ```json {"question":"How do I reset my PIN?","language":"en","expected_document_ids":["account-001"]} ``` ## Safety design | Risk | Current control | | --- | --- | | Unsupported answer | Retrieval threshold and human escalation | | Secret or PII exposure | Input redaction and output validation | | Prompt injection | Pattern-based blocking before retrieval | | Incorrect language | Detection plus explicit language override | | Missing evidence | Document IDs, titles, and retrieval scores | | Operational failure | Health endpoint, metrics, tests, and container health check | This is a portfolio reference implementation, not a production financial system. Production deployment would additionally require authentication, authorization, rate limiting, encrypted audit logs, provider data-retention review, stronger classifiers, adversarial evaluation, model monitoring, incident response, human-agent integration, and jurisdiction-specific compliance controls. ## Project structure ```text multilingual-support-ai/ ├── app/ # API, retrieval, safety, language and generation ├── data/ # Synthetic multilingual support knowledge base ├── evaluation/ # Golden dataset and evaluation runner ├── tests/ # API, retrieval and safety tests ├── .github/workflows/ # Continuous integration ├── Dockerfile ├── docker-compose.yml └── README.md ``` ## Tests and linting ```bash pytest ruff check . ``` ## Roadmap - Add streaming responses and conversation-state storage - Add ASR/TTS adapters for low-latency voice support - Add semantic and hybrid retrieval - Add groundedness and multilingual quality scoring - Add human-agent handoff webhooks - Add load tests, tracing, dashboards, and rate limiting ## Author **Ousman Jallow** — VAS & Software Engineer based in The Gambia - [LinkedIn](https://www.linkedin.com/in/ousman-jallow-14b57b29b/) - [GitHub](https://github.com/Ous39) ## License Released under the [MIT License](LICENSE). > This independent educational project is not affiliated with or endorsed by any employer, client, telecom operator, or financial-services company. # multilingual-support-ai