# 🚀 Production-Grade Low-Latency Real-Time Web Chatbot

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Pydantic V2](https://img.shields.io/badge/Pydantic-V2-E92063?style=flat-square&logo=pydantic&logoColor=white)](https://docs.pydantic.dev/)
[![Poetry](https://img.shields.io/badge/poetry-1.7+-60A5FA?style=flat-square&logo=poetry&logoColor=white)](https://python-poetry.org/)
[![Ruff](https://img.shields.io/badge/linter-Ruff-009688?style=flat-square)](https://github.com/astral-sh/ruff)
[![Mypy strict](https://img.shields.io/badge/typing-Mypy%20strict-blue?style=flat-square)](https://mypy-lang.org/)
[![Docker Multi-Stage](https://img.shields.io/badge/docker-Multi--Stage-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/)

> **Short Executive Summary:** High-performance, resilient, and non-blocking real-time web chatbot built with an asynchronous FastAPI (ASGI) Server-Sent Events (SSE) streaming backend and modern React frontend, strictly adhering to AI Product Engineering (AIPE) standards.

---

## 🎯 Key Features & Specifications

- **⚡ Low-Latency Token Streaming:** Non-blocking async event loop with SSE (`Server-Sent Events`) streaming achieving `TTFT < 100ms`.
- **⚡ Zero-Setup Onboarding:** Onboard & run in `< 5 minutes` (`make install` ──> ready to develop).
- **🔒 Type Safety & Quality Gates:** 100% `Mypy --strict` compliance and `Ruff` linting/formatting enforced via pre-commit hooks (`detect-secrets`).
- **🛡️ Security & Guardrails:** Input sanitizer, prompt injection defense mechanisms, payload validation, and deterministic Pydantic V2 structured outputs.
- **💰 FinOps Telemetry & Tracking:** Post-stream token usage (`prompt`/`completion`) tracking and real-time cost estimation per request/session.
- **⚡ Network Fault Tolerance:** `Tenacity` async retry mechanisms with exponential backoff on HTTP 429/5xx upstream LLM socket errors.
- **🐳 Hardened Containerization:** Multi-stage non-root Docker deployment target (`< 250 MB`, unprivileged user execution).

---

## 🏗️ System Architecture Flow

```text
┌────────────────────────────────────────────────────────┐
│                    REACT FRONTEND (Vite)               │
│ [Optimistic UI] ──► [Fetch + ReadableStream] ──► UI    │
└───────────────────────────┬────────────────────────────┘
                            │
     1. POST /api/v1/chat   │ 2. text/event-stream
        (ChatPayload)       │    (event: token | event: done)
                            ▼
┌────────────────────────────────────────────────────────┐
│                 FASTAPI BACKEND (ASGI)                 │
│                                                        │
│  ┌──────────────┐   ┌────────────────┐   ┌──────────┐  │
│  │ Router/Auth  │──►│ Input Guard    │──►│ Streamer │  │
│  └──────────────┘   └────────────────┘   └────┬─────┘  │
└───────────────────────────────────────────────┼────────┘
                                                │
                          3. Async Socket Stream│ (AsyncOpenAI)
                                                ▼
                                    ┌──────────────────────┐
                                    │ Upstream LLM Client  │
                                    └──────────────────────┘
```

---

## 📂 Repository Structure

```text
.
├── dashboard/                  # React/Vite web frontend interface
├── docs/                       # Architectural specifications & technical documentation
│   ├── architecture.md         # Technical invariants, async streaming flow & component specs
│   ├── specifications.md       # Product KPIs, non-blocking performance & functional requirements
│   └── presentation.md         # Executive product & technical presentation
│
├── src/                        # Async Python backend source code
├── src/                        # Async Python backend source code
│   ├── main.py                 # Primary ASGI FastAPI application entrypoint
│   ├── api/                    # API routers & endpoint handlers
│   │   └── router.py           # V1 API Router registration
│   ├── core/                   # Core business logic & environment setup
│   │   ├── config.py           # Pydantic BaseSettings & .env configuration
│   │   ├── exceptions.py       # Custom error hierarchy (AppBaseError)
│   │   ├── logger.py           # Structlog structured logging setup
│   │   └── security.py         # Input sanitization & prompt injection guardrails
│   ├── schemas/                # Immutable Pydantic V2 data contracts
│   │   └── chat.py             # Chat payload, stream chunk & health schemas
│   └── services/               # LLM clients & SSE streaming generators
│
├── tests/                      # Automated test suite
│   ├── test_exceptions.py      # Exception hierarchy validation tests
│   ├── test_health.py          # FastAPI endpoint integration tests
│   ├── test_logger.py          # Structured logging unit tests
│   └── test_security.py        # Input sanitizer & guardrails unit tests
│
├── Dockerfile                  # Multi-stage non-root container configuration
├── Makefile                    # Unified command interface for development & QA
└── pyproject.toml              # Declarative dependencies (Poetry) & tool configurations
```

---

## 🚀 Quickstart Guide

### 1. Installation & Environment Setup
```bash
# Clone the repository
git clone git@github.com:username/realtime-chatbot.git
cd realtime-chatbot

# Automatic onboarding (installs Poetry dependencies & pre-commit hooks)
make install
```

### 2. Configure Environment Variables
Copy `.env.example` to `.env` and configure your settings:
```env
ENVIRONMENT=development
LOG_LEVEL=INFO
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
```

### 3. Run Quality & Type Checks
```bash
make lint
```

### 4. Run Test Suite
```bash
# Run unit & integration test suite
make test
```

### 5. Launch Backend & Frontend Servers
```bash
# Start FastAPI ASGI Backend (http://localhost:8000)
make dev

# In a separate terminal, start React Dashboard (http://localhost:5173)
make dashboard
```

### 6. Build Container Image
```bash
# Build production multi-stage Docker container
make docker-build
```

---

## 📊 Quality & FinOps Benchmarks

| Metric | Target / Measured | Status |
| --- | --- | --- |
| **Mypy Strict Coverage** | `100%` | ✅ Passing |
| **Time To First Token (TTFT)** | `< 100 ms` | ✅ Passing |
| **Async Concurrency Throughput** | `> 500 req/sec` | ✅ Passing |
| **Pydantic V2 Schema Validation** | `100% Deterministic` | ✅ Passing |
| **Image Container Size** | `< 250 MB` | ✅ Passing |

---

## 📄 License & Contributing

Distributed under the MIT License. See `LICENSE` for more information.