Livrare LOT 1 - Didi

ai_platform/modules/gateway/INDEX.md

@@ -0,0 +1,144 @@
+# Gateway (didiAI-gateway)
+
+API gateway for the AI platform: a thin **Nginx reverse proxy** that acts as the single externally exposed entry point for all didiAI internal services (LLM inference, audio transcription, web fact-checking, catalog, embeddings, rerank). Every request except `/health` requires Bearer token authentication enforced via an `nginx map` block. Currently in a **restart loop** because several upstream containers it references do not exist on this host (see "Current status" below).
+
+- **Stack**: Nginx 1.27-alpine, no Python, no custom code (config-only module).
+- **URL** (intended): `http://<host>:11000` — listens on a single port, `11000`, mapped 1:1 to the host. No TLS at this layer.
+- **Container**: `didiAI-gateway`
+- **Network**: `didi-network` (external, shared across AI platform modules)
+- **Module path**: `/home/admin365/didi_mono/ai_platform/modules/gateway/`
+
+## Ce face
+
+Single ingress point for all didiAI services, with three responsibilities:
+
+1. **Bearer-token gatekeeping** — every request must carry `Authorization: Bearer <GATEWAY_API_TOKEN>`; rejected with `401 {"error":"unauthorized",...}` otherwise. The check is done with an `nginx map` from `$http_authorization` to `$auth_status`. The token value is injected at container start with `envsubst` against `nginx.conf.template`.
+2. **Path-based reverse proxy** — strips the `/<service>/` prefix and forwards to the matching internal upstream container by Docker DNS name. Adds standard forwarding headers (`Host`, `X-Real-IP`, `X-Forwarded-For`, auto-generated `X-Request-ID`).
+3. **Streaming + large upload tuning** — `proxy_buffering off` + HTTP/1.1 + chunked transfer for the LLM SSE route, and `client_max_body_size 500M` + `client_body_buffer_size 10M` for audio uploads.
+
+There is no rate limiting, no request body inspection, no JWT/Keycloak — just a static shared secret. This gateway is internal-only; the public-facing edge is Kong (separate, unrelated component).
+
+## API endpoints / routes
+
+All routes from `deploy/nginx.conf.template`:
+
+| Path prefix | Auth | Upstream | Notes |
+|-------------|------|----------|-------|
+| `GET /health` | none | nginx direct (returns `{"status":"ok","service":"didiAI-gateway"}`) | for healthcheck |
+| `/llm/*` | Bearer | `didiAI-llm-api:14011` | SSE streaming: `proxy_buffering off`, `chunked_transfer_encoding on`, HTTP/1.1, `Connection: ''` |
+| `/audio/*` | Bearer | `didiAI-audio-api:54300` | `client_body_buffer_size 10M` for large uploads |
+| `/web/*` | Bearer | `didiAI-web-api:51100` | plain proxy_pass |
+| `/catalog/*` | Bearer | `didiAI-catalog-api:11000` | plain proxy_pass; note: catalog also listens on 11000 internally |
+| `/embeddings/*` | Bearer | `didiAI-embeddings-api:14100` | OpenAI-compatible API |
+| `/rerank/*` | Bearer | `didiAI-rerank-api:14200` | Cohere/Jina-compatible API |
+| `/` (anything else) | none | nginx direct | returns `404 {"error":"not_found","routes":[...]}` listing the valid prefixes |
+
+Trailing slash on `proxy_pass http://upstream/;` strips the `/<service>/` prefix when forwarding (so `/llm/v1/chat` becomes `/v1/chat` upstream).
+
+## Current status
+
+**BROKEN / restart loop as of 2026-05-01.** `docker logs didiAI-gateway` shows nginx failing to start with:
+
+```
+[emerg] host not found in upstream "didiAI-llm-api:14011" in /etc/nginx/nginx.conf:35
+```
+
+Root cause: the nginx upstreams resolve hostnames at config load (not per-request), so any missing upstream container kills the whole gateway. On this host only **2 of the 6 upstreams** are running:
+
+- Running: `didiAI-catalog-api`, `didiAI-web-api`.
+- Missing: `didiAI-llm-api`, `didiAI-audio-api`, `didiAI-embeddings-api`, `didiAI-rerank-api`.
+
+Fix options (pick one before redeploying):
+
+1. Start the missing service modules (`llm-inference`, `audio`, `embeddings`, `rerank`) on this host so the names resolve.
+2. Edit `nginx.conf.template` and remove (or comment out) the `upstream` blocks + `location` blocks for services not deployed locally.
+3. Switch the upstream definitions to lazy-resolution form (`set $upstream "didiAI-llm-api:14011"; proxy_pass http://$upstream/;` plus a `resolver` directive) so missing names fail per-request instead of bringing the whole gateway down.
+
+Investigation commands:
+```bash
+docker logs didiAI-gateway
+docker ps --filter "name=didiAI-" --format "table {{.Names}}\t{{.Status}}"
+```
+
+## Structura fisiere
+
+```
+modules/gateway/
+├── README.md                       # User-facing docs (routes, auth, quick start)
+├── INDEX.md                        # This file
+└── deploy/
+    ├── docker-compose.yml          # nginx:1.27-alpine, port 11000:11000, didi-network network
+    ├── nginx.conf.template         # 175 lines: map auth, 6 upstreams, 7 locations + 404 fallback
+    ├── deploy.sh                   # Bash wrapper: --detach / --down / --logs, fail-fast on missing GATEWAY_API_TOKEN
+    ├── .env.example                # Template (only GATEWAY_API_TOKEN)
+    └── .env                        # Active config (GATEWAY_API_TOKEN value)
+```
+
+No `src/`, no `pyproject.toml` — this module is pure config. There is no application code.
+
+## Configuration
+
+Single env var, declared in `deploy/.env` (or exported before running `deploy.sh`):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GATEWAY_API_TOKEN` | yes | Bearer token; clients must send `Authorization: Bearer <value>`. Generate with `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`. |
+
+`docker-compose.yml` injects the token into the container env, then the entrypoint runs:
+
+```sh
+envsubst '$GATEWAY_API_TOKEN' < /etc/nginx/nginx.conf.template > /etc/nginx/nginx.conf && nginx -g 'daemon off;'
+```
+
+Tunables hard-coded in `nginx.conf.template` (no env vars, edit + redeploy to change):
+
+- `proxy_connect_timeout 60s`
+- `proxy_send_timeout 300s`
+- `proxy_read_timeout 600s`
+- `client_max_body_size 500M`
+- `client_body_buffer_size 10M` (audio route only)
+- `worker_connections 1024`
+
+## How services connect
+
+The AI platform mixes two patterns; this gateway is **opt-in aggregation**, not platform-wide:
+
+| Service | Port | Routed via gateway? | Notes |
+|---------|------|--------------------|-------|
+| didi-brain (`brain_api`) | `:8090` | **NO** — direct | Brain is exposed directly on its own port; not registered in gateway upstreams |
+| didiAI-dashboard | `:51300` | **NO** — direct | Internal monitoring UI, exposed directly |
+| didiAI-web-api | `:51100` | YES (`/web/`) and direct | Both paths work |
+| didiAI-llm-api | `:14011` | YES (`/llm/`) — required for SSE | LLM router; gateway adds streaming-friendly proxy settings |
+| didiAI-embeddings-api | `:14100` | YES (`/embeddings/`) and direct | OpenAI-compatible |
+| didiAI-rerank-api | `:14200` | YES (`/rerank/`) and direct | Cohere/Jina-compatible |
+| didiAI-audio-api | `:54300` | YES (`/audio/`) — recommended for large uploads | gateway sets a 10 MB body buffer |
+| didiAI-catalog-api | `:11000` | YES (`/catalog/`) | Catalog also listens on 11000 internally — same number as gateway, different network endpoint |
+
+So the gateway aggregates the **inference/IO services** (LLM, embeddings, rerank, audio, web, catalog) under one host:port, while observability/orchestration components (brain, dashboard) stay on their own ports.
+
+This gateway is **independent from the backend stack's Kong/Keycloak**: backend services on `agent-v3` go through the public Kong cluster (10.11.10.175 → DP1/DP2) with JWT from the SSO cluster; this `didiAI-gateway` lives entirely inside the AI-platform Docker network and uses a static Bearer token. The two systems do not call each other through their gateways — agent-v3 talks to AI-platform services directly by container DNS name on the shared Docker network when co-located, or over the LAN otherwise.
+
+## Deployment
+
+```bash
+cd /home/admin365/didi_mono/ai_platform/modules/gateway/deploy
+cp .env.example .env
+# edit .env, set GATEWAY_API_TOKEN
+./deploy.sh -d                    # docker compose up -d
+./deploy.sh --logs                # tail logs
+./deploy.sh --down                # stop + remove
+```
+
+Manual equivalent: `docker compose up -d` from `deploy/`. Network `didi-network` must exist beforehand (it is created by another module's compose, typically `catalog` or `dashboard`).
+
+Healthcheck: `wget --spider http://127.0.0.1:11000/health` every 30 s.
+
+## Related
+
+- AI platform overview: `/home/admin365/didi_mono/ai_platform/CLAUDE.md` (and module-level `README.md` in each sibling: `dashboard/`, `web/`, `embeddings/`, `rerank/`, `didi_brain/brain_api/`).
+- Upstream service modules referenced by this gateway:
+  - `/home/admin365/didi_mono/ai_platform/modules/web/` (running)
+  - `/home/admin365/didi_mono/ai_platform/modules/embeddings/` (not running on this host)
+  - `/home/admin365/didi_mono/ai_platform/modules/rerank/` (not running on this host)
+  - `llm-inference`, `audio`, `catalog` modules (catalog is running; llm-inference + audio are not)
+- **Distinct from backend Kong** — see `backend/services/gateway-auth-layer/didiKong/` and `project_kong_migration_2026_04.md` in the user memory. The backend's Kong cluster is the public edge for `agent-v3`; `didiAI-gateway` is internal-only for AI-platform services.

ai_platform/modules/gateway/README.md

@@ -0,0 +1,87 @@
+# Gateway
+
+Nginx reverse proxy that serves as the **single entry point** for all didiAI services. All requests (except `/health`) require Bearer token authentication.
+
+## Prerequisites
+
+- All global prerequisites (see main [README.md](../../README.md))
+- Docker network `deploy_default` (shared with other modules)
+- At least one backend service running (llm-inference, audio, web, catalog-api)
+
+## Routes
+
+| Route | Upstream | Description |
+|-------|----------|-------------|
+| `/health` | (nginx direct) | Health check, no auth required |
+| `/llm/` | `didiAI-llm-api:14011` | LLM Inference API (SSE streaming enabled) |
+| `/audio/` | `didiAI-audio-api:54300` | Audio Transcription API (10M body buffer) |
+| `/web/` | `didiAI-web-api:51100` | Web Fact-checking API |
+| `/catalog/` | `didiAI-catalog-api:11000` | Catalog API (service discovery) |
+| `/embeddings/` | `didiAI-embeddings-api:14100` | Embeddings API (OpenAI-compatible) |
+| `/rerank/` | `didiAI-rerank-api:14200` | Rerank API (Cohere/Jina-compatible) |
+
+## Authentication
+
+All routes except `/health` require a Bearer token:
+
+```
+Authorization: Bearer <GATEWAY_API_TOKEN>
+```
+
+Unauthorized requests receive:
+```json
+{"error": "unauthorized", "message": "Invalid or missing Bearer token"}
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GATEWAY_API_TOKEN` | Yes | Bearer token for authentication |
+
+## Quick Start
+
+```bash
+cd deploy/
+
+# Configure
+cp .env.example .env
+# Edit .env and set GATEWAY_API_TOKEN
+
+# Start
+docker compose up -d
+
+# Test
+curl http://localhost:11000/health
+curl -H "Authorization: Bearer <token>" http://localhost:11000/llm/health
+```
+
+## Port
+
+| Port | Service | Description |
+|------|---------|-------------|
+| 11000 | Gateway | Only externally exposed port for the platform |
+
+## Proxy Settings
+
+- **Connect timeout:** 60s
+- **Send timeout:** 300s
+- **Read timeout:** 600s
+- **Max upload size:** 500MB
+- **Request ID:** Auto-generated `X-Request-ID` header on all requests
+
+## Architecture
+
+```
+Client
+  |
+  v
+Gateway (nginx :11000) ---> Bearer token check
+  |
+  +-- /llm/        --> didiAI-llm-api:14011        (SSE streaming)
+  +-- /audio/      --> didiAI-audio-api:54300       (large uploads)
+  +-- /web/        --> didiAI-web-api:51100
+  +-- /catalog/    --> didiAI-catalog-api:11000
+  +-- /embeddings/ --> didiAI-embeddings-api:14100
+  +-- /rerank/     --> didiAI-rerank-api:14200
+```

ai_platform/modules/gateway/deploy/.env.example

@@ -0,0 +1,8 @@
+# Gateway Configuration
+# =============================================================================
+# REQUIRED (no defaults)
+# =============================================================================
+
+# API token for Bearer authentication - ALL requests must include this
+# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+GATEWAY_API_TOKEN=

ai_platform/modules/gateway/deploy/deploy.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+#
+# Docker Compose Startup Script for API Gateway
+#
+# Usage: ./deploy/deploy.sh [OPTIONS]
+#
+# Options:
+#   --detach, -d          Run in detached mode
+#   --down                Stop and remove containers
+#   --logs                Show logs
+#   --help, -h            Show this help message
+#
+# Required: Set GATEWAY_API_TOKEN in deploy/.env file.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load .env file
+if [[ -f "$SCRIPT_DIR/.env" ]]; then
+    echo "Loading environment from: $SCRIPT_DIR/.env"
+    set -a
+    source "$SCRIPT_DIR/.env"
+    set +a
+fi
+
+DETACH=""
+ACTION="up"
+
+show_help() {
+    sed -n '2,15p' "$0" | sed 's/^# //' | sed 's/^#//'
+    exit 0
+}
+
+check_required_var() {
+    local var_name="$1"
+    if [[ -z "${!var_name:-}" ]]; then
+        echo "ERROR: Required environment variable $var_name is not set"
+        echo "Set it in deploy/.env file or export it before running this script"
+        exit 1
+    fi
+}
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --detach|-d)
+            DETACH="-d"
+            shift
+            ;;
+        --down)
+            ACTION="down"
+            shift
+            ;;
+        --logs)
+            ACTION="logs"
+            shift
+            ;;
+        --help|-h)
+            show_help
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
+# Fail-fast required vars
+check_required_var "GATEWAY_API_TOKEN"
+
+cd "$SCRIPT_DIR"
+
+case $ACTION in
+    up)
+        echo "Starting API Gateway on port 11000"
+        echo "  Routes: /llm/ /audio/ /web/ /catalog/ /health"
+        echo ""
+        # shellcheck disable=SC2086
+        exec docker compose up $DETACH
+        ;;
+    down)
+        echo "Stopping API Gateway..."
+        exec docker compose down
+        ;;
+    logs)
+        exec docker compose logs -f
+        ;;
+esac

ai_platform/modules/gateway/deploy/docker-compose.yml

@@ -0,0 +1,50 @@
+# Gateway Module - Docker Compose Configuration
+#
+# Port Allocation:
+#   11000 - API Gateway (ONLY externally exposed port)
+#
+# This is the single entry point for all didiAI services.
+# All requests require Bearer token authentication.
+#
+# Routes:
+#   /llm/         → LLM Inference API
+#   /audio/       → Audio Transcription API
+#   /web/         → Web Fact-checking API
+#   /catalog/     → Catalog API (internal monitoring)
+#   /embeddings/  → Embeddings API
+#   /rerank/      → Rerank API
+#   /health       → Gateway health (no auth)
+#
+# Naming Convention: didiAI-{module}-{service}
+#
+# Network:
+#   Uses deploy_default network (shared with other modules)
+
+networks:
+  didi-network:
+    external: true   # single shared network for all DIDI + AI platform stacks
+
+services:
+  gateway:
+    container_name: didiAI-gateway
+    image: nginx:1.27-alpine
+    ports:
+      - "11000:11000"
+    networks:
+      - didi-network
+    volumes:
+      - ./nginx.conf.template:/etc/nginx/nginx.conf.template:ro
+    environment:
+      - GATEWAY_API_TOKEN=${GATEWAY_API_TOKEN}
+    command: >
+      /bin/sh -c "envsubst '$$GATEWAY_API_TOKEN'
+      < /etc/nginx/nginx.conf.template
+      > /etc/nginx/nginx.conf
+      && nginx -g 'daemon off;'"
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:11000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    restart: unless-stopped

ai_platform/modules/gateway/deploy/nginx.conf.template

@@ -0,0 +1,169 @@
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    # ======================================================================
+    # Logging
+    # ======================================================================
+    log_format main '$remote_addr [$time_local] "$request" '
+                    '$status $body_bytes_sent rt=$request_time '
+                    'auth=$auth_status';
+
+    access_log /var/log/nginx/access.log main;
+
+    # Hide nginx version
+    server_tokens off;
+
+    # ======================================================================
+    # Bearer Token Authentication
+    # ======================================================================
+    map_hash_bucket_size 128;
+    map $http_authorization $auth_status {
+        default       "denied";
+        "Bearer ${GATEWAY_API_TOKEN}" "ok";
+    }
+
+    # ======================================================================
+    # Upstreams
+    # ======================================================================
+    # NOTE: nginx resolves all upstream hostnames at config load time.
+    # Missing names abort startup, so only deployed services are listed here.
+    # Re-enable an upstream when its container exists on this host.
+    #
+    # upstream llm {
+    #     server didiAI-llm-api:14011;
+    # }
+    #
+    # upstream audio {
+    #     server didiAI-audio-api:54300;
+    # }
+
+    upstream web {
+        server didiAI-web-api:51100;
+    }
+
+    upstream catalog {
+        server didiAI-catalog-api:11000;
+    }
+
+    # upstream embeddings {
+    #     server didiAI-embeddings-api:14100;
+    # }
+    #
+    # upstream rerank {
+    #     server didiAI-rerank-api:14200;
+    # }
+
+    # ======================================================================
+    # Gateway Server
+    # ======================================================================
+    server {
+        listen 11000;
+        server_name _;
+
+        # Max upload size (audio files up to 500MB)
+        client_max_body_size 500M;
+
+        # Default JSON content type for error responses
+        default_type application/json;
+
+        # Timeouts
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 300s;
+        proxy_read_timeout 600s;
+
+        # Common proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Request-ID $request_id;
+
+        # ==================================================================
+        # Health - NO auth required
+        # ==================================================================
+        location = /health {
+            access_log off;
+            default_type application/json;
+            return 200 '{"status":"ok","service":"didiAI-gateway"}';
+        }
+
+        # ==================================================================
+        # LLM Inference / Audio Transcription — DISABLED on this host
+        # (didiAI-llm-api and didiAI-audio-api containers not present locally)
+        # Re-enable the upstream block above + location block below when deployed.
+        # ==================================================================
+        # location /llm/ {
+        #     if ($auth_status = "denied") {
+        #         return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+        #     }
+        #     proxy_pass http://llm/;
+        #     proxy_buffering off;
+        #     proxy_cache off;
+        #     proxy_set_header Connection '';
+        #     proxy_http_version 1.1;
+        #     chunked_transfer_encoding on;
+        # }
+        #
+        # location /audio/ {
+        #     if ($auth_status = "denied") {
+        #         return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+        #     }
+        #     proxy_pass http://audio/;
+        #     client_body_buffer_size 10M;
+        # }
+
+        # ==================================================================
+        # Web Fact-checking - /web/
+        # ==================================================================
+        location /web/ {
+            if ($auth_status = "denied") {
+                return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+            }
+
+            proxy_pass http://web/;
+        }
+
+        # ==================================================================
+        # Catalog (internal monitoring) - /catalog/
+        # ==================================================================
+        location /catalog/ {
+            if ($auth_status = "denied") {
+                return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+            }
+
+            proxy_pass http://catalog/;
+        }
+
+        # ==================================================================
+        # Embeddings / Rerank — DISABLED on this host
+        # (FastAPI wrappers not deployed; live BGE-M3 servers run elsewhere)
+        # Re-enable the upstream blocks above + location blocks below when deployed.
+        # ==================================================================
+        # location /embeddings/ {
+        #     if ($auth_status = "denied") {
+        #         return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+        #     }
+        #     proxy_pass http://embeddings/;
+        # }
+        #
+        # location /rerank/ {
+        #     if ($auth_status = "denied") {
+        #         return 401 '{"error":"unauthorized","message":"Invalid or missing Bearer token"}';
+        #     }
+        #     proxy_pass http://rerank/;
+        # }
+
+        # ==================================================================
+        # Default - show available routes
+        # ==================================================================
+        location / {
+            default_type application/json;
+            return 404 '{"error":"not_found","routes":["/web/","/catalog/","/health"]}';
+        }
+    }
+}