diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..3a0fe30
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,15 @@
+# Database
+DATABASE_URL=DatabaseURL
+
+# OpenTelemetry
+OTEL_SERVICE_NAME=App Name
+OTEL_EXPORTER_OTLP_ENDPOINT=Url
+
+# Datadog (Required for OTel Collector)
+DD_API_KEY=APIKey
+DD_SITE=DDSite
+
+# Google Cloud / Vertex AI
+GCP_PROJECT_ID=ProjectID
+GCP_LOCATION=Location
+GEMINI_API_KEY=APIKey
\ No newline at end of file
diff --git a/README.md b/README.md
index b07c4f6..4547a37 100644
--- a/README.md
+++ b/README.md
@@ -8,26 +8,15 @@
╚██████╗███████╗███████╗███████║ ██║ ██║╚██████╔╝ ███████║██║ ██║██║███████╗███████╗██████╔╝
╚═════╝╚══════╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚══▀▀═╝ ╚══════╝╚═╝ ╚═╝╚═╝╚══════╝╚══════╝╚═════╝
- 🛡️ AGENT CORE - AI Security Gateway 🛡️
- Multi-Layer Defense for LLM Applications
+🛡️ AGENT CORE - AI Security Gateway 🛡️
+Multi-Layer Defense for LLM Applications
```
-
- 
- 
- 
- 
- 
-
-
-
- 
- 
- 
- 
- 
- 
-
+[](/)
+[](/)
+[](/)
+[](/)
+[](/)
---
@@ -39,2152 +28,240 @@
-## ✨ Key Features
-
-
-
-|
-
-### 🛡️ **Defense-in-Depth Security**
-```
-┌─────────────────────────────────┐
-│ Layer 4: Output Validation │
-│ ┌───────────────────────────┐ │
-│ │ Layer 3: Input Security │ │
-│ │ ┌─────────────────────┐ │ │
-│ │ │ Layer 2: Rate Limit │ │ │
-│ │ │ ┌───────────────┐ │ │ │
-│ │ │ │ Layer 1: Auth │ │ │ │
-│ │ │ └───────────────┘ │ │ │
-│ │ └─────────────────────┘ │ │
-│ └───────────────────────────┘ │
-└─────────────────────────────────┘
-```
-
-**4 Specialized Microservices**
-- 🔐 Eagle-Eye (IAM)
-- 🎯 Sentinel (Input Security)
-- 👁️ Guardian (Output Validation)
-- 🌐 Gateway (Orchestration)
-
- |
-
-
-### 🔍 **Real-Time Threat Detection**
-
-| Threat Type | Detection Method | Action |
-|------------|------------------|--------|
-| SQL Injection | ✅ Pattern Matching | 🚫 Block |
-| XSS | ✅ Script Analysis | 🚫 Block |
-| Cmd Injection | ✅ OS Command Scan | 🚫 Block |
-| Prompt Injection | ✅ LLM Analysis | 🚫 Block |
-| PII Leakage | ✅ Regex + ML | 🔒 Redact |
-| Hallucination | ✅ Fact Check | ⚠️ Warn |
-| Toxicity | ✅ Content Filter | 🚫 Block |
-
-**99.9% Detection Rate** | **<5% False Positives**
-
- |
-
-
-|
-
-### 📊 **Full Observability**
-
-```mermaid
-graph LR
- A[Services] -->|Traces| B[Datadog APM]
- A -->|Metrics| C[DogStatsD]
- A -->|Logs| D[Log Collector]
- B --> E[Dashboard]
- C --> E
- D --> E
- E -->|Alerts| F[PagerDuty]
-```
-
-**Monitoring Stack**
-- 📈 **Metrics**: 25+ custom metrics
-- 🔍 **Traces**: Distributed tracing
-- 📝 **Logs**: JSON structured logs
-- 🚨 **Alerts**: Real-time monitoring
-
- |
-
-
-### ⚡ **Performance**
-
-
-
-| Metric | Value | Target |
-|--------|-------|--------|
-| P50 Latency | **850ms** | ✅ <1s |
-| P95 Latency | **2.3s** | ✅ <3s |
-| P99 Latency | **4.1s** | ✅ <5s |
-| Throughput | **500 req/s** | ✅ >300 |
-| Availability | **99.95%** | ✅ >99.9% |
-| Error Rate | **0.02%** | ✅ <0.1% |
-
-
-
-**Async Architecture** | **Parallel Processing**
-
- |
-
-
-
----
-
-## 🏆 **Why Choose Clestiq Shield?**
-
-
-
-| Feature | Clestiq Shield | Traditional WAF | API Gateway Only |
-|---------|:--------------:|:---------------:|:----------------:|
-| **LLM-Specific Security** | ✅ | ❌ | ❌ |
-| **Hallucination Detection** | ✅ | ❌ | ❌ |
-| **PII Redaction** | ✅ | ⚠️ Basic | ❌ |
-| **Rate Limiting** | ✅ Token-based | ✅ Request-based | ✅ Request-based |
-| **Threat Detection** | ✅ Multi-layer | ✅ Network-layer | ❌ |
-| **Output Validation** | ✅ | ❌ | ❌ |
-| **Distributed Tracing** | ✅ | ⚠️ Limited | ⚠️ Limited |
-| **Production Ready** | ✅ | ✅ | ⚠️ Varies |
-
-
-
----
-
## 📋 Table of Contents
-
-
-|
-
-**🏗️ Architecture**
-- [Overview](#-architecture-overview)
-- [Service Deep Dive](#-service-deep-dive)
-- [Request Flow](#request-flow-sequence)
-
- |
-
-
-**🔒 Security & APIs**
-- [Security Features](#️-security-features)
-- [API Reference](#-api-reference)
-- [Rate Limiting](#-rate-limiting--quotas)
-
- |
-
-
-**⚙️ Operations**
-- [Deployment](#-deployment)
-- [Observability](#-observability--monitoring)
-- [Development](#-development-guide)
-
- |
-
-
+- [🏗️ System Architecture](#-system-architecture)
+- [📂 Repository Structure](#-repository-structure)
+- [🔬 Service Deep Dive](#-service-deep-dive)
+ - [1. Gateway Service](#1-gateway-service)
+ - [2. Eagle-Eye (IAM)](#2-eagle-eye-iam)
+ - [3. Sentinel (Input Security)](#3-sentinel-input-security)
+ - [4. Guardian (Output Validation)](#4-guardian-output-validation)
+- [🚀 Quick Start](#-quick-start)
+- [📊 Observability](#-observability-datadog)
---
-## 🚀 Quick Start
-
-
+## 🏗️ System Architecture
-### **Get Started in 5 Minutes!**
+Clestiq Shield protects your LLM applications using a **distributed microservices pattern**. Traffic flows through multiple security layers before reaching the LLM, and the response is validated before returning to the user.
```mermaid
-graph LR
- A[📥 Clone Repo] -->|2 min| B[🔧 Configure .env]
- B -->|1 min| C[🐳 Docker Compose Up]
- C -->|1 min| D[✅ Verify Services]
- D -->|1 min| E[🎉 Make First Request]
+graph TD
+ User([User / Client])
- style A fill:#4CAF50,stroke:#2E7D32,color:#fff
- style B fill:#2196F3,stroke:#1565C0,color:#fff
- style C fill:#FF9800,stroke:#E65100,color:#fff
- style D fill:#9C27B0,stroke:#6A1B9A,color:#fff
- style E fill:#F44336,stroke:#C62828,color:#fff
-```
-
-
-
-### Step 1️⃣: Clone & Configure
-
-```bash
-# Clone the repository
-git clone https://github.com/your-org/ClestiqShield-AgentCore.git
-cd ClestiqShield-AgentCore
-
-# Configure environment variables
-cat > .env << EOF
-# Required: Google Gemini AI API Key
-GEMINI_API_KEY=your_gemini_api_key_here
-
-# Required: Datadog API Key (for monitoring)
-DD_API_KEY=your_datadog_api_key_here
-DD_SITE=us5.datadoghq.com
-
-# Database (auto-configured in docker-compose)
-DATABASE_URL=postgresql+asyncpg://user:password@db:5432/clestiq_shield
-EOF
-```
-
-### Step 2️⃣: Launch Services
-
-```bash
-# Start all microservices with Docker Compose
-docker-compose up --build -d
-
-# Watch the logs (optional)
-docker-compose logs -f
-```
-
-
-📦 What's Being Started? (Click to expand)
-
-| Service | Port | Status URL | Purpose |
-|---------|------|-----------|---------|
-| 🌐 **Gateway** | 8000 | http://localhost:8000/health | API Gateway & Orchestrator |
-| 🔐 **Eagle-Eye** | 8003 | http://localhost:8003/health | Authentication & IAM |
-| 🎯 **Sentinel** | 8001 | http://localhost:8001/health | Input Security Agent |
-| 👁️ **Guardian** | 8002 | http://localhost:8002/health | Output Validation Agent |
-| 🗄️ **PostgreSQL** | 5432 | - | Database |
-| ⚡ **Redis** | 6379 | - | Rate Limiting Cache |
-| 📊 **Datadog Agent** | 8126 | - | APM & Monitoring |
-
-
-
-### Step 3️⃣: Verify Health
-
-```bash
-# Check all services are healthy
-curl http://localhost:8000/health # Gateway
-curl http://localhost:8003/health # Eagle-Eye
-curl http://localhost:8001/health # Sentinel
-curl http://localhost:8002/health # Guardian
-```
-
-**Expected Response:**
-```json
-{
- "status": "ok",
- "service": "clestiq-shield-gateway",
- "version": "1.0.0"
-}
-```
-
-### Step 4️⃣: Create Your First User & App
-
-
-
-|
-
-**Register a User**
-```bash
-curl -X POST http://localhost:8000/api/v1/auth/register \
- -H "Content-Type: application/json" \
- -d '{
- "email": "demo@example.com",
- "password": "SecurePass123!"
- }'
-```
-
-**Response:**
-```json
-{
- "id": "550e8400-...",
- "email": "demo@example.com",
- "is_active": true
-}
-```
-
- |
-
-
-**Login & Get Token**
-```bash
-curl -X POST http://localhost:8000/api/v1/auth/login \
- -d "username=demo@example.com&password=SecurePass123!"
-```
-
-**Response:**
-```json
-{
- "access_token": "eyJhbGciOi...",
- "token_type": "bearer",
- "user": {
- "id": "550e8400-...",
- "email": "demo@example.com"
- }
-}
-```
-
- |
-
-
-
-**Create an Application:**
-```bash
-# Save your JWT token from login
-TOKEN="eyJhbGciOi..."
-
-curl -X POST http://localhost:8000/api/v1/apps/ \
- -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{
- "name": "my-awesome-app",
- "description": "My first AI-powered application"
- }'
-```
-
-**Generate an API Key:**
-```bash
-# Use the app_id from the previous response
-APP_ID="660e8400-..."
-
-curl -X POST http://localhost:8000/api/v1/apps/$APP_ID/keys \
- -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{
- "name": "Production Key"
- }'
-```
-
-**⚠️ IMPORTANT:** Save the `api_key` from the response - it's only shown once!
-
-### Step 5️⃣: Make Your First Secure AI Request
-
-```bash
-# Use the API key you just generated
-API_KEY="cs_4x7K9mLp2qR8..."
-
-curl -X POST http://localhost:8000/chat \
- -H "X-API-Key: $API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "query": "What is machine learning?",
- "model": "gemini-3-flash-preview",
- "moderation": "moderate",
- "settings": {
- "sanitize_input": true,
- "detect_threats": true,
- "content_filter": true,
- "hallucination_check": true
- }
- }'
-```
-
-**🎉 Success Response:**
-```json
-{
- "response": "Machine learning is a subset of artificial intelligence...",
- "app": "my-awesome-app",
- "metrics": {
- "security_score": 0.98,
- "token_usage": {
- "input_tokens": 125,
- "output_tokens": 387,
- "total_tokens": 512
- },
- "processing_time_ms": 2345.67,
- "threats_detected": 0,
- "hallucination_detected": false,
- "tone_compliant": true
- }
-}
-```
-
-
-
-### ✅ **Congratulations!**
-You've successfully:
-- ✨ Deployed a production-grade AI security gateway
-- 🔐 Created a secure user account and application
-- 🔑 Generated an authenticated API key
-- 🛡️ Made a fully secured AI request with threat detection
-
-**Next Steps:** Explore the [API Reference](#-api-reference) or dive into [Security Features](#️-security-features)
-
-
-
----
-
-## 🏗️ Architecture Overview
-
-### High-Level System Architecture
-
-Clestiq Shield follows a **distributed microservices pattern** with clear separation of concerns:
+ subgraph "Google Cloud Platform (Region: us-east1)"
+ Gateway[Gateway Service :8000]
+
+ subgraph "Observability Hub (Central)"
+ DD[Datadog Agent & DaemonSet]
+ end
-```mermaid
-graph TB
- Client[Client Application] -->|HTTP + X-API-Key| Gateway[Gateway Service :8000]
-
- subgraph "Control Plane"
- Gateway -->|1. Verify API Key| EagleEye[Eagle-Eye Service :8003]
- EagleEye -->|User/App/Key Data| DB[(PostgreSQL :5432)]
- Gateway -->|Rate Limit Check| Redis[(Redis :6379)]
+ subgraph "Security Services"
+ Sentinel[Sentinel Service :8001]
+ Guardian[Guardian Service :8002]
+ end
+
+ subgraph "Identity & Management"
+ EagleEye[Eagle-Eye Service :8003]
+ end
+
+ Redis[(Redis Cache)]
+ DB[(PostgreSQL)]
end
- subgraph "Security Plane"
- Gateway -->|2. Analyze Input| Sentinel[Sentinel Service :8001]
- Sentinel -->|LLM Security Check| GeminiAPI[Google Gemini AI]
- Sentinel -->|3. Validate Output| Guardian[Guardian Service :8002]
- Guardian -->|LLM Validation| GeminiAPI
+ subgraph "External SaaS"
+ Gemini[Google Gemini API]
+ DDCloud[Datadog Cloud Platform]
end
- subgraph "Observability Plane"
- Gateway -->|Traces/Metrics/Logs| Datadog[Datadog Agent :8126]
- Sentinel -->|Traces/Metrics/Logs| Datadog
- Guardian -->|Traces/Metrics/Logs| Datadog
- EagleEye -->|Traces/Metrics/Logs| Datadog
- Datadog -->|Export| DatadogCloud[Datadog Cloud]
- end
+ %% Traffic Flow
+ User -- HTTPS --> Gateway
+ Gateway -- Rate Limits --> Redis
- Guardian -->|Validated Response| Sentinel
- Sentinel -->|Final Response| Gateway
- Gateway -->|Secure Response| Client
-
- style Gateway fill:#4CAF50,stroke:#2E7D32,color:#fff
- style EagleEye fill:#9C27B0,stroke:#6A1B9A,color:#fff
- style Sentinel fill:#2196F3,stroke:#1565C0,color:#fff
- style Guardian fill:#E91E63,stroke:#AD1457,color:#fff
- style Datadog fill:#632CA6,stroke:#3E1B66,color:#fff
-```
-
-### Request Flow Sequence
-
-```mermaid
-sequenceDiagram
- participant Client
- participant Gateway
- participant Redis
- participant EagleEye
- participant Sentinel
- participant Guardian
- participant Gemini
- participant Datadog
-
- Client->>Gateway: POST /chat (query + X-API-Key)
+ %% Semantic Routing
+ Gateway -- "/auth, /apps, /users" --> EagleEye
+ EagleEye -- Data --> DB
- rect rgb(240, 240, 255)
- Note over Gateway,EagleEye: Authentication Layer
- Gateway->>EagleEye: Validate API Key
- EagleEye->>EagleEye: Check DB (hashed key)
- EagleEye-->>Gateway: ✓ Valid (App Context)
- end
+ Gateway -- "/chat (Validated)" --> Sentinel
+ Sentinel -- Threat Check --> Gemini
+ Sentinel -- Generate Response --> Gemini
+ Sentinel -. Optional Validation .-> Guardian
+ Guardian -- Hallucination Check --> Gemini
- rect rgb(255, 245, 230)
- Note over Gateway,Redis: Rate Limiting
- Gateway->>Redis: Check token usage
- Redis-->>Gateway: ✓ Within Limits
- end
+ %% Return Path
+ Guardian -. Result .-> Sentinel
+ Sentinel -- Response --> Gateway
+ Gateway -- Final Response --> User
+
+ %% Observability Connections (The Central Hub)
+ Gateway -. Metrics, Logs, Traces .-> DD
+ EagleEye -. Metrics, Logs, Traces .-> DD
+ Sentinel -. Logs & Traces .-> DD
+ Guardian -. Logs & Traces .-> DD
- rect rgb(230, 245, 255)
- Note over Gateway,Sentinel: Input Security
- Gateway->>Sentinel: Analyze Input
- Sentinel->>Sentinel: Sanitize HTML/Unicode
- Sentinel->>Sentinel: PII Detection/Redaction
- Sentinel->>Sentinel: Threat Detection (SQLi, XSS)
- Sentinel->>Gemini: LLM Security Check (if enabled)
- Gemini-->>Sentinel: LLM Response
- Sentinel-->>Gateway: Security Verdict + Sanitized Input
- end
+ DD == Encrypted Export ==> DDCloud
- alt Input Blocked
- Gateway-->>Client: 400 Bad Request (Threat Detected)
- else Input Safe
- rect rgb(255, 240, 245)
- Note over Sentinel,Guardian: Output Validation
- Sentinel->>Guardian: Validate LLM Response
- Guardian->>Guardian: Content Filter (Toxicity)
- Guardian->>Guardian: Hallucination Detection
- Guardian->>Guardian: Citation Verification
- Guardian->>Guardian: Tone Compliance Check
- Guardian->>Guardian: PII Leak Detection
- Guardian-->>Sentinel: Validated Response + Metrics
- end
-
- Sentinel-->>Gateway: Final Response + Metrics
- Gateway->>Redis: Update Token Usage
- Gateway->>Datadog: Record Metrics
- Gateway-->>Client: 200 OK (Validated Response)
- end
-```
-
-### Security Layers
-
-1. **Layer 1 - Authentication (Eagle-Eye)**
- - API Key validation (Argon2 hashing)
- - User & application management
- - JWT token generation
-
-2. **Layer 2 - Rate Limiting (Gateway + Redis)**
- - Token-based rate limiting (5000 tokens/5 min per API key)
- - Automatic key suspension after violations
- - Graceful degradation on Redis failure
-
-3. **Layer 3 - Input Security (Sentinel)**
- - Input sanitization (HTML, Unicode normalization)
- - PII detection and redaction (SSN, email, phone, credit cards)
- - Threat detection (SQL injection, XSS, command injection)
- - LLM-based semantic security analysis
- - TOON (Threat-Obfuscated Object Notation) conversion
-
-4. **Layer 4 - Output Validation (Guardian)**
- - Hallucination detection
- - Citation verification
- - Tone compliance checking
- - Toxicity filtering
- - False refusal detection
- - Disclaimer injection
-
----
-
-## 🔬 Service Deep Dive
-
-### 1. Gateway Service (Port 8000)
-
-**Role**: API Gateway, Request Orchestrator, Authentication Enforcer
-
-**Key Responsibilities**:
-- Single entry point for all client requests
-- API key authentication via `X-API-Key` header
-- Rate limiting enforcement (Redis-backed)
-- Request routing to Sentinel for security processing
-- Response aggregation and metrics calculation
-- Datadog telemetry export
-- Health monitoring
-
-**Core Endpoints**:
-- `POST /chat` - Main chat endpoint with security processing
-- `GET /health` - Health check
-- `GET /` - Service info
-
-**API Request Flow**:
-```python
-1. Extract & validate X-API-Key header
-2. Check Redis rate limits (tokens/time)
-3. Forward to Sentinel with security settings
-4. Receive validated response from Sentinel
-5. Update token usage in Redis
-6. Record metrics to Datadog
-7. Return response with security headers
-```
-
-**Rate Limiting Details**:
-- **Token Limit**: 5,000 tokens per 5 minutes (300 seconds)
-- **Violation Tracking**: 2 violations in 20 minutes = key suspension
-- **Enforcement**: Pre-request check + post-request increment
-- **Storage**: Redis with TTL-based sliding windows
-
-**Database Models**:
-- `Application` - App metadata (name, description, owner)
-- `ApiKey` - API key records (hash, prefix, usage stats)
-
-**Environment Variables**:
-```bash
-DATABASE_URL # PostgreSQL connection string
-REDIS_URL # Redis connection URL
-SENTINEL_SERVICE_URL # Sentinel internal endpoint
-SECRET_KEY # JWT signing secret
-ALGORITHM # JWT algorithm (HS256)
-DD_SERVICE # Datadog service name
-DD_VERSION # Service version
-```
-
----
-
-### 2. Eagle-Eye Service (Port 8003)
-
-**Role**: Identity & Access Management (IAM), User/App/Key Management
-
-**Key Responsibilities**:
-- User registration and authentication
-- Application lifecycle management
-- API key generation and validation
-- Token-based authentication (JWT)
-- Business metrics collection
-
-**Core Endpoints**:
-
-**Authentication**:
-- `POST /auth/register` - User registration (email + password)
-- `POST /auth/login` - User login (returns JWT + user data)
-
-**User Management**:
-- `GET /users/` - Get current user profile
-- `PATCH /users/` - Update user profile
-- `DELETE /users/account-closure` - Delete account (requires no active apps)
-
-**Application Management**:
-- `POST /apps/` - Create new application
-- `GET /apps/` - List user's applications
-- `GET /apps/{app_id}` - Get application details
-- `PATCH /apps/{app_id}` - Update application
-- `DELETE /apps/{app_id}` - Delete application
-
-**API Key Management**:
-- `POST /apps/{app_id}/keys` - Generate new API key
-- `GET /apps/{app_id}/keys` - List application's API keys
-- `DELETE /apps/{app_id}/keys/{key_id}` - Revoke API key
-
-**Security Implementation**:
-```python
-# Password Hashing (Argon2)
-hashed_password = argon2.hash(plain_password)
-
-# API Key Generation
-plain_key = secrets.token_urlsafe(32) # e.g., "cs_4x7K...92qP"
-key_hash = argon2.hash(plain_key)
-key_prefix = plain_key[:4] # For display
-
-# JWT Token Creation
-access_token = jwt.encode(
- {"sub": str(user_id), "exp": expiry},
- SECRET_KEY,
- algorithm="HS256"
-)
-```
-
-**Database Models**:
-```python
-User:
- - id (UUID)
- - email (unique)
- - hashed_password
- - full_name
- - is_active
- - created_at
-
-Application:
- - id (UUID)
- - name (unique)
- - description
- - owner_id (FK to User)
- - created_at
-
-ApiKey:
- - id (UUID)
- - key_hash (indexed)
- - key_prefix (display)
- - name
- - application_id (FK)
- - is_active
- - request_count
- - usage_data (JSON)
- - last_used_at
+ %% Styles
+ style User fill:#f9f,stroke:#000,stroke-width:2px,color:#000
+ style Gateway fill:#bfb,stroke:#000,stroke-width:2px,color:#000
+ style EagleEye fill:#bfb,stroke:#000,stroke-width:2px,color:#000
+ style Sentinel fill:#bfb,stroke:#000,stroke-width:2px,color:#000
+ style Guardian fill:#bfb,stroke:#000,stroke-width:2px,color:#000
+ style DD fill:#632CA6,stroke:#000,stroke-width:4px,color:#fff
+ style Redis fill:#eee,stroke:#000,stroke-width:2px,color:#000
+ style Gemini fill:#fbb,stroke:#000,stroke-width:2px,color:#000
+ style DDCloud fill:#632CA6,stroke:#000,stroke-width:2px,color:#fff
```
-**Business Metrics** (Datadog):
-- `clestiq.eagleeye.users.created` - User registration count
-- `clestiq.eagleeye.apps.created` - Application creation count
-- `clestiq.eagleeye.apps.deleted` - Application deletion count
-- `clestiq.eagleeye.api_keys.created` - API key generation count
-- `clestiq.eagleeye.api_keys.revoked` - API key revocation count
-
---
-### 3. Sentinel Service (Port 8001)
-
-**Role**: Input Security Agent, Threat Detection, LLM Orchestration
-
-**Key Responsibilities**:
-- Input sanitization (HTML, Unicode, null bytes)
-- PII detection and redaction
-- Threat detection (SQLi, XSS, Command Injection)
-- LLM-based semantic security analysis
-- TOON (Threat-Obfuscated) encoding
-- LLM request forwarding to Gemini
-- Output validation via Guardian
-- Parallel LLM processing for performance
-
-**Endpoint**:
-- `POST /chat` - Process chat request with security checks
-
-**Request Schema** (`ChatRequest`):
-```json
-{
- "query": "User's prompt/question",
- "system_prompt": "You are a helpful AI assistant",
- "model": "gemini-3-flash-preview",
- "moderation": "moderate",
- "output_format": "json",
- "max_output_tokens": 8192,
- "settings": {
- "pii_masking": false,
- "sanitize_input": false,
- "detect_threats": false,
- "content_filter": false,
- "hallucination_check": false,
- "citation_check": false,
- "tone_check": false,
- "toon_mode": false,
- "enable_llm_forward": false
- },
- "client_ip": "192.168.1.1",
- "user_agent": "Mozilla/5.0..."
-}
-```
-
-**Response Schema** (`ChatResponse`):
-```json
-{
- "is_blocked": false,
- "block_reason": null,
- "llm_response": "AI-generated response text",
- "metrics": {
- "security_score": 0.95,
- "tokens_saved": 150,
- "llm_tokens": {
- "input": 250,
- "output": 450,
- "total": 700
- },
- "model_used": "gemini-3-flash-preview",
- "threats_detected": 0,
- "pii_redacted": 2,
- "processing_time_ms": 3245.67,
- "guardian_metrics": {
- "hallucination_detected": false,
- "citations_verified": true,
- "tone_compliant": true,
- "disclaimer_injected": false,
- "false_refusal_detected": false,
- "toxicity_score": 0.02
- }
- }
-}
-```
-
-**LangGraph Processing Pipeline** (Nodes):
-
-1. **Sanitization Node** (`sanitizers.py`)
- - HTML entity escaping (bleach)
- - Unicode normalization (NFKC)
- - Null byte removal
- - Control character stripping
-
-2. **PII Redaction Node** (`security.py`)
- - **SSN**: `\d{3}-\d{2}-\d{4}` → `[SSN-REDACTED]`
- - **Email**: `email-validator` → `[EMAIL-REDACTED]`
- - **Phone**: `phonenumbers` → `[PHONE-REDACTED]`
- - **Credit Card**: Luhn algorithm → `[CC-REDACTED]`
-
-3. **Threat Detection Node** (`threat_detectors.py`)
- - **SQL Injection**: Pattern matching (`UNION SELECT`, `DROP TABLE`, etc.)
- - **XSS**: Script tag detection, event handler attributes
- - **Command Injection**: OS command patterns (`; rm -rf`, `| curl`, etc.)
-
-4. **LLM Security Check Node** (`llm_responder.py`)
- - Semantic analysis for prompt injection
- - Jailbreak attempt detection
- - Context-aware threat assessment
+## 📂 Repository Structure
-5. **TOON Conversion Node** (`toon_converter.py`)
- - Threat-Obfuscated Object Notation encoding
- - Context preservation with threat masking
+The `services/` directory contains the independent microservices:
-6. **Parallel LLM Node** (`parallel_llm.py`)
- - Forward sanitized input to Gemini API
- - Parallel Guardian validation
- - Response aggregation
-
-**Agent Graph Flow**:
-```
-Input → Sanitize → PII Redact → Threat Detect → [Block?]
- ↓ No
- LLM Security Check → [Block?]
- ↓ No
- Generate LLM Response
- ↓
- Guardian Validation
- ↓
- Final Response
-```
-
-**Configuration Flags** (Environment):
```bash
-SECURITY_SANITIZATION_ENABLED=false # Opt-in per request
-SECURITY_PII_REDACTION_ENABLED=false
-SECURITY_SQL_INJECTION_DETECTION_ENABLED=false
-SECURITY_XSS_PROTECTION_ENABLED=false
-SECURITY_COMMAND_INJECTION_DETECTION_ENABLED=false
-TOON_CONVERSION_ENABLED=false
-LLM_FORWARD_ENABLED=false # Enable LLM generation
-LLM_MODEL_NAME=gemini-3-flash-preview
-LLM_MAX_TOKENS=8192
-GUARDIAN_SERVICE_URL=http://guardian:8002
-GEMINI_API_KEY=
+services/
+├── 🌐 gateway/ # Entry point, Rate Limiting, Orchestration
+├── 🔐 eagle-eye/ # Identity (IAM), Users, Apps, API Keys
+├── 🎯 security-agent/ # "Sentinel": Input Security, PII, Threat Detection
+└── 👁️ guardian/ # "Guardian": Output Validation, Hallucination, Toxicity
```
---
-### 4. Guardian Service (Port 8002)
-
-**Role**: Output Validation Agent, Content Quality Assurance
+## 🔬 Service Deep Dive
-**Key Responsibilities**:
-- Content filtering (toxicity, harmful content)
-- Hallucination detection
-- Citation verification (fact-checking)
-- Tone compliance checking
-- False refusal detection
-- PII leak prevention
-- Disclaimer injection
-- TOON decoding
+### 1. Gateway Service
+**Orchestrator & First Line of Defense**
-**Endpoint**:
-- `POST /validate` - Validate LLM-generated response
+The Gateway is the single entry point. It handles **Authentication enforcement** (delegating logic to Eagle-Eye) and **Rate Limiting** (using Redis) before routing requests to the security agents.
-**Request Schema** (`ValidateRequest`):
-```json
-{
- "llm_response": "AI-generated text to validate",
- "moderation_mode": "moderate",
- "output_format": "json",
- "original_query": "User's original question",
- "guardrails": {
- "allowed_topics": ["finance", "health"],
- "forbidden_topics": ["violence", "self-harm"]
- },
- "config": {
- "enable_content_filter": true,
- "enable_pii_scanner": true,
- "enable_hallucination_detector": true,
- "enable_citation_verifier": true,
- "enable_tone_checker": true,
- "enable_refusal_detector": true,
- "enable_disclaimer_injector": false,
- "enable_toon_decoder": false
- }
-}
-```
+**Key Features:**
+- 🛡️ **Rate Limiting**: Sliding window counters backed by Redis.
+- 🔑 **Auth Enforcement**: Validates `X-API-Key` headers.
+- 🚦 **Routing**: Directs traffic to Sentinel for inspection.
+- 📊 **Telemetry**: Metric aggregation point.
-**Response Schema** (`ValidateResponse`):
-```json
-{
- "validated_response": "Validated and potentially modified response",
- "validation_passed": true,
- "content_blocked": false,
- "content_block_reason": null,
- "content_warnings": [],
- "output_pii_leaks": [],
- "output_redacted": false,
- "was_toon": false,
- "metrics": {
- "hallucination_detected": false,
- "hallucination_details": null,
- "citations_verified": true,
- "fake_citations": [],
- "tone_compliant": true,
- "tone_violation_reason": null,
- "disclaimer_injected": false,
- "disclaimer_text": null,
- "false_refusal_detected": false,
- "toxicity_score": 0.05,
- "toxicity_details": {
- "insult": 0.01,
- "threat": 0.00,
- "profanity": 0.02
- },
- "warnings_count": 0,
- "pii_leaks_count": 0,
- "moderation_mode": "moderate"
- }
-}
+```mermaid
+graph LR
+ Req[Request] --> Auth{Auth Check?}
+ Auth -- Valid --> Limit{Rate Limit?}
+ Auth -- Invalid --> 401[401 Unauth]
+
+ Limit -- OK --> Sentinel[Route to Sentinel OR EagleEye]
+ Limit -- Exceeded --> 429[429 Too Many Requests]
+
+ style Req fill:#fff,stroke:#000,color:#000
+ style 401 fill:#fbb,stroke:#000,color:#000
+ style 429 fill:#fbb,stroke:#000,color:#000
+ style Sentinel fill:#bfb,stroke:#000,color:#000
```
-**LangGraph Validation Pipeline** (Nodes):
-
-1. **Content Filter Node** (`content_filter.py`)
- - **Moderation Modes**:
- - `strict`: Block anything above 0.5 toxicity
- - `moderate`: Block above 0.7, warn 0.5-0.7
- - `relaxed`: Block above 0.8, warn 0.6-0.8
- - `raw`: No filtering
- - **Detection Categories**: toxicity, insult, threat, profanity, sexual content
+### 2. Eagle-Eye (IAM)
+**Identity & Access Management**
-2. **Hallucination Detector Node** (`hallucination_detector.py`)
- - Compare response claims against original query context
- - LLM-based fact verification
- - Confidence scoring
- - Citation extraction
+Manages the hierarchical relationship between **Users**, **Applications**, and **API Keys**. Use this service to generate keys for your clients.
-3. **Citation Verifier Node** (`citation_verifier.py`)
- - Extract all citations/sources from response
- - Verify URL validity
- - Check for fabricated references
- - Flag "hallucinated citations"
+**Key Features:**
+- 🔐 **Argon2 Hashing**: Secure API key storage.
+- 🏢 **Multi-Tenancy**: Users can own multiple Apps; Apps have multiple Keys.
+- 🎫 **JWT Auth**: Bearer token authentication for management APIs.
-4. **Tone Checker Node** (`tone_checker.py`)
- - Brand voice consistency
- - Professional/casual tone detection
- - Inappropriate tone flagging
- - Sentiment analysis
+### 3. Sentinel (Input Security)
+**The "Security Agent" - Proactive Threat Defense**
-5. **Refusal Detector Node** (`refusal_detector.py`)
- - Detect false refusals ("I cannot answer...")
- - Distinguish legitimate vs. unnecessary refusals
- - Context-aware analysis
+Sentinel analyzes incoming prompts *before* they reach the LLM. It focuses on **Input Sanitization** and **Threat Detection**.
-6. **PII Scanner Node** (`pii_scanner.py`)
- - Scan for leaked PII in output
- - Same patterns as Sentinel PII detection
- - Double-check for data leakage
-
-7. **Disclaimer Injector Node** (`disclaimer_injector.py`)
- - Add required disclaimers (medical, legal, financial)
- - Context-aware disclaimer selection
- - Seamless text integration
-
-8. **TOON Decoder Node** (`toon_decoder.py`)
- - Decode TOON-encoded responses
- - Convert to JSON or plain text
- - Preserve structure integrity
-
-**Moderation Thresholds**:
-```python
-THRESHOLDS = {
- "strict": {
- "harmful_content": 0.5,
- "inappropriate_content": 0.4
- },
- "moderate": {
- "harmful_content": 0.7,
- "inappropriate_content": 0.6
- },
- "relaxed": {
- "harmful_content": 0.8,
- "inappropriate_content": 0.7
- }
-}
-```
+**Key Features:**
+- 🧹 **Sanitization**: Strips dangerous HTML, optimizes Unicode.
+- 🕵️ **PII Redaction**: Detects & masks SSNs, Emails, Phones, Credit Cards.
+- 🛡️ **Threat Detection**: Blocks SQL Injection, XSS, Command Injection, and Jailbreak attempts.
+- 🎭 **TOON Conversion**: Threat-Obfuscated Object Notation for safe processing.
+- ⏭️ **LLM Forwarding**: Intelligent routing to allow or block LLM access based on threat level.
+- 🎼 **Orchestration**: Manages the LLM interaction and optionally delegates to Guardian.
-**Configuration** (Environment):
-```bash
-DEFAULT_MODERATION_MODE=moderate
-HARMFUL_CONTENT_THRESHOLD=0.7
-INAPPROPRIATE_CONTENT_THRESHOLD=0.6
-OUTPUT_PII_DETECTION_ENABLED=false # Opt-in per request
-AUTO_CONVERT_TOON_TO_JSON=false
-GEMINI_API_KEY=
+```mermaid
+graph TD
+ Input --> Sanitize[Sanitization]
+ Sanitize --> PII[PII Redaction]
+ PII --> Threats[Thread Detection]
+
+ Threats -- Attack Detected --> Block[🚫 Block Request]
+ Threats -- Safe --> LLM[LLM Processing]
+
+ style Block fill:#fbb,stroke:#000,color:#000
+ style LLM fill:#bfb,stroke:#000,color:#000
```
----
-
-### 5. Supporting Services
+### 4. Guardian (Output Validation)
+**The "Quality Agent" - Reactive Response Validation**
-#### PostgreSQL Database (Port 5432)
-- **Version**: PostgreSQL 15 Alpine
-- **Schema Management**: Auto-created by Eagle-Eye on startup
-- **Tables**: `users`, `applications`, `api_keys`
-- **Features**: UUID primary keys, timestamps, foreign key constraints
-- **Health Check**: `pg_isready` command
+Guardian analyzes the LLM's response before it is returned to the user. It ensures the AI is helpful, harmless, and honest.
-#### Redis Cache (Port 6379)
-- **Version**: Redis 7 Alpine
-- **Usage**: Rate limiting, token counters, violation tracking
-- **Persistence**: RDB snapshots to `/data` volume
-- **Features**: TTL-based expiration, atomic increments
-- **Health Check**: `redis-cli ping`
-
-#### Datadog Agent (Ports 8126, 8125)
-- **Image**: `gcr.io/datadoghq/agent:latest`
-- **Features**:
- - APM (Application Performance Monitoring)
- - DogStatsD metrics collection (Unix socket)
- - Log collection (container auto-discovery)
- - Runtime metrics and profiling
- - Universal Service Monitoring (USM)
-- **Dashboard**: Datadog Cloud (us5.datadoghq.com)
+**Key Features:**
+- 🤥 **Hallucination Detection**: Cross-references claims with knowledge base.
+- ☢️ **Toxicity Check**: Filters hate speech and harmful content.
+- 🏛️ **Tone Analysis**: Ensures brand-compliant response style.
+- 📚 **Citation Verification**: Validates links and references.
+- 🕵️ **PII Leak Detection**: Prevents sensitive data from leaking in LLM responses.
+- 🛑 **False Refusal Detection**: Identifies when the LLM incorrectly refuses a safe prompt.
+- 📝 **Structured Output**: Enforces valid JSON/TOON output formats.
+- ⚠️ **Disclaimer Injection**: Adds necessary warnings or legal disclaimers.
---
-## 🛡️ Security Features
-
-### Multi-Layer Security Architecture
-
-#### Layer 1: Authentication & Authorization
-
-**API Key Security**:
-- **Generation**: 32-byte cryptographically secure random tokens
-- **Storage**: Argon2id hashing (never store plaintext)
-- **Validation**: Constant-time hash comparison
-- **Display**: Only first 4 characters shown in UI
-- **Rotation**: Manual revocation + regeneration
-
-**JWT Authentication**:
-- **Algorithm**: HS256 (HMAC SHA-256)
-- **Expiry**: Configurable (default: 24 hours)
-- **Claims**: User ID, expiration timestamp
-- **Validation**: Signature verification, expiry check
-
-**Access Control**:
-- User-owned applications (FK constraint)
-- Application-scoped API keys
-- Endpoint-level authentication (FastAPI dependencies)
-
-#### Layer 2: Input Security (Sentinel)
-
-**Sanitization**:
-```python
-# HTML Escaping
-bleach.clean(input_text, tags=[], attributes={}, strip=True)
-
-# Unicode Normalization
-unicodedata.normalize('NFKC', text)
-
-# Null Byte Removal
-text.replace('\x00', '')
-```
-
-**PII Redaction**:
-| PII Type | Pattern | Replacement |
-|----------|---------|-------------|
-| SSN | `\d{3}-\d{2}-\d{4}` | `[SSN-REDACTED]` |
-| Email | RFC 5322 validation | `[EMAIL-REDACTED]` |
-| Phone | E.164 parsing | `[PHONE-REDACTED]` |
-| Credit Card | Luhn algorithm | `[CC-REDACTED]` |
-
-**Threat Detection**:
-
-*SQL Injection Patterns*:
-```regex
-UNION\s+SELECT
-INSERT\s+INTO
-DROP\s+TABLE
-DELETE\s+FROM
-exec\s*\(
-```
-
-*XSS Patterns*:
-```regex
-]*>
-javascript:
-on\w+\s*=\s*["']
-eval\(
-```
-
-*Command Injection Patterns*:
-```regex
-;\s*rm\s+-rf
-\|\s*curl
-&&\s*wget
-`.*`
-$(...)
-```
-
-**LLM Security Check**:
-- Prompt injection detection (via Gemini analysis)
-- Jailbreak attempt identification
-- Semantic threat assessment
-- Context-aware scoring
-
-#### Layer 3: Rate Limiting
-
-**Token-Based Limits**:
-- **Quota**: 5,000 tokens per 5 minutes
-- **Window**: Sliding window (Redis TTL)
-- **Violation Tracking**: 2 violations in 20 minutes
-- **Penalty**: Automatic API key suspension
-
-**Implementation**:
-```python
-# Pre-flight check
-await rate_limiter.check_current_usage(
- f"rate:tokens:{key_id}",
- limit=5000
-)
-
-# Post-request increment
-await rate_limiter.increment_and_check(
- f"rate:tokens:{key_id}",
- amount=total_tokens,
- limit=5000,
- window=300
-)
-
-# Violation recording
-violations = await rate_limiter.record_violation(
- f"rate:violations:{key_id}",
- window=1200
-)
-if violations >= 2:
- api_key.is_active = False
-```
-
-**Graceful Degradation**:
-- Redis failure → Allow traffic (fail-open)
-- Prevents outages due to cache issues
-
-#### Layer 4: Output Validation (Guardian)
+## 🚀 Quick Start
-**Content Filtering**:
-- Toxicity scoring (0.0-1.0)
-- Harmful content detection
-- Inappropriate content blocking
-- Mode-based thresholds
+### Prerequisites
+- Docker & Docker Compose
+- Google Gemini API Key
+- Datadog API Key
-**Hallucination Detection**:
-- Claim extraction from response
-- Fact verification against context
-- Confidence scoring
-- Automated blocking/warning
+### Run Locally
-**Citation Verification**:
-- Extract all source references
-- URL validation
-- Check for fabricated citations
-- Flag "hallucination citations"
+1. **Clone & Configure**
+ ```bash
+ git clone https://github.com/your-org/ClestiqShield-AgentCore.git
+ cd ClestiqShield-AgentCore
+
+ # Create .env from .env.example
+ cp .env.example .env
+
+ # ⚠️ IMPORTANT: Configure Datadog for Full Observability
+ # Edit .env and add your Keys
+ ```
-**Tone Compliance**:
-- Brand voice consistency check
-- Professional/casual tone detection
-- Sentiment analysis
-- Inappropriate tone flagging
+2. **Start Services**
+ ```bash
+ docker-compose up --build -d
+ ```
-**PII Leak Prevention**:
-- Output scanning for leaked PII
-- Same regex patterns as input
-- Automated redaction
-- Audit logging
+3. **Verify**
+ ```bash
+ curl http://localhost:8000/health
+ ```
---
-## 📚 API Reference
-
-### Gateway API
-
-#### POST /chat
-
-**Description**: Main chat endpoint with multi-layer security processing
-
-**Authentication**: Required (`X-API-Key` header)
-
-**Headers**:
-```http
-X-API-Key: cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-Content-Type: application/json
-```
-
-**Request Body**:
-```json
-{
- "query": "What is machine learning?",
- "system_prompt": "You are an expert AI tutor",
- "model": "gemini-3-flash-preview",
- "moderation": "moderate",
- "output_format": "json",
- "max_output_tokens": 4096,
- "settings": {
- "pii_masking": true,
- "sanitize_input": true,
- "detect_threats": true,
- "content_filter": true,
- "hallucination_check": true,
- "citation_check": false,
- "tone_check": true,
- "toon_mode": false,
- "enable_llm_forward": true
- }
-}
-```
-
-**Response** (200 OK):
-```json
-{
- "response": "Machine learning is a subset of artificial intelligence...",
- "app": "my-awesome-app",
- "metrics": {
- "security_score": 0.98,
- "tokens_saved": 0,
- "token_usage": {
- "input_tokens": 125,
- "output_tokens": 387,
- "total_tokens": 512
- },
- "model_used": "gemini-3-flash-preview",
- "threats_detected": 0,
- "pii_redacted": 0,
- "processing_time_ms": 2345.67,
- "hallucination_detected": false,
- "citations_verified": null,
- "tone_compliant": true,
- "disclaimer_injected": false,
- "false_refusal_detected": false,
- "toxicity_score": 0.01
- }
-}
-```
-
-**Response Headers**:
-```http
-X-Security-Score: 0.980
-X-Security-Decision: passed
-```
-
-**Error Responses**:
+## 📊 Observability (Datadog)
-*401 Unauthorized*:
-```json
-{
- "detail": "Invalid API Key"
-}
-```
+All services are fully instrumented with **Datadog**.
-*429 Too Many Requests*:
-```json
-{
- "detail": "Token rate limit exceeded (5000 tokens / 5 mins)"
-}
-```
+- **APM**: Distributed tracing across all 4 microservices.
+- **Metrics**:
+ - `clestiq.gateway.requests`
+ - `clestiq.sentinel.threats_detected`
+ - `clestiq.guardian.hallucinations`
+- **Logs**: Structured JSON logging.
-*400 Bad Request* (Blocked):
-```json
-{
- "detail": {
- "error": "Request blocked",
- "reason": "SQL injection detected in input"
- }
-}
+```mermaid
+graph LR
+ Svcs[Microservices] -- Traces --> DD[Datadog Agent]
+ Svcs -- Metrics (DogStatsD) --> DD
+ Svcs -- Logs --> DD
+ K8s[Kube DaemonSet] -- Infra Stats / Profiling --> DD
+
+ style DD fill:#ff9,stroke:#000,stroke-width:2px,color:#000
+ style K8s fill:#eee,stroke:#000,color:#000
```
-
----
-
-### Eagle-Eye API
-
-#### POST /api/v1/auth/register
-
-**Description**: Register a new user account
-
-**Request**:
-```json
-{
- "email": "user@example.com",
- "password": "SecurePassword123!"
-}
-```
-
-**Response** (200 OK):
-```json
-{
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "email": "user@example.com",
- "full_name": null,
- "is_active": true,
- "created_at": "2025-12-29T12:00:00Z"
-}
-```
-
----
-
-#### POST /api/v1/auth/login
-
-**Description**: Authenticate user and receive JWT token
-
-**Request** (form-urlencoded):
-```
-username=user@example.com&password=SecurePassword123!
-```
-
-**Response** (200 OK):
-```json
-{
- "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
- "token_type": "bearer",
- "user": {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "email": "user@example.com",
- "full_name": null,
- "is_active": true
- }
-}
-```
-
----
-
-#### POST /api/v1/apps/
-
-**Description**: Create a new application
-
-**Authentication**: Required (JWT Bearer token)
-
-**Request**:
-```json
-{
- "name": "my-awesome-app",
- "description": "Production chatbot for customer support"
-}
-```
-
-**Response** (200 OK):
-```json
-{
- "id": "660e8400-e29b-41d4-a716-446655440001",
- "name": "my-awesome-app",
- "description": "Production chatbot for customer support",
- "created_at": "2025-12-29T12:05:00Z",
- "updated_at": null
-}
-```
-
----
-
-#### POST /api/v1/apps/{app_id}/keys
-
-**Description**: Generate a new API key for an application
-
-**Authentication**: Required (JWT Bearer token)
-
-**Request**:
-```json
-{
- "name": "Production Key"
-}
-```
-
-**Response** (200 OK):
-```json
-{
- "id": "770e8400-e29b-41d4-a716-446655440002",
- "key_prefix": "cs_4",
- "name": "Production Key",
- "created_at": "2025-12-29T12:10:00Z",
- "last_used_at": null,
- "is_active": true,
- "api_key": "cs_4x7K9mLp2qR8vTn3wYz5aB6cD1eF0gH8iJ4kL7mN9pQ2rS5tU8vW1xY3z"
-}
-```
-
-**⚠️ IMPORTANT**: The `api_key` field is only shown once. Store it securely.
-
----
-
-### Sentinel API
-
-#### POST /chat
-
-**Description**: Process chat request with input security and LLM generation
-
-**Request**: See [ChatRequest schema](#request-schema-chatrequest)
-
-**Response**: See [ChatResponse schema](#response-schema-chatresponse)
-
----
-
-### Guardian API
-
-#### POST /validate
-
-**Description**: Validate LLM-generated response for safety and quality
-
-**Request**: See [ValidateRequest schema](#request-schema-validaterequest)
-
-**Response**: See [ValidateResponse schema](#response-schema-validateresponse)
-
----
-
-## 💾 Data Models
-
-### Entity-Relationship Diagram
-
-```mermaid
-erDiagram
- User ||--o{ Application : owns
- Application ||--o{ ApiKey : has
-
- User {
- uuid id PK
- string email UK
- string hashed_password
- string full_name
- boolean is_active
- datetime created_at
- }
-
- Application {
- uuid id PK
- string name UK
- string description
- uuid owner_id FK
- datetime created_at
- datetime updated_at
- }
-
- ApiKey {
- uuid id PK
- string key_hash
- string key_prefix
- string name
- uuid application_id FK
- boolean is_active
- datetime created_at
- datetime last_used_at
- int request_count
- json usage_data
- }
-```
-
-### Database Schema
-
-**Users Table**:
-```sql
-CREATE TABLE users (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- email VARCHAR UNIQUE NOT NULL,
- hashed_password VARCHAR NOT NULL,
- full_name VARCHAR,
- is_active BOOLEAN DEFAULT TRUE,
- created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
-CREATE INDEX idx_users_email ON users(email);
-```
-
-**Applications Table**:
-```sql
-CREATE TABLE applications (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- name VARCHAR UNIQUE NOT NULL,
- description VARCHAR,
- owner_id UUID NOT NULL REFERENCES users(id),
- created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
- updated_at TIMESTAMP WITH TIME ZONE
-);
-
-CREATE INDEX idx_applications_name ON applications(name);
-CREATE INDEX idx_applications_owner ON applications(owner_id);
-```
-
-**API Keys Table**:
-```sql
-CREATE TABLE api_keys (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- key_hash VARCHAR NOT NULL,
- key_prefix VARCHAR NOT NULL,
- name VARCHAR,
- application_id UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
- is_active BOOLEAN DEFAULT TRUE,
- created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
- expires_at TIMESTAMP WITH TIME ZONE,
- last_used_at TIMESTAMP WITH TIME ZONE,
- request_count INTEGER DEFAULT 0,
- usage_data JSON DEFAULT '{}'
-);
-
-CREATE INDEX idx_api_keys_hash ON api_keys(key_hash);
-CREATE INDEX idx_api_keys_app ON api_keys(application_id);
-```
-
----
-
-## ⏱️ Rate Limiting & Quotas
-
-### Rate Limiting Strategy
-
-**Token-Based Rate Limiting**:
-- **Metric**: Total tokens (input + output)
-- **Limit**: 5,000 tokens per API key
-- **Window**: 5 minutes (300 seconds)
-- **Implementation**: Redis sliding window with TTL
-
-**Violation Tracking**:
-- **Threshold**: 2 violations
-- **Window**: 20 minutes (1200 seconds)
-- **Penalty**: Automatic API key suspension (`is_active = false`)
-
-### Redis Key Schema
-
-```
-rate:tokens:{api_key_id} # Current token usage (TTL: 300s)
-rate:violations:{api_key_id} # Violation count (TTL: 1200s)
-```
-
-### Rate Limit Flow
-
-```mermaid
-stateDiagram-v2
- [*] --> CheckUsage
- CheckUsage --> WithinLimit: usage < 5000
- CheckUsage --> ExceededLimit: usage >= 5000
-
- ExceededLimit --> RecordViolation
- RecordViolation --> CheckViolations
-
- CheckViolations --> SuspendKey: violations >= 2
- CheckViolations --> RejectRequest: violations < 2
-
- SuspendKey --> Return403
- RejectRequest --> Return429
-
- WithinLimit --> ProcessRequest
- ProcessRequest --> IncrementUsage
- IncrementUsage --> Return200
-
- Return403 --> [*]
- Return429 --> [*]
- Return200 --> [*]
-```
-
-### Usage Tracking
-
-**Per-Request**:
-```python
-# Update token usage
-api_key.request_count += 1
-api_key.last_used_at = now()
-
-# Update per-model usage stats
-api_key.usage_data = {
- "gemini-3-flash-preview": {
- "input_tokens": 12450,
- "output_tokens": 34870
- },
- "gemini-2.5-pro": {
- "input_tokens": 5600,
- "output_tokens": 8900
- }
-}
-```
-
-### Future: Tier-Based Rate Limiting
-
-**Planned Tiers** (not yet implemented):
-
-| Tier | Requests/Min | Tokens/Hour | Price/Month |
-|------|--------------|-------------|-------------|
-| Free | 10 | 50,000 | $0 |
-| Starter | 100 | 500,000 | $29 |
-| Professional | 1,000 | 5,000,000 | $199 |
-| Enterprise | Unlimited | Unlimited | Custom |
-
-**Implementation Plan**:
-1. Add `tier` column to `applications` table
-2. Configure tier-specific Redis limits
-3. Add metering and billing logic
-4. Implement usage dashboards
-
----
-
-## 📊 Observability & Monitoring
-
-### Datadog Integration
-
-**Instrumentation**:
-- **APM**: `ddtrace` library auto-instrumentation
-- **Metrics**: DogStatsD client (Unix socket)
-- **Logs**: Container log collection with JSON parsing
-- **Profiling**: Continuous profiling enabled
-- **Runtime Metrics**: Python runtime stats
-
-**Configuration** (per service):
-```bash
-DD_ENV=production
-DD_SERVICE=clestiq-shield-gateway
-DD_VERSION=1.0.0
-DD_AGENT_HOST=datadog-agent
-DD_TRACE_AGENT_PORT=8126
-DD_DOGSTATSD_SOCKET=/var/run/datadog/dsd.socket
-DD_LOGS_INJECTION=true
-DD_PROFILING_ENABLED=true
-DD_RUNTIME_METRICS_ENABLED=true
-```
-
-### Custom Metrics
-
-**Gateway Metrics**:
-```python
-# Request counts
-clestiq.gateway.requests
- tags: app:, model:, status:, reason:
-
-# Latency
-clestiq.gateway.latency (histogram)
- tags: app:, model:
-
-# Security score
-clestiq.gateway.security_score (gauge)
- tags: app:
-
-# Token usage
-clestiq.gateway.tokens (count)
- tags: app:, model:, type:
-
-# Tokens saved (efficiency)
-clestiq.gateway.tokens_saved (count)
- tags: app:, model:
-
-# Threats detected
-clestiq.gateway.threats (count)
- tags: app:, model:
-
-# PII redactions
-clestiq.gateway.pii_redacted (count)
- tags: app:
-
-# API key suspensions
-clestiq.gateway.keys_disabled (count)
- tags: app:
-```
-
-**Guardian Metrics**:
-```python
-# Hallucination detection
-clestiq.guardian.hallucination (count)
- tags: app:, model:
-
-# Toxicity score
-clestiq.guardian.toxicity (gauge)
- tags: app:
-```
-
-**Eagle-Eye Metrics**:
-```python
-# User registrations
-clestiq.eagleeye.users.created (count)
-
-# App lifecycle
-clestiq.eagleeye.apps.created (count)
-clestiq.eagleeye.apps.deleted (count)
-
-# API key lifecycle
-clestiq.eagleeye.api_keys.created (count)
- tags: app:, user:
-
-clestiq.eagleeye.api_keys.revoked (count)
- tags: app:, user:
-```
-
-### Distributed Tracing
-
-**Trace Attributes**:
-```python
-# Gateway traces
-span.set_attribute("app.name", app_name)
-span.set_attribute("app.id", app_id)
-span.set_attribute("llm.model", model)
-span.set_attribute("security.score", security_score)
-span.set_attribute("security.blocked", is_blocked)
-```
-
-**Service Map**:
-```
-Client → Gateway → Sentinel → [Gemini API, Guardian] → Response
-```
-
-### Structured Logging
-
-**Format**: JSON with Datadog log injection
-
-**Example**:
-```json
-{
- "timestamp": "2025-12-29T12:43:15Z",
- "level": "info",
- "logger": "clestiq.gateway",
- "message": "Request passed Sentinel check",
- "app_name": "my-awesome-app",
- "app_id": "660e8400-e29b-41d4-a716-446655440001",
- "model": "gemini-3-flash-preview",
- "security_score": 0.98,
- "dd.service": "clestiq-shield-gateway",
- "dd.trace_id": "1234567890123456789",
- "dd.span_id": "9876543210987654321"
-}
-```
-
-### Health Checks
-
-**All Services**:
-- **Endpoint**: `GET /health`
-- **Interval**: 30 seconds
-- **Timeout**: 10 seconds
-- **Retries**: 3
-- **Start Period**: 40 seconds
-
-**Database**:
-- **Command**: `pg_isready -U user -d clestiq_shield`
-- **Interval**: 10 seconds
-
-**Redis**:
-- **Command**: `redis-cli ping`
-- **Interval**: 10 seconds
-
----
-
-## 🔧 Technology Stack
-
-### Core Framework
-- **FastAPI** 0.109+ - Modern async web framework
- - OpenAPI auto-documentation
- - Pydantic validation
- - Dependency injection
- - WebSocket support
-
-### Language & Runtime
-- **Python** 3.11+ - Type hints, performance improvements
-- **Uvicorn** 0.27+ - ASGI server with auto-reload
-
-### LLM & AI
-- **Google Gemini AI** - LLM provider
- - `gemini-3-flash-preview` - Fast inference
- - `gemini-2.5-pro` - Advanced reasoning
-- **LangChain** 1.2+ - LLM orchestration framework
-- **LangGraph** 1.0+ - Multi-agent workflow graphs
-
-### Database & Cache
-- **PostgreSQL** 15+ - Primary database
- - UUID support
- - JSON columns
- - Async driver (asyncpg)
-- **Redis** 7+ - Rate limiting and caching
- - Async driver (redis-py)
- - TTL-based expiration
-
-### ORM & Data
-- **SQLAlchemy** 2.0+ - Async ORM
- - Declarative models
- - Alembic migrations (dev)
-- **Pydantic** 2.0+ - Data validation
- - Settings management
- - Schema definitions
-
-### Security
-- **Argon2-CFFI** - Password hashing
-- **python-jose** - JWT encoding/decoding
-- **bleach** - HTML sanitization
-- **email-validator** - Email validation
-- **phonenumbers** - Phone number parsing
-
-### Observability
-- **Datadog** (`ddtrace`) - APM and metrics
-- **structlog** - Structured logging
-- **OpenTelemetry** - Distributed tracing
-
-### HTTP Client
-- **httpx** 0.27+ - Async HTTP client
- - Service-to-service communication
-
-### Infrastructure
-- **Docker** - Containerization
-- **Docker Compose** - Local orchestration
-- **Poetry** - Dependency management
-
----
-
-## 🚀 Deployment
-
-### Docker Compose (Local Development)
-
-**Prerequisites**:
-- Docker 20.10+
-- Docker Compose 2.0+
-- 4GB+ RAM available
-
-**Environment Setup**:
-
-1. **Clone Repository**:
-```bash
-cd ClestiqShield-AgentCore
-```
-
-2. **Configure Environment**:
-```bash
-# Edit .env file
-GEMINI_API_KEY=your_gemini_api_key_here
-DD_API_KEY=your_datadog_api_key_here
-DD_SITE=us5.datadoghq.com
-
-DATABASE_URL=postgresql+asyncpg://user:password@db:5432/clestiq_shield
-```
-
-3. **Start Services**:
-```bash
-docker-compose up --build
-```
-
-4. **Verify Health**:
-```bash
-# Gateway
-curl http://localhost:8000/health
-
-# Eagle-Eye
-curl http://localhost:8003/health
-
-# Sentinel
-curl http://localhost:8001/health
-
-# Guardian
-curl http://localhost:8002/health
-```
-
-### Production Deployment (Kubernetes)
-
-**Manifests** (in Terraform repository):
-- `gateway.yaml` - Gateway deployment + service + ingress
-- `eagle-eye.yaml` - Eagle-Eye deployment + service
-- `sentinel.yaml` - Sentinel deployment + service
-- `guardian.yaml` - Guardian deployment + service
-- `redis.yaml` - Redis StatefulSet + service
-- `postgres.yaml` - PostgreSQL StatefulSet + PVC
-
-**Secrets**:
-```bash
-kubectl create secret generic gemini-secrets \
- --from-literal=GEMINI_API_KEY=
-
-kubectl create secret generic db-secrets \
- --from-literal=DATABASE_URL=
-
-kubectl create secret generic jwt-secrets \
- --from-literal=SECRET_KEY=
-```
-
-**Datadog Integration**:
-```bash
-kubectl create secret generic datadog-secrets \
- --from-literal=DD_API_KEY=
-
-# Deploy Datadog Agent as DaemonSet
-kubectl apply -f datadog-agent.yaml
-```
-
-**Deploy**:
-```bash
-kubectl apply -f k8s/
-```
-
----
-
-## ⚙️ Configuration
-
-### Gateway Configuration
-
-**Environment Variables**:
-```bash
-# Database
-DATABASE_URL=postgresql+asyncpg://user:password@db:5432/clestiq_shield
-
-# Redis
-REDIS_URL=redis://redis:6379/0
-
-# Service Discovery
-SENTINEL_SERVICE_URL=http://sentinel:8001
-
-# Security
-SECRET_KEY=your_strong_secret_key_here
-ALGORITHM=HS256
-
-# Datadog
-DD_ENV=production
-DD_SERVICE=clestiq-shield-gateway
-DD_VERSION=1.0.0
-DD_AGENT_HOST=datadog-agent
-DD_DOGSTATSD_SOCKET=/var/run/datadog/dsd.socket
-DD_LOGS_INJECTION=true
-DD_PROFILING_ENABLED=true
-```
-
-### Sentinel Configuration
-
-**Security Flags** (opt-in per request):
-```bash
-SECURITY_SANITIZATION_ENABLED=false
-SECURITY_PII_REDACTION_ENABLED=false
-SECURITY_XSS_PROTECTION_ENABLED=false
-SECURITY_SQL_INJECTION_DETECTION_ENABLED=false
-SECURITY_COMMAND_INJECTION_DETECTION_ENABLED=false
-TOON_CONVERSION_ENABLED=false
-LLM_FORWARD_ENABLED=false
-```
-
-**LLM Settings**:
-```bash
-GEMINI_API_KEY=your_gemini_api_key
-LLM_MODEL_NAME=gemini-3-flash-preview
-LLM_MAX_TOKENS=8192
-GUARDIAN_SERVICE_URL=http://guardian:8002
-```
-
-### Guardian Configuration
-
-**Moderation Settings**:
-```bash
-DEFAULT_MODERATION_MODE=moderate
-HARMFUL_CONTENT_THRESHOLD=0.7
-INAPPROPRIATE_CONTENT_THRESHOLD=0.6
-```
-
-**Feature Flags**:
-```bash
-OUTPUT_PII_DETECTION_ENABLED=false
-AUTO_CONVERT_TOON_TO_JSON=false
-```
-
-### Eagle-Eye Configuration
-
-```bash
-DATABASE_URL=postgresql+asyncpg://user:password@db:5432/clestiq_shield
-SECRET_KEY=your_jwt_secret_key
-ALGORITHM=HS256
-```
-
----
-
-## 👨💻 Development Guide
-
-### Local Development Setup
-
-**Prerequisites**:
-- Python 3.11+
-- Poetry 1.7+
-- PostgreSQL 15+
-- Redis 7+
-
-**Install Dependencies** (per service):
-```bash
-cd services/gateway
-poetry install
-
-cd ../eagle-eye
-poetry install
-
-cd ../security-agent
-poetry install
-
-cd ../guardian
-poetry install
-```
-
-**Run Services Individually**:
-
-*Gateway*:
-```bash
-cd services/gateway
-poetry run uvicorn app.main:app --reload --port 8000
-```
-
-*Eagle-Eye*:
-```bash
-cd services/eagle-eye
-poetry run uvicorn app.main:app --reload --port 8003
-```
-
-*Sentinel*:
-```bash
-cd services/security-agent
-poetry run uvicorn app.main:app --reload --port 8001
-```
-
-*Guardian*:
-```bash
-cd services/guardian
-poetry run uvicorn app.main:app --reload --port 8002
-```
-
-### Testing
-
-**Unit Tests** (per service):
-```bash
-cd services/gateway
-poetry run pytest tests/ -v --cov=app
-
-cd services/security-agent
-poetry run pytest tests/ -v --cov=app
-```
-
-**Integration Testing**:
-```bash
-# Start all services
-docker-compose up -d
-
-# Run integration tests
-poetry run pytest tests/integration/
-
-# Or manual testing
-curl -X POST http://localhost:8000/chat \
- -H "X-API-Key: " \
- -H "Content-Type: application/json" \
- -d '{
- "query": "Test prompt",
- "model": "gemini-3-flash-preview",
- "settings": {
- "sanitize_input": true,
- "detect_threats": true,
- "content_filter": true
- }
- }'
-```
-
-### Code Style
-
-**Formatting**:
-```bash
-# Black (code formatter)
-poetry run black app/
-
-# isort (import sorting)
-poetry run isort app/
-```
-
-**Linting**:
-```bash
-# Flake8
-poetry run flake8 app/
-
-# mypy (type checking)
-poetry run mypy app/
-```
-
-### Database Migrations (Eagle-Eye)
-
-```bash
-cd services/eagle-eye
-
-# Create migration
-poetry run alembic revision --autogenerate -m "Add new column"
-
-# Apply migration
-poetry run alembic upgrade head
-
-# Rollback
-poetry run alembic downgrade -1
-```
-
----
-
-## 📖 Additional Resources
-
-### Documentation
-- **API Docs (Swagger)**: http://localhost:8000/docs
-- **Alternative Docs (ReDoc)**: http://localhost:8000/redoc
-- **Eagle-Eye Docs**: http://localhost:8003/docs
-
-### External Documentation
-- [FastAPI Documentation](https://fastapi.tiangolo.com/)
-- [LangGraph Guide](https://langchain-ai.github.io/langgraph/)
-- [Google Gemini API](https://ai.google.dev/docs)
-- [Datadog APM](https://docs.datadoghq.com/tracing/)
-
-### Repository Structure
-```
-ClestiqShield-AgentCore/
-├── services/
-│ ├── gateway/ # API Gateway
-│ │ ├── app/
-│ │ │ ├── api/ # API endpoints
-│ │ │ ├── core/ # Config, DB, telemetry
-│ │ │ ├── models/ # SQLAlchemy models
-│ │ │ ├── schemas/ # Pydantic schemas
-│ │ │ └── main.py
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ ├── eagle-eye/ # Auth & IAM
-│ │ ├── app/
-│ │ │ ├── api/v1/endpoints/ # Auth, users, apps, keys
-│ │ │ ├── core/
-│ │ │ ├── models/
-│ │ │ └── main.py
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ ├── security-agent/ # Sentinel (Input Security)
-│ │ ├── app/
-│ │ │ ├── agents/
-│ │ │ │ ├── nodes/ # LangGraph nodes
-│ │ │ │ ├── graph.py
-│ │ │ │ └── state.py
-│ │ │ ├── core/
-│ │ │ ├── schemas/
-│ │ │ └── main.py
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ └── guardian/ # Output Validation
-│ ├── app/
-│ │ ├── agents/
-│ │ │ ├── nodes/ # Validation nodes
-│ │ │ ├── graph.py
-│ │ │ └── state.py
-│ │ ├── core/
-│ │ ├── schemas/
-│ │ └── main.py
-│ ├── Dockerfile
-│ └── pyproject.toml
-├── docker-compose.yml # Local orchestration
-├── .env # Environment variables
-├── LICENSE
-└── README.md
-```
-
----
-
-## 🎯 Key Metrics & Performance
-
-### Typical Performance Benchmarks
-
-**Latency** (end-to-end):
-- **Minimal Security** (sanitization only): ~500-800ms
-- **Standard Security** (threats + PII): ~1,200-2,000ms
-- **Full Validation** (all features): ~3,000-5,000ms
-
-**Throughput**:
-- **Gateway**: ~500 req/sec (per instance)
-- **Sentinel**: ~200 req/sec (LLM-limited)
-- **Guardian**: ~300 req/sec (validation-heavy)
-
-**Resource Usage** (per service):
-- **CPU**: 0.5-1.0 cores (idle), 2-4 cores (load)
-- **Memory**: 512MB-1GB (typical), 2GB (peak)
-
-### Scaling Recommendations
-
-**Horizontal Scaling**:
-- Gateway: 3+ replicas (load balancer)
-- Sentinel: 2-3 replicas (LLM bottleneck)
-- Guardian: 2-3 replicas
-- Eagle-Eye: 2 replicas (auth latency)
-
-**Database**:
-- PostgreSQL: Read replicas for high traffic
-- Redis: Redis Cluster for distributed rate limiting
-
-**Cost Optimization**:
-- Use `gemini-3-flash-preview` for most requests (cheaper)
-- Enable caching for repeated queries
-- Batch security checks where possible
-
----
-
-## 📝 License
-
-MIT License - See [LICENSE](LICENSE) file for details
-
-Copyright (c) 2025 Clestiq Shield
-
----
-
-## 🙏 Acknowledgments
-
-**Technologies**:
-- FastAPI team for the excellent async framework
-- LangChain community for agent orchestration tools
-- Google for Gemini AI API
-- Datadog for observability platform
-
-**Contributors**:
-- Architecture design and implementation
-- Security research and threat modeling
-- Performance optimization and testing
-
----
-
-## 📞 Support & Contact
-
-**Issues**: Please report bugs and feature requests via GitHub Issues
-
-**Security Vulnerabilities**: Report privately to security@clestiq.com
-
-**Documentation**: Full API documentation at `/docs` on each service
-
----
-
-**Built with ❤️ for secure, production-ready LLM applications**
diff --git a/services/eagle-eye/app/api/v1/endpoints/users.py b/services/eagle-eye/app/api/v1/endpoints/users.py
index dbb2165..f6db15a 100644
--- a/services/eagle-eye/app/api/v1/endpoints/users.py
+++ b/services/eagle-eye/app/api/v1/endpoints/users.py
@@ -43,9 +43,10 @@ async def get_user(
db: AsyncSession = Depends(get_db),
):
result = await db.execute(select(User).where(User.id == current_user_id))
- if not result.scalars().first():
+ user = result.scalars().first()
+ if not user:
raise HTTPException(status_code=404, detail="User not found")
- return result.scalars().first()
+ return user
@router.delete("/account-closure", status_code=status.HTTP_204_NO_CONTENT)
diff --git a/services/eagle-eye/app/schemas/__init__.py b/services/eagle-eye/app/schemas/__init__.py
index acc47cb..41a0c6c 100644
--- a/services/eagle-eye/app/schemas/__init__.py
+++ b/services/eagle-eye/app/schemas/__init__.py
@@ -21,7 +21,7 @@ class UserUpdate(BaseModel):
class UserResponse(UserBase):
id: UUID
full_name: Optional[str] = None
- is_active: bool
+ is_active: bool = True
created_at: datetime
class Config:
@@ -64,6 +64,8 @@ class ApiKeyResponse(BaseModel):
created_at: datetime
last_used_at: Optional[datetime] = None
is_active: bool
+ request_count: int = 0
+ usage_data: Optional[dict] = None
class Config:
from_attributes = True