Automated deployment update

.dockerignore

@@ -0,0 +1,38 @@
+# Version Control
+.git
+.gitignore
+.github
+
+# Dependencies
+**/node_modules
+**/vendor
+
+# Build Artifacts
+**/bin
+**/dist
+**/.next
+**/out
+*.exe
+*.test
+*.prof
+
+# IDEs
+.vscode
+.idea
+*.swp
+*.swo
+
+# Environment Variables
+.env
+.env.*
+!.env.example
+
+# OS Files
+.DS_Store
+Thumbs.db
+
+# Large Documentation/Assets
+docs/
+tests/integration
+frontend/packages/*/dist
+frontend/apps/*/dist

.env.example

@@ -0,0 +1,118 @@
+# AmaniQuery Consolidated Environment Variables Example
+# Copy this file to .env and adjust the values as needed.
+
+# =============================================================================
+# General Configuration
+# =============================================================================
+ENV=development
+LOG_LEVEL=info
+VERSION=1.0.0
+
+# =============================================================================
+# Server Configuration
+# =============================================================================
+# Main Service
+AMANI_SERVER_GRPC_PORT=9090
+AMANI_SERVER_HTTP_PORT=8080
+AMANI_SERVER_GRACEFUL_TIMEOUT=30s
+AMANI_SERVER_MAX_CONNECTIONS=1000
+
+# Notification Service
+PORT=:8080
+NOTIF_SERVER_READ_TIMEOUT=30s
+NOTIF_SERVER_WRITE_TIMEOUT=30s
+NOTIF_SERVER_SHUTDOWN_TIMEOUT=30s
+
+# =============================================================================
+# LLM Providers (Main Service)
+# =============================================================================
+# Fallback order: Gemini -> Moonshot -> Ollama -> OpenAI -> Anthropic
+GEMINI_API_KEY=your-gemini-api-key
+GOOGLE_API_KEY=your-gemini-api-key # Alias for GEMINI_API_KEY
+
+MOONSHOT_API_KEY=your-moonshot-api-key
+
+OLLAMA_BASE_URL=http://localhost:11434
+
+OPENAI_API_KEY=your-openai-api-key
+
+ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# LLM Settings
+AMANI_LLM_DEFAULT_MODEL=gemini-2.5-flash
+AMANI_LLM_MAX_TOKENS=4096
+AMANI_LLM_TEMPERATURE=0.7
+AMANI_LLM_TIMEOUT=60s
+AMANI_LLM_MAX_RETRIES=3
+AMANI_LLM_ENABLE_FALLBACK=true
+
+# =============================================================================
+# Vector Store (Qdrant)
+# =============================================================================
+QDRANT_URL=localhost:6334
+QDRANT_API_KEY=your_qdrant_api_key_here
+AMANI_VECTOR_STORE_COLLECTION=amaniquery
+AMANI_VECTOR_STORE_DIMENSION=1536
+AMANI_VECTOR_STORE_DISTANCE=Cosine
+
+# =============================================================================
+# Caching & Queue (Redis)
+# =============================================================================
+# Used by both Main and Notification services
+REDIS_URL=redis://localhost:6379
+REDIS_ADDR=localhost:6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# =============================================================================
+# Database (MongoDB)
+# =============================================================================
+# Primarily used by Notification Service and Memory Service
+MONGO_URI=mongodb://localhost:27017
+MONGO_DATABASE=amaniquery_notifications
+
+# =============================================================================
+# Security (JWT & Auth)
+# =============================================================================
+JWT_SECRET=your-secure-jwt-secret-key-at-least-32-characters
+JWT_ISSUER=amaniquery
+JWT_AUDIENCE=amaniquery-notifications
+
+# =============================================================================
+# Notification Service Providers
+# =============================================================================
+# Mailtrap (Email)
+MAILTRAP_API_KEY=your-mailtrap-api-key
+MAILTRAP_ACCOUNT_ID=your-mailtrap-account-id
+MAILTRAP_SENDER_NAME=AmaniQuery
+MAILTRAP_SENDER_EMAIL=noreply@yourdomain.com
+
+# Africa's Talking (SMS)
+AFRICASTALKING_USERNAME=sandbox
+AFRICASTALKING_API_KEY=your-africastalking-api-key
+AFRICASTALKING_SENDER_ID=AmaniQuery
+AFRICASTALKING_SANDBOX=true
+
+# =============================================================================
+# Observability & Monitoring
+# =============================================================================
+JAEGER_ENDPOINT=localhost:4317
+AMANI_OBSERVABILITY_TRACING_ENABLED=true
+AMANI_OBSERVABILITY_METRICS_ENABLED=true
+AMANI_OBSERVABILITY_METRICS_PORT=9091
+
+# Prometheus (Notifications)
+METRICS_ENABLED=true
+METRICS_PORT=:9090
+METRICS_PATH=/metrics
+
+# Grafana
+GRAFANA_PASSWORD=your-grafana-admin-password
+
+# =============================================================================
+# Memory Service Configuration
+# =============================================================================
+AMANI_MEMORY_RUST_SERVICE_HOST=localhost
+AMANI_MEMORY_RUST_SERVICE_PORT=9091
+AMANI_MEMORY_ENABLE_RUST_SERVICE=false
+AMANI_MEMORY_ENABLE_GDPR=true

.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: CI
+
+on:
+    push:
+        branches: [master, develop]
+    pull_request:
+        branches: [master]
+
+env:
+    GO_VERSION: "1.21"
+
+jobs:
+    lint:
+        name: Lint
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Go
+              uses: actions/setup-go@v5
+              with:
+                  go-version: ${{ env.GO_VERSION }}
+                  cache: true
+
+            - name: golangci-lint
+              uses: golangci/golangci-lint-action@v3
+              with:
+                  version: v1.55.2
+                  args: --timeout=5m
+
+    test:
+        name: Test
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Go
+              uses: actions/setup-go@v5
+              with:
+                  go-version: ${{ env.GO_VERSION }}
+                  cache: true
+
+            - name: Run tests
+              run: go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
+
+            - name: Upload coverage
+              uses: codecov/codecov-action@v3
+              with:
+                  file: ./coverage.out
+                  fail_ci_if_error: false
+
+    build:
+        name: Build
+        runs-on: ubuntu-latest
+        needs: [lint, test]
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Go
+              uses: actions/setup-go@v5
+              with:
+                  go-version: ${{ env.GO_VERSION }}
+                  cache: true
+
+            - name: Build agent-server
+              run: go build -ldflags="-s -w" -o bin/agent-server ./cmd/agent-server
+
+    docker:
+        name: Docker Build
+        runs-on: ubuntu-latest
+        needs: [build]
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Login to GitHub Container Registry
+              uses: docker/login-action@v3
+              with:
+                  registry: ghcr.io
+                  username: ${{ github.actor }}
+                  password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Build and push agent-server
+              uses: docker/build-push-action@v5
+              with:
+                  context: .
+                  file: deployments/docker/Dockerfile.agent
+                  push: true
+                  tags: |
+                      ghcr.io/${{ github.repository }}/agent-server:latest
+                      ghcr.io/${{ github.repository }}/agent-server:${{ github.sha }}
+                  cache-from: type=gha
+                  cache-to: type=gha,mode=max
+
+    security-scan:
+        name: Security Scan
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Run Trivy vulnerability scanner
+              uses: aquasecurity/trivy-action@master
+              with:
+                  scan-type: "fs"
+                  scan-ref: "."
+                  ignore-unfixed: true
+                  format: "sarif"
+                  output: "trivy-results.sarif"
+
+            - name: Upload Trivy scan results to GitHub Security tab
+              uses: github/codeql-action/upload-sarif@v2
+              if: always()
+              with:
+                  sarif_file: "trivy-results.sarif"

.gitignore

@@ -0,0 +1,70 @@
+# Binaries
+bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+
+# Dependency directories
+vendor/
+
+# Go workspace sum file (keep go.work for local development)
+go.work.sum
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+config.yaml
+!config.example.yaml
+
+# Temporary files
+tmp/
+temp/
+
+# Build artifacts
+dist/
+
+# Docker
+.docker/
+
+# Kubernetes secrets (never commit)
+*-secret.yaml
+*-secrets.yaml
+
+# Coverage reports
+coverage/
+coverage.html
+coverage.txt
+
+# Bleve index files
+*.bleve/
+amaniquery_index/
+
+# Qdrant data (for local development)
+qdrant_storage/
+
+# Proto generated files (regenerate from source)
+pkg/proto/gen/

.golangci.yml

@@ -0,0 +1,76 @@
+run:
+  timeout: 5m
+  tests: true
+
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - gofmt
+    - goimports
+    - revive
+    - gosec
+    - prealloc
+    - unconvert
+    - misspell
+    - goconst
+    - bodyclose
+    - noctx
+    - dupl
+    - nestif
+
+linters-settings:
+  gofmt:
+    simplify: true
+  goimports:
+    local-prefixes: github.com/AmaniQuery/amaniquery
+  revive:
+    severity: warning
+    rules:
+      - name: blank-imports
+      - name: context-as-argument
+      - name: context-keys-type
+      - name: error-return
+      - name: error-strings
+      - name: error-naming
+      - name: exported
+      - name: increment-decrement
+      - name: var-naming
+      - name: package-comments
+      - name: range
+      - name: receiver-naming
+      - name: time-naming
+      - name: unexported-return
+      - name: indent-error-flow
+  gosec:
+    excludes:
+      - G104 # Unhandled error - too noisy for grpc
+      - G107 # Potential HTTP request made with variable url
+  nestif:
+    min-complexity: 5
+  goconst:
+    min-len: 3
+    min-occurrences: 3
+  dupl:
+    threshold: 150
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 50
+  max-same-issues: 10
+  exclude-rules:
+    - path: _test\.go
+      linters:
+        - dupl
+        - gosec
+        - goconst
+    - path: cmd/
+      linters:
+        - gochecknoinits
+    - linters:
+        - staticcheck
+      text: "SA1019:" # Deprecated

Dockerfile

@@ -0,0 +1,51 @@
+# Go Build Stage
+FROM golang:1.24-alpine AS go-builder
+WORKDIR /app
+RUN apk add --no-cache git ca-certificates
+COPY go.mod go.sum ./
+COPY go.work go.work.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /agent-server ./cmd/agent-server
+
+# Rust Build Stage
+FROM rust:1.76-alpine AS rust-builder
+WORKDIR /app
+RUN apk add --no-cache musl-dev
+COPY rust-memory-service/Cargo.toml rust-memory-service/Cargo.lock ./
+# Dummy build to cache deps
+RUN mkdir src && echo "fn main() {}" > src/main.rs
+RUN cargo build --release
+RUN rm -rf src
+COPY rust-memory-service/ .
+RUN cargo build --release
+RUN cp target/release/memory-server /memory-server
+
+# Runtime Stage
+FROM alpine:3.19
+RUN apk add --no-cache ca-certificates tzdata
+RUN adduser -D -g '' appuser
+WORKDIR /app
+
+# Copy binaries
+COPY --from=go-builder /agent-server .
+COPY --from=rust-builder /memory-server .
+
+# Copy scripts and configs
+COPY deployments/huggingface/start.sh .
+COPY config.example.yaml ./config.yaml
+COPY rust-memory-service/.env.example .env
+
+RUN chmod +x start.sh && chown -R appuser:appuser /app
+
+USER appuser
+EXPOSE 7860
+
+# Environment variables
+ENV PORT=7860
+ENV MEMORY_BIND_ADDR=127.0.0.1:9091
+# Configure Go agent to use local memory service (needs env var mapping in config/env)
+ENV MEMORY_SERVICE_HOST=127.0.0.1
+ENV MEMORY_SERVICE_PORT=9091
+
+CMD ["./start.sh"]

Makefile

@@ -0,0 +1,118 @@
+.PHONY: all build clean test proto run-agent run-retriever docker infra-up infra-down lint
+
+# Variables
+PROTO_DIR := pkg/proto
+GO_OUT := pkg/proto/gen
+DOCKER_COMPOSE := docker-compose -f deployments/docker/docker-compose.yml
+
+# Default target
+all: proto build
+
+# Generate Go code from protobuf definitions
+proto:
+	@echo "Generating protobuf code..."
+	@mkdir -p $(GO_OUT)
+	protoc --go_out=. --go_opt=paths=source_relative \
+		--go-grpc_out=. --go-grpc_opt=paths=source_relative \
+		$(PROTO_DIR)/agent.proto $(PROTO_DIR)/generator.proto $(PROTO_DIR)/retriever.proto
+	protoc --go_out=. --go_opt=paths=source_relative \
+		--go-grpc_out=. --go-grpc_opt=paths=source_relative \
+		$(PROTO_DIR)/clara.proto
+
+# Build all services
+build:
+	@echo "Building services..."
+	go build -o bin/agent-server ./cmd/agent-server
+	go build -o bin/retriever-server ./cmd/retriever-server
+	go build -o bin/generator-server ./cmd/generator-server
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning..."
+	rm -rf bin/
+	rm -rf $(GO_OUT)
+
+# Run tests
+test:
+	@echo "Running tests..."
+	go test -v -race -cover ./...
+
+# Run integration tests
+test-integration:
+	@echo "Running integration tests..."
+	go test -v -tags=integration ./tests/...
+
+# Run agent server
+run-agent:
+	@echo "Starting agent server..."
+	go run ./cmd/agent-server
+
+# Run retriever server
+run-retriever:
+	@echo "Starting retriever server..."
+	go run ./cmd/retriever-server
+
+# Run generator server
+run-generator:
+	@echo "Starting generator server..."
+	go run ./cmd/generator-server
+
+# Build Docker images
+docker:
+	@echo "Building Docker images..."
+	docker build -t amaniquery/agent-server:latest -f deployments/docker/Dockerfile.agent .
+	docker build -t amaniquery/retriever-server:latest -f deployments/docker/Dockerfile.retriever .
+	docker build -t amaniquery/generator-server:latest -f deployments/docker/Dockerfile.generator .
+
+# Start infrastructure (Qdrant, Redis, etc.)
+infra-up:
+	@echo "Starting infrastructure..."
+	$(DOCKER_COMPOSE) up -d qdrant redis
+
+# Stop infrastructure
+infra-down:
+	@echo "Stopping infrastructure..."
+	$(DOCKER_COMPOSE) down
+
+# Start all services with Docker Compose
+up:
+	@echo "Starting all services..."
+	$(DOCKER_COMPOSE) up -d
+
+# Stop all services
+down:
+	@echo "Stopping all services..."
+	$(DOCKER_COMPOSE) down
+
+# View logs
+logs:
+	$(DOCKER_COMPOSE) logs -f
+
+# Lint code
+lint:
+	@echo "Linting..."
+	golangci-lint run ./...
+
+# Format code
+fmt:
+	@echo "Formatting..."
+	go fmt ./...
+	goimports -w .
+
+# Download dependencies
+deps:
+	@echo "Downloading dependencies..."
+	go mod download
+	go mod tidy
+
+# Generate mocks for testing
+mocks:
+	@echo "Generating mocks..."
+	mockgen -source=internal/agent/orchestrator.go -destination=internal/agent/mocks/orchestrator_mock.go
+	mockgen -source=internal/retriever/retriever.go -destination=internal/retriever/mocks/retriever_mock.go
+
+# Security scan
+security:
+	@echo "Running security scan..."
+	gosec ./...
+	trivy fs .

README.md

@@ -1,10 +1,467 @@
+# AmaniQuery
+
+**AI-Powered Legal & News Intelligence Platform for Kenya**
+
+[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://go.dev/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Build Status](https://img.shields.io/badge/Build-Passing-success)](https://github.com/amaniquery/amaniquery)
+
+AmaniQuery is an AI agent framework designed to democratize access to legal information and civil education in Kenya. Built with a production-ready, Go-based RAG (Retrieval-Augmented Generation) architecture, it provides accurate, contextual answers about Kenya Law and current affairs.
+
+---
+
+## 🎯 Vision
+
+**Democratizing Access to Information and Civil Education**
+
+AmaniQuery aims to make legal knowledge accessible to every Kenyan citizen by:
+- Providing accurate answers to legal questions in plain language
+- Aggregating and contextualizing news relevant to civic matters
+- Offering a reliable, fast, and secure platform for information retrieval
+
+---
+
+## 📐 Architecture Overview
+
+### High-Level System Architecture
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        UI[Web UI/React]
+        API[REST/gRPC API]
+        CLI[Command Line]
+    end
+
+    subgraph "Control Plane"
+        AGENT[Agent Orchestrator<br/>Go-based Coordinator]
+        ROUTER[Query Router<br/>Semantic Classifier]
+        EVAL[Evaluation Engine<br/>Quality Scorer]
+        GUARDRAILS[NeMo Guardrails<br/>Safety Filter]
+    end
+
+    subgraph "Data Plane"
+        EMBED[Embedding Service<br/>GPU-Accelerated]
+        RETRIEVER[Retriever Service<br/>Hybrid Search]
+        RERANK[Reranker Service<br/>Cross-Encoder]
+        GENERATOR[Generator Service<br/>LLM Gateway]
+    end
+
+    subgraph "Storage Layer"
+        VDB[(Vector DB<br/>Qdrant)]
+        CACHE[(Redis Cache)]
+        OBJ[(Object Store<br/>MinIO/S3)]
+        GRAPH[(Graph DB<br/>Neo4j)]
+    end
+
+    subgraph "Infrastructure"
+        MONITOR[Monitoring<br/>Prometheus/Grafana]
+        TRACING[Tracing<br/>Jaeger]
+        VAULT[Secrets Vault<br/>HashiCorp Vault]
+    end
+
+    UI --> API
+    CLI --> API
+    API --> AGENT
+    AGENT --> ROUTER
+    ROUTER --> GUARDRAILS
+    GUARDRAILS --> EMBED
+    GUARDRAILS --> RETRIEVER
+    RETRIEVER --> VDB
+    RETRIEVER --> GRAPH
+    EMBED --> VDB
+    RETRIEVER --> RERANK
+    RERANK --> GENERATOR
+    GENERATOR --> EVAL
+    EVAL --> CACHE
+    CACHE --> API
+    AGENT --> MONITOR
+    AGENT --> TRACING
+    VAULT --> AGENT
+```
+
+### Query Router & Semantic Classification
+
+```mermaid
+graph LR
+    Q[User Query] --> PREPROCESS[Preprocessor<br/>Cleaning/Normalization]
+    PREPROCESS --> CLASSIFIER[Classifier<br/>Intent Detection]
+    CLASSIFIER --> C1{Query Type}
+    C1 -->|Factual| VSS[Vector Search]
+    C1 -->|Keyword| BM25[BM25 Search]
+    C1 -->|Relational| GRAPH[GraphRAG]
+    C1 -->|Multi-hop| AGENT[Agentic Search]
+    
+    VSS --> HYBRID[Hybrid Results]
+    BM25 --> HYBRID
+    GRAPH --> HYBRID
+    AGENT --> HYBRID
+    HYBRID --> FUSION[Rank Fusion<br/>Reciprocal Rank]
+    FUSION --> OUTPUT[Ranked Chunks]
+```
+
+### Security Architecture
+
+```mermaid
+graph TB
+    subgraph "Perimeter Security"
+        WAF[Web App Firewall]
+        API_GATEWAY[API Gateway<br/>Kong/Envoy]
+        RATE_LIMIT[Rate Limiter<br/>Token Bucket]
+    end
+    
+    subgraph "Authentication & Authorization"
+        OIDC[OIDC Provider<br/>Keycloak]
+        JWT[JWT Validator<br/>RS256]
+        OPA[OPA Policy Agent]
+        POLICY[Rego Policies]
+    end
+    
+    subgraph "Data Security"
+        TLS[TLS 1.3<br/>mTLS Internal]
+        ENCRYPT[AES-256-GCM]
+        VAULT[(HashiCorp Vault)]
+    end
+    
+    subgraph "Compliance"
+        AUDIT[Audit Logger]
+        GUARDRAILS2[Content Filter]
+        PII[PII Detector]
+    end
+    
+    CLIENT[Client] --> WAF
+    WAF --> RATE_LIMIT
+    RATE_LIMIT --> API_GATEWAY
+    API_GATEWAY --> OIDC
+    OIDC --> JWT
+    JWT --> OPA
+    OPA --> POLICY
+    POLICY --> SERVICE[Core Services]
+    SERVICE --> TLS
+    SERVICE --> VAULT
+    SERVICE --> AUDIT
+    SERVICE --> GUARDRAILS2
+    SERVICE --> PII
+```
+
+### Synchronous Query Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API_Gateway
+    participant Agent
+    participant Router
+    participant Guardrails
+    participant Retriever
+    participant Generator
+    participant Cache
+    
+    Client->>API_Gateway: POST /query
+    API_Gateway->>Agent: Forward query
+    
+    Agent->>Cache: Check cache
+    alt Cache Hit
+        Cache-->>Agent: Cached result
+        Agent-->>Client: Response 200ms
+    else Cache Miss
+        Agent->>Router: RouteQuery()
+        Router-->>Agent: RoutingDecision
+        
+        Agent->>Guardrails: ValidateQuery()
+        Guardrails-->>Agent: Safe/Unsafe
+        
+        Agent->>Retriever: HybridSearch()
+        Retriever-->>Agent: Top-K chunks
+        
+        Agent->>Generator: GenerateResponse()
+        Generator-->>Agent: Answer
+        
+        Agent->>Cache: Store result
+        Agent-->>Client: Response 2-3s
+    end
+```
+
+### Agentic Multi-Step Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Agent
+    participant Planner
+    participant Tools
+    participant Evaluator
+    
+    Client->>Agent: Complex query
+    Agent->>Planner: Create plan
+    Planner-->>Agent: Multi-step plan
+    
+    loop For each step
+        Agent->>Tools: Execute tool
+        Tools-->>Agent: Result
+        Agent->>Planner: Update plan
+    end
+    
+    Agent->>Evaluator: Validate answer
+    Evaluator-->>Agent: Score
+    
+    alt Score >= threshold
+        Agent-->>Client: Final answer
+    else Score < threshold
+        Agent->>Planner: Revise plan
+    end
+```
+
+### Data Ingestion Pipeline
+
+```mermaid
+graph TB
+    SRC[Data Sources<br/>PDF/DB/API] --> INGEST[Ingestion API]
+    
+    INGEST --> QUEUE1[Message Queue<br/>Kafka/RabbitMQ]
+    
+    QUEUE1 --> PREPROC[Preprocessor<br/>Go Workers]
+    
+    PREPROC --> CHUNK[Chunking Engine<br/>Semantic Splitter]
+    
+    CHUNK --> ENRICH[Enrichment<br/>Metadata/NER]
+    
+    ENRICH --> EMBED2[Embedding Worker<br/>Batched GPU]
+    
+    EMBED2 --> INDEX[Indexing Worker]
+    
+    INDEX --> VDB2[(Vector DB)]
+    INDEX --> GRAPH2[(Graph DB)]
+    INDEX --> CACHE3[(Cache)]
+
+    style PREPROC fill:#4A90D9
+    style CHUNK fill:#50C878
+    style EMBED2 fill:#FF6B6B
+    style INDEX fill:#DA70D6
+```
+
+### Multi-Tier Caching Strategy
+
+```mermaid
+graph LR
+    CLIENT[Query] --> CACHE1[L1 Cache<br/>CDN/Edge]
+    
+    CACHE1 -->|Miss| CACHE2[L2 Cache<br/>Redis Cluster]
+    
+    CACHE2 -->|Miss| CACHE3[L3 Compute Cache]
+    
+    CACHE3 -->|Miss| EMBED[Embedding Cache<br/>Local LRU]
+    
+    EMBED -->|Miss| MODEL[Embedding Model]
+    
+    style CACHE1 fill:#FF69B4
+    style CACHE2 fill:#6495ED
+    style CACHE3 fill:#90EE90
+    style EMBED fill:#FFB6C1
+```
+
+---
+
+## 🗂️ Project Structure
+
+```
+AmaniQuery/
+├── cmd/                          # Application entry points
+│   ├── agent-server/            # Agent Orchestrator service
+│   ├── retriever-server/        # Retrieval service
+│   └── generator-server/        # LLM Gateway service
+├── internal/                     # Private application code
+│   ├── agent/                   # Agent orchestration logic
+│   ├── retriever/               # Hybrid search implementation
+│   │   ├── vector/              # Vector store clients
+│   │   ├── keyword/             # BM25/Bleve implementation
+│   │   └── graph/               # Neo4j GraphRAG
+│   ├── generator/               # LLM client and prompting
+│   ├── router/                  # Query classification
+│   ├── guardrails/              # Content safety filters
+│   ├── cache/                   # Multi-tier caching
+│   └── security/                # Auth, encryption, policies
+├── pkg/                          # Public shared libraries
+│   ├── proto/                   # gRPC/protobuf definitions
+│   ├── config/                  # Configuration management
+│   ├── observability/           # Metrics, tracing, logging
+│   └── errors/                  # Custom error types
+├── api/                          # REST API layer
+├── deployments/                  # Kubernetes/Helm configs
+│   ├── docker/                  # Dockerfiles
+│   └── k8s/                     # Kubernetes manifests
+├── scripts/                      # Build and deployment scripts
+├── docs/                         # Documentation
+└── tests/                        # Integration tests
+```
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Go 1.21+
+- Docker & Docker Compose
+- Make
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/amaniquery/amaniquery.git
+cd amaniquery
+
+# Install dependencies
+go mod download
+
+# Generate protobuf code
+make proto
+
+# Start infrastructure (Qdrant, Redis)
+make infra-up
+
+# Run the agent server
+make run-agent
+
+# Run tests
+make test
+```
+
+### Docker Compose
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f agent-server
+
+# Stop services
+docker-compose down
+```
+
 ---
-title: Amaniquery Agent
-emoji: 🐢
-colorFrom: indigo
-colorTo: purple
-sdk: docker
-pinned: false
+
+## 📡 API Usage
+
+### gRPC
+
+```bash
+# List available services
+grpcurl -plaintext localhost:9090 list
+
+# Process a query
+grpcurl -plaintext -d '{
+  "query": "What does the Kenya Constitution say about land rights?",
+  "session_id": "user-123"
+}' localhost:9090 rag.v1.AgentService/ProcessQuery
+```
+
+### REST API
+
+```bash
+# Health check
+curl http://localhost:8080/health
+
+# Process query
+curl -X POST http://localhost:8080/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "Explain the Bill of Rights in Kenya"}'
+```
+
+---
+
+## ⚙️ Configuration
+
+Configuration is managed through environment variables and YAML files:
+
+```yaml
+# config.yaml
+server:
+  grpc_port: 9090
+  http_port: 8080
+  
+vector_store:
+  type: qdrant
+  host: localhost
+  port: 6333
+  collection: amaniquery
+  
+llm:
+  provider: openai  # openai, anthropic, google
+  model: gpt-4o
+  max_tokens: 4096
+  temperature: 0.7
+  
+cache:
+  redis_url: redis://localhost:6379
+  local_size: 10000
+  ttl: 3600
+  
+security:
+  jwt_secret: ${JWT_SECRET}
+  vault_addr: ${VAULT_ADDR}
+```
+
+---
+
+## 📊 Performance Targets
+
+| Metric | Target | Description |
+|--------|--------|-------------|
+| P95 Latency | < 3s | 95th percentile query latency |
+| P99 Latency | < 5s | 99th percentile query latency |
+| Cache Hit Rate | > 85% | Query cache effectiveness |
+| Throughput | 10k docs/min | Document ingestion rate |
+| Concurrent Users | 10,000+ | Simultaneous connections |
+| Availability | 99.95% | Uptime SLA |
+
+---
+
+## 🔒 Security
+
+AmaniQuery implements enterprise-grade security:
+
+- **mTLS**: Service-to-service encryption
+- **JWT + OIDC**: Token-based authentication
+- **OPA/Rego**: Fine-grained authorization policies
+- **HashiCorp Vault**: Secrets management
+- **PII Detection**: Automatic sensitive data handling
+- **Audit Logging**: Immutable activity logs
+- **Rate Limiting**: DDoS protection
+
+---
+
+## 📈 Observability
+
+- **Metrics**: Prometheus + Grafana dashboards
+- **Tracing**: Jaeger distributed tracing
+- **Logging**: Structured JSON logs with correlation IDs
+- **Alerting**: PagerDuty/Slack integration
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with inspiration from NVIDIA's RAG Blueprint
+- Kenya Law Reports for legal data access
+- The Go community for excellent tooling
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <b>AmaniQuery</b> - Democratizing Access to Legal Knowledge
+</p>

agent.pb.go

@@ -0,0 +1,1837 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        v6.33.2
+// source: agent.proto
+
+package ragv1
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// ChunkType defines the type of streaming chunk
+type ChunkType int32
+
+const (
+	ChunkType_CHUNK_TYPE_UNSPECIFIED ChunkType = 0
+	ChunkType_CHUNK_TYPE_THINKING    ChunkType = 1
+	ChunkType_CHUNK_TYPE_RETRIEVAL   ChunkType = 2
+	ChunkType_CHUNK_TYPE_GENERATION  ChunkType = 3
+	ChunkType_CHUNK_TYPE_COMPLETE    ChunkType = 4
+	ChunkType_CHUNK_TYPE_ERROR       ChunkType = 5
+)
+
+// Enum value maps for ChunkType.
+var (
+	ChunkType_name = map[int32]string{
+		0: "CHUNK_TYPE_UNSPECIFIED",
+		1: "CHUNK_TYPE_THINKING",
+		2: "CHUNK_TYPE_RETRIEVAL",
+		3: "CHUNK_TYPE_GENERATION",
+		4: "CHUNK_TYPE_COMPLETE",
+		5: "CHUNK_TYPE_ERROR",
+	}
+	ChunkType_value = map[string]int32{
+		"CHUNK_TYPE_UNSPECIFIED": 0,
+		"CHUNK_TYPE_THINKING":    1,
+		"CHUNK_TYPE_RETRIEVAL":   2,
+		"CHUNK_TYPE_GENERATION":  3,
+		"CHUNK_TYPE_COMPLETE":    4,
+		"CHUNK_TYPE_ERROR":       5,
+	}
+)
+
+func (x ChunkType) Enum() *ChunkType {
+	p := new(ChunkType)
+	*p = x
+	return p
+}
+
+func (x ChunkType) String() string {
+	return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (ChunkType) Descriptor() protoreflect.EnumDescriptor {
+	return file_agent_proto_enumTypes[0].Descriptor()
+}
+
+func (ChunkType) Type() protoreflect.EnumType {
+	return &file_agent_proto_enumTypes[0]
+}
+
+func (x ChunkType) Number() protoreflect.EnumNumber {
+	return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use ChunkType.Descriptor instead.
+func (ChunkType) EnumDescriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{0}
+}
+
+// MessageRole defines who sent the message
+type MessageRole int32
+
+const (
+	MessageRole_MESSAGE_ROLE_UNSPECIFIED MessageRole = 0
+	MessageRole_MESSAGE_ROLE_USER        MessageRole = 1
+	MessageRole_MESSAGE_ROLE_ASSISTANT   MessageRole = 2
+	MessageRole_MESSAGE_ROLE_SYSTEM      MessageRole = 3
+)
+
+// Enum value maps for MessageRole.
+var (
+	MessageRole_name = map[int32]string{
+		0: "MESSAGE_ROLE_UNSPECIFIED",
+		1: "MESSAGE_ROLE_USER",
+		2: "MESSAGE_ROLE_ASSISTANT",
+		3: "MESSAGE_ROLE_SYSTEM",
+	}
+	MessageRole_value = map[string]int32{
+		"MESSAGE_ROLE_UNSPECIFIED": 0,
+		"MESSAGE_ROLE_USER":        1,
+		"MESSAGE_ROLE_ASSISTANT":   2,
+		"MESSAGE_ROLE_SYSTEM":      3,
+	}
+)
+
+func (x MessageRole) Enum() *MessageRole {
+	p := new(MessageRole)
+	*p = x
+	return p
+}
+
+func (x MessageRole) String() string {
+	return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (MessageRole) Descriptor() protoreflect.EnumDescriptor {
+	return file_agent_proto_enumTypes[1].Descriptor()
+}
+
+func (MessageRole) Type() protoreflect.EnumType {
+	return &file_agent_proto_enumTypes[1]
+}
+
+func (x MessageRole) Number() protoreflect.EnumNumber {
+	return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use MessageRole.Descriptor instead.
+func (MessageRole) EnumDescriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{1}
+}
+
+// StepType defines execution step types
+type StepType int32
+
+const (
+	StepType_STEP_TYPE_UNSPECIFIED StepType = 0
+	StepType_STEP_TYPE_SEARCH      StepType = 1
+	StepType_STEP_TYPE_ANALYZE     StepType = 2
+	StepType_STEP_TYPE_SYNTHESIZE  StepType = 3
+	StepType_STEP_TYPE_VALIDATE    StepType = 4
+)
+
+// Enum value maps for StepType.
+var (
+	StepType_name = map[int32]string{
+		0: "STEP_TYPE_UNSPECIFIED",
+		1: "STEP_TYPE_SEARCH",
+		2: "STEP_TYPE_ANALYZE",
+		3: "STEP_TYPE_SYNTHESIZE",
+		4: "STEP_TYPE_VALIDATE",
+	}
+	StepType_value = map[string]int32{
+		"STEP_TYPE_UNSPECIFIED": 0,
+		"STEP_TYPE_SEARCH":      1,
+		"STEP_TYPE_ANALYZE":     2,
+		"STEP_TYPE_SYNTHESIZE":  3,
+		"STEP_TYPE_VALIDATE":    4,
+	}
+)
+
+func (x StepType) Enum() *StepType {
+	p := new(StepType)
+	*p = x
+	return p
+}
+
+func (x StepType) String() string {
+	return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (StepType) Descriptor() protoreflect.EnumDescriptor {
+	return file_agent_proto_enumTypes[2].Descriptor()
+}
+
+func (StepType) Type() protoreflect.EnumType {
+	return &file_agent_proto_enumTypes[2]
+}
+
+func (x StepType) Number() protoreflect.EnumNumber {
+	return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use StepType.Descriptor instead.
+func (StepType) EnumDescriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{2}
+}
+
+// ExecutionStatus for plan execution
+type ExecutionStatus int32
+
+const (
+	ExecutionStatus_EXECUTION_STATUS_UNSPECIFIED ExecutionStatus = 0
+	ExecutionStatus_EXECUTION_STATUS_PENDING     ExecutionStatus = 1
+	ExecutionStatus_EXECUTION_STATUS_RUNNING     ExecutionStatus = 2
+	ExecutionStatus_EXECUTION_STATUS_COMPLETED   ExecutionStatus = 3
+	ExecutionStatus_EXECUTION_STATUS_FAILED      ExecutionStatus = 4
+)
+
+// Enum value maps for ExecutionStatus.
+var (
+	ExecutionStatus_name = map[int32]string{
+		0: "EXECUTION_STATUS_UNSPECIFIED",
+		1: "EXECUTION_STATUS_PENDING",
+		2: "EXECUTION_STATUS_RUNNING",
+		3: "EXECUTION_STATUS_COMPLETED",
+		4: "EXECUTION_STATUS_FAILED",
+	}
+	ExecutionStatus_value = map[string]int32{
+		"EXECUTION_STATUS_UNSPECIFIED": 0,
+		"EXECUTION_STATUS_PENDING":     1,
+		"EXECUTION_STATUS_RUNNING":     2,
+		"EXECUTION_STATUS_COMPLETED":   3,
+		"EXECUTION_STATUS_FAILED":      4,
+	}
+)
+
+func (x ExecutionStatus) Enum() *ExecutionStatus {
+	p := new(ExecutionStatus)
+	*p = x
+	return p
+}
+
+func (x ExecutionStatus) String() string {
+	return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (ExecutionStatus) Descriptor() protoreflect.EnumDescriptor {
+	return file_agent_proto_enumTypes[3].Descriptor()
+}
+
+func (ExecutionStatus) Type() protoreflect.EnumType {
+	return &file_agent_proto_enumTypes[3]
+}
+
+func (x ExecutionStatus) Number() protoreflect.EnumNumber {
+	return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use ExecutionStatus.Descriptor instead.
+func (ExecutionStatus) EnumDescriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{3}
+}
+
+// QueryRequest represents a user query
+type QueryRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// The user's query text
+	Query string `protobuf:"bytes,1,opt,name=query,proto3" json:"query,omitempty"`
+	// Session ID for conversation continuity
+	SessionId string `protobuf:"bytes,2,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
+	// User ID for personalization and audit
+	UserId string `protobuf:"bytes,3,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
+	// Conversation history for context
+	ConversationHistory []*Message `protobuf:"bytes,4,rep,name=conversation_history,json=conversationHistory,proto3" json:"conversation_history,omitempty"`
+	// Additional metadata
+	Metadata map[string]string `protobuf:"bytes,5,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	// Query configuration options
+	Options       *QueryOptions `protobuf:"bytes,6,opt,name=options,proto3" json:"options,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryRequest) Reset() {
+	*x = QueryRequest{}
+	mi := &file_agent_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryRequest) ProtoMessage() {}
+
+func (x *QueryRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryRequest.ProtoReflect.Descriptor instead.
+func (*QueryRequest) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *QueryRequest) GetQuery() string {
+	if x != nil {
+		return x.Query
+	}
+	return ""
+}
+
+func (x *QueryRequest) GetSessionId() string {
+	if x != nil {
+		return x.SessionId
+	}
+	return ""
+}
+
+func (x *QueryRequest) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+func (x *QueryRequest) GetConversationHistory() []*Message {
+	if x != nil {
+		return x.ConversationHistory
+	}
+	return nil
+}
+
+func (x *QueryRequest) GetMetadata() map[string]string {
+	if x != nil {
+		return x.Metadata
+	}
+	return nil
+}
+
+func (x *QueryRequest) GetOptions() *QueryOptions {
+	if x != nil {
+		return x.Options
+	}
+	return nil
+}
+
+// QueryOptions configures query processing behavior
+type QueryOptions struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Maximum number of sources to retrieve
+	MaxSources int32 `protobuf:"varint,1,opt,name=max_sources,json=maxSources,proto3" json:"max_sources,omitempty"`
+	// Enable/disable caching
+	UseCache bool `protobuf:"varint,2,opt,name=use_cache,json=useCache,proto3" json:"use_cache,omitempty"`
+	// Enable agentic multi-step reasoning
+	EnableAgentic bool `protobuf:"varint,3,opt,name=enable_agentic,json=enableAgentic,proto3" json:"enable_agentic,omitempty"`
+	// Specific knowledge bases to search
+	KnowledgeBases []string `protobuf:"bytes,4,rep,name=knowledge_bases,json=knowledgeBases,proto3" json:"knowledge_bases,omitempty"`
+	// Temperature for LLM generation (0.0 - 1.0)
+	Temperature float32 `protobuf:"fixed32,5,opt,name=temperature,proto3" json:"temperature,omitempty"`
+	// Maximum tokens for response
+	MaxTokens     int32 `protobuf:"varint,6,opt,name=max_tokens,json=maxTokens,proto3" json:"max_tokens,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryOptions) Reset() {
+	*x = QueryOptions{}
+	mi := &file_agent_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryOptions) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryOptions) ProtoMessage() {}
+
+func (x *QueryOptions) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryOptions.ProtoReflect.Descriptor instead.
+func (*QueryOptions) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *QueryOptions) GetMaxSources() int32 {
+	if x != nil {
+		return x.MaxSources
+	}
+	return 0
+}
+
+func (x *QueryOptions) GetUseCache() bool {
+	if x != nil {
+		return x.UseCache
+	}
+	return false
+}
+
+func (x *QueryOptions) GetEnableAgentic() bool {
+	if x != nil {
+		return x.EnableAgentic
+	}
+	return false
+}
+
+func (x *QueryOptions) GetKnowledgeBases() []string {
+	if x != nil {
+		return x.KnowledgeBases
+	}
+	return nil
+}
+
+func (x *QueryOptions) GetTemperature() float32 {
+	if x != nil {
+		return x.Temperature
+	}
+	return 0
+}
+
+func (x *QueryOptions) GetMaxTokens() int32 {
+	if x != nil {
+		return x.MaxTokens
+	}
+	return 0
+}
+
+// QueryResponse contains the complete answer
+type QueryResponse struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// The generated answer text
+	Answer string `protobuf:"bytes,1,opt,name=answer,proto3" json:"answer,omitempty"`
+	// Sources used to generate the answer
+	Sources []*Source `protobuf:"bytes,2,rep,name=sources,proto3" json:"sources,omitempty"`
+	// Confidence score (0.0 - 1.0)
+	Confidence float32 `protobuf:"fixed32,3,opt,name=confidence,proto3" json:"confidence,omitempty"`
+	// Query processing metadata
+	Metadata *QueryMetadata `protobuf:"bytes,4,opt,name=metadata,proto3" json:"metadata,omitempty"`
+	// Suggested follow-up questions
+	FollowUpQuestions []string `protobuf:"bytes,5,rep,name=follow_up_questions,json=followUpQuestions,proto3" json:"follow_up_questions,omitempty"`
+	unknownFields     protoimpl.UnknownFields
+	sizeCache         protoimpl.SizeCache
+}
+
+func (x *QueryResponse) Reset() {
+	*x = QueryResponse{}
+	mi := &file_agent_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryResponse) ProtoMessage() {}
+
+func (x *QueryResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryResponse.ProtoReflect.Descriptor instead.
+func (*QueryResponse) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *QueryResponse) GetAnswer() string {
+	if x != nil {
+		return x.Answer
+	}
+	return ""
+}
+
+func (x *QueryResponse) GetSources() []*Source {
+	if x != nil {
+		return x.Sources
+	}
+	return nil
+}
+
+func (x *QueryResponse) GetConfidence() float32 {
+	if x != nil {
+		return x.Confidence
+	}
+	return 0
+}
+
+func (x *QueryResponse) GetMetadata() *QueryMetadata {
+	if x != nil {
+		return x.Metadata
+	}
+	return nil
+}
+
+func (x *QueryResponse) GetFollowUpQuestions() []string {
+	if x != nil {
+		return x.FollowUpQuestions
+	}
+	return nil
+}
+
+// QueryResponseChunk for streaming responses
+type QueryResponseChunk struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Chunk type: THINKING, RETRIEVAL, GENERATION, COMPLETE
+	Type ChunkType `protobuf:"varint,1,opt,name=type,proto3,enum=rag.v1.ChunkType" json:"type,omitempty"`
+	// Text content of the chunk
+	Content string `protobuf:"bytes,2,opt,name=content,proto3" json:"content,omitempty"`
+	// Sources (populated in RETRIEVAL chunks)
+	Sources []*Source `protobuf:"bytes,3,rep,name=sources,proto3" json:"sources,omitempty"`
+	// Is this the final chunk?
+	IsFinal       bool `protobuf:"varint,4,opt,name=is_final,json=isFinal,proto3" json:"is_final,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryResponseChunk) Reset() {
+	*x = QueryResponseChunk{}
+	mi := &file_agent_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryResponseChunk) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryResponseChunk) ProtoMessage() {}
+
+func (x *QueryResponseChunk) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryResponseChunk.ProtoReflect.Descriptor instead.
+func (*QueryResponseChunk) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *QueryResponseChunk) GetType() ChunkType {
+	if x != nil {
+		return x.Type
+	}
+	return ChunkType_CHUNK_TYPE_UNSPECIFIED
+}
+
+func (x *QueryResponseChunk) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+func (x *QueryResponseChunk) GetSources() []*Source {
+	if x != nil {
+		return x.Sources
+	}
+	return nil
+}
+
+func (x *QueryResponseChunk) GetIsFinal() bool {
+	if x != nil {
+		return x.IsFinal
+	}
+	return false
+}
+
+// Source represents a retrieved document chunk
+type Source struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Unique identifier for the source
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Document title
+	Title string `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
+	// Relevant text content
+	Content string `protobuf:"bytes,3,opt,name=content,proto3" json:"content,omitempty"`
+	// Source URL or path
+	Url string `protobuf:"bytes,4,opt,name=url,proto3" json:"url,omitempty"`
+	// Relevance score (0.0 - 1.0)
+	Score float32 `protobuf:"fixed32,5,opt,name=score,proto3" json:"score,omitempty"`
+	// Source metadata
+	Metadata map[string]string `protobuf:"bytes,6,rep,name=metadata,proto3" json:"metadata,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	// Page number or section reference
+	Location      string `protobuf:"bytes,7,opt,name=location,proto3" json:"location,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Source) Reset() {
+	*x = Source{}
+	mi := &file_agent_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Source) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Source) ProtoMessage() {}
+
+func (x *Source) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Source.ProtoReflect.Descriptor instead.
+func (*Source) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *Source) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *Source) GetTitle() string {
+	if x != nil {
+		return x.Title
+	}
+	return ""
+}
+
+func (x *Source) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+func (x *Source) GetUrl() string {
+	if x != nil {
+		return x.Url
+	}
+	return ""
+}
+
+func (x *Source) GetScore() float32 {
+	if x != nil {
+		return x.Score
+	}
+	return 0
+}
+
+func (x *Source) GetMetadata() map[string]string {
+	if x != nil {
+		return x.Metadata
+	}
+	return nil
+}
+
+func (x *Source) GetLocation() string {
+	if x != nil {
+		return x.Location
+	}
+	return ""
+}
+
+// Message represents a conversation turn
+type Message struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Message role: USER, ASSISTANT, SYSTEM
+	Role MessageRole `protobuf:"varint,1,opt,name=role,proto3,enum=rag.v1.MessageRole" json:"role,omitempty"`
+	// Message content
+	Content string `protobuf:"bytes,2,opt,name=content,proto3" json:"content,omitempty"`
+	// Timestamp
+	Timestamp     int64 `protobuf:"varint,3,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Message) Reset() {
+	*x = Message{}
+	mi := &file_agent_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Message) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Message) ProtoMessage() {}
+
+func (x *Message) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Message.ProtoReflect.Descriptor instead.
+func (*Message) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{5}
+}
+
+func (x *Message) GetRole() MessageRole {
+	if x != nil {
+		return x.Role
+	}
+	return MessageRole_MESSAGE_ROLE_UNSPECIFIED
+}
+
+func (x *Message) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+func (x *Message) GetTimestamp() int64 {
+	if x != nil {
+		return x.Timestamp
+	}
+	return 0
+}
+
+// QueryMetadata contains processing information
+type QueryMetadata struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Total processing time in milliseconds
+	ProcessingTimeMs int64 `protobuf:"varint,1,opt,name=processing_time_ms,json=processingTimeMs,proto3" json:"processing_time_ms,omitempty"`
+	// Number of chunks retrieved
+	ChunksRetrieved int32 `protobuf:"varint,2,opt,name=chunks_retrieved,json=chunksRetrieved,proto3" json:"chunks_retrieved,omitempty"`
+	// Tokens used for generation
+	TokensUsed int32 `protobuf:"varint,3,opt,name=tokens_used,json=tokensUsed,proto3" json:"tokens_used,omitempty"`
+	// Whether result was cached
+	CacheHit bool `protobuf:"varint,4,opt,name=cache_hit,json=cacheHit,proto3" json:"cache_hit,omitempty"`
+	// Query routing decision
+	RoutingStrategy string `protobuf:"bytes,5,opt,name=routing_strategy,json=routingStrategy,proto3" json:"routing_strategy,omitempty"`
+	// Trace ID for debugging
+	TraceId       string `protobuf:"bytes,6,opt,name=trace_id,json=traceId,proto3" json:"trace_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryMetadata) Reset() {
+	*x = QueryMetadata{}
+	mi := &file_agent_proto_msgTypes[6]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryMetadata) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryMetadata) ProtoMessage() {}
+
+func (x *QueryMetadata) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[6]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryMetadata.ProtoReflect.Descriptor instead.
+func (*QueryMetadata) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *QueryMetadata) GetProcessingTimeMs() int64 {
+	if x != nil {
+		return x.ProcessingTimeMs
+	}
+	return 0
+}
+
+func (x *QueryMetadata) GetChunksRetrieved() int32 {
+	if x != nil {
+		return x.ChunksRetrieved
+	}
+	return 0
+}
+
+func (x *QueryMetadata) GetTokensUsed() int32 {
+	if x != nil {
+		return x.TokensUsed
+	}
+	return 0
+}
+
+func (x *QueryMetadata) GetCacheHit() bool {
+	if x != nil {
+		return x.CacheHit
+	}
+	return false
+}
+
+func (x *QueryMetadata) GetRoutingStrategy() string {
+	if x != nil {
+		return x.RoutingStrategy
+	}
+	return ""
+}
+
+func (x *QueryMetadata) GetTraceId() string {
+	if x != nil {
+		return x.TraceId
+	}
+	return ""
+}
+
+// CreateAgentRequest for creating specialized agents
+type CreateAgentRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Agent name
+	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// Agent description
+	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
+	// System prompt for the agent
+	SystemPrompt string `protobuf:"bytes,3,opt,name=system_prompt,json=systemPrompt,proto3" json:"system_prompt,omitempty"`
+	// Tools available to the agent
+	Tools []string `protobuf:"bytes,4,rep,name=tools,proto3" json:"tools,omitempty"`
+	// Agent configuration
+	Config        *AgentConfig `protobuf:"bytes,5,opt,name=config,proto3" json:"config,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CreateAgentRequest) Reset() {
+	*x = CreateAgentRequest{}
+	mi := &file_agent_proto_msgTypes[7]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CreateAgentRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CreateAgentRequest) ProtoMessage() {}
+
+func (x *CreateAgentRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[7]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CreateAgentRequest.ProtoReflect.Descriptor instead.
+func (*CreateAgentRequest) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{7}
+}
+
+func (x *CreateAgentRequest) GetName() string {
+	if x != nil {
+		return x.Name
+	}
+	return ""
+}
+
+func (x *CreateAgentRequest) GetDescription() string {
+	if x != nil {
+		return x.Description
+	}
+	return ""
+}
+
+func (x *CreateAgentRequest) GetSystemPrompt() string {
+	if x != nil {
+		return x.SystemPrompt
+	}
+	return ""
+}
+
+func (x *CreateAgentRequest) GetTools() []string {
+	if x != nil {
+		return x.Tools
+	}
+	return nil
+}
+
+func (x *CreateAgentRequest) GetConfig() *AgentConfig {
+	if x != nil {
+		return x.Config
+	}
+	return nil
+}
+
+// Agent represents a configured AI agent
+type Agent struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Unique agent ID
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Agent name
+	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// Agent description
+	Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
+	// Creation timestamp
+	CreatedAt int64 `protobuf:"varint,4,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+	// Agent configuration
+	Config        *AgentConfig `protobuf:"bytes,5,opt,name=config,proto3" json:"config,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Agent) Reset() {
+	*x = Agent{}
+	mi := &file_agent_proto_msgTypes[8]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Agent) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Agent) ProtoMessage() {}
+
+func (x *Agent) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[8]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Agent.ProtoReflect.Descriptor instead.
+func (*Agent) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{8}
+}
+
+func (x *Agent) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *Agent) GetName() string {
+	if x != nil {
+		return x.Name
+	}
+	return ""
+}
+
+func (x *Agent) GetDescription() string {
+	if x != nil {
+		return x.Description
+	}
+	return ""
+}
+
+func (x *Agent) GetCreatedAt() int64 {
+	if x != nil {
+		return x.CreatedAt
+	}
+	return 0
+}
+
+func (x *Agent) GetConfig() *AgentConfig {
+	if x != nil {
+		return x.Config
+	}
+	return nil
+}
+
+// AgentConfig contains agent settings
+type AgentConfig struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// LLM model to use
+	Model string `protobuf:"bytes,1,opt,name=model,proto3" json:"model,omitempty"`
+	// Temperature setting
+	Temperature float32 `protobuf:"fixed32,2,opt,name=temperature,proto3" json:"temperature,omitempty"`
+	// Maximum iterations for agentic loops
+	MaxIterations int32 `protobuf:"varint,3,opt,name=max_iterations,json=maxIterations,proto3" json:"max_iterations,omitempty"`
+	// Timeout in seconds
+	TimeoutSeconds int32 `protobuf:"varint,4,opt,name=timeout_seconds,json=timeoutSeconds,proto3" json:"timeout_seconds,omitempty"`
+	unknownFields  protoimpl.UnknownFields
+	sizeCache      protoimpl.SizeCache
+}
+
+func (x *AgentConfig) Reset() {
+	*x = AgentConfig{}
+	mi := &file_agent_proto_msgTypes[9]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *AgentConfig) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*AgentConfig) ProtoMessage() {}
+
+func (x *AgentConfig) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[9]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use AgentConfig.ProtoReflect.Descriptor instead.
+func (*AgentConfig) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{9}
+}
+
+func (x *AgentConfig) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *AgentConfig) GetTemperature() float32 {
+	if x != nil {
+		return x.Temperature
+	}
+	return 0
+}
+
+func (x *AgentConfig) GetMaxIterations() int32 {
+	if x != nil {
+		return x.MaxIterations
+	}
+	return 0
+}
+
+func (x *AgentConfig) GetTimeoutSeconds() int32 {
+	if x != nil {
+		return x.TimeoutSeconds
+	}
+	return 0
+}
+
+// ExecutionPlan for multi-step queries
+type ExecutionPlan struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Plan ID
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Original query
+	Query string `protobuf:"bytes,2,opt,name=query,proto3" json:"query,omitempty"`
+	// Execution steps
+	Steps         []*ExecutionStep `protobuf:"bytes,3,rep,name=steps,proto3" json:"steps,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ExecutionPlan) Reset() {
+	*x = ExecutionPlan{}
+	mi := &file_agent_proto_msgTypes[10]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ExecutionPlan) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ExecutionPlan) ProtoMessage() {}
+
+func (x *ExecutionPlan) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[10]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ExecutionPlan.ProtoReflect.Descriptor instead.
+func (*ExecutionPlan) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{10}
+}
+
+func (x *ExecutionPlan) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *ExecutionPlan) GetQuery() string {
+	if x != nil {
+		return x.Query
+	}
+	return ""
+}
+
+func (x *ExecutionPlan) GetSteps() []*ExecutionStep {
+	if x != nil {
+		return x.Steps
+	}
+	return nil
+}
+
+// ExecutionStep represents a single step in the plan
+type ExecutionStep struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Step ID
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Step type: SEARCH, ANALYZE, SYNTHESIZE
+	Type StepType `protobuf:"varint,2,opt,name=type,proto3,enum=rag.v1.StepType" json:"type,omitempty"`
+	// Step description
+	Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
+	// Tool to use
+	Tool string `protobuf:"bytes,4,opt,name=tool,proto3" json:"tool,omitempty"`
+	// Input for the step
+	Input string `protobuf:"bytes,5,opt,name=input,proto3" json:"input,omitempty"`
+	// Dependencies (IDs of steps that must complete first)
+	Dependencies  []string `protobuf:"bytes,6,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ExecutionStep) Reset() {
+	*x = ExecutionStep{}
+	mi := &file_agent_proto_msgTypes[11]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ExecutionStep) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ExecutionStep) ProtoMessage() {}
+
+func (x *ExecutionStep) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[11]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ExecutionStep.ProtoReflect.Descriptor instead.
+func (*ExecutionStep) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{11}
+}
+
+func (x *ExecutionStep) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *ExecutionStep) GetType() StepType {
+	if x != nil {
+		return x.Type
+	}
+	return StepType_STEP_TYPE_UNSPECIFIED
+}
+
+func (x *ExecutionStep) GetDescription() string {
+	if x != nil {
+		return x.Description
+	}
+	return ""
+}
+
+func (x *ExecutionStep) GetTool() string {
+	if x != nil {
+		return x.Tool
+	}
+	return ""
+}
+
+func (x *ExecutionStep) GetInput() string {
+	if x != nil {
+		return x.Input
+	}
+	return ""
+}
+
+func (x *ExecutionStep) GetDependencies() []string {
+	if x != nil {
+		return x.Dependencies
+	}
+	return nil
+}
+
+// PlanResult contains execution results
+type PlanResult struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Plan ID
+	PlanId string `protobuf:"bytes,1,opt,name=plan_id,json=planId,proto3" json:"plan_id,omitempty"`
+	// Execution status
+	Status ExecutionStatus `protobuf:"varint,2,opt,name=status,proto3,enum=rag.v1.ExecutionStatus" json:"status,omitempty"`
+	// Step results
+	StepResults []*StepResult `protobuf:"bytes,3,rep,name=step_results,json=stepResults,proto3" json:"step_results,omitempty"`
+	// Final answer
+	FinalAnswer string `protobuf:"bytes,4,opt,name=final_answer,json=finalAnswer,proto3" json:"final_answer,omitempty"`
+	// Total execution time
+	ExecutionTimeMs int64 `protobuf:"varint,5,opt,name=execution_time_ms,json=executionTimeMs,proto3" json:"execution_time_ms,omitempty"`
+	unknownFields   protoimpl.UnknownFields
+	sizeCache       protoimpl.SizeCache
+}
+
+func (x *PlanResult) Reset() {
+	*x = PlanResult{}
+	mi := &file_agent_proto_msgTypes[12]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *PlanResult) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PlanResult) ProtoMessage() {}
+
+func (x *PlanResult) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[12]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PlanResult.ProtoReflect.Descriptor instead.
+func (*PlanResult) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *PlanResult) GetPlanId() string {
+	if x != nil {
+		return x.PlanId
+	}
+	return ""
+}
+
+func (x *PlanResult) GetStatus() ExecutionStatus {
+	if x != nil {
+		return x.Status
+	}
+	return ExecutionStatus_EXECUTION_STATUS_UNSPECIFIED
+}
+
+func (x *PlanResult) GetStepResults() []*StepResult {
+	if x != nil {
+		return x.StepResults
+	}
+	return nil
+}
+
+func (x *PlanResult) GetFinalAnswer() string {
+	if x != nil {
+		return x.FinalAnswer
+	}
+	return ""
+}
+
+func (x *PlanResult) GetExecutionTimeMs() int64 {
+	if x != nil {
+		return x.ExecutionTimeMs
+	}
+	return 0
+}
+
+// StepResult contains individual step results
+type StepResult struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Step ID
+	StepId string `protobuf:"bytes,1,opt,name=step_id,json=stepId,proto3" json:"step_id,omitempty"`
+	// Step status
+	Status ExecutionStatus `protobuf:"varint,2,opt,name=status,proto3,enum=rag.v1.ExecutionStatus" json:"status,omitempty"`
+	// Step output
+	Output string `protobuf:"bytes,3,opt,name=output,proto3" json:"output,omitempty"`
+	// Error message if failed
+	Error string `protobuf:"bytes,4,opt,name=error,proto3" json:"error,omitempty"`
+	// Execution time
+	ExecutionTimeMs int64 `protobuf:"varint,5,opt,name=execution_time_ms,json=executionTimeMs,proto3" json:"execution_time_ms,omitempty"`
+	unknownFields   protoimpl.UnknownFields
+	sizeCache       protoimpl.SizeCache
+}
+
+func (x *StepResult) Reset() {
+	*x = StepResult{}
+	mi := &file_agent_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StepResult) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StepResult) ProtoMessage() {}
+
+func (x *StepResult) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StepResult.ProtoReflect.Descriptor instead.
+func (*StepResult) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *StepResult) GetStepId() string {
+	if x != nil {
+		return x.StepId
+	}
+	return ""
+}
+
+func (x *StepResult) GetStatus() ExecutionStatus {
+	if x != nil {
+		return x.Status
+	}
+	return ExecutionStatus_EXECUTION_STATUS_UNSPECIFIED
+}
+
+func (x *StepResult) GetOutput() string {
+	if x != nil {
+		return x.Output
+	}
+	return ""
+}
+
+func (x *StepResult) GetError() string {
+	if x != nil {
+		return x.Error
+	}
+	return ""
+}
+
+func (x *StepResult) GetExecutionTimeMs() int64 {
+	if x != nil {
+		return x.ExecutionTimeMs
+	}
+	return 0
+}
+
+// QueryStatusRequest to check query progress
+type QueryStatusRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Query ID
+	QueryId       string `protobuf:"bytes,1,opt,name=query_id,json=queryId,proto3" json:"query_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryStatusRequest) Reset() {
+	*x = QueryStatusRequest{}
+	mi := &file_agent_proto_msgTypes[14]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryStatusRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryStatusRequest) ProtoMessage() {}
+
+func (x *QueryStatusRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[14]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryStatusRequest.ProtoReflect.Descriptor instead.
+func (*QueryStatusRequest) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{14}
+}
+
+func (x *QueryStatusRequest) GetQueryId() string {
+	if x != nil {
+		return x.QueryId
+	}
+	return ""
+}
+
+// QueryStatus represents current query state
+type QueryStatus struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Query ID
+	QueryId string `protobuf:"bytes,1,opt,name=query_id,json=queryId,proto3" json:"query_id,omitempty"`
+	// Current status
+	Status ExecutionStatus `protobuf:"varint,2,opt,name=status,proto3,enum=rag.v1.ExecutionStatus" json:"status,omitempty"`
+	// Progress percentage (0-100)
+	Progress int32 `protobuf:"varint,3,opt,name=progress,proto3" json:"progress,omitempty"`
+	// Current step description
+	CurrentStep   string `protobuf:"bytes,4,opt,name=current_step,json=currentStep,proto3" json:"current_step,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *QueryStatus) Reset() {
+	*x = QueryStatus{}
+	mi := &file_agent_proto_msgTypes[15]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *QueryStatus) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*QueryStatus) ProtoMessage() {}
+
+func (x *QueryStatus) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[15]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use QueryStatus.ProtoReflect.Descriptor instead.
+func (*QueryStatus) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{15}
+}
+
+func (x *QueryStatus) GetQueryId() string {
+	if x != nil {
+		return x.QueryId
+	}
+	return ""
+}
+
+func (x *QueryStatus) GetStatus() ExecutionStatus {
+	if x != nil {
+		return x.Status
+	}
+	return ExecutionStatus_EXECUTION_STATUS_UNSPECIFIED
+}
+
+func (x *QueryStatus) GetProgress() int32 {
+	if x != nil {
+		return x.Progress
+	}
+	return 0
+}
+
+func (x *QueryStatus) GetCurrentStep() string {
+	if x != nil {
+		return x.CurrentStep
+	}
+	return ""
+}
+
+// SecurityContext for request authentication/authorization
+type SecurityContext struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// User ID
+	UserId string `protobuf:"bytes,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
+	// User roles
+	Roles []string `protobuf:"bytes,2,rep,name=roles,proto3" json:"roles,omitempty"`
+	// Tenant ID for multi-tenancy
+	TenantId string `protobuf:"bytes,3,opt,name=tenant_id,json=tenantId,proto3" json:"tenant_id,omitempty"`
+	// Additional claims
+	Claims        map[string]string `protobuf:"bytes,4,rep,name=claims,proto3" json:"claims,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *SecurityContext) Reset() {
+	*x = SecurityContext{}
+	mi := &file_agent_proto_msgTypes[16]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *SecurityContext) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SecurityContext) ProtoMessage() {}
+
+func (x *SecurityContext) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_proto_msgTypes[16]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SecurityContext.ProtoReflect.Descriptor instead.
+func (*SecurityContext) Descriptor() ([]byte, []int) {
+	return file_agent_proto_rawDescGZIP(), []int{16}
+}
+
+func (x *SecurityContext) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+func (x *SecurityContext) GetRoles() []string {
+	if x != nil {
+		return x.Roles
+	}
+	return nil
+}
+
+func (x *SecurityContext) GetTenantId() string {
+	if x != nil {
+		return x.TenantId
+	}
+	return ""
+}
+
+func (x *SecurityContext) GetClaims() map[string]string {
+	if x != nil {
+		return x.Claims
+	}
+	return nil
+}
+
+var File_agent_proto protoreflect.FileDescriptor
+
+const file_agent_proto_rawDesc = "" +
+	"\n" +
+	"\vagent.proto\x12\x06rag.v1\"\xcd\x02\n" +
+	"\fQueryRequest\x12\x14\n" +
+	"\x05query\x18\x01 \x01(\tR\x05query\x12\x1d\n" +
+	"\n" +
+	"session_id\x18\x02 \x01(\tR\tsessionId\x12\x17\n" +
+	"\auser_id\x18\x03 \x01(\tR\x06userId\x12B\n" +
+	"\x14conversation_history\x18\x04 \x03(\v2\x0f.rag.v1.MessageR\x13conversationHistory\x12>\n" +
+	"\bmetadata\x18\x05 \x03(\v2\".rag.v1.QueryRequest.MetadataEntryR\bmetadata\x12.\n" +
+	"\aoptions\x18\x06 \x01(\v2\x14.rag.v1.QueryOptionsR\aoptions\x1a;\n" +
+	"\rMetadataEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" +
+	"\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\xdd\x01\n" +
+	"\fQueryOptions\x12\x1f\n" +
+	"\vmax_sources\x18\x01 \x01(\x05R\n" +
+	"maxSources\x12\x1b\n" +
+	"\tuse_cache\x18\x02 \x01(\bR\buseCache\x12%\n" +
+	"\x0eenable_agentic\x18\x03 \x01(\bR\renableAgentic\x12'\n" +
+	"\x0fknowledge_bases\x18\x04 \x03(\tR\x0eknowledgeBases\x12 \n" +
+	"\vtemperature\x18\x05 \x01(\x02R\vtemperature\x12\x1d\n" +
+	"\n" +
+	"max_tokens\x18\x06 \x01(\x05R\tmaxTokens\"\xd4\x01\n" +
+	"\rQueryResponse\x12\x16\n" +
+	"\x06answer\x18\x01 \x01(\tR\x06answer\x12(\n" +
+	"\asources\x18\x02 \x03(\v2\x0e.rag.v1.SourceR\asources\x12\x1e\n" +
+	"\n" +
+	"confidence\x18\x03 \x01(\x02R\n" +
+	"confidence\x121\n" +
+	"\bmetadata\x18\x04 \x01(\v2\x15.rag.v1.QueryMetadataR\bmetadata\x12.\n" +
+	"\x13follow_up_questions\x18\x05 \x03(\tR\x11followUpQuestions\"\x9a\x01\n" +
+	"\x12QueryResponseChunk\x12%\n" +
+	"\x04type\x18\x01 \x01(\x0e2\x11.rag.v1.ChunkTypeR\x04type\x12\x18\n" +
+	"\acontent\x18\x02 \x01(\tR\acontent\x12(\n" +
+	"\asources\x18\x03 \x03(\v2\x0e.rag.v1.SourceR\asources\x12\x19\n" +
+	"\bis_final\x18\x04 \x01(\bR\aisFinal\"\x83\x02\n" +
+	"\x06Source\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n" +
+	"\x05title\x18\x02 \x01(\tR\x05title\x12\x18\n" +
+	"\acontent\x18\x03 \x01(\tR\acontent\x12\x10\n" +
+	"\x03url\x18\x04 \x01(\tR\x03url\x12\x14\n" +
+	"\x05score\x18\x05 \x01(\x02R\x05score\x128\n" +
+	"\bmetadata\x18\x06 \x03(\v2\x1c.rag.v1.Source.MetadataEntryR\bmetadata\x12\x1a\n" +
+	"\blocation\x18\a \x01(\tR\blocation\x1a;\n" +
+	"\rMetadataEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" +
+	"\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"j\n" +
+	"\aMessage\x12'\n" +
+	"\x04role\x18\x01 \x01(\x0e2\x13.rag.v1.MessageRoleR\x04role\x12\x18\n" +
+	"\acontent\x18\x02 \x01(\tR\acontent\x12\x1c\n" +
+	"\ttimestamp\x18\x03 \x01(\x03R\ttimestamp\"\xec\x01\n" +
+	"\rQueryMetadata\x12,\n" +
+	"\x12processing_time_ms\x18\x01 \x01(\x03R\x10processingTimeMs\x12)\n" +
+	"\x10chunks_retrieved\x18\x02 \x01(\x05R\x0fchunksRetrieved\x12\x1f\n" +
+	"\vtokens_used\x18\x03 \x01(\x05R\n" +
+	"tokensUsed\x12\x1b\n" +
+	"\tcache_hit\x18\x04 \x01(\bR\bcacheHit\x12)\n" +
+	"\x10routing_strategy\x18\x05 \x01(\tR\x0froutingStrategy\x12\x19\n" +
+	"\btrace_id\x18\x06 \x01(\tR\atraceId\"\xb2\x01\n" +
+	"\x12CreateAgentRequest\x12\x12\n" +
+	"\x04name\x18\x01 \x01(\tR\x04name\x12 \n" +
+	"\vdescription\x18\x02 \x01(\tR\vdescription\x12#\n" +
+	"\rsystem_prompt\x18\x03 \x01(\tR\fsystemPrompt\x12\x14\n" +
+	"\x05tools\x18\x04 \x03(\tR\x05tools\x12+\n" +
+	"\x06config\x18\x05 \x01(\v2\x13.rag.v1.AgentConfigR\x06config\"\x99\x01\n" +
+	"\x05Agent\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x12\n" +
+	"\x04name\x18\x02 \x01(\tR\x04name\x12 \n" +
+	"\vdescription\x18\x03 \x01(\tR\vdescription\x12\x1d\n" +
+	"\n" +
+	"created_at\x18\x04 \x01(\x03R\tcreatedAt\x12+\n" +
+	"\x06config\x18\x05 \x01(\v2\x13.rag.v1.AgentConfigR\x06config\"\x95\x01\n" +
+	"\vAgentConfig\x12\x14\n" +
+	"\x05model\x18\x01 \x01(\tR\x05model\x12 \n" +
+	"\vtemperature\x18\x02 \x01(\x02R\vtemperature\x12%\n" +
+	"\x0emax_iterations\x18\x03 \x01(\x05R\rmaxIterations\x12'\n" +
+	"\x0ftimeout_seconds\x18\x04 \x01(\x05R\x0etimeoutSeconds\"b\n" +
+	"\rExecutionPlan\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n" +
+	"\x05query\x18\x02 \x01(\tR\x05query\x12+\n" +
+	"\x05steps\x18\x03 \x03(\v2\x15.rag.v1.ExecutionStepR\x05steps\"\xb5\x01\n" +
+	"\rExecutionStep\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12$\n" +
+	"\x04type\x18\x02 \x01(\x0e2\x10.rag.v1.StepTypeR\x04type\x12 \n" +
+	"\vdescription\x18\x03 \x01(\tR\vdescription\x12\x12\n" +
+	"\x04tool\x18\x04 \x01(\tR\x04tool\x12\x14\n" +
+	"\x05input\x18\x05 \x01(\tR\x05input\x12\"\n" +
+	"\fdependencies\x18\x06 \x03(\tR\fdependencies\"\xdc\x01\n" +
+	"\n" +
+	"PlanResult\x12\x17\n" +
+	"\aplan_id\x18\x01 \x01(\tR\x06planId\x12/\n" +
+	"\x06status\x18\x02 \x01(\x0e2\x17.rag.v1.ExecutionStatusR\x06status\x125\n" +
+	"\fstep_results\x18\x03 \x03(\v2\x12.rag.v1.StepResultR\vstepResults\x12!\n" +
+	"\ffinal_answer\x18\x04 \x01(\tR\vfinalAnswer\x12*\n" +
+	"\x11execution_time_ms\x18\x05 \x01(\x03R\x0fexecutionTimeMs\"\xb0\x01\n" +
+	"\n" +
+	"StepResult\x12\x17\n" +
+	"\astep_id\x18\x01 \x01(\tR\x06stepId\x12/\n" +
+	"\x06status\x18\x02 \x01(\x0e2\x17.rag.v1.ExecutionStatusR\x06status\x12\x16\n" +
+	"\x06output\x18\x03 \x01(\tR\x06output\x12\x14\n" +
+	"\x05error\x18\x04 \x01(\tR\x05error\x12*\n" +
+	"\x11execution_time_ms\x18\x05 \x01(\x03R\x0fexecutionTimeMs\"/\n" +
+	"\x12QueryStatusRequest\x12\x19\n" +
+	"\bquery_id\x18\x01 \x01(\tR\aqueryId\"\x98\x01\n" +
+	"\vQueryStatus\x12\x19\n" +
+	"\bquery_id\x18\x01 \x01(\tR\aqueryId\x12/\n" +
+	"\x06status\x18\x02 \x01(\x0e2\x17.rag.v1.ExecutionStatusR\x06status\x12\x1a\n" +
+	"\bprogress\x18\x03 \x01(\x05R\bprogress\x12!\n" +
+	"\fcurrent_step\x18\x04 \x01(\tR\vcurrentStep\"\xd5\x01\n" +
+	"\x0fSecurityContext\x12\x17\n" +
+	"\auser_id\x18\x01 \x01(\tR\x06userId\x12\x14\n" +
+	"\x05roles\x18\x02 \x03(\tR\x05roles\x12\x1b\n" +
+	"\ttenant_id\x18\x03 \x01(\tR\btenantId\x12;\n" +
+	"\x06claims\x18\x04 \x03(\v2#.rag.v1.SecurityContext.ClaimsEntryR\x06claims\x1a9\n" +
+	"\vClaimsEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" +
+	"\x05value\x18\x02 \x01(\tR\x05value:\x028\x01*\xa4\x01\n" +
+	"\tChunkType\x12\x1a\n" +
+	"\x16CHUNK_TYPE_UNSPECIFIED\x10\x00\x12\x17\n" +
+	"\x13CHUNK_TYPE_THINKING\x10\x01\x12\x18\n" +
+	"\x14CHUNK_TYPE_RETRIEVAL\x10\x02\x12\x19\n" +
+	"\x15CHUNK_TYPE_GENERATION\x10\x03\x12\x17\n" +
+	"\x13CHUNK_TYPE_COMPLETE\x10\x04\x12\x14\n" +
+	"\x10CHUNK_TYPE_ERROR\x10\x05*w\n" +
+	"\vMessageRole\x12\x1c\n" +
+	"\x18MESSAGE_ROLE_UNSPECIFIED\x10\x00\x12\x15\n" +
+	"\x11MESSAGE_ROLE_USER\x10\x01\x12\x1a\n" +
+	"\x16MESSAGE_ROLE_ASSISTANT\x10\x02\x12\x17\n" +
+	"\x13MESSAGE_ROLE_SYSTEM\x10\x03*\x84\x01\n" +
+	"\bStepType\x12\x19\n" +
+	"\x15STEP_TYPE_UNSPECIFIED\x10\x00\x12\x14\n" +
+	"\x10STEP_TYPE_SEARCH\x10\x01\x12\x15\n" +
+	"\x11STEP_TYPE_ANALYZE\x10\x02\x12\x18\n" +
+	"\x14STEP_TYPE_SYNTHESIZE\x10\x03\x12\x16\n" +
+	"\x12STEP_TYPE_VALIDATE\x10\x04*\xac\x01\n" +
+	"\x0fExecutionStatus\x12 \n" +
+	"\x1cEXECUTION_STATUS_UNSPECIFIED\x10\x00\x12\x1c\n" +
+	"\x18EXECUTION_STATUS_PENDING\x10\x01\x12\x1c\n" +
+	"\x18EXECUTION_STATUS_RUNNING\x10\x02\x12\x1e\n" +
+	"\x1aEXECUTION_STATUS_COMPLETED\x10\x03\x12\x1b\n" +
+	"\x17EXECUTION_STATUS_FAILED\x10\x042\xcc\x02\n" +
+	"\fAgentService\x12;\n" +
+	"\fProcessQuery\x12\x14.rag.v1.QueryRequest\x1a\x15.rag.v1.QueryResponse\x12H\n" +
+	"\x12ProcessQueryStream\x12\x14.rag.v1.QueryRequest\x1a\x1a.rag.v1.QueryResponseChunk0\x01\x128\n" +
+	"\vCreateAgent\x12\x1a.rag.v1.CreateAgentRequest\x1a\r.rag.v1.Agent\x128\n" +
+	"\vExecutePlan\x12\x15.rag.v1.ExecutionPlan\x1a\x12.rag.v1.PlanResult\x12A\n" +
+	"\x0eGetQueryStatus\x12\x1a.rag.v1.QueryStatusRequest\x1a\x13.rag.v1.QueryStatusB6Z4github.com/AmaniQuery/amaniquery/pkg/proto/gen/ragv1b\x06proto3"
+
+var (
+	file_agent_proto_rawDescOnce sync.Once
+	file_agent_proto_rawDescData []byte
+)
+
+func file_agent_proto_rawDescGZIP() []byte {
+	file_agent_proto_rawDescOnce.Do(func() {
+		file_agent_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_agent_proto_rawDesc), len(file_agent_proto_rawDesc)))
+	})
+	return file_agent_proto_rawDescData
+}
+
+var file_agent_proto_enumTypes = make([]protoimpl.EnumInfo, 4)
+var file_agent_proto_msgTypes = make([]protoimpl.MessageInfo, 20)
+var file_agent_proto_goTypes = []any{
+	(ChunkType)(0),             // 0: rag.v1.ChunkType
+	(MessageRole)(0),           // 1: rag.v1.MessageRole
+	(StepType)(0),              // 2: rag.v1.StepType
+	(ExecutionStatus)(0),       // 3: rag.v1.ExecutionStatus
+	(*QueryRequest)(nil),       // 4: rag.v1.QueryRequest
+	(*QueryOptions)(nil),       // 5: rag.v1.QueryOptions
+	(*QueryResponse)(nil),      // 6: rag.v1.QueryResponse
+	(*QueryResponseChunk)(nil), // 7: rag.v1.QueryResponseChunk
+	(*Source)(nil),             // 8: rag.v1.Source
+	(*Message)(nil),            // 9: rag.v1.Message
+	(*QueryMetadata)(nil),      // 10: rag.v1.QueryMetadata
+	(*CreateAgentRequest)(nil), // 11: rag.v1.CreateAgentRequest
+	(*Agent)(nil),              // 12: rag.v1.Agent
+	(*AgentConfig)(nil),        // 13: rag.v1.AgentConfig
+	(*ExecutionPlan)(nil),      // 14: rag.v1.ExecutionPlan
+	(*ExecutionStep)(nil),      // 15: rag.v1.ExecutionStep
+	(*PlanResult)(nil),         // 16: rag.v1.PlanResult
+	(*StepResult)(nil),         // 17: rag.v1.StepResult
+	(*QueryStatusRequest)(nil), // 18: rag.v1.QueryStatusRequest
+	(*QueryStatus)(nil),        // 19: rag.v1.QueryStatus
+	(*SecurityContext)(nil),    // 20: rag.v1.SecurityContext
+	nil,                        // 21: rag.v1.QueryRequest.MetadataEntry
+	nil,                        // 22: rag.v1.Source.MetadataEntry
+	nil,                        // 23: rag.v1.SecurityContext.ClaimsEntry
+}
+var file_agent_proto_depIdxs = []int32{
+	9,  // 0: rag.v1.QueryRequest.conversation_history:type_name -> rag.v1.Message
+	21, // 1: rag.v1.QueryRequest.metadata:type_name -> rag.v1.QueryRequest.MetadataEntry
+	5,  // 2: rag.v1.QueryRequest.options:type_name -> rag.v1.QueryOptions
+	8,  // 3: rag.v1.QueryResponse.sources:type_name -> rag.v1.Source
+	10, // 4: rag.v1.QueryResponse.metadata:type_name -> rag.v1.QueryMetadata
+	0,  // 5: rag.v1.QueryResponseChunk.type:type_name -> rag.v1.ChunkType
+	8,  // 6: rag.v1.QueryResponseChunk.sources:type_name -> rag.v1.Source
+	22, // 7: rag.v1.Source.metadata:type_name -> rag.v1.Source.MetadataEntry
+	1,  // 8: rag.v1.Message.role:type_name -> rag.v1.MessageRole
+	13, // 9: rag.v1.CreateAgentRequest.config:type_name -> rag.v1.AgentConfig
+	13, // 10: rag.v1.Agent.config:type_name -> rag.v1.AgentConfig
+	15, // 11: rag.v1.ExecutionPlan.steps:type_name -> rag.v1.ExecutionStep
+	2,  // 12: rag.v1.ExecutionStep.type:type_name -> rag.v1.StepType
+	3,  // 13: rag.v1.PlanResult.status:type_name -> rag.v1.ExecutionStatus
+	17, // 14: rag.v1.PlanResult.step_results:type_name -> rag.v1.StepResult
+	3,  // 15: rag.v1.StepResult.status:type_name -> rag.v1.ExecutionStatus
+	3,  // 16: rag.v1.QueryStatus.status:type_name -> rag.v1.ExecutionStatus
+	23, // 17: rag.v1.SecurityContext.claims:type_name -> rag.v1.SecurityContext.ClaimsEntry
+	4,  // 18: rag.v1.AgentService.ProcessQuery:input_type -> rag.v1.QueryRequest
+	4,  // 19: rag.v1.AgentService.ProcessQueryStream:input_type -> rag.v1.QueryRequest
+	11, // 20: rag.v1.AgentService.CreateAgent:input_type -> rag.v1.CreateAgentRequest
+	14, // 21: rag.v1.AgentService.ExecutePlan:input_type -> rag.v1.ExecutionPlan
+	18, // 22: rag.v1.AgentService.GetQueryStatus:input_type -> rag.v1.QueryStatusRequest
+	6,  // 23: rag.v1.AgentService.ProcessQuery:output_type -> rag.v1.QueryResponse
+	7,  // 24: rag.v1.AgentService.ProcessQueryStream:output_type -> rag.v1.QueryResponseChunk
+	12, // 25: rag.v1.AgentService.CreateAgent:output_type -> rag.v1.Agent
+	16, // 26: rag.v1.AgentService.ExecutePlan:output_type -> rag.v1.PlanResult
+	19, // 27: rag.v1.AgentService.GetQueryStatus:output_type -> rag.v1.QueryStatus
+	23, // [23:28] is the sub-list for method output_type
+	18, // [18:23] is the sub-list for method input_type
+	18, // [18:18] is the sub-list for extension type_name
+	18, // [18:18] is the sub-list for extension extendee
+	0,  // [0:18] is the sub-list for field type_name
+}
+
+func init() { file_agent_proto_init() }
+func file_agent_proto_init() {
+	if File_agent_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_agent_proto_rawDesc), len(file_agent_proto_rawDesc)),
+			NumEnums:      4,
+			NumMessages:   20,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_agent_proto_goTypes,
+		DependencyIndexes: file_agent_proto_depIdxs,
+		EnumInfos:         file_agent_proto_enumTypes,
+		MessageInfos:      file_agent_proto_msgTypes,
+	}.Build()
+	File_agent_proto = out.File
+	file_agent_proto_goTypes = nil
+	file_agent_proto_depIdxs = nil
+}

agent_grpc.pb.go

@@ -0,0 +1,291 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.6.0
+// - protoc             v6.33.2
+// source: agent.proto
+
+package ragv1
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	AgentService_ProcessQuery_FullMethodName       = "/rag.v1.AgentService/ProcessQuery"
+	AgentService_ProcessQueryStream_FullMethodName = "/rag.v1.AgentService/ProcessQueryStream"
+	AgentService_CreateAgent_FullMethodName        = "/rag.v1.AgentService/CreateAgent"
+	AgentService_ExecutePlan_FullMethodName        = "/rag.v1.AgentService/ExecutePlan"
+	AgentService_GetQueryStatus_FullMethodName     = "/rag.v1.AgentService/GetQueryStatus"
+)
+
+// AgentServiceClient is the client API for AgentService service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// AgentService handles query processing and orchestration
+type AgentServiceClient interface {
+	// Process a single query and return a complete response
+	ProcessQuery(ctx context.Context, in *QueryRequest, opts ...grpc.CallOption) (*QueryResponse, error)
+	// Process a query with streaming response for real-time updates
+	ProcessQueryStream(ctx context.Context, in *QueryRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[QueryResponseChunk], error)
+	// Create a new agent with specific configuration
+	CreateAgent(ctx context.Context, in *CreateAgentRequest, opts ...grpc.CallOption) (*Agent, error)
+	// Execute a pre-defined execution plan
+	ExecutePlan(ctx context.Context, in *ExecutionPlan, opts ...grpc.CallOption) (*PlanResult, error)
+	// Get the status of an ongoing query
+	GetQueryStatus(ctx context.Context, in *QueryStatusRequest, opts ...grpc.CallOption) (*QueryStatus, error)
+}
+
+type agentServiceClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewAgentServiceClient(cc grpc.ClientConnInterface) AgentServiceClient {
+	return &agentServiceClient{cc}
+}
+
+func (c *agentServiceClient) ProcessQuery(ctx context.Context, in *QueryRequest, opts ...grpc.CallOption) (*QueryResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(QueryResponse)
+	err := c.cc.Invoke(ctx, AgentService_ProcessQuery_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *agentServiceClient) ProcessQueryStream(ctx context.Context, in *QueryRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[QueryResponseChunk], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &AgentService_ServiceDesc.Streams[0], AgentService_ProcessQueryStream_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[QueryRequest, QueryResponseChunk]{ClientStream: stream}
+	if err := x.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := x.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type AgentService_ProcessQueryStreamClient = grpc.ServerStreamingClient[QueryResponseChunk]
+
+func (c *agentServiceClient) CreateAgent(ctx context.Context, in *CreateAgentRequest, opts ...grpc.CallOption) (*Agent, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(Agent)
+	err := c.cc.Invoke(ctx, AgentService_CreateAgent_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *agentServiceClient) ExecutePlan(ctx context.Context, in *ExecutionPlan, opts ...grpc.CallOption) (*PlanResult, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(PlanResult)
+	err := c.cc.Invoke(ctx, AgentService_ExecutePlan_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *agentServiceClient) GetQueryStatus(ctx context.Context, in *QueryStatusRequest, opts ...grpc.CallOption) (*QueryStatus, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(QueryStatus)
+	err := c.cc.Invoke(ctx, AgentService_GetQueryStatus_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// AgentServiceServer is the server API for AgentService service.
+// All implementations must embed UnimplementedAgentServiceServer
+// for forward compatibility.
+//
+// AgentService handles query processing and orchestration
+type AgentServiceServer interface {
+	// Process a single query and return a complete response
+	ProcessQuery(context.Context, *QueryRequest) (*QueryResponse, error)
+	// Process a query with streaming response for real-time updates
+	ProcessQueryStream(*QueryRequest, grpc.ServerStreamingServer[QueryResponseChunk]) error
+	// Create a new agent with specific configuration
+	CreateAgent(context.Context, *CreateAgentRequest) (*Agent, error)
+	// Execute a pre-defined execution plan
+	ExecutePlan(context.Context, *ExecutionPlan) (*PlanResult, error)
+	// Get the status of an ongoing query
+	GetQueryStatus(context.Context, *QueryStatusRequest) (*QueryStatus, error)
+	mustEmbedUnimplementedAgentServiceServer()
+}
+
+// UnimplementedAgentServiceServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedAgentServiceServer struct{}
+
+func (UnimplementedAgentServiceServer) ProcessQuery(context.Context, *QueryRequest) (*QueryResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method ProcessQuery not implemented")
+}
+func (UnimplementedAgentServiceServer) ProcessQueryStream(*QueryRequest, grpc.ServerStreamingServer[QueryResponseChunk]) error {
+	return status.Error(codes.Unimplemented, "method ProcessQueryStream not implemented")
+}
+func (UnimplementedAgentServiceServer) CreateAgent(context.Context, *CreateAgentRequest) (*Agent, error) {
+	return nil, status.Error(codes.Unimplemented, "method CreateAgent not implemented")
+}
+func (UnimplementedAgentServiceServer) ExecutePlan(context.Context, *ExecutionPlan) (*PlanResult, error) {
+	return nil, status.Error(codes.Unimplemented, "method ExecutePlan not implemented")
+}
+func (UnimplementedAgentServiceServer) GetQueryStatus(context.Context, *QueryStatusRequest) (*QueryStatus, error) {
+	return nil, status.Error(codes.Unimplemented, "method GetQueryStatus not implemented")
+}
+func (UnimplementedAgentServiceServer) mustEmbedUnimplementedAgentServiceServer() {}
+func (UnimplementedAgentServiceServer) testEmbeddedByValue()                      {}
+
+// UnsafeAgentServiceServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to AgentServiceServer will
+// result in compilation errors.
+type UnsafeAgentServiceServer interface {
+	mustEmbedUnimplementedAgentServiceServer()
+}
+
+func RegisterAgentServiceServer(s grpc.ServiceRegistrar, srv AgentServiceServer) {
+	// If the following call panics, it indicates UnimplementedAgentServiceServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&AgentService_ServiceDesc, srv)
+}
+
+func _AgentService_ProcessQuery_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(QueryRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServiceServer).ProcessQuery(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: AgentService_ProcessQuery_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServiceServer).ProcessQuery(ctx, req.(*QueryRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _AgentService_ProcessQueryStream_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(QueryRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(AgentServiceServer).ProcessQueryStream(m, &grpc.GenericServerStream[QueryRequest, QueryResponseChunk]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type AgentService_ProcessQueryStreamServer = grpc.ServerStreamingServer[QueryResponseChunk]
+
+func _AgentService_CreateAgent_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(CreateAgentRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServiceServer).CreateAgent(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: AgentService_CreateAgent_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServiceServer).CreateAgent(ctx, req.(*CreateAgentRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _AgentService_ExecutePlan_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ExecutionPlan)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServiceServer).ExecutePlan(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: AgentService_ExecutePlan_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServiceServer).ExecutePlan(ctx, req.(*ExecutionPlan))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _AgentService_GetQueryStatus_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(QueryStatusRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServiceServer).GetQueryStatus(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: AgentService_GetQueryStatus_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServiceServer).GetQueryStatus(ctx, req.(*QueryStatusRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+// AgentService_ServiceDesc is the grpc.ServiceDesc for AgentService service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var AgentService_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "rag.v1.AgentService",
+	HandlerType: (*AgentServiceServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{
+			MethodName: "ProcessQuery",
+			Handler:    _AgentService_ProcessQuery_Handler,
+		},
+		{
+			MethodName: "CreateAgent",
+			Handler:    _AgentService_CreateAgent_Handler,
+		},
+		{
+			MethodName: "ExecutePlan",
+			Handler:    _AgentService_ExecutePlan_Handler,
+		},
+		{
+			MethodName: "GetQueryStatus",
+			Handler:    _AgentService_GetQueryStatus_Handler,
+		},
+	},
+	Streams: []grpc.StreamDesc{
+		{
+			StreamName:    "ProcessQueryStream",
+			Handler:       _AgentService_ProcessQueryStream_Handler,
+			ServerStreams: true,
+		},
+	},
+	Metadata: "agent.proto",
+}

cmd/agent-server/main.go

@@ -0,0 +1,270 @@
+// Package main provides the entry point for the Agent Orchestrator service.
+// This is the primary service that coordinates query processing and orchestrates
+// interactions between the Retriever and Generator services.
+package main
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/AmaniQuery/amaniquery/internal/agent"
+	"github.com/AmaniQuery/amaniquery/internal/cache"
+	"github.com/AmaniQuery/amaniquery/internal/generator"
+	"github.com/AmaniQuery/amaniquery/internal/generator/llm"
+	"github.com/AmaniQuery/amaniquery/internal/retriever"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/keyword"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/vector"
+	"github.com/AmaniQuery/amaniquery/internal/router"
+	"github.com/AmaniQuery/amaniquery/pkg/config"
+	"github.com/AmaniQuery/amaniquery/pkg/observability"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/health"
+	"google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/reflection"
+)
+
+func main() {
+	// Load configuration
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to load configuration: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Initialize logger
+	logger, err := observability.NewLogger(cfg.Observability.LogLevel, cfg.Observability.LogFormat)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to initialize logger: %v\n", err)
+		os.Exit(1)
+	}
+	defer logger.Sync()
+
+	logger.Info("starting AmaniQuery agent server",
+		zap.String("version", cfg.Version),
+		zap.String("environment", cfg.Environment),
+		zap.Strings("llm_providers", cfg.LLM.GetConfiguredProviders()),
+	)
+
+	// Initialize observability (tracing + metrics)
+	tracingShutdown, err := observability.InitProvider(observability.Config{
+		ServiceName:     "amaniquery-agent",
+		ServiceVersion:  cfg.Version,
+		TracingEnabled:  cfg.Observability.TracingEnabled,
+		TracingEndpoint: cfg.Observability.TracingEndpoint,
+		MetricsEnabled:  cfg.Observability.MetricsEnabled,
+		MetricsPort:     cfg.Observability.MetricsPort,
+	})
+	if err != nil {
+		logger.Warn("failed to initialize tracing, continuing without", zap.Error(err))
+	} else {
+		defer tracingShutdown(context.Background())
+	}
+
+	// Start metrics server
+	if cfg.Observability.MetricsEnabled {
+		metricsServer := observability.StartMetricsServer(cfg.Observability.MetricsPort)
+		defer metricsServer.Shutdown(context.Background())
+		logger.Info("metrics server started", zap.Int("port", cfg.Observability.MetricsPort))
+	}
+
+	// Build dependencies
+	deps, err := buildDependencies(cfg, logger)
+	if err != nil {
+		logger.Fatal("failed to build dependencies", zap.Error(err))
+	}
+	defer deps.Close()
+
+	// Create gRPC server with interceptors
+	grpcServer := grpc.NewServer(
+		grpc.ChainUnaryInterceptor(
+			observability.UnaryServerInterceptor(),
+			agent.LoggingInterceptor(logger),
+			agent.RecoveryInterceptor(),
+		),
+		grpc.ChainStreamInterceptor(
+			observability.StreamServerInterceptor(),
+		),
+	)
+
+	// Register Agent service
+	agentServer := agent.NewServer(deps, logger)
+	agent.RegisterAgentServiceServer(grpcServer, agentServer)
+
+	// Register health service
+	healthServer := health.NewServer()
+	grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
+	healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
+
+	// Enable reflection for grpcurl
+	reflection.Register(grpcServer)
+
+	// Start gRPC server
+	addr := fmt.Sprintf(":%d", cfg.Server.GRPCPort)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		logger.Fatal("failed to listen", zap.String("addr", addr), zap.Error(err))
+	}
+
+	logger.Info("gRPC server starting",
+		zap.String("addr", addr),
+		zap.Int("http_port", cfg.Server.HTTPPort),
+	)
+
+	// Graceful shutdown handling
+	errChan := make(chan error, 1)
+	go func() {
+		errChan <- grpcServer.Serve(listener)
+	}()
+
+	// Wait for shutdown signal
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case err := <-errChan:
+		logger.Fatal("server error", zap.Error(err))
+	case sig := <-quit:
+		logger.Info("shutting down", zap.String("signal", sig.String()))
+	}
+
+	// Graceful shutdown with timeout
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.Server.GracefulTimeout)
+	defer cancel()
+
+	healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_NOT_SERVING)
+	grpcServer.GracefulStop()
+
+	logger.Info("server stopped gracefully")
+	_ = ctx // used for cleanup operations
+}
+
+// buildDependencies initializes all service dependencies
+func buildDependencies(cfg *config.Config, logger *zap.Logger) (*agent.Dependencies, error) {
+	deps := &agent.Dependencies{}
+
+	// Initialize vector store client (Qdrant)
+	logger.Info("connecting to vector store",
+		zap.String("type", cfg.VectorStore.Type),
+		zap.String("host", cfg.VectorStore.Host),
+		zap.Int("port", cfg.VectorStore.Port),
+	)
+	vectorClient, err := vector.NewQdrantClient(vector.Config{
+		Host:       cfg.VectorStore.Host,
+		Port:       cfg.VectorStore.Port,
+		APIKey:     cfg.VectorStore.APIKey,
+		Collection: cfg.VectorStore.Collection,
+		Dimension:  cfg.VectorStore.Dimension,
+		Distance:   cfg.VectorStore.Distance,
+	})
+	if err != nil {
+		logger.Warn("failed to connect to vector store, continuing without", zap.Error(err))
+	} else {
+		deps.VectorStore = vectorClient
+		logger.Info("connected to vector store")
+	}
+
+	// Initialize cache
+	logger.Info("connecting to cache", zap.String("url", cfg.Cache.RedisURL))
+	cacheClient, err := cache.New(cache.Config{
+		RedisURL:   cfg.Cache.RedisURL,
+		LocalSize:  cfg.Cache.LocalSize,
+		TTL:        cfg.Cache.TTL,
+		MaxRetries: cfg.Cache.MaxRetries,
+		PoolSize:   cfg.Cache.PoolSize,
+	})
+	if err != nil {
+		logger.Warn("failed to initialize cache, continuing without", zap.Error(err))
+	} else {
+		deps.Cache = cacheClient
+		logger.Info("cache initialized")
+	}
+
+	// Initialize embedding client
+	logger.Info("initializing embedding client",
+		zap.String("provider", cfg.Embedding.Provider),
+		zap.String("model", cfg.Embedding.Model),
+	)
+	embeddingClient := generator.NewOpenAIEmbeddingClient(generator.EmbeddingConfig{
+		Provider:   cfg.Embedding.Provider,
+		APIKey:     cfg.Embedding.APIKey,
+		Model:      cfg.Embedding.Model,
+		Dimension:  cfg.Embedding.Dimension,
+		BatchSize:  cfg.Embedding.BatchSize,
+		Timeout:    30 * time.Second,
+		MaxRetries: 3,
+	})
+	deps.EmbeddingClient = embeddingClient
+	logger.Info("embedding client initialized")
+
+	// Initialize multi-provider LLM client with fallback
+	// Fallback order: Gemini → Moonshot → Ollama → OpenAI → Anthropic
+	logger.Info("initializing LLM client with fallback",
+		zap.Strings("providers", cfg.LLM.GetConfiguredProviders()),
+	)
+	llmClient := llm.NewFallbackClient(llm.Config{
+		GeminiAPIKey:    cfg.LLM.GeminiAPIKey,
+		MoonshotAPIKey:  cfg.LLM.MoonshotAPIKey,
+		OllamaBaseURL:   cfg.LLM.OllamaBaseURL,
+		OpenAIAPIKey:    cfg.LLM.OpenAIAPIKey,
+		AnthropicAPIKey: cfg.LLM.AnthropicAPIKey,
+		DefaultModel:    cfg.LLM.DefaultModel,
+		MaxTokens:       cfg.LLM.MaxTokens,
+		Temperature:     cfg.LLM.Temperature,
+		Timeout:         cfg.LLM.Timeout,
+		MaxRetries:      cfg.LLM.MaxRetries,
+		EnableFallback:  cfg.LLM.EnableFallback,
+		Logger:          logger,
+	})
+	deps.LLMClient = llmClient
+	logger.Info("LLM client initialized",
+		zap.Int("provider_count", len(llmClient.GetAvailableProviders())),
+		zap.Strings("available_providers", toStringSlice(llmClient.GetAvailableProviders())),
+	)
+
+	// Initialize keyword search engine
+	logger.Info("initializing keyword search engine")
+	keywordEngine, err := keyword.NewBleveEngine(keyword.Config{
+		InMemory: true, // Use in-memory for development
+	})
+	if err != nil {
+		logger.Warn("failed to initialize keyword engine, continuing without", zap.Error(err))
+	} else {
+		deps.KeywordEngine = keywordEngine
+		logger.Info("keyword search engine initialized")
+	}
+
+	// Initialize query router
+	queryRouter := router.NewRouter(router.DefaultRouterConfig())
+	deps.Router = queryRouter
+	logger.Info("query router initialized")
+
+	// Initialize hybrid retriever
+	if deps.VectorStore != nil || deps.KeywordEngine != nil {
+		hybridRetriever := retriever.NewHybridRetriever(
+			deps.VectorStore,
+			deps.KeywordEngine,
+			deps.EmbeddingClient,
+			retriever.DefaultConfig(),
+		)
+		deps.Retriever = hybridRetriever
+		logger.Info("hybrid retriever initialized")
+	}
+
+	return deps, nil
+}
+
+// toStringSlice converts Provider slice to string slice for logging
+func toStringSlice(providers []llm.Provider) []string {
+	result := make([]string, len(providers))
+	for i, p := range providers {
+		result[i] = string(p)
+	}
+	return result
+}

cmd/generator-server/main.go

@@ -0,0 +1,290 @@
+// Package main provides the entry point for the Generator service.
+// This service handles LLM interactions for text generation and embeddings.
+package main
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/AmaniQuery/amaniquery/internal/generator"
+	"github.com/AmaniQuery/amaniquery/internal/generator/llm"
+	"github.com/AmaniQuery/amaniquery/pkg/config"
+	"github.com/AmaniQuery/amaniquery/pkg/observability"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/health"
+	"google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/reflection"
+	"google.golang.org/grpc/status"
+)
+
+func main() {
+	// Load configuration
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to load configuration: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Initialize logger
+	logger, err := observability.NewLogger(cfg.Observability.LogLevel, cfg.Observability.LogFormat)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to initialize logger: %v\n", err)
+		os.Exit(1)
+	}
+	defer logger.Sync()
+
+	logger.Info("starting AmaniQuery generator server",
+		zap.String("version", cfg.Version),
+		zap.Strings("llm_providers", cfg.LLM.GetConfiguredProviders()),
+	)
+
+	// Initialize observability
+	tracingShutdown, err := observability.InitProvider(observability.Config{
+		ServiceName:     "amaniquery-generator",
+		ServiceVersion:  cfg.Version,
+		TracingEnabled:  cfg.Observability.TracingEnabled,
+		TracingEndpoint: cfg.Observability.TracingEndpoint,
+	})
+	if err != nil {
+		logger.Warn("failed to initialize tracing", zap.Error(err))
+	} else {
+		defer tracingShutdown(context.Background())
+	}
+
+	// Build dependencies
+	deps, err := buildGeneratorDependencies(cfg, logger)
+	if err != nil {
+		logger.Fatal("failed to build dependencies", zap.Error(err))
+	}
+
+	// Create gRPC server
+	grpcServer := grpc.NewServer(
+		grpc.ChainUnaryInterceptor(
+			observability.UnaryServerInterceptor(),
+		),
+	)
+
+	// Register generator service
+	generatorServer := NewGeneratorServer(deps, logger)
+	RegisterGeneratorServiceServer(grpcServer, generatorServer)
+
+	// Register health service
+	healthServer := health.NewServer()
+	grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
+	healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
+
+	// Enable reflection
+	reflection.Register(grpcServer)
+
+	// Start server
+	port := 9092 // Different port from other servers
+	addr := fmt.Sprintf(":%d", port)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		logger.Fatal("failed to listen", zap.String("addr", addr), zap.Error(err))
+	}
+
+	logger.Info("gRPC generator server starting", zap.String("addr", addr))
+
+	// Graceful shutdown
+	errChan := make(chan error, 1)
+	go func() {
+		errChan <- grpcServer.Serve(listener)
+	}()
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case err := <-errChan:
+		logger.Fatal("server error", zap.Error(err))
+	case sig := <-quit:
+		logger.Info("shutting down", zap.String("signal", sig.String()))
+	}
+
+	grpcServer.GracefulStop()
+	logger.Info("generator server stopped")
+}
+
+// GeneratorDependencies holds generator service dependencies
+type GeneratorDependencies struct {
+	LLMClient       *llm.FallbackClient
+	EmbeddingClient *generator.OpenAIEmbeddingClient
+}
+
+func buildGeneratorDependencies(cfg *config.Config, logger *zap.Logger) (*GeneratorDependencies, error) {
+	// Initialize LLM client with fallback
+	llmClient := llm.NewFallbackClient(llm.Config{
+		GeminiAPIKey:    cfg.LLM.GeminiAPIKey,
+		MoonshotAPIKey:  cfg.LLM.MoonshotAPIKey,
+		OllamaBaseURL:   cfg.LLM.OllamaBaseURL,
+		OpenAIAPIKey:    cfg.LLM.OpenAIAPIKey,
+		AnthropicAPIKey: cfg.LLM.AnthropicAPIKey,
+		DefaultModel:    cfg.LLM.DefaultModel,
+		MaxTokens:       cfg.LLM.MaxTokens,
+		Temperature:     cfg.LLM.Temperature,
+		Timeout:         cfg.LLM.Timeout,
+		MaxRetries:      cfg.LLM.MaxRetries,
+		EnableFallback:  cfg.LLM.EnableFallback,
+		Logger:          logger,
+	})
+
+	// Initialize embedding client
+	embeddingClient := generator.NewOpenAIEmbeddingClient(generator.EmbeddingConfig{
+		Provider:  cfg.Embedding.Provider,
+		APIKey:    cfg.Embedding.APIKey,
+		Model:     cfg.Embedding.Model,
+		Dimension: cfg.Embedding.Dimension,
+		BatchSize: cfg.Embedding.BatchSize,
+	})
+
+	return &GeneratorDependencies{
+		LLMClient:       llmClient,
+		EmbeddingClient: embeddingClient,
+	}, nil
+}
+
+// GeneratorServer implements the GeneratorService gRPC server
+type GeneratorServer struct {
+	UnimplementedGeneratorServiceServer
+	deps   *GeneratorDependencies
+	logger *zap.Logger
+}
+
+// NewGeneratorServer creates a new generator server
+func NewGeneratorServer(deps *GeneratorDependencies, logger *zap.Logger) *GeneratorServer {
+	return &GeneratorServer{
+		deps:   deps,
+		logger: logger,
+	}
+}
+
+// Generate performs text generation
+func (s *GeneratorServer) Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error) {
+	if len(req.Messages) == 0 {
+		return nil, status.Error(codes.InvalidArgument, "messages are required")
+	}
+
+	// Convert messages
+	messages := make([]llm.Message, len(req.Messages))
+	for i, m := range req.Messages {
+		messages[i] = llm.Message{
+			Role:    m.Role,
+			Content: m.Content,
+		}
+	}
+
+	// Generate response
+	resp, err := s.deps.LLMClient.Generate(ctx, messages, llm.Options{
+		Model:       req.Model,
+		Temperature: req.Temperature,
+		MaxTokens:   int(req.MaxTokens),
+	})
+	if err != nil {
+		return nil, status.Error(codes.Internal, err.Error())
+	}
+
+	return &GenerateResponse{
+		Content:      resp.Content,
+		FinishReason: resp.FinishReason,
+		Model:        resp.Model,
+		Provider:     string(resp.Provider),
+		Usage: &TokenUsage{
+			PromptTokens:     int32(resp.Usage.PromptTokens),
+			CompletionTokens: int32(resp.Usage.CompletionTokens),
+			TotalTokens:      int32(resp.Usage.TotalTokens),
+		},
+	}, nil
+}
+
+// GenerateEmbedding generates embeddings for text
+func (s *GeneratorServer) GenerateEmbedding(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error) {
+	if req.Text == "" {
+		return nil, status.Error(codes.InvalidArgument, "text is required")
+	}
+
+	embedding, err := s.deps.EmbeddingClient.Generate(ctx, req.Text)
+	if err != nil {
+		return nil, status.Error(codes.Internal, err.Error())
+	}
+
+	return &EmbeddingResponse{
+		Embedding: embedding,
+		Dimension: int32(len(embedding)),
+	}, nil
+}
+
+// BatchGenerateEmbeddings generates embeddings for multiple texts
+func (s *GeneratorServer) BatchGenerateEmbeddings(ctx context.Context, req *BatchEmbeddingRequest) (*BatchEmbeddingResponse, error) {
+	if len(req.Texts) == 0 {
+		return nil, status.Error(codes.InvalidArgument, "texts are required")
+	}
+
+	embeddings, err := s.deps.EmbeddingClient.GenerateBatch(ctx, req.Texts)
+	if err != nil {
+		return nil, status.Error(codes.Internal, err.Error())
+	}
+
+	return &BatchEmbeddingResponse{
+		Embeddings: embeddings,
+	}, nil
+}
+
+// Stub types - replace with generated protobuf code
+type Message struct {
+	Role    string
+	Content string
+}
+
+type GenerateRequest struct {
+	Messages    []*Message
+	Model       string
+	Temperature float32
+	MaxTokens   int32
+}
+
+type GenerateResponse struct {
+	Content      string
+	FinishReason string
+	Model        string
+	Provider     string
+	Usage        *TokenUsage
+}
+
+type TokenUsage struct {
+	PromptTokens     int32
+	CompletionTokens int32
+	TotalTokens      int32
+}
+
+type EmbeddingRequest struct {
+	Text  string
+	Model string
+}
+
+type EmbeddingResponse struct {
+	Embedding []float32
+	Dimension int32
+}
+
+type BatchEmbeddingRequest struct {
+	Texts []string
+	Model string
+}
+
+type BatchEmbeddingResponse struct {
+	Embeddings [][]float32
+}
+
+type UnimplementedGeneratorServiceServer struct{}
+
+func RegisterGeneratorServiceServer(s *grpc.Server, srv *GeneratorServer) {
+	// Registration happens when protobuf is generated
+}

cmd/retriever-server/main.go

@@ -0,0 +1,317 @@
+// Package main provides the entry point for the Retriever service.
+// This service handles document retrieval using vector, keyword, and graph search.
+package main
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/AmaniQuery/amaniquery/internal/generator"
+	"github.com/AmaniQuery/amaniquery/internal/retriever"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/keyword"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/vector"
+	"github.com/AmaniQuery/amaniquery/pkg/config"
+	"github.com/AmaniQuery/amaniquery/pkg/observability"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/health"
+	"google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/reflection"
+	"google.golang.org/grpc/status"
+)
+
+func main() {
+	// Load configuration
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to load configuration: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Initialize logger
+	logger, err := observability.NewLogger(cfg.Observability.LogLevel, cfg.Observability.LogFormat)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to initialize logger: %v\n", err)
+		os.Exit(1)
+	}
+	defer logger.Sync()
+
+	logger.Info("starting AmaniQuery retriever server",
+		zap.String("version", cfg.Version),
+		zap.String("environment", cfg.Environment),
+	)
+
+	// Initialize observability
+	tracingShutdown, err := observability.InitProvider(observability.Config{
+		ServiceName:     "amaniquery-retriever",
+		ServiceVersion:  cfg.Version,
+		TracingEnabled:  cfg.Observability.TracingEnabled,
+		TracingEndpoint: cfg.Observability.TracingEndpoint,
+	})
+	if err != nil {
+		logger.Warn("failed to initialize tracing", zap.Error(err))
+	} else {
+		defer tracingShutdown(context.Background())
+	}
+
+	// Build dependencies
+	deps, err := buildRetrieverDependencies(cfg, logger)
+	if err != nil {
+		logger.Fatal("failed to build dependencies", zap.Error(err))
+	}
+
+	// Create gRPC server
+	grpcServer := grpc.NewServer(
+		grpc.ChainUnaryInterceptor(
+			observability.UnaryServerInterceptor(),
+		),
+	)
+
+	// Register retriever service
+	retrieverServer := NewRetrieverServer(deps, logger)
+	RegisterRetrieverServiceServer(grpcServer, retrieverServer)
+
+	// Register health service
+	healthServer := health.NewServer()
+	grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
+	healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
+
+	// Enable reflection
+	reflection.Register(grpcServer)
+
+	// Start server
+	port := 9091 // Different port from agent server
+	addr := fmt.Sprintf(":%d", port)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		logger.Fatal("failed to listen", zap.String("addr", addr), zap.Error(err))
+	}
+
+	logger.Info("gRPC retriever server starting", zap.String("addr", addr))
+
+	// Graceful shutdown
+	errChan := make(chan error, 1)
+	go func() {
+		errChan <- grpcServer.Serve(listener)
+	}()
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case err := <-errChan:
+		logger.Fatal("server error", zap.Error(err))
+	case sig := <-quit:
+		logger.Info("shutting down", zap.String("signal", sig.String()))
+	}
+
+	grpcServer.GracefulStop()
+	logger.Info("retriever server stopped")
+}
+
+// RetrieverDependencies holds retriever service dependencies
+type RetrieverDependencies struct {
+	VectorStore     *vector.QdrantClient
+	KeywordEngine   *keyword.BleveEngine
+	EmbeddingClient *generator.OpenAIEmbeddingClient
+	HybridRetriever *retriever.HybridRetriever
+}
+
+func buildRetrieverDependencies(cfg *config.Config, logger *zap.Logger) (*RetrieverDependencies, error) {
+	deps := &RetrieverDependencies{}
+
+	// Initialize vector store
+	vectorClient, err := vector.NewQdrantClient(vector.Config{
+		Host:       cfg.VectorStore.Host,
+		Port:       cfg.VectorStore.Port,
+		APIKey:     cfg.VectorStore.APIKey,
+		Collection: cfg.VectorStore.Collection,
+		Dimension:  cfg.VectorStore.Dimension,
+		Distance:   cfg.VectorStore.Distance,
+	})
+	if err != nil {
+		logger.Warn("failed to connect to vector store", zap.Error(err))
+	} else {
+		deps.VectorStore = vectorClient
+	}
+
+	// Initialize keyword engine
+	keywordEngine, err := keyword.NewBleveEngine(keyword.Config{
+		InMemory: true,
+	})
+	if err != nil {
+		logger.Warn("failed to initialize keyword engine", zap.Error(err))
+	} else {
+		deps.KeywordEngine = keywordEngine
+	}
+
+	// Initialize embedding client
+	embeddingClient := generator.NewOpenAIEmbeddingClient(generator.EmbeddingConfig{
+		Provider:  cfg.Embedding.Provider,
+		APIKey:    cfg.Embedding.APIKey,
+		Model:     cfg.Embedding.Model,
+		Dimension: cfg.Embedding.Dimension,
+		BatchSize: cfg.Embedding.BatchSize,
+	})
+	deps.EmbeddingClient = embeddingClient
+
+	// Initialize hybrid retriever
+	deps.HybridRetriever = retriever.NewHybridRetriever(
+		deps.VectorStore,
+		deps.KeywordEngine,
+		deps.EmbeddingClient,
+		retriever.DefaultConfig(),
+	)
+
+	return deps, nil
+}
+
+// RetrieverServer implements the RetrieverService gRPC server
+type RetrieverServer struct {
+	UnimplementedRetrieverServiceServer
+	deps   *RetrieverDependencies
+	logger *zap.Logger
+}
+
+// NewRetrieverServer creates a new retriever server
+func NewRetrieverServer(deps *RetrieverDependencies, logger *zap.Logger) *RetrieverServer {
+	return &RetrieverServer{
+		deps:   deps,
+		logger: logger,
+	}
+}
+
+// HybridSearch performs hybrid search
+func (s *RetrieverServer) HybridSearch(ctx context.Context, req *SearchRequest) (*SearchResponse, error) {
+	if req.Query == "" {
+		return nil, status.Error(codes.InvalidArgument, "query is required")
+	}
+
+	topK := int(req.TopK)
+	if topK == 0 {
+		topK = 10
+	}
+
+	searchResp, err := s.deps.HybridRetriever.Search(ctx, retriever.SearchRequest{
+		Query:     req.Query,
+		TopK:      topK,
+		UseVector: true,
+		UseKeyword: true,
+	})
+	if err != nil {
+		return nil, status.Error(codes.Internal, err.Error())
+	}
+
+	// Convert results
+	documents := make([]*Document, len(searchResp.Results))
+	for i, r := range searchResp.Results {
+		documents[i] = &Document{
+			Id:      r.ID,
+			Content: r.Content,
+			Title:   r.Title,
+			Source:  r.Source,
+			Score:   r.Score,
+		}
+	}
+
+	return &SearchResponse{
+		Documents:    documents,
+		TotalCount:   int32(searchResp.TotalCount),
+		SearchTimeMs: searchResp.SearchTimeMs,
+	}, nil
+}
+
+// IndexDocument indexes a document
+func (s *RetrieverServer) IndexDocument(ctx context.Context, req *IndexRequest) (*IndexResponse, error) {
+	if req.Document == nil {
+		return nil, status.Error(codes.InvalidArgument, "document is required")
+	}
+
+	// Generate embedding
+	embedding, err := s.deps.EmbeddingClient.Generate(ctx, req.Document.Content)
+	if err != nil {
+		return nil, status.Error(codes.Internal, "failed to generate embedding")
+	}
+
+	// Index in vector store
+	if s.deps.VectorStore != nil {
+		err = s.deps.VectorStore.Index(ctx, vector.Document{
+			ID:        req.Document.Id,
+			Content:   req.Document.Content,
+			Embedding: embedding,
+			Metadata:  convertMetadata(req.Document.Metadata),
+		})
+		if err != nil {
+			return nil, status.Error(codes.Internal, "failed to index in vector store")
+		}
+	}
+
+	// Index in keyword engine
+	if s.deps.KeywordEngine != nil {
+		err = s.deps.KeywordEngine.Index(ctx, keyword.Document{
+			ID:      req.Document.Id,
+			Title:   req.Document.Title,
+			Content: req.Document.Content,
+			Source:  req.Document.Source,
+		})
+		if err != nil {
+			s.logger.Warn("failed to index in keyword engine", zap.Error(err))
+		}
+	}
+
+	return &IndexResponse{
+		DocumentId: req.Document.Id,
+		Success:    true,
+	}, nil
+}
+
+func convertMetadata(m map[string]string) map[string]interface{} {
+	result := make(map[string]interface{}, len(m))
+	for k, v := range m {
+		result[k] = v
+	}
+	return result
+}
+
+// Stub types for protobuf - replace with generated code
+type SearchRequest struct {
+	Query     string
+	TopK      int32
+	Embedding []float32
+}
+
+type SearchResponse struct {
+	Documents    []*Document
+	TotalCount   int32
+	SearchTimeMs int64
+}
+
+type Document struct {
+	Id       string
+	Content  string
+	Title    string
+	Source   string
+	Score    float32
+	Metadata map[string]string
+}
+
+type IndexRequest struct {
+	Document *Document
+}
+
+type IndexResponse struct {
+	DocumentId string
+	Success    bool
+}
+
+type UnimplementedRetrieverServiceServer struct{}
+
+func RegisterRetrieverServiceServer(s *grpc.Server, srv *RetrieverServer) {
+	// Registration happens when protobuf is generated
+}

cmd/worker/main.go

@@ -0,0 +1,327 @@
+// Package main provides the Temporal worker for RAG pipeline execution
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/AmaniQuery/amaniquery/internal/generator"
+	"github.com/AmaniQuery/amaniquery/internal/generator/llm"
+	"github.com/AmaniQuery/amaniquery/internal/guardrails"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/graph"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/keyword"
+	"github.com/AmaniQuery/amaniquery/internal/retriever/vector"
+	"github.com/AmaniQuery/amaniquery/internal/workflow"
+	"github.com/AmaniQuery/amaniquery/pkg/config"
+	"github.com/AmaniQuery/amaniquery/pkg/observability"
+
+	"go.temporal.io/sdk/client"
+	"go.temporal.io/sdk/worker"
+	"go.uber.org/zap"
+)
+
+const taskQueue = "amaniquery-rag"
+
+func main() {
+	// Load configuration
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Initialize logger
+	logger, err := observability.NewLogger(cfg.Observability.LogLevel, cfg.Observability.LogFormat)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to init logger: %v\n", err)
+		os.Exit(1)
+	}
+	defer logger.Sync()
+
+	logger.Info("starting Temporal worker",
+		zap.String("task_queue", taskQueue),
+	)
+
+	// Create Temporal client
+	temporalClient, err := client.Dial(client.Options{
+		HostPort: getEnv("TEMPORAL_HOST", "localhost:7233"),
+		Logger:   NewTemporalZapLogger(logger),
+	})
+	if err != nil {
+		logger.Fatal("failed to create Temporal client", zap.Error(err))
+	}
+	defer temporalClient.Close()
+
+	// Build activity dependencies
+	deps, err := buildDependencies(cfg, logger)
+	if err != nil {
+		logger.Fatal("failed to build dependencies", zap.Error(err))
+	}
+
+	// Create activities instance
+	activities := workflow.NewActivities(deps)
+
+	// Create worker
+	w := worker.New(temporalClient, taskQueue, worker.Options{
+		MaxConcurrentActivityExecutionSize:     10,
+		MaxConcurrentWorkflowTaskExecutionSize: 10,
+	})
+
+	// Register workflow and activities
+	w.RegisterWorkflow(workflow.RAGWorkflow)
+	w.RegisterActivity(activities.ValidateInput)
+	w.RegisterActivity(activities.GenerateEmbedding)
+	w.RegisterActivity(activities.VectorSearch)
+	w.RegisterActivity(activities.KeywordSearch)
+	w.RegisterActivity(activities.GraphSearch)
+	w.RegisterActivity(activities.RankSources)
+	w.RegisterActivity(activities.GenerateResponse)
+	w.RegisterActivity(activities.ValidateOutput)
+
+	// Start worker
+	errChan := make(chan error, 1)
+	go func() {
+		errChan <- w.Run(worker.InterruptCh())
+	}()
+
+	logger.Info("Temporal worker started", zap.String("task_queue", taskQueue))
+
+	// Wait for shutdown
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case err := <-errChan:
+		logger.Fatal("worker error", zap.Error(err))
+	case sig := <-quit:
+		logger.Info("shutting down", zap.String("signal", sig.String()))
+	}
+
+	w.Stop()
+	logger.Info("worker stopped")
+}
+
+func buildDependencies(cfg *config.Config, logger *zap.Logger) (*workflow.ActivityDependencies, error) {
+	deps := &workflow.ActivityDependencies{}
+
+	// Embedding client
+	embeddingClient := generator.NewOpenAIEmbeddingClient(generator.EmbeddingConfig{
+		Provider:  cfg.Embedding.Provider,
+		APIKey:    cfg.Embedding.APIKey,
+		Model:     cfg.Embedding.Model,
+		Dimension: cfg.Embedding.Dimension,
+	})
+	deps.EmbeddingClient = embeddingClient
+
+	// Vector store
+	vectorClient, err := vector.NewQdrantClient(vector.Config{
+		Host:       cfg.VectorStore.Host,
+		Port:       cfg.VectorStore.Port,
+		APIKey:     cfg.VectorStore.APIKey,
+		Collection: cfg.VectorStore.Collection,
+	})
+	if err != nil {
+		logger.Warn("vector store unavailable", zap.Error(err))
+	} else {
+		deps.VectorStore = &vectorStoreAdapter{client: vectorClient}
+	}
+
+	// Keyword engine
+	keywordEngine, err := keyword.NewBleveEngine(keyword.Config{InMemory: true})
+	if err != nil {
+		logger.Warn("keyword engine unavailable", zap.Error(err))
+	} else {
+		deps.KeywordEngine = &keywordAdapter{engine: keywordEngine}
+	}
+
+	// Graph store (Neo4j)
+	neo4jCfg := graph.DefaultConfig()
+	if uri := os.Getenv("NEO4J_URI"); uri != "" {
+		neo4jCfg.URI = uri
+	}
+	if user := os.Getenv("NEO4J_USERNAME"); user != "" {
+		neo4jCfg.Username = user
+		neo4jCfg.Password = os.Getenv("NEO4J_PASSWORD")
+	}
+	graphClient, err := graph.NewClient(neo4jCfg)
+	if err != nil {
+		logger.Warn("graph store unavailable", zap.Error(err))
+	} else {
+		deps.GraphStore = &graphAdapter{client: graphClient}
+	}
+
+	// Guardrails
+	guardrailsCfg := guardrails.DefaultConfig()
+	if url := os.Getenv("GUARDRAILS_URL"); url != "" {
+		guardrailsCfg.BaseURL = url
+	}
+	guardrailsClient := guardrails.NewClient(guardrailsCfg)
+	deps.Guardrails = &guardrailsAdapter{client: guardrailsClient}
+
+	// LLM client
+	llmClient := llm.NewFallbackClient(llm.Config{
+		GeminiAPIKey:    cfg.LLM.GeminiAPIKey,
+		MoonshotAPIKey:  cfg.LLM.MoonshotAPIKey,
+		OllamaBaseURL:   cfg.LLM.OllamaBaseURL,
+		OpenAIAPIKey:    cfg.LLM.OpenAIAPIKey,
+		AnthropicAPIKey: cfg.LLM.AnthropicAPIKey,
+		Logger:          logger,
+	})
+	deps.LLMClient = &llmAdapter{client: llmClient}
+
+	return deps, nil
+}
+
+// Adapters to match workflow interfaces
+
+type vectorStoreAdapter struct {
+	client *vector.QdrantClient
+}
+
+func (a *vectorStoreAdapter) Search(ctx context.Context, embedding []float32, topK int, filters map[string]interface{}) ([]workflow.Source, error) {
+	results, err := a.client.Search(ctx, embedding, topK, filters)
+	if err != nil {
+		return nil, err
+	}
+	sources := make([]workflow.Source, len(results))
+	for i, r := range results {
+		sources[i] = workflow.Source{
+			ID:      r.ID,
+			Title:   r.Title,
+			Content: r.Content,
+			Score:   r.Score,
+		}
+	}
+	return sources, nil
+}
+
+type keywordAdapter struct {
+	engine *keyword.BleveEngine
+}
+
+func (a *keywordAdapter) Search(ctx context.Context, query string, topK int) ([]workflow.Source, error) {
+	results, err := a.engine.Search(ctx, query, topK)
+	if err != nil {
+		return nil, err
+	}
+	sources := make([]workflow.Source, len(results))
+	for i, r := range results {
+		sources[i] = workflow.Source{
+			ID:      r.ID,
+			Title:   r.Title,
+			Content: r.Content,
+			Score:   r.Score,
+		}
+	}
+	return sources, nil
+}
+
+type graphAdapter struct {
+	client *graph.Client
+}
+
+func (a *graphAdapter) Search(ctx context.Context, query string, embedding []float32, topK int) ([]workflow.Source, error) {
+	results, err := a.client.Search(ctx, graph.SearchRequest{
+		Query:     query,
+		Embedding: embedding,
+		TopK:      topK,
+		MaxHops:   2,
+	})
+	if err != nil {
+		return nil, err
+	}
+	sources := make([]workflow.Source, len(results))
+	for i, r := range results {
+		sources[i] = workflow.Source{
+			ID:      r.ID,
+			Title:   r.Title,
+			Content: r.Content,
+			Score:   r.Score,
+		}
+	}
+	return sources, nil
+}
+
+type guardrailsAdapter struct {
+	client *guardrails.Client
+}
+
+func (a *guardrailsAdapter) ValidateInput(ctx context.Context, input string) (bool, string, error) {
+	resp, err := a.client.ValidateInput(ctx, input)
+	if err != nil {
+		return true, "", err // Fail open
+	}
+	return !resp.Blocked, resp.Reason, nil
+}
+
+func (a *guardrailsAdapter) ValidateOutput(ctx context.Context, input, output string) (bool, string, error) {
+	resp, err := a.client.ValidateOutput(ctx, input, output)
+	if err != nil {
+		return true, "", err
+	}
+	return !resp.Blocked, resp.Reason, nil
+}
+
+type llmAdapter struct {
+	client *llm.FallbackClient
+}
+
+func (a *llmAdapter) Generate(ctx context.Context, prompt string, options workflow.GenerateOptions) (string, int, error) {
+	resp, err := a.client.Generate(ctx, []llm.Message{
+		{Role: "user", Content: prompt},
+	}, llm.Options{
+		Temperature: options.Temperature,
+		MaxTokens:   options.MaxTokens,
+	})
+	if err != nil {
+		return "", 0, err
+	}
+	return resp.Content, resp.Usage.TotalTokens, nil
+}
+
+func getEnv(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
+
+// TemporalZapLogger adapts zap.Logger for Temporal
+type TemporalZapLogger struct {
+	logger *zap.Logger
+}
+
+func NewTemporalZapLogger(logger *zap.Logger) *TemporalZapLogger {
+	return &TemporalZapLogger{logger: logger.Named("temporal")}
+}
+
+func (l *TemporalZapLogger) Debug(msg string, keyvals ...interface{}) {
+	l.logger.Debug(msg, toZapFields(keyvals)...)
+}
+
+func (l *TemporalZapLogger) Info(msg string, keyvals ...interface{}) {
+	l.logger.Info(msg, toZapFields(keyvals)...)
+}
+
+func (l *TemporalZapLogger) Warn(msg string, keyvals ...interface{}) {
+	l.logger.Warn(msg, toZapFields(keyvals)...)
+}
+
+func (l *TemporalZapLogger) Error(msg string, keyvals ...interface{}) {
+	l.logger.Error(msg, toZapFields(keyvals)...)
+}
+
+func toZapFields(keyvals []interface{}) []zap.Field {
+	fields := make([]zap.Field, 0, len(keyvals)/2)
+	for i := 0; i < len(keyvals)-1; i += 2 {
+		key, ok := keyvals[i].(string)
+		if !ok {
+			continue
+		}
+		fields = append(fields, zap.Any(key, keyvals[i+1]))
+	}
+	return fields
+}

config.example.yaml

@@ -0,0 +1,67 @@
+# AmaniQuery Configuration
+# Copy this file to config.yaml and customize as needed
+
+version: "1.0.0"
+environment: "development"
+
+server:
+  grpc_port: 9090
+  http_port: 8080
+  graceful_timeout: 30s
+  max_connections: 1000
+
+vector_store:
+  type: qdrant
+  host: localhost
+  port: 6334
+  # api_key: set via QDRANT_API_KEY env var
+  collection: amaniquery
+  dimension: 1536
+  distance: Cosine
+
+cache:
+  redis_url: redis://localhost:6379
+  local_size: 10000
+  ttl: 1h
+  max_retries: 3
+  pool_size: 10
+
+# LLM Configuration with Multi-Provider Fallback
+# Fallback order: Gemini → Moonshot → Ollama → OpenAI → Anthropic
+# Set API keys via environment variables:
+#   GEMINI_API_KEY or GOOGLE_API_KEY
+#   MOONSHOT_API_KEY
+#   OLLAMA_BASE_URL (for local Ollama, default: http://localhost:11434)
+#   OPENAI_API_KEY
+#   ANTHROPIC_API_KEY
+llm:
+  default_model: gemini-1.5-flash # Used when provider doesn't specify model
+  max_tokens: 4096
+  temperature: 0.7
+  timeout: 60s
+  max_retries: 3
+  enable_fallback: true # Automatically try next provider on failure
+  ollama_base_url: http://localhost:11434 # For local Ollama
+
+embedding:
+  provider: openai # openai for text-embedding-3-small
+  # api_key: falls back to OPENAI_API_KEY
+  model: text-embedding-3-small
+  dimension: 1536
+  batch_size: 100
+
+observability:
+  tracing_enabled: true
+  tracing_endpoint: localhost:4317
+  metrics_enabled: true
+  metrics_port: 9091
+  log_level: info # debug, info, warn, error
+  log_format: json # json, console
+
+security:
+  # jwt_secret: set via JWT_SECRET env var
+  jwt_issuer: amaniquery
+  enable_mtls: false
+  # cert_file: /path/to/cert.pem
+  # key_file: /path/to/key.pem
+  # ca_file: /path/to/ca.pem

deploy.md

@@ -0,0 +1,149 @@
+# AmaniQuery Render Deployment Guide
+
+This guide details the steps to deploy the AmaniQuery monorepo components to [Render.com](https://render.com).
+
+## Prerequisites
+
+1. **GitHub Repository**: Ensure your code is pushed to a GitHub repository connected to Render.
+2. **Docker**, **Node.js**, and **Go** knowledge.
+3. **Render Account**: Created and ready.
+
+## 1. Database & Infrastructure (Render Postgres & Redis)
+
+Before deploying services, set up your managed data stores.
+
+### PostgreSQL
+
+- **Type**: PostgreSQL
+- **Name**: `amaniquery-db`
+- **Region**: Frankfurt (EU-Central) or nearest.
+- **Environment**:
+  - `POSTGRES_USER`: `amaniquery`
+  - `POSTGRES_DB`: `amaniquery`
+- **Internal Connection URL**: Copy this for use in service env vars.
+
+### Redis
+
+- **Type**: Redis
+- **Name**: `amaniquery-redis`
+- **Max Memory Policy**: `allkeys-lru`
+- **Internal Connection URL**: Copy this (`redis://...`).
+
+## 2. Backend Services (Docker Runtime)
+
+Since AmaniQuery is a monorepo, using **Docker** as the Runtime is recommended for Go services to handle build context correctly (copying `go.mod` from root).
+
+### Common Configuration for All Backend Services
+
+- **Runtime**: Docker
+- **Repository**: `your-repo/amaniquery`
+- **Region**: Same as Database.
+
+| Service Name | Dockerfile Path | Build Context Directory | Env Vars |
+| :--- | :--- | :--- | :--- |
+| `amaniquery-portal` | `services/portal/Dockerfile` | `.` (Root) | `SERVER_HTTP_PORT=8080`, `DB_HOST=...` |
+| `amaniquery-ingestion`| `services/ingestion/Dockerfile`| `.` (Root) | `QDRANT_URL=...`, `RABBITMQ_URL=...` |
+| `amaniquery-voice` | `services/voice/Dockerfile` | `.` (Root) | `OPENAI_API_KEY=...` |
+| `amaniquery-files` | `services/files/Dockerfile` | `.` (Root) | `MINIO_ENDPOINT=...` |
+| `amaniquery-notifications`| `services/notifications/Dockerfile.gateway` | `.` (Root) | `MAILTRAP_API_KEY=...` |
+
+> [!TIP]
+> **Root Directory Setting**: In Render, set "Root Directory" to `.` (default) so Docker builds have access to the full monorepo context.
+
+## 3. Frontend Applications (Static Sites)
+
+We will use the **Static Site** type for frontends, relying on the `Dockerfile` or Render's Native Node build.
+*Recommendation*: Use **Static Site** with Node build command for faster deploys, or **Docker** if you need Nginx customization.
+
+### Option A: Static Site (Native Node - Recommended)
+
+- **Build Command**: `yarn && yarn turbo run build --filter=admin-portal`
+- **Publish Directory**: `frontend/apps/admin/dist`
+- **Root Directory**: `frontend`
+
+### Option B: Docker (Using our new Turbo Dockerfiles)
+
+- **Runtime**: Docker
+- **Dockerfile Path**: `frontend/apps/admin/Dockerfile`
+- **Context**: `frontend` (Important: context is `frontend` subfolder, not root, for these specific Dockerfiles)
+
+| App Name | Build Command (Static) | Publish Dir | Context |
+| :--- | :--- | :--- | :--- |
+| `admin-portal` | `yarn build:admin` | `apps/admin/dist` | `frontend` |
+| `developer-portal` | `yarn build:dev` | `apps/developer-portal/dist` | `frontend` |
+| `web-app` | `yarn build:web` | `apps/web/dist` | `frontend` |
+
+> *Note: You may need to add helper scripts in `frontend/package.json` like `"build:admin": "turbo run build --filter=admin-portal"` to keep commands simple.*
+
+## 4. HuggingFace Spaces (Docker Deployment)
+
+For users preferring HuggingFace Spaces (free tier: 2 vCPU, 16GB RAM, 50GB disk), follow these steps.
+
+### Prerequisites
+
+- HuggingFace Account
+- External Databases (Managed Services):
+  - **PostgreSQL**: Neon.tech (Free Tier available)
+  - **Redis**: Upstash (Free Tier available)
+  - **Qdrant**: Qdrant Cloud (Free Tier available)
+
+### Deployment Steps
+
+1. **Create a New Space**:
+    - Go to [HuggingFace Spaces](https://huggingface.co/new-space)
+    - Enter a name (e.g., `amaniquery`)
+    - Select **Docker** as the Space SDK
+    - Choose "Blank" for the template
+
+2. **Deploy via Script (Recommended)**:
+    - Set `HF_TOKEN` in your local `.env`.
+    - Run: `python scripts/deploy_hf.py agent`
+    - This deploys both the Go Agent and Rust Memory Service in a single container (Sidecar pattern) for maximum efficiency and localhost communication.
+
+3. **Deploy Manually (Alternative)**:
+    - Clone your Space's repository locally.
+    - Copy `deployments/huggingface/Dockerfile.hf` to `Dockerfile` in the root.
+    - Copy `deployments/huggingface/README.md` to the root.
+    - Push to HuggingFace.
+
+4. **Configure Secrets**:
+    - Go to **Settings** -> **Variables and Secrets** in your Space.
+    - Add the secrets listed in `deployments/huggingface/.env.hf.example`.
+
+5. **Status**:
+    - The Space will build and start both `agent-server` and `memory-server`.
+    - The Go agent will automatically connect to the local memory service.
+
+6. **Automated Deployment (Optional)**:
+   We provided a script `scripts/deploy_hf.py` to automate the deployment process.
+
+   **Prerequisites**:
+   - `HF_TOKEN` must be set in your `.env` file (Get it from [HF Settings](https://huggingface.co/settings/tokens)).
+   - The Spaces must be created first (e.g., `AmaniQuery/amaniquery-agent` and `AmaniQuery/amaniquery-memory`).
+
+   **Usage**:
+
+   ```bash
+   # Deploy Agent
+   python scripts/deploy_hf.py agent
+   
+   # Deploy Memory Service
+   python scripts/deploy_hf.py memory
+   
+   # Deploy Both
+   python scripts/deploy_hf.py all
+   ```
+
+## 5. Environment Variables Checklist
+
+Transfer these from your `env.example` files to Render's "Environment" tab for each service.
+
+- [ ] **Portal**: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `REDIS_URL`, `JWT_SECRET`
+- [ ] **Voice**: `OPENAI_API_KEY`, `ELEVENLABS_API_KEY`, `REDIS_URL`
+- [ ] **Frontend**: `VITE_API_BASE_URL` (Set this to the `https://...onrender.com` URL of your Portal service).
+
+## 6. Deployment Order
+
+1. **Infrastructure** (Postgres/Redis) - Wait for healthy.
+2. **Backend Services** (Portal, etc.) - Deploy & check logs.
+3. **Frontend Apps** - Deploy & update `VITE_API_BASE_URL` with backend URL.

docs/API_GATEWAY.md

@@ -0,0 +1,211 @@
+# API Gateway for RAG Agent Framework
+
+A production-ready, multi-protocol API Gateway for the AmaniQuery RAG Agent Framework. Provides unified access for frontend clients with comprehensive security, observability, and performance features.
+
+## Architecture
+
+![API Gateway Architecture](docs/images/api-gateway-architecture.png)
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        WEB[Web Browser]
+        MOBILE[Mobile App]
+        DEVELOPER[Developer Portal]
+    end
+    
+    subgraph "API Gateway Layer"
+        GW[API Gateway<br/>Go Service]
+        
+        subgraph "Middleware Stack"
+            CORS[CORS Handler]
+            RATE[Rate Limiter]
+            AUTH[JWT Validator]
+            AUDIT[Audit Logger]
+        end
+        
+        subgraph "Protocol Handlers"
+            REST[REST Handler]
+            WS[WebSocket Handler]
+            GQL[GraphQL Handler]
+        end
+    end
+    
+    subgraph "Backend Services"
+        AGENT[Agent Service]
+        RETRIEVER[Retriever Service]
+        GENERATOR[Generator Service]
+        MEMORY[Memory Service]
+    end
+    
+    WEB --> GW
+    MOBILE --> GW
+    DEVELOPER --> GW
+    
+    GW --> CORS --> RATE --> AUTH --> AUDIT
+    AUDIT --> REST
+    AUDIT --> WS
+    AUDIT --> GQL
+    
+    REST --> AGENT
+    WS --> AGENT
+    GQL --> AGENT
+```
+
+## Features
+
+### Multi-Protocol Support
+- **REST API** - Standard HTTP endpoints for queries, agents, memory
+- **WebSocket** - Real-time streaming for query responses
+- **Server-Sent Events** - Lightweight streaming alternative
+- **GraphQL** - Flexible query interface (placeholder)
+
+### Security
+- **JWT Authentication** - Token-based auth with HMAC/RSA signing
+- **OPA Authorization** - Fine-grained policy-based access control
+- **Rate Limiting** - Token bucket with per-tenant/user isolation
+- **CORS** - Configurable cross-origin policies
+- **Security Headers** - HSTS, CSP, X-Frame-Options, etc.
+
+### Observability
+- **Prometheus Metrics** - Request counts, latencies, cache hits
+- **OpenTelemetry Tracing** - Distributed request tracing
+- **Audit Logging** - Structured logs for compliance
+
+### Performance
+- **Redis Caching** - Query response caching with smart TTL
+- **Circuit Breakers** - Failure isolation per service
+- **Connection Pooling** - Efficient gRPC connections
+
+## Quick Start
+
+### Prerequisites
+- Go 1.21+
+- Docker & Docker Compose
+- Redis (for caching/rate limiting)
+
+### Running Locally
+
+```bash
+# Clone the repository
+cd AmaniQuery
+
+# Copy example config
+cp gateway.example.yaml gateway.yaml
+
+# Run with Docker Compose
+cd deployments/docker
+docker-compose up -d api-gateway
+```
+
+### Configuration
+
+See `gateway.example.yaml` for all options. Key settings:
+
+```yaml
+server:
+  bindAddr: ":8443"
+  
+auth:
+  jwtSecret: "${JWT_SECRET}"
+  
+cache:
+  redisAddr: "redis:6379"
+```
+
+Environment variables override config with `GATEWAY_` prefix.
+
+## API Endpoints
+
+### Queries
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v2/queries` | Execute RAG query |
+| GET | `/v2/queries/{id}` | Get async query result |
+| WS | `/v2/queries/stream` | Streaming query |
+
+### Agents
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v2/agents` | Create agent |
+| GET | `/v2/agents/{id}` | Get agent |
+| DELETE | `/v2/agents/{id}` | Delete agent |
+| POST | `/v2/agents/{id}/execute` | Execute plan |
+
+### Memory
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v2/memory/context` | Get context window |
+| POST | `/v2/memory/sessions/{id}/consolidate` | Consolidate memory |
+
+### Admin
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/admin/health` | Health check |
+| GET | `/admin/metrics` | Prometheus metrics |
+
+## WebSocket Protocol
+
+```javascript
+// Connect
+const ws = new WebSocket('wss://api.example.com/v2/queries/stream?token=JWT');
+
+// Send query
+ws.send(JSON.stringify({
+  type: 'query',
+  payload: { query: 'What is RAG?', userId: 'user-123' }
+}));
+
+// Receive chunks
+ws.onmessage = (e) => {
+  const msg = JSON.parse(e.data);
+  if (msg.type === 'chunk') console.log(msg.data);
+  if (msg.type === 'done') console.log('Complete');
+};
+```
+
+## Deployment
+
+### Docker
+```bash
+docker build -f deployments/docker/Dockerfile.gateway -t api-gateway .
+docker run -p 8443:8443 api-gateway
+```
+
+### Kubernetes
+```bash
+kubectl apply -f deployments/k8s/gateway.yaml
+```
+
+## Project Structure
+
+```
+internal/gateway/
+├── config.go           # Configuration
+├── gateway.go          # Main server
+├── types.go            # Request/response types
+├── cache/
+│   └── cache.go        # Redis cache
+├── handlers/
+│   ├── query.go        # Query endpoints
+│   ├── websocket.go    # WebSocket streaming
+│   ├── agent.go        # Agent CRUD
+│   ├── memory.go       # Memory endpoints
+│   ├── admin.go        # Health/metrics
+│   └���─ auth.go         # Token endpoint
+├── middleware/
+│   ├── cors.go         # CORS handling
+│   ├── ratelimit.go    # Rate limiting
+│   ├── auth.go         # JWT + OPA auth
+│   ├── audit.go        # Audit logging
+│   └── tracing.go      # OpenTelemetry
+├── observability/
+│   └── metrics.go      # Prometheus metrics
+└── services/
+    ├── registry.go     # Service discovery
+    └── clients.go      # gRPC clients
+```
+
+## License
+
+Apache 2.0

gateway.example.yaml

@@ -0,0 +1,96 @@
+# Gateway Configuration Example
+server:
+  bindAddr: ":8443"
+  readTimeout: 30s
+  writeTimeout: 60s
+  idleTimeout: 120s
+  shutdownTimeout: 30s
+  maxHeaderBytes: 1048576
+  enableHttp2: true
+
+tls:
+  enabled: false
+  certFile: "/certs/tls.crt"
+  keyFile: "/certs/tls.key"
+  minVersion: "1.2"
+
+rateLimit:
+  enabled: true
+  requestsPerSec: 100
+  burstSize: 200
+  perTenant: true
+  perUser: true
+  redisEnabled: true
+  cleanupInterval: 10m
+
+cors:
+  allowedOrigins:
+    - "https://app.rag-agent.io"
+    - "https://admin.rag-agent.io"
+    - "http://localhost:3000"
+  allowedMethods:
+    - "GET"
+    - "POST"
+    - "PUT"
+    - "DELETE"
+    - "OPTIONS"
+  allowedHeaders:
+    - "Authorization"
+    - "Content-Type"
+    - "X-Request-ID"
+    - "X-Client-Version"
+  allowCredentials: true
+  maxAge: 3600
+
+auth:
+  jwtSecret: "${JWT_SECRET}"
+  jwtIssuer: "rag-agent"
+  jwtAudience: "api"
+  tokenDuration: 24h
+  opaEnabled: false
+  opaAddr: "http://opa:8181"
+  opaPolicy: "authz/allow"
+  skipPaths:
+    - "/admin/health"
+    - "/admin/metrics"
+
+cache:
+  enabled: true
+  redisAddr: "redis:6379"
+  redisPassword: ""
+  redisDb: 0
+  defaultTtl: 5m
+  maxEntrySize: 1048576
+  keyPrefix: "rag:gateway:"
+
+serviceDiscovery:
+  enabled: false
+  consulAddr: "consul:8500"
+  consulToken: ""
+  serviceRefreshInterval: 30s
+  agentServiceAddr: "agent-server:9090"
+  retrieverServiceAddr: "retriever-server:9091"
+  generatorServiceAddr: "generator-server:9092"
+  memoryServiceAddr: "memory-server:9093"
+
+circuitBreaker:
+  maxRequests: 5
+  interval: 60s
+  timeout: 30s
+  failureThreshold: 3
+
+observability:
+  metricsEnabled: true
+  metricsPath: "/admin/metrics"
+  tracingEnabled: true
+  tracingEndpoint: "jaeger:4317"
+  serviceName: "api-gateway"
+  auditLogEnabled: true
+
+websocket:
+  readBufferSize: 1024
+  writeBufferSize: 1024
+  pingInterval: 30s
+  pongWait: 60s
+  writeWait: 10s
+  maxMessageSize: 524288

generator.pb.go

@@ -0,0 +1,1414 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        v6.33.2
+// source: generator.proto
+
+package ragv1
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// GenerateRequest for LLM generation
+type GenerateRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// System prompt
+	SystemPrompt string `protobuf:"bytes,1,opt,name=system_prompt,json=systemPrompt,proto3" json:"system_prompt,omitempty"`
+	// User query/prompt
+	Prompt string `protobuf:"bytes,2,opt,name=prompt,proto3" json:"prompt,omitempty"`
+	// Context from retrieved documents
+	Context []*ContextDocument `protobuf:"bytes,3,rep,name=context,proto3" json:"context,omitempty"`
+	// Conversation history
+	History []*ChatMessage `protobuf:"bytes,4,rep,name=history,proto3" json:"history,omitempty"`
+	// Generation configuration
+	Config        *GenerateConfig `protobuf:"bytes,5,opt,name=config,proto3" json:"config,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *GenerateRequest) Reset() {
+	*x = GenerateRequest{}
+	mi := &file_generator_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GenerateRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GenerateRequest) ProtoMessage() {}
+
+func (x *GenerateRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GenerateRequest.ProtoReflect.Descriptor instead.
+func (*GenerateRequest) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *GenerateRequest) GetSystemPrompt() string {
+	if x != nil {
+		return x.SystemPrompt
+	}
+	return ""
+}
+
+func (x *GenerateRequest) GetPrompt() string {
+	if x != nil {
+		return x.Prompt
+	}
+	return ""
+}
+
+func (x *GenerateRequest) GetContext() []*ContextDocument {
+	if x != nil {
+		return x.Context
+	}
+	return nil
+}
+
+func (x *GenerateRequest) GetHistory() []*ChatMessage {
+	if x != nil {
+		return x.History
+	}
+	return nil
+}
+
+func (x *GenerateRequest) GetConfig() *GenerateConfig {
+	if x != nil {
+		return x.Config
+	}
+	return nil
+}
+
+// ContextDocument represents retrieved context
+type ContextDocument struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Document content
+	Content string `protobuf:"bytes,1,opt,name=content,proto3" json:"content,omitempty"`
+	// Document title
+	Title string `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
+	// Source reference
+	Source string `protobuf:"bytes,3,opt,name=source,proto3" json:"source,omitempty"`
+	// Relevance score
+	Score         float32 `protobuf:"fixed32,4,opt,name=score,proto3" json:"score,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ContextDocument) Reset() {
+	*x = ContextDocument{}
+	mi := &file_generator_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ContextDocument) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ContextDocument) ProtoMessage() {}
+
+func (x *ContextDocument) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ContextDocument.ProtoReflect.Descriptor instead.
+func (*ContextDocument) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *ContextDocument) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+func (x *ContextDocument) GetTitle() string {
+	if x != nil {
+		return x.Title
+	}
+	return ""
+}
+
+func (x *ContextDocument) GetSource() string {
+	if x != nil {
+		return x.Source
+	}
+	return ""
+}
+
+func (x *ContextDocument) GetScore() float32 {
+	if x != nil {
+		return x.Score
+	}
+	return 0
+}
+
+// ChatMessage for conversation history
+type ChatMessage struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Role: user, assistant, system
+	Role string `protobuf:"bytes,1,opt,name=role,proto3" json:"role,omitempty"`
+	// Message content
+	Content       string `protobuf:"bytes,2,opt,name=content,proto3" json:"content,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ChatMessage) Reset() {
+	*x = ChatMessage{}
+	mi := &file_generator_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ChatMessage) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ChatMessage) ProtoMessage() {}
+
+func (x *ChatMessage) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ChatMessage.ProtoReflect.Descriptor instead.
+func (*ChatMessage) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *ChatMessage) GetRole() string {
+	if x != nil {
+		return x.Role
+	}
+	return ""
+}
+
+func (x *ChatMessage) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+// GenerateConfig for generation parameters
+type GenerateConfig struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Model to use
+	Model string `protobuf:"bytes,1,opt,name=model,proto3" json:"model,omitempty"`
+	// Temperature (0.0 - 2.0)
+	Temperature float32 `protobuf:"fixed32,2,opt,name=temperature,proto3" json:"temperature,omitempty"`
+	// Maximum tokens to generate
+	MaxTokens int32 `protobuf:"varint,3,opt,name=max_tokens,json=maxTokens,proto3" json:"max_tokens,omitempty"`
+	// Top-p sampling
+	TopP float32 `protobuf:"fixed32,4,opt,name=top_p,json=topP,proto3" json:"top_p,omitempty"`
+	// Frequency penalty
+	FrequencyPenalty float32 `protobuf:"fixed32,5,opt,name=frequency_penalty,json=frequencyPenalty,proto3" json:"frequency_penalty,omitempty"`
+	// Presence penalty
+	PresencePenalty float32 `protobuf:"fixed32,6,opt,name=presence_penalty,json=presencePenalty,proto3" json:"presence_penalty,omitempty"`
+	// Stop sequences
+	StopSequences []string `protobuf:"bytes,7,rep,name=stop_sequences,json=stopSequences,proto3" json:"stop_sequences,omitempty"`
+	// Response format: text, json
+	ResponseFormat string `protobuf:"bytes,8,opt,name=response_format,json=responseFormat,proto3" json:"response_format,omitempty"`
+	unknownFields  protoimpl.UnknownFields
+	sizeCache      protoimpl.SizeCache
+}
+
+func (x *GenerateConfig) Reset() {
+	*x = GenerateConfig{}
+	mi := &file_generator_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GenerateConfig) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GenerateConfig) ProtoMessage() {}
+
+func (x *GenerateConfig) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GenerateConfig.ProtoReflect.Descriptor instead.
+func (*GenerateConfig) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *GenerateConfig) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *GenerateConfig) GetTemperature() float32 {
+	if x != nil {
+		return x.Temperature
+	}
+	return 0
+}
+
+func (x *GenerateConfig) GetMaxTokens() int32 {
+	if x != nil {
+		return x.MaxTokens
+	}
+	return 0
+}
+
+func (x *GenerateConfig) GetTopP() float32 {
+	if x != nil {
+		return x.TopP
+	}
+	return 0
+}
+
+func (x *GenerateConfig) GetFrequencyPenalty() float32 {
+	if x != nil {
+		return x.FrequencyPenalty
+	}
+	return 0
+}
+
+func (x *GenerateConfig) GetPresencePenalty() float32 {
+	if x != nil {
+		return x.PresencePenalty
+	}
+	return 0
+}
+
+func (x *GenerateConfig) GetStopSequences() []string {
+	if x != nil {
+		return x.StopSequences
+	}
+	return nil
+}
+
+func (x *GenerateConfig) GetResponseFormat() string {
+	if x != nil {
+		return x.ResponseFormat
+	}
+	return ""
+}
+
+// GenerateResponse contains the generated text
+type GenerateResponse struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Generated text
+	Text string `protobuf:"bytes,1,opt,name=text,proto3" json:"text,omitempty"`
+	// Token usage
+	Usage *TokenUsage `protobuf:"bytes,2,opt,name=usage,proto3" json:"usage,omitempty"`
+	// Finish reason: stop, length, content_filter
+	FinishReason string `protobuf:"bytes,3,opt,name=finish_reason,json=finishReason,proto3" json:"finish_reason,omitempty"`
+	// Model used
+	Model string `protobuf:"bytes,4,opt,name=model,proto3" json:"model,omitempty"`
+	// Generation metadata
+	Metadata      *GenerateMetadata `protobuf:"bytes,5,opt,name=metadata,proto3" json:"metadata,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *GenerateResponse) Reset() {
+	*x = GenerateResponse{}
+	mi := &file_generator_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GenerateResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GenerateResponse) ProtoMessage() {}
+
+func (x *GenerateResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GenerateResponse.ProtoReflect.Descriptor instead.
+func (*GenerateResponse) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *GenerateResponse) GetText() string {
+	if x != nil {
+		return x.Text
+	}
+	return ""
+}
+
+func (x *GenerateResponse) GetUsage() *TokenUsage {
+	if x != nil {
+		return x.Usage
+	}
+	return nil
+}
+
+func (x *GenerateResponse) GetFinishReason() string {
+	if x != nil {
+		return x.FinishReason
+	}
+	return ""
+}
+
+func (x *GenerateResponse) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *GenerateResponse) GetMetadata() *GenerateMetadata {
+	if x != nil {
+		return x.Metadata
+	}
+	return nil
+}
+
+// TokenUsage tracks token consumption
+type TokenUsage struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Prompt tokens
+	PromptTokens int32 `protobuf:"varint,1,opt,name=prompt_tokens,json=promptTokens,proto3" json:"prompt_tokens,omitempty"`
+	// Completion tokens
+	CompletionTokens int32 `protobuf:"varint,2,opt,name=completion_tokens,json=completionTokens,proto3" json:"completion_tokens,omitempty"`
+	// Total tokens
+	TotalTokens int32 `protobuf:"varint,3,opt,name=total_tokens,json=totalTokens,proto3" json:"total_tokens,omitempty"`
+	// Estimated cost in USD
+	EstimatedCost float32 `protobuf:"fixed32,4,opt,name=estimated_cost,json=estimatedCost,proto3" json:"estimated_cost,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *TokenUsage) Reset() {
+	*x = TokenUsage{}
+	mi := &file_generator_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *TokenUsage) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*TokenUsage) ProtoMessage() {}
+
+func (x *TokenUsage) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use TokenUsage.ProtoReflect.Descriptor instead.
+func (*TokenUsage) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{5}
+}
+
+func (x *TokenUsage) GetPromptTokens() int32 {
+	if x != nil {
+		return x.PromptTokens
+	}
+	return 0
+}
+
+func (x *TokenUsage) GetCompletionTokens() int32 {
+	if x != nil {
+		return x.CompletionTokens
+	}
+	return 0
+}
+
+func (x *TokenUsage) GetTotalTokens() int32 {
+	if x != nil {
+		return x.TotalTokens
+	}
+	return 0
+}
+
+func (x *TokenUsage) GetEstimatedCost() float32 {
+	if x != nil {
+		return x.EstimatedCost
+	}
+	return 0
+}
+
+// GenerateMetadata for generation info
+type GenerateMetadata struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Latency in milliseconds
+	LatencyMs int64 `protobuf:"varint,1,opt,name=latency_ms,json=latencyMs,proto3" json:"latency_ms,omitempty"`
+	// Provider used
+	Provider string `protobuf:"bytes,2,opt,name=provider,proto3" json:"provider,omitempty"`
+	// Trace ID
+	TraceId       string `protobuf:"bytes,3,opt,name=trace_id,json=traceId,proto3" json:"trace_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *GenerateMetadata) Reset() {
+	*x = GenerateMetadata{}
+	mi := &file_generator_proto_msgTypes[6]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GenerateMetadata) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GenerateMetadata) ProtoMessage() {}
+
+func (x *GenerateMetadata) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[6]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GenerateMetadata.ProtoReflect.Descriptor instead.
+func (*GenerateMetadata) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *GenerateMetadata) GetLatencyMs() int64 {
+	if x != nil {
+		return x.LatencyMs
+	}
+	return 0
+}
+
+func (x *GenerateMetadata) GetProvider() string {
+	if x != nil {
+		return x.Provider
+	}
+	return ""
+}
+
+func (x *GenerateMetadata) GetTraceId() string {
+	if x != nil {
+		return x.TraceId
+	}
+	return ""
+}
+
+// GenerateChunk for streaming responses
+type GenerateChunk struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Text delta
+	Delta string `protobuf:"bytes,1,opt,name=delta,proto3" json:"delta,omitempty"`
+	// Is this the final chunk?
+	IsFinal bool `protobuf:"varint,2,opt,name=is_final,json=isFinal,proto3" json:"is_final,omitempty"`
+	// Token usage (in final chunk)
+	Usage *TokenUsage `protobuf:"bytes,3,opt,name=usage,proto3" json:"usage,omitempty"`
+	// Finish reason (in final chunk)
+	FinishReason  string `protobuf:"bytes,4,opt,name=finish_reason,json=finishReason,proto3" json:"finish_reason,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *GenerateChunk) Reset() {
+	*x = GenerateChunk{}
+	mi := &file_generator_proto_msgTypes[7]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GenerateChunk) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GenerateChunk) ProtoMessage() {}
+
+func (x *GenerateChunk) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[7]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GenerateChunk.ProtoReflect.Descriptor instead.
+func (*GenerateChunk) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{7}
+}
+
+func (x *GenerateChunk) GetDelta() string {
+	if x != nil {
+		return x.Delta
+	}
+	return ""
+}
+
+func (x *GenerateChunk) GetIsFinal() bool {
+	if x != nil {
+		return x.IsFinal
+	}
+	return false
+}
+
+func (x *GenerateChunk) GetUsage() *TokenUsage {
+	if x != nil {
+		return x.Usage
+	}
+	return nil
+}
+
+func (x *GenerateChunk) GetFinishReason() string {
+	if x != nil {
+		return x.FinishReason
+	}
+	return ""
+}
+
+// EmbeddingRequest for generating embeddings
+type EmbeddingRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Text to embed
+	Text string `protobuf:"bytes,1,opt,name=text,proto3" json:"text,omitempty"`
+	// Model to use
+	Model string `protobuf:"bytes,2,opt,name=model,proto3" json:"model,omitempty"`
+	// Embedding dimensions (if configurable)
+	Dimensions    int32 `protobuf:"varint,3,opt,name=dimensions,proto3" json:"dimensions,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *EmbeddingRequest) Reset() {
+	*x = EmbeddingRequest{}
+	mi := &file_generator_proto_msgTypes[8]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *EmbeddingRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*EmbeddingRequest) ProtoMessage() {}
+
+func (x *EmbeddingRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[8]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use EmbeddingRequest.ProtoReflect.Descriptor instead.
+func (*EmbeddingRequest) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{8}
+}
+
+func (x *EmbeddingRequest) GetText() string {
+	if x != nil {
+		return x.Text
+	}
+	return ""
+}
+
+func (x *EmbeddingRequest) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *EmbeddingRequest) GetDimensions() int32 {
+	if x != nil {
+		return x.Dimensions
+	}
+	return 0
+}
+
+// EmbeddingResponse contains the embedding
+type EmbeddingResponse struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Embedding vector
+	Embedding []float32 `protobuf:"fixed32,1,rep,packed,name=embedding,proto3" json:"embedding,omitempty"`
+	// Model used
+	Model string `protobuf:"bytes,2,opt,name=model,proto3" json:"model,omitempty"`
+	// Token usage
+	Tokens int32 `protobuf:"varint,3,opt,name=tokens,proto3" json:"tokens,omitempty"`
+	// Dimensions
+	Dimensions    int32 `protobuf:"varint,4,opt,name=dimensions,proto3" json:"dimensions,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *EmbeddingResponse) Reset() {
+	*x = EmbeddingResponse{}
+	mi := &file_generator_proto_msgTypes[9]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *EmbeddingResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*EmbeddingResponse) ProtoMessage() {}
+
+func (x *EmbeddingResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[9]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use EmbeddingResponse.ProtoReflect.Descriptor instead.
+func (*EmbeddingResponse) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{9}
+}
+
+func (x *EmbeddingResponse) GetEmbedding() []float32 {
+	if x != nil {
+		return x.Embedding
+	}
+	return nil
+}
+
+func (x *EmbeddingResponse) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *EmbeddingResponse) GetTokens() int32 {
+	if x != nil {
+		return x.Tokens
+	}
+	return 0
+}
+
+func (x *EmbeddingResponse) GetDimensions() int32 {
+	if x != nil {
+		return x.Dimensions
+	}
+	return 0
+}
+
+// BatchEmbeddingRequest for bulk embeddings
+type BatchEmbeddingRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Texts to embed
+	Texts []string `protobuf:"bytes,1,rep,name=texts,proto3" json:"texts,omitempty"`
+	// Model to use
+	Model string `protobuf:"bytes,2,opt,name=model,proto3" json:"model,omitempty"`
+	// Embedding dimensions
+	Dimensions    int32 `protobuf:"varint,3,opt,name=dimensions,proto3" json:"dimensions,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *BatchEmbeddingRequest) Reset() {
+	*x = BatchEmbeddingRequest{}
+	mi := &file_generator_proto_msgTypes[10]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *BatchEmbeddingRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*BatchEmbeddingRequest) ProtoMessage() {}
+
+func (x *BatchEmbeddingRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[10]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use BatchEmbeddingRequest.ProtoReflect.Descriptor instead.
+func (*BatchEmbeddingRequest) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{10}
+}
+
+func (x *BatchEmbeddingRequest) GetTexts() []string {
+	if x != nil {
+		return x.Texts
+	}
+	return nil
+}
+
+func (x *BatchEmbeddingRequest) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+func (x *BatchEmbeddingRequest) GetDimensions() int32 {
+	if x != nil {
+		return x.Dimensions
+	}
+	return 0
+}
+
+// BatchEmbeddingResponse for bulk embeddings
+type BatchEmbeddingResponse struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Embeddings
+	Embeddings []*EmbeddingResult `protobuf:"bytes,1,rep,name=embeddings,proto3" json:"embeddings,omitempty"`
+	// Total tokens used
+	TotalTokens int32 `protobuf:"varint,2,opt,name=total_tokens,json=totalTokens,proto3" json:"total_tokens,omitempty"`
+	// Model used
+	Model         string `protobuf:"bytes,3,opt,name=model,proto3" json:"model,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *BatchEmbeddingResponse) Reset() {
+	*x = BatchEmbeddingResponse{}
+	mi := &file_generator_proto_msgTypes[11]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *BatchEmbeddingResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*BatchEmbeddingResponse) ProtoMessage() {}
+
+func (x *BatchEmbeddingResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[11]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use BatchEmbeddingResponse.ProtoReflect.Descriptor instead.
+func (*BatchEmbeddingResponse) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{11}
+}
+
+func (x *BatchEmbeddingResponse) GetEmbeddings() []*EmbeddingResult {
+	if x != nil {
+		return x.Embeddings
+	}
+	return nil
+}
+
+func (x *BatchEmbeddingResponse) GetTotalTokens() int32 {
+	if x != nil {
+		return x.TotalTokens
+	}
+	return 0
+}
+
+func (x *BatchEmbeddingResponse) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+// EmbeddingResult for individual embedding
+type EmbeddingResult struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Index in the batch
+	Index int32 `protobuf:"varint,1,opt,name=index,proto3" json:"index,omitempty"`
+	// Embedding vector
+	Embedding []float32 `protobuf:"fixed32,2,rep,packed,name=embedding,proto3" json:"embedding,omitempty"`
+	// Tokens used
+	Tokens        int32 `protobuf:"varint,3,opt,name=tokens,proto3" json:"tokens,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *EmbeddingResult) Reset() {
+	*x = EmbeddingResult{}
+	mi := &file_generator_proto_msgTypes[12]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *EmbeddingResult) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*EmbeddingResult) ProtoMessage() {}
+
+func (x *EmbeddingResult) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[12]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use EmbeddingResult.ProtoReflect.Descriptor instead.
+func (*EmbeddingResult) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *EmbeddingResult) GetIndex() int32 {
+	if x != nil {
+		return x.Index
+	}
+	return 0
+}
+
+func (x *EmbeddingResult) GetEmbedding() []float32 {
+	if x != nil {
+		return x.Embedding
+	}
+	return nil
+}
+
+func (x *EmbeddingResult) GetTokens() int32 {
+	if x != nil {
+		return x.Tokens
+	}
+	return 0
+}
+
+// RerankRequest for document reranking
+type RerankRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Query for relevance scoring
+	Query string `protobuf:"bytes,1,opt,name=query,proto3" json:"query,omitempty"`
+	// Documents to rerank
+	Documents []*RerankDocument `protobuf:"bytes,2,rep,name=documents,proto3" json:"documents,omitempty"`
+	// Number of top results to return
+	TopN int32 `protobuf:"varint,3,opt,name=top_n,json=topN,proto3" json:"top_n,omitempty"`
+	// Model to use for reranking
+	Model         string `protobuf:"bytes,4,opt,name=model,proto3" json:"model,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *RerankRequest) Reset() {
+	*x = RerankRequest{}
+	mi := &file_generator_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *RerankRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*RerankRequest) ProtoMessage() {}
+
+func (x *RerankRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use RerankRequest.ProtoReflect.Descriptor instead.
+func (*RerankRequest) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *RerankRequest) GetQuery() string {
+	if x != nil {
+		return x.Query
+	}
+	return ""
+}
+
+func (x *RerankRequest) GetDocuments() []*RerankDocument {
+	if x != nil {
+		return x.Documents
+	}
+	return nil
+}
+
+func (x *RerankRequest) GetTopN() int32 {
+	if x != nil {
+		return x.TopN
+	}
+	return 0
+}
+
+func (x *RerankRequest) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+// RerankDocument for reranking input
+type RerankDocument struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Document ID
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Document content
+	Content string `protobuf:"bytes,2,opt,name=content,proto3" json:"content,omitempty"`
+	// Original score (optional)
+	OriginalScore float32 `protobuf:"fixed32,3,opt,name=original_score,json=originalScore,proto3" json:"original_score,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *RerankDocument) Reset() {
+	*x = RerankDocument{}
+	mi := &file_generator_proto_msgTypes[14]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *RerankDocument) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*RerankDocument) ProtoMessage() {}
+
+func (x *RerankDocument) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[14]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use RerankDocument.ProtoReflect.Descriptor instead.
+func (*RerankDocument) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{14}
+}
+
+func (x *RerankDocument) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *RerankDocument) GetContent() string {
+	if x != nil {
+		return x.Content
+	}
+	return ""
+}
+
+func (x *RerankDocument) GetOriginalScore() float32 {
+	if x != nil {
+		return x.OriginalScore
+	}
+	return 0
+}
+
+// RerankResponse contains reranked documents
+type RerankResponse struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Reranked results
+	Results []*RerankResult `protobuf:"bytes,1,rep,name=results,proto3" json:"results,omitempty"`
+	// Model used
+	Model         string `protobuf:"bytes,2,opt,name=model,proto3" json:"model,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *RerankResponse) Reset() {
+	*x = RerankResponse{}
+	mi := &file_generator_proto_msgTypes[15]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *RerankResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*RerankResponse) ProtoMessage() {}
+
+func (x *RerankResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[15]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use RerankResponse.ProtoReflect.Descriptor instead.
+func (*RerankResponse) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{15}
+}
+
+func (x *RerankResponse) GetResults() []*RerankResult {
+	if x != nil {
+		return x.Results
+	}
+	return nil
+}
+
+func (x *RerankResponse) GetModel() string {
+	if x != nil {
+		return x.Model
+	}
+	return ""
+}
+
+// RerankResult for reranked document
+type RerankResult struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Document ID
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// New relevance score
+	Score float32 `protobuf:"fixed32,2,opt,name=score,proto3" json:"score,omitempty"`
+	// New rank position
+	Rank int32 `protobuf:"varint,3,opt,name=rank,proto3" json:"rank,omitempty"`
+	// Original rank position
+	OriginalRank  int32 `protobuf:"varint,4,opt,name=original_rank,json=originalRank,proto3" json:"original_rank,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *RerankResult) Reset() {
+	*x = RerankResult{}
+	mi := &file_generator_proto_msgTypes[16]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *RerankResult) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*RerankResult) ProtoMessage() {}
+
+func (x *RerankResult) ProtoReflect() protoreflect.Message {
+	mi := &file_generator_proto_msgTypes[16]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use RerankResult.ProtoReflect.Descriptor instead.
+func (*RerankResult) Descriptor() ([]byte, []int) {
+	return file_generator_proto_rawDescGZIP(), []int{16}
+}
+
+func (x *RerankResult) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *RerankResult) GetScore() float32 {
+	if x != nil {
+		return x.Score
+	}
+	return 0
+}
+
+func (x *RerankResult) GetRank() int32 {
+	if x != nil {
+		return x.Rank
+	}
+	return 0
+}
+
+func (x *RerankResult) GetOriginalRank() int32 {
+	if x != nil {
+		return x.OriginalRank
+	}
+	return 0
+}
+
+var File_generator_proto protoreflect.FileDescriptor
+
+const file_generator_proto_rawDesc = "" +
+	"\n" +
+	"\x0fgenerator.proto\x12\x06rag.v1\"\xe0\x01\n" +
+	"\x0fGenerateRequest\x12#\n" +
+	"\rsystem_prompt\x18\x01 \x01(\tR\fsystemPrompt\x12\x16\n" +
+	"\x06prompt\x18\x02 \x01(\tR\x06prompt\x121\n" +
+	"\acontext\x18\x03 \x03(\v2\x17.rag.v1.ContextDocumentR\acontext\x12-\n" +
+	"\ahistory\x18\x04 \x03(\v2\x13.rag.v1.ChatMessageR\ahistory\x12.\n" +
+	"\x06config\x18\x05 \x01(\v2\x16.rag.v1.GenerateConfigR\x06config\"o\n" +
+	"\x0fContextDocument\x12\x18\n" +
+	"\acontent\x18\x01 \x01(\tR\acontent\x12\x14\n" +
+	"\x05title\x18\x02 \x01(\tR\x05title\x12\x16\n" +
+	"\x06source\x18\x03 \x01(\tR\x06source\x12\x14\n" +
+	"\x05score\x18\x04 \x01(\x02R\x05score\";\n" +
+	"\vChatMessage\x12\x12\n" +
+	"\x04role\x18\x01 \x01(\tR\x04role\x12\x18\n" +
+	"\acontent\x18\x02 \x01(\tR\acontent\"\xa4\x02\n" +
+	"\x0eGenerateConfig\x12\x14\n" +
+	"\x05model\x18\x01 \x01(\tR\x05model\x12 \n" +
+	"\vtemperature\x18\x02 \x01(\x02R\vtemperature\x12\x1d\n" +
+	"\n" +
+	"max_tokens\x18\x03 \x01(\x05R\tmaxTokens\x12\x13\n" +
+	"\x05top_p\x18\x04 \x01(\x02R\x04topP\x12+\n" +
+	"\x11frequency_penalty\x18\x05 \x01(\x02R\x10frequencyPenalty\x12)\n" +
+	"\x10presence_penalty\x18\x06 \x01(\x02R\x0fpresencePenalty\x12%\n" +
+	"\x0estop_sequences\x18\a \x03(\tR\rstopSequences\x12'\n" +
+	"\x0fresponse_format\x18\b \x01(\tR\x0eresponseFormat\"\xc1\x01\n" +
+	"\x10GenerateResponse\x12\x12\n" +
+	"\x04text\x18\x01 \x01(\tR\x04text\x12(\n" +
+	"\x05usage\x18\x02 \x01(\v2\x12.rag.v1.TokenUsageR\x05usage\x12#\n" +
+	"\rfinish_reason\x18\x03 \x01(\tR\ffinishReason\x12\x14\n" +
+	"\x05model\x18\x04 \x01(\tR\x05model\x124\n" +
+	"\bmetadata\x18\x05 \x01(\v2\x18.rag.v1.GenerateMetadataR\bmetadata\"\xa8\x01\n" +
+	"\n" +
+	"TokenUsage\x12#\n" +
+	"\rprompt_tokens\x18\x01 \x01(\x05R\fpromptTokens\x12+\n" +
+	"\x11completion_tokens\x18\x02 \x01(\x05R\x10completionTokens\x12!\n" +
+	"\ftotal_tokens\x18\x03 \x01(\x05R\vtotalTokens\x12%\n" +
+	"\x0eestimated_cost\x18\x04 \x01(\x02R\restimatedCost\"h\n" +
+	"\x10GenerateMetadata\x12\x1d\n" +
+	"\n" +
+	"latency_ms\x18\x01 \x01(\x03R\tlatencyMs\x12\x1a\n" +
+	"\bprovider\x18\x02 \x01(\tR\bprovider\x12\x19\n" +
+	"\btrace_id\x18\x03 \x01(\tR\atraceId\"\x8f\x01\n" +
+	"\rGenerateChunk\x12\x14\n" +
+	"\x05delta\x18\x01 \x01(\tR\x05delta\x12\x19\n" +
+	"\bis_final\x18\x02 \x01(\bR\aisFinal\x12(\n" +
+	"\x05usage\x18\x03 \x01(\v2\x12.rag.v1.TokenUsageR\x05usage\x12#\n" +
+	"\rfinish_reason\x18\x04 \x01(\tR\ffinishReason\"\\\n" +
+	"\x10EmbeddingRequest\x12\x12\n" +
+	"\x04text\x18\x01 \x01(\tR\x04text\x12\x14\n" +
+	"\x05model\x18\x02 \x01(\tR\x05model\x12\x1e\n" +
+	"\n" +
+	"dimensions\x18\x03 \x01(\x05R\n" +
+	"dimensions\"\x7f\n" +
+	"\x11EmbeddingResponse\x12\x1c\n" +
+	"\tembedding\x18\x01 \x03(\x02R\tembedding\x12\x14\n" +
+	"\x05model\x18\x02 \x01(\tR\x05model\x12\x16\n" +
+	"\x06tokens\x18\x03 \x01(\x05R\x06tokens\x12\x1e\n" +
+	"\n" +
+	"dimensions\x18\x04 \x01(\x05R\n" +
+	"dimensions\"c\n" +
+	"\x15BatchEmbeddingRequest\x12\x14\n" +
+	"\x05texts\x18\x01 \x03(\tR\x05texts\x12\x14\n" +
+	"\x05model\x18\x02 \x01(\tR\x05model\x12\x1e\n" +
+	"\n" +
+	"dimensions\x18\x03 \x01(\x05R\n" +
+	"dimensions\"\x8a\x01\n" +
+	"\x16BatchEmbeddingResponse\x127\n" +
+	"\n" +
+	"embeddings\x18\x01 \x03(\v2\x17.rag.v1.EmbeddingResultR\n" +
+	"embeddings\x12!\n" +
+	"\ftotal_tokens\x18\x02 \x01(\x05R\vtotalTokens\x12\x14\n" +
+	"\x05model\x18\x03 \x01(\tR\x05model\"]\n" +
+	"\x0fEmbeddingResult\x12\x14\n" +
+	"\x05index\x18\x01 \x01(\x05R\x05index\x12\x1c\n" +
+	"\tembedding\x18\x02 \x03(\x02R\tembedding\x12\x16\n" +
+	"\x06tokens\x18\x03 \x01(\x05R\x06tokens\"\x86\x01\n" +
+	"\rRerankRequest\x12\x14\n" +
+	"\x05query\x18\x01 \x01(\tR\x05query\x124\n" +
+	"\tdocuments\x18\x02 \x03(\v2\x16.rag.v1.RerankDocumentR\tdocuments\x12\x13\n" +
+	"\x05top_n\x18\x03 \x01(\x05R\x04topN\x12\x14\n" +
+	"\x05model\x18\x04 \x01(\tR\x05model\"a\n" +
+	"\x0eRerankDocument\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x18\n" +
+	"\acontent\x18\x02 \x01(\tR\acontent\x12%\n" +
+	"\x0eoriginal_score\x18\x03 \x01(\x02R\roriginalScore\"V\n" +
+	"\x0eRerankResponse\x12.\n" +
+	"\aresults\x18\x01 \x03(\v2\x14.rag.v1.RerankResultR\aresults\x12\x14\n" +
+	"\x05model\x18\x02 \x01(\tR\x05model\"m\n" +
+	"\fRerankResult\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n" +
+	"\x05score\x18\x02 \x01(\x02R\x05score\x12\x12\n" +
+	"\x04rank\x18\x03 \x01(\x05R\x04rank\x12#\n" +
+	"\roriginal_rank\x18\x04 \x01(\x05R\foriginalRank2\xf2\x02\n" +
+	"\x10GeneratorService\x12=\n" +
+	"\bGenerate\x12\x17.rag.v1.GenerateRequest\x1a\x18.rag.v1.GenerateResponse\x12B\n" +
+	"\x0eGenerateStream\x12\x17.rag.v1.GenerateRequest\x1a\x15.rag.v1.GenerateChunk0\x01\x12H\n" +
+	"\x11GenerateEmbedding\x12\x18.rag.v1.EmbeddingRequest\x1a\x19.rag.v1.EmbeddingResponse\x12X\n" +
+	"\x17BatchGenerateEmbeddings\x12\x1d.rag.v1.BatchEmbeddingRequest\x1a\x1e.rag.v1.BatchEmbeddingResponse\x127\n" +
+	"\x06Rerank\x12\x15.rag.v1.RerankRequest\x1a\x16.rag.v1.RerankResponseB6Z4github.com/AmaniQuery/amaniquery/pkg/proto/gen/ragv1b\x06proto3"
+
+var (
+	file_generator_proto_rawDescOnce sync.Once
+	file_generator_proto_rawDescData []byte
+)
+
+func file_generator_proto_rawDescGZIP() []byte {
+	file_generator_proto_rawDescOnce.Do(func() {
+		file_generator_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_generator_proto_rawDesc), len(file_generator_proto_rawDesc)))
+	})
+	return file_generator_proto_rawDescData
+}
+
+var file_generator_proto_msgTypes = make([]protoimpl.MessageInfo, 17)
+var file_generator_proto_goTypes = []any{
+	(*GenerateRequest)(nil),        // 0: rag.v1.GenerateRequest
+	(*ContextDocument)(nil),        // 1: rag.v1.ContextDocument
+	(*ChatMessage)(nil),            // 2: rag.v1.ChatMessage
+	(*GenerateConfig)(nil),         // 3: rag.v1.GenerateConfig
+	(*GenerateResponse)(nil),       // 4: rag.v1.GenerateResponse
+	(*TokenUsage)(nil),             // 5: rag.v1.TokenUsage
+	(*GenerateMetadata)(nil),       // 6: rag.v1.GenerateMetadata
+	(*GenerateChunk)(nil),          // 7: rag.v1.GenerateChunk
+	(*EmbeddingRequest)(nil),       // 8: rag.v1.EmbeddingRequest
+	(*EmbeddingResponse)(nil),      // 9: rag.v1.EmbeddingResponse
+	(*BatchEmbeddingRequest)(nil),  // 10: rag.v1.BatchEmbeddingRequest
+	(*BatchEmbeddingResponse)(nil), // 11: rag.v1.BatchEmbeddingResponse
+	(*EmbeddingResult)(nil),        // 12: rag.v1.EmbeddingResult
+	(*RerankRequest)(nil),          // 13: rag.v1.RerankRequest
+	(*RerankDocument)(nil),         // 14: rag.v1.RerankDocument
+	(*RerankResponse)(nil),         // 15: rag.v1.RerankResponse
+	(*RerankResult)(nil),           // 16: rag.v1.RerankResult
+}
+var file_generator_proto_depIdxs = []int32{
+	1,  // 0: rag.v1.GenerateRequest.context:type_name -> rag.v1.ContextDocument
+	2,  // 1: rag.v1.GenerateRequest.history:type_name -> rag.v1.ChatMessage
+	3,  // 2: rag.v1.GenerateRequest.config:type_name -> rag.v1.GenerateConfig
+	5,  // 3: rag.v1.GenerateResponse.usage:type_name -> rag.v1.TokenUsage
+	6,  // 4: rag.v1.GenerateResponse.metadata:type_name -> rag.v1.GenerateMetadata
+	5,  // 5: rag.v1.GenerateChunk.usage:type_name -> rag.v1.TokenUsage
+	12, // 6: rag.v1.BatchEmbeddingResponse.embeddings:type_name -> rag.v1.EmbeddingResult
+	14, // 7: rag.v1.RerankRequest.documents:type_name -> rag.v1.RerankDocument
+	16, // 8: rag.v1.RerankResponse.results:type_name -> rag.v1.RerankResult
+	0,  // 9: rag.v1.GeneratorService.Generate:input_type -> rag.v1.GenerateRequest
+	0,  // 10: rag.v1.GeneratorService.GenerateStream:input_type -> rag.v1.GenerateRequest
+	8,  // 11: rag.v1.GeneratorService.GenerateEmbedding:input_type -> rag.v1.EmbeddingRequest
+	10, // 12: rag.v1.GeneratorService.BatchGenerateEmbeddings:input_type -> rag.v1.BatchEmbeddingRequest
+	13, // 13: rag.v1.GeneratorService.Rerank:input_type -> rag.v1.RerankRequest
+	4,  // 14: rag.v1.GeneratorService.Generate:output_type -> rag.v1.GenerateResponse
+	7,  // 15: rag.v1.GeneratorService.GenerateStream:output_type -> rag.v1.GenerateChunk
+	9,  // 16: rag.v1.GeneratorService.GenerateEmbedding:output_type -> rag.v1.EmbeddingResponse
+	11, // 17: rag.v1.GeneratorService.BatchGenerateEmbeddings:output_type -> rag.v1.BatchEmbeddingResponse
+	15, // 18: rag.v1.GeneratorService.Rerank:output_type -> rag.v1.RerankResponse
+	14, // [14:19] is the sub-list for method output_type
+	9,  // [9:14] is the sub-list for method input_type
+	9,  // [9:9] is the sub-list for extension type_name
+	9,  // [9:9] is the sub-list for extension extendee
+	0,  // [0:9] is the sub-list for field type_name
+}
+
+func init() { file_generator_proto_init() }
+func file_generator_proto_init() {
+	if File_generator_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_generator_proto_rawDesc), len(file_generator_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   17,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_generator_proto_goTypes,
+		DependencyIndexes: file_generator_proto_depIdxs,
+		MessageInfos:      file_generator_proto_msgTypes,
+	}.Build()
+	File_generator_proto = out.File
+	file_generator_proto_goTypes = nil
+	file_generator_proto_depIdxs = nil
+}

generator_grpc.pb.go

@@ -0,0 +1,291 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.6.0
+// - protoc             v6.33.2
+// source: generator.proto
+
+package ragv1
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	GeneratorService_Generate_FullMethodName                = "/rag.v1.GeneratorService/Generate"
+	GeneratorService_GenerateStream_FullMethodName          = "/rag.v1.GeneratorService/GenerateStream"
+	GeneratorService_GenerateEmbedding_FullMethodName       = "/rag.v1.GeneratorService/GenerateEmbedding"
+	GeneratorService_BatchGenerateEmbeddings_FullMethodName = "/rag.v1.GeneratorService/BatchGenerateEmbeddings"
+	GeneratorService_Rerank_FullMethodName                  = "/rag.v1.GeneratorService/Rerank"
+)
+
+// GeneratorServiceClient is the client API for GeneratorService service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// GeneratorService handles LLM-based response generation
+type GeneratorServiceClient interface {
+	// Generate a complete response
+	Generate(ctx context.Context, in *GenerateRequest, opts ...grpc.CallOption) (*GenerateResponse, error)
+	// Generate with streaming output
+	GenerateStream(ctx context.Context, in *GenerateRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[GenerateChunk], error)
+	// Generate embeddings for text
+	GenerateEmbedding(ctx context.Context, in *EmbeddingRequest, opts ...grpc.CallOption) (*EmbeddingResponse, error)
+	// Batch generate embeddings
+	BatchGenerateEmbeddings(ctx context.Context, in *BatchEmbeddingRequest, opts ...grpc.CallOption) (*BatchEmbeddingResponse, error)
+	// Rerank documents based on query relevance
+	Rerank(ctx context.Context, in *RerankRequest, opts ...grpc.CallOption) (*RerankResponse, error)
+}
+
+type generatorServiceClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewGeneratorServiceClient(cc grpc.ClientConnInterface) GeneratorServiceClient {
+	return &generatorServiceClient{cc}
+}
+
+func (c *generatorServiceClient) Generate(ctx context.Context, in *GenerateRequest, opts ...grpc.CallOption) (*GenerateResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(GenerateResponse)
+	err := c.cc.Invoke(ctx, GeneratorService_Generate_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *generatorServiceClient) GenerateStream(ctx context.Context, in *GenerateRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[GenerateChunk], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &GeneratorService_ServiceDesc.Streams[0], GeneratorService_GenerateStream_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[GenerateRequest, GenerateChunk]{ClientStream: stream}
+	if err := x.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := x.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type GeneratorService_GenerateStreamClient = grpc.ServerStreamingClient[GenerateChunk]
+
+func (c *generatorServiceClient) GenerateEmbedding(ctx context.Context, in *EmbeddingRequest, opts ...grpc.CallOption) (*EmbeddingResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(EmbeddingResponse)
+	err := c.cc.Invoke(ctx, GeneratorService_GenerateEmbedding_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *generatorServiceClient) BatchGenerateEmbeddings(ctx context.Context, in *BatchEmbeddingRequest, opts ...grpc.CallOption) (*BatchEmbeddingResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(BatchEmbeddingResponse)
+	err := c.cc.Invoke(ctx, GeneratorService_BatchGenerateEmbeddings_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *generatorServiceClient) Rerank(ctx context.Context, in *RerankRequest, opts ...grpc.CallOption) (*RerankResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(RerankResponse)
+	err := c.cc.Invoke(ctx, GeneratorService_Rerank_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// GeneratorServiceServer is the server API for GeneratorService service.
+// All implementations must embed UnimplementedGeneratorServiceServer
+// for forward compatibility.
+//
+// GeneratorService handles LLM-based response generation
+type GeneratorServiceServer interface {
+	// Generate a complete response
+	Generate(context.Context, *GenerateRequest) (*GenerateResponse, error)
+	// Generate with streaming output
+	GenerateStream(*GenerateRequest, grpc.ServerStreamingServer[GenerateChunk]) error
+	// Generate embeddings for text
+	GenerateEmbedding(context.Context, *EmbeddingRequest) (*EmbeddingResponse, error)
+	// Batch generate embeddings
+	BatchGenerateEmbeddings(context.Context, *BatchEmbeddingRequest) (*BatchEmbeddingResponse, error)
+	// Rerank documents based on query relevance
+	Rerank(context.Context, *RerankRequest) (*RerankResponse, error)
+	mustEmbedUnimplementedGeneratorServiceServer()
+}
+
+// UnimplementedGeneratorServiceServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedGeneratorServiceServer struct{}
+
+func (UnimplementedGeneratorServiceServer) Generate(context.Context, *GenerateRequest) (*GenerateResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method Generate not implemented")
+}
+func (UnimplementedGeneratorServiceServer) GenerateStream(*GenerateRequest, grpc.ServerStreamingServer[GenerateChunk]) error {
+	return status.Error(codes.Unimplemented, "method GenerateStream not implemented")
+}
+func (UnimplementedGeneratorServiceServer) GenerateEmbedding(context.Context, *EmbeddingRequest) (*EmbeddingResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method GenerateEmbedding not implemented")
+}
+func (UnimplementedGeneratorServiceServer) BatchGenerateEmbeddings(context.Context, *BatchEmbeddingRequest) (*BatchEmbeddingResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method BatchGenerateEmbeddings not implemented")
+}
+func (UnimplementedGeneratorServiceServer) Rerank(context.Context, *RerankRequest) (*RerankResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method Rerank not implemented")
+}
+func (UnimplementedGeneratorServiceServer) mustEmbedUnimplementedGeneratorServiceServer() {}
+func (UnimplementedGeneratorServiceServer) testEmbeddedByValue()                          {}
+
+// UnsafeGeneratorServiceServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to GeneratorServiceServer will
+// result in compilation errors.
+type UnsafeGeneratorServiceServer interface {
+	mustEmbedUnimplementedGeneratorServiceServer()
+}
+
+func RegisterGeneratorServiceServer(s grpc.ServiceRegistrar, srv GeneratorServiceServer) {
+	// If the following call panics, it indicates UnimplementedGeneratorServiceServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&GeneratorService_ServiceDesc, srv)
+}
+
+func _GeneratorService_Generate_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(GenerateRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GeneratorServiceServer).Generate(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GeneratorService_Generate_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GeneratorServiceServer).Generate(ctx, req.(*GenerateRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GeneratorService_GenerateStream_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(GenerateRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(GeneratorServiceServer).GenerateStream(m, &grpc.GenericServerStream[GenerateRequest, GenerateChunk]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type GeneratorService_GenerateStreamServer = grpc.ServerStreamingServer[GenerateChunk]
+
+func _GeneratorService_GenerateEmbedding_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(EmbeddingRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GeneratorServiceServer).GenerateEmbedding(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GeneratorService_GenerateEmbedding_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GeneratorServiceServer).GenerateEmbedding(ctx, req.(*EmbeddingRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GeneratorService_BatchGenerateEmbeddings_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(BatchEmbeddingRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GeneratorServiceServer).BatchGenerateEmbeddings(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GeneratorService_BatchGenerateEmbeddings_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GeneratorServiceServer).BatchGenerateEmbeddings(ctx, req.(*BatchEmbeddingRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GeneratorService_Rerank_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(RerankRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GeneratorServiceServer).Rerank(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GeneratorService_Rerank_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GeneratorServiceServer).Rerank(ctx, req.(*RerankRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+// GeneratorService_ServiceDesc is the grpc.ServiceDesc for GeneratorService service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var GeneratorService_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "rag.v1.GeneratorService",
+	HandlerType: (*GeneratorServiceServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{
+			MethodName: "Generate",
+			Handler:    _GeneratorService_Generate_Handler,
+		},
+		{
+			MethodName: "GenerateEmbedding",
+			Handler:    _GeneratorService_GenerateEmbedding_Handler,
+		},
+		{
+			MethodName: "BatchGenerateEmbeddings",
+			Handler:    _GeneratorService_BatchGenerateEmbeddings_Handler,
+		},
+		{
+			MethodName: "Rerank",
+			Handler:    _GeneratorService_Rerank_Handler,
+		},
+	},
+	Streams: []grpc.StreamDesc{
+		{
+			StreamName:    "GenerateStream",
+			Handler:       _GeneratorService_GenerateStream_Handler,
+			ServerStreams: true,
+		},
+	},
+	Metadata: "generator.proto",
+}

go.mod

@@ -0,0 +1,118 @@
+module github.com/AmaniQuery/amaniquery
+
+go 1.24.0
+
+require (
+	github.com/blevesearch/bleve/v2 v2.3.10
+	github.com/golang-jwt/jwt/v5 v5.2.0
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/mux v1.8.1
+	github.com/gorilla/websocket v1.5.1
+	github.com/graph-gophers/graphql-go v1.5.0
+	github.com/hashicorp/consul/api v1.27.0
+	github.com/neo4j/neo4j-go-driver/v5 v5.17.0
+	github.com/pierrec/lz4/v4 v4.1.15
+	github.com/prometheus/client_golang v1.18.0
+	github.com/qdrant/go-client v1.7.0
+	github.com/redis/go-redis/v9 v9.4.0
+	github.com/sony/gobreaker v0.5.0
+	github.com/spf13/viper v1.18.2
+	go.opentelemetry.io/otel v1.38.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.22.0
+	go.opentelemetry.io/otel/sdk v1.38.0
+	go.opentelemetry.io/otel/trace v1.38.0
+	go.temporal.io/sdk v1.26.0
+	go.uber.org/zap v1.26.0
+	golang.org/x/sync v0.19.0
+	golang.org/x/time v0.5.0
+	google.golang.org/grpc v1.77.0
+	google.golang.org/protobuf v1.36.11
+)
+
+require (
+	github.com/RoaringBitmap/roaring v1.2.3 // indirect
+	github.com/armon/go-metrics v0.4.1 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/bits-and-blooms/bitset v1.2.0 // indirect
+	github.com/blevesearch/bleve_index_api v1.0.6 // indirect
+	github.com/blevesearch/geo v0.1.18 // indirect
+	github.com/blevesearch/go-porterstemmer v1.0.3 // indirect
+	github.com/blevesearch/gtreap v0.1.1 // indirect
+	github.com/blevesearch/mmap-go v1.0.4 // indirect
+	github.com/blevesearch/scorch_segment_api/v2 v2.1.6 // indirect
+	github.com/blevesearch/segment v0.9.1 // indirect
+	github.com/blevesearch/snowballstem v0.9.0 // indirect
+	github.com/blevesearch/upsidedown_store_api v1.0.2 // indirect
+	github.com/blevesearch/vellum v1.0.10 // indirect
+	github.com/blevesearch/zapx/v11 v11.3.10 // indirect
+	github.com/blevesearch/zapx/v12 v12.3.10 // indirect
+	github.com/blevesearch/zapx/v13 v13.3.10 // indirect
+	github.com/blevesearch/zapx/v14 v14.3.10 // indirect
+	github.com/blevesearch/zapx/v15 v15.3.13 // indirect
+	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a // indirect
+	github.com/fatih/color v1.14.1 // indirect
+	github.com/fsnotify/fsnotify v1.7.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/geo v0.0.0-20210211234256-740aa86cb551 // indirect
+	github.com/golang/mock v1.6.0 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/golang/snappy v0.0.4 // indirect
+	github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.1 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-hclog v1.5.0 // indirect
+	github.com/hashicorp/go-immutable-radix v1.3.1 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/hashicorp/go-rootcerts v1.0.2 // indirect
+	github.com/hashicorp/golang-lru v0.5.4 // indirect
+	github.com/hashicorp/hcl v1.0.0 // indirect
+	github.com/hashicorp/serf v0.10.1 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.17 // indirect
+	github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/mschoch/smat v0.2.0 // indirect
+	github.com/pborman/uuid v1.2.1 // indirect
+	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/client_model v0.5.0 // indirect
+	github.com/prometheus/common v0.45.0 // indirect
+	github.com/prometheus/procfs v0.12.0 // indirect
+	github.com/robfig/cron v1.2.0 // indirect
+	github.com/sagikazarmark/locafero v0.4.0 // indirect
+	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
+	github.com/sourcegraph/conc v0.3.0 // indirect
+	github.com/spf13/afero v1.11.0 // indirect
+	github.com/spf13/cast v1.6.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
+	go.etcd.io/bbolt v1.3.7 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.22.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.1.0 // indirect
+	go.temporal.io/api v1.29.1 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	golang.org/x/exp v0.0.0-20231127185646-65229373498e // indirect
+	golang.org/x/net v0.48.0 // indirect
+	golang.org/x/sys v0.39.0 // indirect
+	golang.org/x/text v0.32.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20251022142026-3a174f9686a8 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251213004720-97cd9d5aeac2 // indirect
+	gopkg.in/ini.v1 v1.67.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,497 @@
+cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
+github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
+github.com/DataDog/datadog-go v3.2.0+incompatible/go.mod h1:LButxg5PwREeZtORoXG3tL4fMGNddJ+vMq1mwgfaqoQ=
+github.com/RoaringBitmap/roaring v1.2.3 h1:yqreLINqIrX22ErkKI0vY47/ivtJr6n+kMhVOVmhWBY=
+github.com/RoaringBitmap/roaring v1.2.3/go.mod h1:plvDsJQpxOC5bw8LRteu/MLWHsHez/3y6cubLI4/1yE=
+github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
+github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
+github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
+github.com/alecthomas/units v0.0.0-20190717042225-c3de453c63f4/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
+github.com/armon/circbuf v0.0.0-20150827004946-bbbad097214e/go.mod h1:3U/XgcO3hCbHZ8TKRvWD2dDTCfh9M9ya+I9JpbB7O8o=
+github.com/armon/go-metrics v0.0.0-20180917152333-f0300d1749da/go.mod h1:Q73ZrmVTwzkszR9V5SSuryQ31EELlFMUz1kKyl939pY=
+github.com/armon/go-metrics v0.4.1 h1:hR91U9KYmb6bLBYLQjyM+3j+rcd/UhE+G78SFnF8gJA=
+github.com/armon/go-metrics v0.4.1/go.mod h1:E6amYzXo6aW1tqzoZGT755KkbgrJsSdpwZ+3JqfkOG4=
+github.com/armon/go-radix v0.0.0-20180808171621-7fddfc383310/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8=
+github.com/armon/go-radix v1.0.0/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8=
+github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
+github.com/beorn7/perks v1.0.0/go.mod h1:KWe93zE9D1o94FZ5RNwFwVgaQK1VOXiVxmqh+CedLV8=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
+github.com/bits-and-blooms/bitset v1.2.0 h1:Kn4yilvwNtMACtf1eYDlG8H77R07mZSPbMjLyS07ChA=
+github.com/bits-and-blooms/bitset v1.2.0/go.mod h1:gIdJ4wp64HaoK2YrL1Q5/N7Y16edYb8uY+O0FJTyyDA=
+github.com/blevesearch/bleve/v2 v2.3.10 h1:z8V0wwGoL4rp7nG/O3qVVLYxUqCbEwskMt4iRJsPLgg=
+github.com/blevesearch/bleve/v2 v2.3.10/go.mod h1:RJzeoeHC+vNHsoLR54+crS1HmOWpnH87fL70HAUCzIA=
+github.com/blevesearch/bleve_index_api v1.0.6 h1:gyUUxdsrvmW3jVhhYdCVL6h9dCjNT/geNU7PxGn37p8=
+github.com/blevesearch/bleve_index_api v1.0.6/go.mod h1:YXMDwaXFFXwncRS8UobWs7nvo0DmusriM1nztTlj1ms=
+github.com/blevesearch/geo v0.1.18 h1:Np8jycHTZ5scFe7VEPLrDoHnnb9C4j636ue/CGrhtDw=
+github.com/blevesearch/geo v0.1.18/go.mod h1:uRMGWG0HJYfWfFJpK3zTdnnr1K+ksZTuWKhXeSokfnM=
+github.com/blevesearch/go-porterstemmer v1.0.3 h1:GtmsqID0aZdCSNiY8SkuPJ12pD4jI+DdXTAn4YRcHCo=
+github.com/blevesearch/go-porterstemmer v1.0.3/go.mod h1:angGc5Ht+k2xhJdZi511LtmxuEf0OVpvUUNrwmM1P7M=
+github.com/blevesearch/gtreap v0.1.1 h1:2JWigFrzDMR+42WGIN/V2p0cUvn4UP3C4Q5nmaZGW8Y=
+github.com/blevesearch/gtreap v0.1.1/go.mod h1:QaQyDRAT51sotthUWAH4Sj08awFSSWzgYICSZ3w0tYk=
+github.com/blevesearch/mmap-go v1.0.4 h1:OVhDhT5B/M1HNPpYPBKIEJaD0F3Si+CrEKULGCDPWmc=
+github.com/blevesearch/mmap-go v1.0.4/go.mod h1:EWmEAOmdAS9z/pi/+Toxu99DnsbhG1TIxUoRmJw/pSs=
+github.com/blevesearch/scorch_segment_api/v2 v2.1.6 h1:CdekX/Ob6YCYmeHzD72cKpwzBjvkOGegHOqhAkXp6yA=
+github.com/blevesearch/scorch_segment_api/v2 v2.1.6/go.mod h1:nQQYlp51XvoSVxcciBjtvuHPIVjlWrN1hX4qwK2cqdc=
+github.com/blevesearch/segment v0.9.1 h1:+dThDy+Lvgj5JMxhmOVlgFfkUtZV2kw49xax4+jTfSU=
+github.com/blevesearch/segment v0.9.1/go.mod h1:zN21iLm7+GnBHWTao9I+Au/7MBiL8pPFtJBJTsk6kQw=
+github.com/blevesearch/snowballstem v0.9.0 h1:lMQ189YspGP6sXvZQ4WZ+MLawfV8wOmPoD/iWeNXm8s=
+github.com/blevesearch/snowballstem v0.9.0/go.mod h1:PivSj3JMc8WuaFkTSRDW2SlrulNWPl4ABg1tC/hlgLs=
+github.com/blevesearch/upsidedown_store_api v1.0.2 h1:U53Q6YoWEARVLd1OYNc9kvhBMGZzVrdmaozG2MfoB+A=
+github.com/blevesearch/upsidedown_store_api v1.0.2/go.mod h1:M01mh3Gpfy56Ps/UXHjEO/knbqyQ1Oamg8If49gRwrQ=
+github.com/blevesearch/vellum v1.0.10 h1:HGPJDT2bTva12hrHepVT3rOyIKFFF4t7Gf6yMxyMIPI=
+github.com/blevesearch/vellum v1.0.10/go.mod h1:ul1oT0FhSMDIExNjIxHqJoGpVrBpKCdgDQNxfqgJt7k=
+github.com/blevesearch/zapx/v11 v11.3.10 h1:hvjgj9tZ9DeIqBCxKhi70TtSZYMdcFn7gDb71Xo/fvk=
+github.com/blevesearch/zapx/v11 v11.3.10/go.mod h1:0+gW+FaE48fNxoVtMY5ugtNHHof/PxCqh7CnhYdnMzQ=
+github.com/blevesearch/zapx/v12 v12.3.10 h1:yHfj3vXLSYmmsBleJFROXuO08mS3L1qDCdDK81jDl8s=
+github.com/blevesearch/zapx/v12 v12.3.10/go.mod h1:0yeZg6JhaGxITlsS5co73aqPtM04+ycnI6D1v0mhbCs=
+github.com/blevesearch/zapx/v13 v13.3.10 h1:0KY9tuxg06rXxOZHg3DwPJBjniSlqEgVpxIqMGahDE8=
+github.com/blevesearch/zapx/v13 v13.3.10/go.mod h1:w2wjSDQ/WBVeEIvP0fvMJZAzDwqwIEzVPnCPrz93yAk=
+github.com/blevesearch/zapx/v14 v14.3.10 h1:SG6xlsL+W6YjhX5N3aEiL/2tcWh3DO75Bnz77pSwwKU=
+github.com/blevesearch/zapx/v14 v14.3.10/go.mod h1:qqyuR0u230jN1yMmE4FIAuCxmahRQEOehF78m6oTgns=
+github.com/blevesearch/zapx/v15 v15.3.13 h1:6EkfaZiPlAxqXz0neniq35my6S48QI94W/wyhnpDHHQ=
+github.com/blevesearch/zapx/v15 v15.3.13/go.mod h1:Turk/TNRKj9es7ZpKK95PS7f6D44Y7fAFy8F4LXQtGg=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
+github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
+github.com/cespare/xxhash/v2 v2.1.1/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/circonus-labs/circonus-gometrics v2.3.1+incompatible/go.mod h1:nmEj6Dob7S7YxXgwXpfOuvO54S+tGdZdw9fuRZt25Ag=
+github.com/circonus-labs/circonusllhist v0.1.3/go.mod h1:kMXHVDlOchFAehlya5ePtbp5jckzBHf4XRpQvBOLI+I=
+github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
+github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
+github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
+github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a h1:yDWHCSQ40h88yih2JAcL6Ls/kVkSE8GFACTGVnMPruw=
+github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a/go.mod h1:7Ga40egUymuWXxAe151lTNnCv97MddSOVsjpPPkityA=
+github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
+github.com/fatih/color v1.9.0/go.mod h1:eQcE1qtQxscV5RaZvpXrrb8Drkc3/DdQ+uUYCNjL+zU=
+github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk=
+github.com/fatih/color v1.14.1 h1:qfhVLaG5s+nCROl1zJsZRxFeYrHLqWroPOQ8BWiNb4w=
+github.com/fatih/color v1.14.1/go.mod h1:2oHN61fhTpgcxD3TSWCgKDiH1+x4OiDVVGH8WlgGZGg=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
+github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
+github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
+github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
+github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
+github.com/go-logfmt/logfmt v0.3.0/go.mod h1:Qt1PoO58o5twSAckw1HlFXLmHsOX5/0LbT9GBnD5lWE=
+github.com/go-logfmt/logfmt v0.4.0/go.mod h1:3RMwSq7FuexP4Kalkev3ejPJsZTpXXBr9+V4qmtdjCk=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.2.3/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
+github.com/gogo/protobuf v1.1.1/go.mod h1:r8qH/GZQm5c6nD/R0oafs1akxWv10x8SbQlK7atdtwQ=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang-jwt/jwt/v5 v5.2.0 h1:d/ix8ftRUorsN+5eMIlF4T6J8CAt9rch3My2winC1Jw=
+github.com/golang-jwt/jwt/v5 v5.2.0/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
+github.com/golang/geo v0.0.0-20210211234256-740aa86cb551 h1:gtexQ/VGyN+VVFRXSFiguSNcXmS6rkKT+X7FdIrTtfo=
+github.com/golang/geo v0.0.0-20210211234256-740aa86cb551/go.mod h1:QZ0nwyI2jOfgRAoBvP+ab5aRr7c9x7lhGEJrKvBwjWI=
+github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
+github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
+github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc=
+github.com/golang/mock v1.6.0/go.mod h1:p6yTPP+5HYm5mzsMV8JkE6ZKdX+/wYM6Hr+LicevLPs=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.3/go.mod h1:vzj43D7+SQXF/4pzW/hwtAqwc6iTitCiVSaWz5lYuqw=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/golang/snappy v0.0.4 h1:yAGX7huGHXlcLOEtBnF4w7FQwA26wojNCwOYAEhLjQM=
+github.com/golang/snappy v0.0.4/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/google/btree v0.0.0-20180813153112-4030bb1f1f0c/go.mod h1:lNA+9X1NB3Zf8V7Ke586lFgjr2dZNuvo3lPJSGZ5JPQ=
+github.com/google/btree v1.0.1 h1:gK4Kx5IaGY9CD5sPJ36FHiBJ6ZXl0kilRiiCj+jdYp4=
+github.com/google/btree v1.0.1/go.mod h1:xXMiIv4Fb/0kKde4SpL7qlzvu5cMJDRkFDxJfI9uaxA=
+github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
+github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.7/go.mod h1:n+brtR0CgQNWTVd5ZUFpTBC8YFBDLK/h/bpaJ8/DtOE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/uuid v1.0.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
+github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
+github.com/gorilla/websocket v1.5.1 h1:gmztn0JnHVt9JZquRuzLw3g4wouNVzKL15iLr/zn/QY=
+github.com/gorilla/websocket v1.5.1/go.mod h1:x3kM2JMyaluk02fnUJpQuwD2dCS5NDG2ZHL0uE0tcaY=
+github.com/graph-gophers/graphql-go v1.5.0 h1:fDqblo50TEpD0LY7RXk/LFVYEVqo3+tXMNMPSVXA1yc=
+github.com/graph-gophers/graphql-go v1.5.0/go.mod h1:YtmJZDLbF1YYNrlNAuiO5zAStUWc3XZT07iGsVqe1Os=
+github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 h1:+9834+KizmvFV7pXQGSXQTsaWhq2GjuNUt0aUU0YBYw=
+github.com/grpc-ecosystem/go-grpc-middleware v1.3.0/go.mod h1:z0ButlSOZa5vEBq9m2m2hlwIgKw+rp3sdCBRoJY+30Y=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.1 h1:/c3QmbOGMGTOumP2iT/rCwB7b0QDGLKzqOmktBjT+Is=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.1/go.mod h1:5SN9VR2LTsRFsrEC6FHgRbTWrTHu6tqPeKxEQv15giM=
+github.com/hashicorp/consul/api v1.27.0 h1:gmJ6DPKQog1426xsdmgk5iqDyoRiNc+ipBdJOqKQFjc=
+github.com/hashicorp/consul/api v1.27.0/go.mod h1:JkekNRSou9lANFdt+4IKx3Za7XY0JzzpQjEb4Ivo1c8=
+github.com/hashicorp/consul/sdk v0.15.1 h1:kKIGxc7CZtflcF5DLfHeq7rOQmRq3vk7kwISN9bif8Q=
+github.com/hashicorp/consul/sdk v0.15.1/go.mod h1:7pxqqhqoaPqnBnzXD1StKed62LqJeClzVsUEy85Zr0A=
+github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
+github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/go-cleanhttp v0.5.0/go.mod h1:JpRdi6/HCYpAwUzNwuwqhbovhLtngrth3wmdIIUrZ80=
+github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
+github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
+github.com/hashicorp/go-hclog v1.5.0 h1:bI2ocEMgcVlz55Oj1xZNBsVi900c7II+fWDyV9o+13c=
+github.com/hashicorp/go-hclog v1.5.0/go.mod h1:W4Qnvbt70Wk/zYJryRzDRU/4r0kIg0PVHBcfoyhpF5M=
+github.com/hashicorp/go-immutable-radix v1.0.0/go.mod h1:0y9vanUI8NX6FsYoO3zeMjhV/C5i9g4Q3DwcSNZ4P60=
+github.com/hashicorp/go-immutable-radix v1.3.1 h1:DKHmCUm2hRBK510BaiZlwvpD40f8bJFeZnpfm2KLowc=
+github.com/hashicorp/go-immutable-radix v1.3.1/go.mod h1:0y9vanUI8NX6FsYoO3zeMjhV/C5i9g4Q3DwcSNZ4P60=
+github.com/hashicorp/go-msgpack v0.5.3/go.mod h1:ahLV/dePpqEmjfWmKiqvPkv/twdG7iPBM1vqhUKIvfM=
+github.com/hashicorp/go-msgpack v0.5.5 h1:i9R9JSrqIz0QVLz3sz+i3YJdT7TTSLcfLLzJi9aZTuI=
+github.com/hashicorp/go-msgpack v0.5.5/go.mod h1:ahLV/dePpqEmjfWmKiqvPkv/twdG7iPBM1vqhUKIvfM=
+github.com/hashicorp/go-multierror v1.0.0/go.mod h1:dHtQlpGsu+cZNNAkkCN/P3hoUDHhCYQXV3UM06sGGrk=
+github.com/hashicorp/go-multierror v1.1.0/go.mod h1:spPvp8C1qA32ftKqdAHm4hHTbPw+vmowP0z+KUhOZdA=
+github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
+github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
+github.com/hashicorp/go-retryablehttp v0.5.3/go.mod h1:9B5zBasrRhHXnJnui7y6sL7es7NDiJgTc6Er0maI1Xs=
+github.com/hashicorp/go-rootcerts v1.0.2 h1:jzhAVGtqPKbwpyCPELlgNWhE1znq+qwJtW5Oi2viEzc=
+github.com/hashicorp/go-rootcerts v1.0.2/go.mod h1:pqUvnprVnM5bf7AOirdbb01K4ccR319Vf4pU3K5EGc8=
+github.com/hashicorp/go-sockaddr v1.0.0/go.mod h1:7Xibr9yA9JjQq1JpNB2Vw7kxv8xerXegt+ozgdvDeDU=
+github.com/hashicorp/go-sockaddr v1.0.2 h1:ztczhD1jLxIRjVejw8gFomI1BQZOe2WoVOu0SyteCQc=
+github.com/hashicorp/go-sockaddr v1.0.2/go.mod h1:rB4wwRAUzs07qva3c5SdrY/NEtAUjGlgmH/UkBUC97A=
+github.com/hashicorp/go-syslog v1.0.0/go.mod h1:qPfqrKkXGihmCqbJM2mZgkZGvKG1dFdvsLplgctolz4=
+github.com/hashicorp/go-uuid v1.0.0/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.1/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
+github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-version v1.2.1 h1:zEfKbn2+PDgroKdiOzqiE8rsmLqU2uwi5PB5pBJ3TkI=
+github.com/hashicorp/go-version v1.2.1/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
+github.com/hashicorp/golang-lru v0.5.4 h1:YDjusn29QI/Das2iO9M0BHnIbxPeyuCHsjMW+lJfyTc=
+github.com/hashicorp/golang-lru v0.5.4/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
+github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
+github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
+github.com/hashicorp/logutils v1.0.0/go.mod h1:QIAnNjmIWmVIIkWDTG1z5v++HQmx9WQRO+LraFDTW64=
+github.com/hashicorp/mdns v1.0.4/go.mod h1:mtBihi+LeNXGtG8L9dX59gAEa12BDtBQSp4v/YAJqrc=
+github.com/hashicorp/memberlist v0.5.0 h1:EtYPN8DpAURiapus508I4n9CzHs2W+8NZGbmmR/prTM=
+github.com/hashicorp/memberlist v0.5.0/go.mod h1:yvyXLpo0QaGE59Y7hDTsTzDD25JYBZ4mHgHUZ8lrOI0=
+github.com/hashicorp/serf v0.10.1 h1:Z1H2J60yRKvfDYAOZLd2MU0ND4AH/WDz7xYHDWQsIPY=
+github.com/hashicorp/serf v0.10.1/go.mod h1:yL2t6BqATOLGc5HF7qbFkTfXoPIY0WZdWHfEvMqbG+4=
+github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
+github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/julienschmidt/httprouter v1.2.0/go.mod h1:SYymIcj16QtmaHHD7aYtjjsJG7VTCxuUUipMqKk8s4w=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
+github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
+github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
+github.com/mattn/go-colorable v0.1.4/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
+github.com/mattn/go-colorable v0.1.6/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
+github.com/mattn/go-colorable v0.1.9/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
+github.com/mattn/go-colorable v0.1.12/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.3/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
+github.com/mattn/go-isatty v0.0.8/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
+github.com/mattn/go-isatty v0.0.11/go.mod h1:PhnuNfih5lzO57/f3n+odYbM4JtupLOxQOAqxQCu2WE=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.17 h1:BTarxUcIeDqL27Mc+vyvdWYSL28zpIhv3RoTdsLMPng=
+github.com/mattn/go-isatty v0.0.17/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
+github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0 h1:jWpvCLoY8Z/e3VKvlsiIGKtc+UG6U5vzxaoagmhXfyg=
+github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0/go.mod h1:QUyp042oQthUoa9bqDv0ER0wrtXnBruoNd7aNjkbP+k=
+github.com/miekg/dns v1.1.26/go.mod h1:bPDLeHnStXmXAq1m/Ch/hvfNHr14JKNPMBo3VZKjuso=
+github.com/miekg/dns v1.1.41 h1:WMszZWJG0XmzbK9FEmzH2TVcqYzFesusSIB41b8KHxY=
+github.com/miekg/dns v1.1.41/go.mod h1:p6aan82bvRIyn+zDIv9xYNUpwa73JcSh9BKwknJysuI=
+github.com/mitchellh/cli v1.1.0/go.mod h1:xcISNoH86gajksDmfB23e/pu+B+GeFRMYmoHXxx3xhI=
+github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/mitchellh/mapstructure v0.0.0-20160808181253-ca63d7c062ee/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/mschoch/smat v0.2.0 h1:8imxQsjDm8yFEAVBe7azKmKSgzSkZXDuKkSq9374khM=
+github.com/mschoch/smat v0.2.0/go.mod h1:kc9mz7DoBKqDyiRL7VZN8KvXQMWeTaVnttLRXOlotKw=
+github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U=
+github.com/neo4j/neo4j-go-driver/v5 v5.17.0 h1:Bdqg1Y8Hd3uLYToXtBjysDYXTdMiP7zeUNUEwfbJkSo=
+github.com/neo4j/neo4j-go-driver/v5 v5.17.0/go.mod h1:Vff8OwT7QpLm7L2yYr85XNWe9Rbqlbeb9asNXJTHO4k=
+github.com/opentracing/opentracing-go v1.1.0/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFStlNbqXla1AfSYxPUl2o=
+github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc=
+github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
+github.com/pascaldekloe/goe v0.1.0 h1:cBOtyMzM9HTpWjXfbbunk26uA6nG3a8n06Wieeh0MwY=
+github.com/pascaldekloe/goe v0.1.0/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
+github.com/pborman/uuid v1.2.1 h1:+ZZIw58t/ozdjRaXh/3awHfmWRbzYxJoAdNJxe/3pvw=
+github.com/pborman/uuid v1.2.1/go.mod h1:X/NO0urCmaxf9VXbdlT7C2Yzkj2IKimNn4k+gtPdI/k=
+github.com/pelletier/go-toml/v2 v2.1.0 h1:FnwAJ4oYMvbT/34k9zzHuZNrhlz48GB3/s6at6/MHO4=
+github.com/pelletier/go-toml/v2 v2.1.0/go.mod h1:tJU2Z3ZkXwnxa4DPO899bsyIoywizdUvyaeZurnPPDc=
+github.com/pierrec/lz4/v4 v4.1.15 h1:MO0/ucJhngq7299dKLwIMtgTfbkoSPF6AoMYDd8Q4q0=
+github.com/pierrec/lz4/v4 v4.1.15/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
+github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI=
+github.com/posener/complete v1.2.3/go.mod h1:WZIdtGGp+qx0sLrYKtIRAruyNpv6hFCicSgv7Sy7s/s=
+github.com/prometheus/client_golang v0.9.1/go.mod h1:7SWBe2y4D6OKWSNQJUaRYU/AaXPKyh/dDVn+NZz0KFw=
+github.com/prometheus/client_golang v1.0.0/go.mod h1:db9x61etRT2tGnBNRi70OPL5FsnadC4Ky3P0J6CfImo=
+github.com/prometheus/client_golang v1.4.0/go.mod h1:e9GMxYsXl05ICDXkRhurwBS4Q3OK1iX/F2sw+iXX5zU=
+github.com/prometheus/client_golang v1.18.0 h1:HzFfmkOzH5Q8L8G+kSJKUx5dtG87sewO+FoDDqP5Tbk=
+github.com/prometheus/client_golang v1.18.0/go.mod h1:T+GXkCk5wSJyOqMIzVgvvjFDlkOQntgjkJWKrN5txjA=
+github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=
+github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.2.0/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.5.0 h1:VQw1hfvPvk3Uv6Qf29VrPF32JB6rtbgI6cYPYQjL0Qw=
+github.com/prometheus/client_model v0.5.0/go.mod h1:dTiFglRmd66nLR9Pv9f0mZi7B7fk5Pm3gvsjB5tr+kI=
+github.com/prometheus/common v0.4.1/go.mod h1:TNfzLD0ON7rHzMJeJkieUDPYmFC7Snx/y86RQel1bk4=
+github.com/prometheus/common v0.9.1/go.mod h1:yhUN8i9wzaXS3w1O07YhxHEBxD+W35wd8bs7vj7HSQ4=
+github.com/prometheus/common v0.45.0 h1:2BGz0eBc2hdMDLnO/8n0jeB3oPrt2D08CekT0lneoxM=
+github.com/prometheus/common v0.45.0/go.mod h1:YJmSTw9BoKxJplESWWxlbyttQR4uaEcGyv9MZjVOJsY=
+github.com/prometheus/procfs v0.0.0-20181005140218-185b4288413d/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=
+github.com/prometheus/procfs v0.0.2/go.mod h1:TjEm7ze935MbeOT/UhFTIMYKhuLP4wbCsTZCD3I8kEA=
+github.com/prometheus/procfs v0.0.8/go.mod h1:7Qr8sr6344vo1JqZ6HhLceV9o3AJ1Ff+GxbHq6oeK9A=
+github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k6Bo=
+github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo=
+github.com/qdrant/go-client v1.7.0 h1:2TeeWyZAWIup7vvD7Ne6aAvo0H+F5OUb1pB9Z8Y4pFk=
+github.com/qdrant/go-client v1.7.0/go.mod h1:680gkxNAsVtre0Z8hAQmtPzJtz1xFAyCu2TUxULtnoE=
+github.com/redis/go-redis/v9 v9.4.0 h1:Yzoz33UZw9I/mFhx4MNrB6Fk+XHO1VukNcCa1+lwyKk=
+github.com/redis/go-redis/v9 v9.4.0/go.mod h1:hdY0cQFCN4fnSYT6TkisLufl/4W5UIXyv0b/CLO2V2M=
+github.com/robfig/cron v1.2.0 h1:ZjScXvvxeQ63Dbyxy76Fj3AT3Ut0aKsyd2/tl3DTMuQ=
+github.com/robfig/cron v1.2.0/go.mod h1:JGuDeoQd7Z6yL4zQhZ3OPEVHB7fL6Ka6skscFHfmt2k=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
+github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
+github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
+github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
+github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
+github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529 h1:nn5Wsu0esKSJiIVhscUtVbo7ada43DJhG55ua/hjS5I=
+github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529/go.mod h1:DxrIzT+xaE7yg65j358z/aeFdxmN0P9QXhEzd20vsDc=
+github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo=
+github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
+github.com/sony/gobreaker v0.5.0 h1:dRCvqm0P490vZPmy7ppEk2qCnCieBooFJ+YoXGYB+yg=
+github.com/sony/gobreaker v0.5.0/go.mod h1:ZKptC7FHNvhBz7dN2LGjPVBz2sZJmc0/PkyDJOjmxWY=
+github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
+github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
+github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
+github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY=
+github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
+github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/viper v1.18.2 h1:LUXCnvUvSM6FXAsj6nnfc8Q2tp1dIgUfY9Kc8GsSOiQ=
+github.com/spf13/viper v1.18.2/go.mod h1:EKmWIqdnk5lOcmR72yw6hS+8OPYcwD0jteitLMVB+yk=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
+github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
+github.com/tv42/httpunix v0.0.0-20150427012821-b75d8614f926/go.mod h1:9ESjWnEqriFuLhtthL60Sar/7RFoluCcXsuvEwTV5KM=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
+go.etcd.io/bbolt v1.3.7 h1:j+zJOnnEjF/kyHlDDgGnVL/AIqIJPq8UoB2GSNfkUfQ=
+go.etcd.io/bbolt v1.3.7/go.mod h1:N9Mkw9X8x5fupy0IKsmuqVtoGDyxsaDlbk4Rd05IAQw=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.6.3/go.mod h1:7BgNga5fNlF/iZjG06hM3yofffp0ofKCDwSXx1GC4dI=
+go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8=
+go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.22.0 h1:9M3+rhx7kZCIQQhQRYaZCdNu1V73tm4TvXs2ntl98C4=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.22.0/go.mod h1:noq80iT8rrHP1SfybmPiRGc9dc5M8RPmGvtwo7Oo7tc=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.22.0 h1:H2JFgRcGiyHg7H7bwcwaQJYrNFqCqrbTQ8K4p1OvDu8=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.22.0/go.mod h1:WfCWp1bGoYK8MeULtI15MmQVczfR+bFkk0DF3h06QmQ=
+go.opentelemetry.io/otel/metric v1.38.0 h1:Kl6lzIYGAh5M159u9NgiRkmoMKjvbsKtYRwgfrA6WpA=
+go.opentelemetry.io/otel/metric v1.38.0/go.mod h1:kB5n/QoRM8YwmUahxvI3bO34eVtQf2i4utNVLr9gEmI=
+go.opentelemetry.io/otel/sdk v1.38.0 h1:l48sr5YbNf2hpCUj/FoGhW9yDkl+Ma+LrVl8qaM5b+E=
+go.opentelemetry.io/otel/sdk v1.38.0/go.mod h1:ghmNdGlVemJI3+ZB5iDEuk4bWA3GkTpW+DOoZMYBVVg=
+go.opentelemetry.io/otel/sdk/metric v1.38.0 h1:aSH66iL0aZqo//xXzQLYozmWrXxyFkBJ6qT5wthqPoM=
+go.opentelemetry.io/otel/sdk/metric v1.38.0/go.mod h1:dg9PBnW9XdQ1Hd6ZnRz689CbtrUp0wMMs9iPcgT9EZA=
+go.opentelemetry.io/otel/trace v1.6.3/go.mod h1:GNJQusJlUgZl9/TQBPKU/Y/ty+0iVB5fjhKeJGZPGFs=
+go.opentelemetry.io/otel/trace v1.38.0 h1:Fxk5bKrDZJUH+AMyyIXGcFAPah0oRcT+LuNtJrmcNLE=
+go.opentelemetry.io/otel/trace v1.38.0/go.mod h1:j1P9ivuFsTceSWe1oY+EeW3sc+Pp42sO++GHkg4wwhs=
+go.opentelemetry.io/proto/otlp v1.1.0 h1:2Di21piLrCqJ3U3eXGCTPHE9R8Nh+0uglSnOyxikMeI=
+go.opentelemetry.io/proto/otlp v1.1.0/go.mod h1:GpBHCBWiqvVLDqmHZsoMM3C5ySeKTC7ej/RNTae6MdY=
+go.temporal.io/api v1.29.1 h1:L722DCy3xCzpTe3Rvh1sFC9kcSaMJXqvodCF+swHGtQ=
+go.temporal.io/api v1.29.1/go.mod h1:wZtsUJ3PySASGWbpXBWYVKJ4aHB2ZODEn/xNcTr9HRs=
+go.temporal.io/sdk v1.26.0 h1:QAi7irgKvJI+5cKmvy+1lkdCDJJDDNpIQAoXdr3dcyM=
+go.temporal.io/sdk v1.26.0/go.mod h1:rcAf1YWlbWgMsjJEuz7XiQd6UYxTQDOk2AqRRIDwq/U=
+go.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q=
+go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo=
+go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so=
+golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20190923035154-9ee001bba392/go.mod h1:/lpIB1dKB+9EgE3H3cr1v9wB50oz8l4C4h62xy7jSTY=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
+golang.org/x/exp v0.0.0-20231127185646-65229373498e h1:Gvh4YaCaXNs6dKTlfgismwWZKyjVZXwOPfIyUaqU3No=
+golang.org/x/exp v0.0.0-20231127185646-65229373498e/go.mod h1:iRJReGqOEeBhDZGkGbynYwcHlctCvnjTYIamk7uXpHI=
+golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
+golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
+golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20181114220301-adae6a3d119a/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190613194153-d28f0bde5980/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190923162816-aa69164e4478/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
+golang.org/x/net v0.0.0-20210410081132-afb366fc7cd1/go.mod h1:9tjilg8BloeKEkVJvy7fQ90B1CfIiPueXVOjqfkSzI8=
+golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
+golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
+golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20180823144017-11551d06cbcc/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20181116152217-5ac8a444bdc5/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190922100055-0a153f010e69/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190924154521-2837fb4f24fe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200122134326-e047566fdf82/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210303074136-134d130e1a04/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210927094055-39ccf1dd6fa6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220503163025-988cb79eb6c6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220728004956-3c1f35247d10/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
+golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
+golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
+golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
+golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
+golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/tools v0.0.0-20190907020128-2ca718005c18/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.1.1/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
+gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
+google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
+google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
+google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
+google.golang.org/genproto v0.0.0-20200423170343-7949de9c1215/go.mod h1:55QSHmfGQM9UVYDPBsyGGes0y52j32PQ3BqQfXhyH3c=
+google.golang.org/genproto/googleapis/api v0.0.0-20251022142026-3a174f9686a8 h1:mepRgnBZa07I4TRuomDE4sTIYieg/osKmzIf4USdWS4=
+google.golang.org/genproto/googleapis/api v0.0.0-20251022142026-3a174f9686a8/go.mod h1:fDMmzKV90WSg1NbozdqrE64fkuTv6mlq2zxo9ad+3yo=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251213004720-97cd9d5aeac2 h1:2I6GHUeJ/4shcDpoUlLs/2WPnhg7yJwvXtqcMJt9liA=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251213004720-97cd9d5aeac2/go.mod h1:7i2o+ce6H/6BluujYR+kqX3GKH+dChPTQU19wjRPiGk=
+google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
+google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
+google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
+google.golang.org/grpc v1.27.0/go.mod h1:qbnxyOmOxrQa7FizSgH+ReBfzJrCY1pSN7KXBS8abTk=
+google.golang.org/grpc v1.29.1/go.mod h1:itym6AZVZYACWQqET3MqgPpjcuV5QH3BxFS3IjizoKk=
+google.golang.org/grpc v1.77.0 h1:wVVY6/8cGA6vvffn+wWK5ToddbgdU3d8MNENr4evgXM=
+google.golang.org/grpc v1.77.0/go.mod h1:z0BY1iVj0q8E1uSQCjL9cppRj+gnZjzDnzV0dHhrNig=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/alecthomas/kingpin.v2 v2.2.6/go.mod h1:FMv+mEhP44yOT+4EoQTLFTRgOQ1FBLkstjWtayDeSgw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
+gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.5/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

go.work

@@ -0,0 +1,10 @@
+go 1.24.0
+
+use (
+	.
+	./services/files
+	./services/ingestion
+	./services/notifications
+	./services/portal
+	./services/voice
+)

internal/agent/interceptors.go

@@ -0,0 +1,60 @@
+// Package agent provides gRPC interceptors for logging, recovery, and authentication
+package agent
+
+import (
+	"context"
+	"runtime/debug"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// LoggingInterceptor returns a gRPC unary server interceptor for logging requests
+func LoggingInterceptor(logger *zap.Logger) grpc.UnaryServerInterceptor {
+	return func(
+		ctx context.Context,
+		req interface{},
+		info *grpc.UnaryServerInfo,
+		handler grpc.UnaryHandler,
+	) (interface{}, error) {
+		logger.Debug("handling request",
+			zap.String("method", info.FullMethod),
+		)
+
+		resp, err := handler(ctx, req)
+
+		if err != nil {
+			logger.Error("request failed",
+				zap.String("method", info.FullMethod),
+				zap.Error(err),
+			)
+		} else {
+			logger.Debug("request completed",
+				zap.String("method", info.FullMethod),
+			)
+		}
+
+		return resp, err
+	}
+}
+
+// RecoveryInterceptor returns a gRPC unary server interceptor that recovers from panics
+func RecoveryInterceptor() grpc.UnaryServerInterceptor {
+	return func(
+		ctx context.Context,
+		req interface{},
+		info *grpc.UnaryServerInfo,
+		handler grpc.UnaryHandler,
+	) (resp interface{}, err error) {
+		defer func() {
+			if r := recover(); r != nil {
+				stack := debug.Stack()
+				err = status.Errorf(codes.Internal, "panic recovered: %v\n%s", r, string(stack))
+			}
+		}()
+
+		return handler(ctx, req)
+	}
+}

internal/agent/orchestrator.go

@@ -0,0 +1,565 @@
+// Package agent implements the Agent Orchestrator service that handles
+// query processing, tool orchestration, and conversation state management.
+package agent
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	llmclient "github.com/AmaniQuery/amaniquery/internal/generator/llm"
+	"github.com/AmaniQuery/amaniquery/internal/retriever"
+	"github.com/AmaniQuery/amaniquery/internal/router"
+	"github.com/AmaniQuery/amaniquery/pkg/observability"
+
+	"github.com/sony/gobreaker"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+)
+
+var tracer = otel.Tracer("agent-orchestrator")
+
+// Default system prompt for Kenya Law and News Intelligence
+const defaultSystemPrompt = `You are AmaniQuery, an AI assistant specialized in Kenya Law and News Intelligence. 
+Your mission is to democratize access to legal information and civil education in Kenya.
+
+When answering questions:
+1. Provide accurate information based on the context provided
+2. Cite specific laws, sections, or articles when relevant
+3. Explain legal concepts in plain, understandable language
+4. If the context doesn't contain enough information, say so clearly
+5. For news-related queries, provide balanced and factual information
+
+Always maintain a helpful, educational tone while being precise about legal matters.`
+
+// Dependencies contains all service dependencies
+type Dependencies struct {
+	VectorStore     VectorStore
+	Cache           CacheClient
+	LLMClient       LLMClient
+	EmbeddingClient EmbeddingClient
+	KeywordEngine   KeywordEngine
+	Router          *router.Router
+	Retriever       *retriever.HybridRetriever
+}
+
+// Close closes all dependencies
+func (d *Dependencies) Close() error {
+	var errs []error
+	if d.VectorStore != nil {
+		if closer, ok := d.VectorStore.(interface{ Close() error }); ok {
+			if err := closer.Close(); err != nil {
+				errs = append(errs, err)
+			}
+		}
+	}
+	if d.Cache != nil {
+		if closer, ok := d.Cache.(interface{ Close() error }); ok {
+			if err := closer.Close(); err != nil {
+				errs = append(errs, err)
+			}
+		}
+	}
+	if d.KeywordEngine != nil {
+		if closer, ok := d.KeywordEngine.(interface{ Close() error }); ok {
+			if err := closer.Close(); err != nil {
+				errs = append(errs, err)
+			}
+		}
+	}
+	if len(errs) > 0 {
+		return errs[0]
+	}
+	return nil
+}
+
+// Interface definitions
+type VectorStore interface {
+	Search(ctx context.Context, embedding []float32, topK int, filters map[string]interface{}) ([]retriever.SearchResult, error)
+}
+
+type CacheClient interface {
+	Get(ctx context.Context, key string) ([]byte, error)
+	Set(ctx context.Context, key string, value []byte, ttlSeconds int) error
+	GetJSON(ctx context.Context, key string, v interface{}) error
+	SetJSON(ctx context.Context, key string, v interface{}, ttlSeconds int) error
+}
+
+type LLMClient interface {
+	Generate(ctx context.Context, messages []llmclient.Message, opts llmclient.Options) (*llmclient.Response, error)
+	GenerateStream(ctx context.Context, messages []llmclient.Message, opts llmclient.Options, callback llmclient.StreamCallback) error
+}
+
+type EmbeddingClient interface {
+	Generate(ctx context.Context, text string) ([]float32, error)
+	GenerateBatch(ctx context.Context, texts []string) ([][]float32, error)
+}
+
+type KeywordEngine interface {
+	Search(ctx context.Context, query string, topK int) ([]retriever.SearchResult, error)
+}
+
+// QueryRequest represents an incoming query
+type QueryRequest struct {
+	Query               string
+	SessionID           string
+	UserID              string
+	ConversationHistory []Message
+	Metadata            map[string]string
+	Options             QueryOptions
+}
+
+// QueryOptions configures query processing
+type QueryOptions struct {
+	MaxSources     int
+	UseCache       bool
+	EnableAgentic  bool
+	KnowledgeBases []string
+	Temperature    float32
+	MaxTokens      int
+}
+
+// QueryResponse contains the query result
+type QueryResponse struct {
+	Answer            string
+	Sources           []Source
+	Confidence        float32
+	Metadata          QueryMetadata
+	FollowUpQuestions []string
+}
+
+// QueryMetadata contains processing information
+type QueryMetadata struct {
+	ProcessingTimeMs int64
+	ChunksRetrieved  int
+	TokensUsed       int
+	CacheHit         bool
+	RoutingStrategy  string
+	TraceID          string
+}
+
+// Source represents a retrieved source document
+type Source struct {
+	ID       string
+	Title    string
+	Content  string
+	URL      string
+	Score    float32
+	Metadata map[string]string
+	Location string
+}
+
+// Message represents a conversation message
+type Message struct {
+	Role      string
+	Content   string
+	Timestamp time.Time
+}
+
+// Tool represents an executable tool for agentic workflows
+type Tool interface {
+	Name() string
+	Description() string
+	Execute(ctx context.Context, input string) (string, error)
+}
+
+// ResponseStream for streaming responses
+type ResponseStream interface {
+	Send(chunk *ResponseChunk) error
+}
+
+// ResponseChunk for streaming
+type ResponseChunk struct {
+	Type    string
+	Content string
+	Sources []Source
+	IsFinal bool
+}
+
+// Orchestrator implements the main query processing logic
+type Orchestrator struct {
+	deps           *Dependencies
+	logger         *zap.Logger
+	tools          map[string]Tool
+	toolsMu        sync.RWMutex
+	circuitBreaker *gobreaker.CircuitBreaker
+}
+
+// NewOrchestrator creates a new agent orchestrator
+func NewOrchestrator(deps *Dependencies, logger *zap.Logger) *Orchestrator {
+	cb := gobreaker.NewCircuitBreaker(gobreaker.Settings{
+		Name:        "agent-orchestrator",
+		MaxRequests: 5,
+		Interval:    10 * time.Second,
+		Timeout:     60 * time.Second,
+		ReadyToTrip: func(counts gobreaker.Counts) bool {
+			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
+			return counts.Requests >= 3 && failureRatio >= 0.6
+		},
+		OnStateChange: func(name string, from, to gobreaker.State) {
+			logger.Warn("circuit breaker state changed",
+				zap.String("name", name),
+				zap.String("from", from.String()),
+				zap.String("to", to.String()),
+			)
+		},
+	})
+
+	return &Orchestrator{
+		deps:           deps,
+		logger:         logger,
+		tools:          make(map[string]Tool),
+		circuitBreaker: cb,
+	}
+}
+
+// ProcessQuery handles a single query through the full RAG pipeline
+func (o *Orchestrator) ProcessQuery(ctx context.Context, req *QueryRequest) (*QueryResponse, error) {
+	ctx, span := tracer.Start(ctx, "ProcessQuery",
+		trace.WithAttributes(
+			attribute.String("query", req.Query),
+			attribute.String("session_id", req.SessionID),
+			attribute.String("user_id", req.UserID),
+		),
+	)
+	defer span.End()
+
+	startTime := time.Now()
+	traceID := span.SpanContext().TraceID().String()
+
+	// Set default options
+	if req.Options.MaxSources == 0 {
+		req.Options.MaxSources = 10
+	}
+	if req.Options.Temperature == 0 {
+		req.Options.Temperature = 0.7
+	}
+	if req.Options.MaxTokens == 0 {
+		req.Options.MaxTokens = 4096
+	}
+
+	// 1. Check cache first
+	if req.Options.UseCache && o.deps.Cache != nil {
+		cacheKey := o.buildCacheKey(req.Query)
+		var cached QueryResponse
+		if err := o.deps.Cache.GetJSON(ctx, cacheKey, &cached); err == nil {
+			span.SetAttributes(attribute.Bool("cache_hit", true))
+			cached.Metadata.CacheHit = true
+			cached.Metadata.TraceID = traceID
+			observability.RecordCacheHit("query")
+			observability.RecordQuery("success", true, cached.Metadata.RoutingStrategy, time.Since(startTime))
+			return &cached, nil
+		}
+		observability.RecordCacheMiss("query")
+	}
+
+	// 2. Route the query to determine retrieval strategy
+	var routingDecision *router.RoutingDecision
+	if o.deps.Router != nil {
+		routingDecision = o.deps.Router.Route(ctx, req.Query)
+		span.SetAttributes(
+			attribute.String("routing_strategy", string(routingDecision.Strategy)),
+			attribute.String("query_type", string(routingDecision.QueryType)),
+			attribute.Float64("routing_confidence", float64(routingDecision.Confidence)),
+		)
+	} else {
+		routingDecision = &router.RoutingDecision{
+			Strategy:      router.StrategyHybrid,
+			SuggestedTopK: req.Options.MaxSources,
+		}
+	}
+
+	// 3. Retrieve relevant documents
+	retrieveStart := time.Now()
+	var documents []retriever.SearchResult
+	var retrieveErr error
+
+	if o.deps.Retriever != nil {
+		searchResp, err := o.deps.Retriever.Search(ctx, retriever.SearchRequest{
+			Query:     req.Query,
+			TopK:      routingDecision.SuggestedTopK,
+			UseVector: routingDecision.Strategy != router.StrategyKeyword,
+			UseKeyword: routingDecision.Strategy != router.StrategyVector,
+		})
+		if err != nil {
+			o.logger.Error("retrieval failed", zap.Error(err))
+			retrieveErr = err
+		} else {
+			documents = searchResp.Results
+		}
+	}
+
+	observability.RecordRetrieval("hybrid", time.Since(retrieveStart))
+	span.SetAttributes(attribute.Int("documents_retrieved", len(documents)))
+
+	if retrieveErr != nil && len(documents) == 0 {
+		return nil, fmt.Errorf("retrieval failed: %w", retrieveErr)
+	}
+
+	// 4. Generate response using LLM
+	generateStart := time.Now()
+	answer, tokensUsed, err := o.generate(ctx, req, documents)
+	if err != nil {
+		observability.RecordError("generation", "orchestrator")
+		return nil, fmt.Errorf("generation failed: %w", err)
+	}
+	observability.RecordGeneration(time.Since(generateStart))
+	observability.RecordTokens("total", tokensUsed)
+
+	// 5. Build response
+	response := &QueryResponse{
+		Answer:     answer,
+		Sources:    o.buildSources(documents),
+		Confidence: o.calculateConfidence(documents),
+		Metadata: QueryMetadata{
+			ProcessingTimeMs: time.Since(startTime).Milliseconds(),
+			ChunksRetrieved:  len(documents),
+			TokensUsed:       tokensUsed,
+			CacheHit:         false,
+			RoutingStrategy:  string(routingDecision.Strategy),
+			TraceID:          traceID,
+		},
+		FollowUpQuestions: o.generateFollowUps(ctx, req.Query, documents),
+	}
+
+	// 6. Cache the response
+	if req.Options.UseCache && o.deps.Cache != nil {
+		cacheKey := o.buildCacheKey(req.Query)
+		if err := o.deps.Cache.SetJSON(ctx, cacheKey, response, 3600); err != nil {
+			o.logger.Warn("failed to cache response", zap.Error(err))
+		}
+	}
+
+	observability.RecordQuery("success", false, string(routingDecision.Strategy), time.Since(startTime))
+	return response, nil
+}
+
+// ProcessQueryStream handles a query with streaming response
+func (o *Orchestrator) ProcessQueryStream(ctx context.Context, req *QueryRequest, stream ResponseStream) error {
+	ctx, span := tracer.Start(ctx, "ProcessQueryStream")
+	defer span.End()
+
+	// Send thinking status
+	if err := stream.Send(&ResponseChunk{Type: "thinking", Content: "Analyzing your query..."}); err != nil {
+		return err
+	}
+
+	// Route query
+	var routingDecision *router.RoutingDecision
+	if o.deps.Router != nil {
+		routingDecision = o.deps.Router.Route(ctx, req.Query)
+	} else {
+		routingDecision = &router.RoutingDecision{
+			Strategy:      router.StrategyHybrid,
+			SuggestedTopK: 10,
+		}
+	}
+
+	// Send retrieval status
+	if err := stream.Send(&ResponseChunk{Type: "retrieval", Content: "Searching knowledge base..."}); err != nil {
+		return err
+	}
+
+	// Retrieve documents
+	var documents []retriever.SearchResult
+	if o.deps.Retriever != nil {
+		searchResp, err := o.deps.Retriever.Search(ctx, retriever.SearchRequest{
+			Query:     req.Query,
+			TopK:      routingDecision.SuggestedTopK,
+			UseVector: true,
+			UseKeyword: true,
+		})
+		if err != nil {
+			o.logger.Warn("retrieval error in stream", zap.Error(err))
+		} else {
+			documents = searchResp.Results
+		}
+	}
+
+	// Send sources
+	sources := o.buildSources(documents)
+	if err := stream.Send(&ResponseChunk{
+		Type:    "retrieval",
+		Content: fmt.Sprintf("Found %d relevant sources", len(documents)),
+		Sources: sources,
+	}); err != nil {
+		return err
+	}
+
+	// Stream generation
+	if o.deps.LLMClient == nil {
+		return stream.Send(&ResponseChunk{
+			Type:    "complete",
+			Content: "LLM client not configured",
+			IsFinal: true,
+		})
+	}
+
+	messages := o.buildMessages(req, documents)
+	opts := llmclient.Options{
+		Temperature: req.Options.Temperature,
+		MaxTokens:   req.Options.MaxTokens,
+	}
+
+	var fullContent string
+	err := o.deps.LLMClient.GenerateStream(ctx, messages, opts, func(chunk string) error {
+		fullContent += chunk
+		return stream.Send(&ResponseChunk{
+			Type:    "generation",
+			Content: chunk,
+		})
+	})
+
+	if err != nil {
+		return err
+	}
+
+	// Send final response
+	return stream.Send(&ResponseChunk{
+		Type:    "complete",
+		Content: fullContent,
+		Sources: sources,
+		IsFinal: true,
+	})
+}
+
+// RegisterTool registers a tool for agentic execution
+func (o *Orchestrator) RegisterTool(name string, tool Tool) error {
+	o.toolsMu.Lock()
+	defer o.toolsMu.Unlock()
+
+	if _, exists := o.tools[name]; exists {
+		return fmt.Errorf("tool %s already registered", name)
+	}
+
+	o.tools[name] = tool
+	o.logger.Info("registered tool", zap.String("name", name))
+	return nil
+}
+
+func (o *Orchestrator) buildCacheKey(query string) string {
+	return "query:" + query
+}
+
+func (o *Orchestrator) generate(ctx context.Context, req *QueryRequest, docs []retriever.SearchResult) (string, int, error) {
+	if o.deps.LLMClient == nil {
+		return "LLM client not configured. Please set OPENAI_API_KEY environment variable.", 0, nil
+	}
+
+	messages := o.buildMessages(req, docs)
+	opts := llmclient.Options{
+		Temperature: req.Options.Temperature,
+		MaxTokens:   req.Options.MaxTokens,
+	}
+
+	resp, err := o.deps.LLMClient.Generate(ctx, messages, opts)
+	if err != nil {
+		return "", 0, err
+	}
+
+	return resp.Content, resp.Usage.TotalTokens, nil
+}
+
+func (o *Orchestrator) buildMessages(req *QueryRequest, docs []retriever.SearchResult) []llmclient.Message {
+	// Build context from documents
+	contextDocs := make([]llmclient.ContextDoc, len(docs))
+	for i, doc := range docs {
+		title := doc.Title
+		if title == "" {
+			if t, ok := doc.Metadata["title"].(string); ok {
+				title = t
+			} else {
+				title = fmt.Sprintf("Source %d", i+1)
+			}
+		}
+		contextDocs[i] = llmclient.ContextDoc{
+			Title:   title,
+			Content: doc.Content,
+			Source:  doc.Source,
+			Score:   doc.Score,
+		}
+	}
+
+	return llmclient.BuildPrompt(defaultSystemPrompt, req.Query, contextDocs)
+}
+
+func (o *Orchestrator) buildSources(docs []retriever.SearchResult) []Source {
+	sources := make([]Source, len(docs))
+	for i, doc := range docs {
+		metadata := make(map[string]string)
+		for k, v := range doc.Metadata {
+			if s, ok := v.(string); ok {
+				metadata[k] = s
+			}
+		}
+		sources[i] = Source{
+			ID:       doc.ID,
+			Title:    doc.Title,
+			Content:  doc.Content,
+			URL:      doc.Source,
+			Score:    doc.Score,
+			Metadata: metadata,
+		}
+	}
+	return sources
+}
+
+func (o *Orchestrator) calculateConfidence(docs []retriever.SearchResult) float32 {
+	if len(docs) == 0 {
+		return 0.0
+	}
+	var totalScore float32
+	for _, doc := range docs {
+		totalScore += doc.Score
+	}
+	return totalScore / float32(len(docs))
+}
+
+func (o *Orchestrator) generateFollowUps(ctx context.Context, query string, docs []retriever.SearchResult) []string {
+	// Generate simple follow-up suggestions based on query patterns
+	followUps := []string{}
+
+	// Check for legal terms to suggest related questions
+	if containsLegalTerms(query) {
+		followUps = append(followUps, "What are the penalties for violating this law?")
+		followUps = append(followUps, "Are there any recent amendments to this law?")
+	}
+
+	// Suggest comparative questions
+	if len(docs) > 0 {
+		followUps = append(followUps, "How does this compare to similar laws in other East African countries?")
+	}
+
+	if len(followUps) > 3 {
+		followUps = followUps[:3]
+	}
+
+	return followUps
+}
+
+func containsLegalTerms(query string) bool {
+	legalTerms := []string{"constitution", "law", "act", "section", "article", "court", "case", "rights"}
+	queryLower := query
+	for _, term := range legalTerms {
+		if contains(queryLower, term) {
+			return true
+		}
+	}
+	return false
+}
+
+func contains(s, substr string) bool {
+	return len(s) >= len(substr) && (s == substr || len(s) > 0 && containsHelper(s, substr))
+}
+
+func containsHelper(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}

internal/agent/server.go

@@ -0,0 +1,311 @@
+// Package agent provides gRPC server implementation for the Agent service
+package agent
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"sync"
+	"time"
+
+	ragv1 "github.com/AmaniQuery/amaniquery/pkg/proto/gen/ragv1"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// Server implements the AgentService gRPC server
+type Server struct {
+	ragv1.UnimplementedAgentServiceServer
+	orchestrator *Orchestrator
+	logger       *zap.Logger
+	mu           sync.RWMutex
+}
+
+// NewServer creates a new Agent gRPC server
+func NewServer(deps *Dependencies, logger *zap.Logger) *Server {
+	return &Server{
+		orchestrator: NewOrchestrator(deps, logger),
+		logger:       logger,
+	}
+}
+
+// ProcessQuery handles a single query via gRPC (unary RPC)
+func (s *Server) ProcessQuery(ctx context.Context, req *ragv1.QueryRequest) (*ragv1.QueryResponse, error) {
+	if req == nil || req.Query == "" {
+		return nil, status.Error(codes.InvalidArgument, "query is required")
+	}
+
+	s.logger.Info("processing query",
+		zap.String("query", req.Query),
+		zap.String("session_id", req.SessionId),
+		zap.String("user_id", req.UserId),
+	)
+
+	// Convert proto request to internal type
+	internalReq := s.protoToQueryRequest(req)
+
+	// Process query through orchestrator
+	response, err := s.orchestrator.ProcessQuery(ctx, internalReq)
+	if err != nil {
+		s.logger.Error("query processing failed",
+			zap.Error(err),
+			zap.String("query", req.Query),
+		)
+		return nil, status.Error(codes.Internal, "query processing failed: "+err.Error())
+	}
+
+	// Convert internal response to proto
+	return s.queryResponseToProto(response), nil
+}
+
+// ProcessQueryStream handles a query with streaming response via gRPC (server streaming RPC)
+func (s *Server) ProcessQueryStream(req *ragv1.QueryRequest, stream ragv1.AgentService_ProcessQueryStreamServer) error {
+	if req == nil || req.Query == "" {
+		return status.Error(codes.InvalidArgument, "query is required")
+	}
+
+	s.logger.Info("processing streaming query",
+		zap.String("query", req.Query),
+		zap.String("session_id", req.SessionId),
+	)
+
+	// Convert proto request to internal type
+	internalReq := s.protoToQueryRequest(req)
+
+	// Create a wrapper that implements ResponseStream
+	streamWrapper := &grpcStreamWrapper{
+		stream: stream,
+		logger: s.logger,
+	}
+
+	return s.orchestrator.ProcessQueryStream(stream.Context(), internalReq, streamWrapper)
+}
+
+// CreateAgent creates a new agent with specific configuration
+func (s *Server) CreateAgent(ctx context.Context, req *ragv1.CreateAgentRequest) (*ragv1.Agent, error) {
+	if req == nil || req.Name == "" {
+		return nil, status.Error(codes.InvalidArgument, "agent name is required")
+	}
+
+	s.logger.Info("creating agent", zap.String("name", req.Name))
+
+	// TODO: Implement agent creation logic with persistence
+	// For now, return a mock agent
+	return &ragv1.Agent{
+		Id:          generateAgentID(),
+		Name:        req.Name,
+		Description: req.Description,
+		CreatedAt:   currentTimestamp(),
+		Config:      req.Config,
+	}, nil
+}
+
+// ExecutePlan executes a pre-defined execution plan
+func (s *Server) ExecutePlan(ctx context.Context, req *ragv1.ExecutionPlan) (*ragv1.PlanResult, error) {
+	if req == nil || req.Id == "" {
+		return nil, status.Error(codes.InvalidArgument, "plan ID is required")
+	}
+
+	s.logger.Info("executing plan",
+		zap.String("plan_id", req.Id),
+		zap.Int("steps", len(req.Steps)),
+	)
+
+	// TODO: Implement multi-step plan execution
+	return &ragv1.PlanResult{
+		PlanId:          req.Id,
+		Status:          ragv1.ExecutionStatus_EXECUTION_STATUS_COMPLETED,
+		StepResults:     make([]*ragv1.StepResult, 0),
+		FinalAnswer:     "Plan execution not yet implemented",
+		ExecutionTimeMs: 0,
+	}, nil
+}
+
+// GetQueryStatus returns the status of an ongoing query
+func (s *Server) GetQueryStatus(ctx context.Context, req *ragv1.QueryStatusRequest) (*ragv1.QueryStatus, error) {
+	if req == nil || req.QueryId == "" {
+		return nil, status.Error(codes.InvalidArgument, "query_id is required")
+	}
+
+	// TODO: Implement query status tracking
+	return &ragv1.QueryStatus{
+		QueryId:     req.QueryId,
+		Status:      ragv1.ExecutionStatus_EXECUTION_STATUS_COMPLETED,
+		Progress:    100,
+		CurrentStep: "completed",
+	}, nil
+}
+
+// RegisterTool registers a tool with the orchestrator
+func (s *Server) RegisterTool(name string, tool Tool) error {
+	return s.orchestrator.RegisterTool(name, tool)
+}
+
+// grpcStreamWrapper wraps gRPC stream to implement ResponseStream interface
+type grpcStreamWrapper struct {
+	stream ragv1.AgentService_ProcessQueryStreamServer
+	logger *zap.Logger
+}
+
+// Send implements ResponseStream.Send by converting internal chunk to protobuf
+func (w *grpcStreamWrapper) Send(chunk *ResponseChunk) error {
+	w.logger.Debug("sending stream chunk",
+		zap.String("type", chunk.Type),
+		zap.Bool("is_final", chunk.IsFinal),
+		zap.Int("content_length", len(chunk.Content)),
+	)
+
+	// Convert chunk type string to proto enum
+	chunkType := w.stringToChunkType(chunk.Type)
+
+	// Convert sources to proto format
+	protoSources := make([]*ragv1.Source, len(chunk.Sources))
+	for i, src := range chunk.Sources {
+		protoSources[i] = &ragv1.Source{
+			Id:       src.ID,
+			Title:    src.Title,
+			Content:  src.Content,
+			Url:      src.URL,
+			Score:    src.Score,
+			Metadata: src.Metadata,
+			Location: src.Location,
+		}
+	}
+
+	// Create proto chunk and send
+	protoChunk := &ragv1.QueryResponseChunk{
+		Type:    chunkType,
+		Content: chunk.Content,
+		Sources: protoSources,
+		IsFinal: chunk.IsFinal,
+	}
+
+	return w.stream.Send(protoChunk)
+}
+
+// stringToChunkType converts string chunk type to proto enum
+func (w *grpcStreamWrapper) stringToChunkType(t string) ragv1.ChunkType {
+	switch t {
+	case "thinking":
+		return ragv1.ChunkType_CHUNK_TYPE_THINKING
+	case "retrieval":
+		return ragv1.ChunkType_CHUNK_TYPE_RETRIEVAL
+	case "generation":
+		return ragv1.ChunkType_CHUNK_TYPE_GENERATION
+	case "complete":
+		return ragv1.ChunkType_CHUNK_TYPE_COMPLETE
+	case "error":
+		return ragv1.ChunkType_CHUNK_TYPE_ERROR
+	default:
+		return ragv1.ChunkType_CHUNK_TYPE_UNSPECIFIED
+	}
+}
+
+// protoToQueryRequest converts proto QueryRequest to internal type
+func (s *Server) protoToQueryRequest(req *ragv1.QueryRequest) *QueryRequest {
+	// Convert conversation history
+	history := make([]Message, len(req.ConversationHistory))
+	for i, msg := range req.ConversationHistory {
+		history[i] = Message{
+			Role:    s.protoRoleToString(msg.Role),
+			Content: msg.Content,
+		}
+	}
+
+	// Set default options if not provided
+	maxSources := int(req.Options.GetMaxSources())
+	if maxSources == 0 {
+		maxSources = 10
+	}
+	maxTokens := int(req.Options.GetMaxTokens())
+	if maxTokens == 0 {
+		maxTokens = 4096
+	}
+	temperature := req.Options.GetTemperature()
+	if temperature == 0 {
+		temperature = 0.7
+	}
+
+	return &QueryRequest{
+		Query:               req.Query,
+		SessionID:           req.SessionId,
+		UserID:              req.UserId,
+		ConversationHistory: history,
+		Metadata:            req.Metadata,
+		Options: QueryOptions{
+			MaxSources:     maxSources,
+			UseCache:       req.Options.GetUseCache(),
+			EnableAgentic:  req.Options.GetEnableAgentic(),
+			KnowledgeBases: req.Options.GetKnowledgeBases(),
+			Temperature:    temperature,
+			MaxTokens:      maxTokens,
+		},
+	}
+}
+
+// queryResponseToProto converts internal QueryResponse to proto type
+func (s *Server) queryResponseToProto(resp *QueryResponse) *ragv1.QueryResponse {
+	// Convert sources
+	protoSources := make([]*ragv1.Source, len(resp.Sources))
+	for i, src := range resp.Sources {
+		protoSources[i] = &ragv1.Source{
+			Id:       src.ID,
+			Title:    src.Title,
+			Content:  src.Content,
+			Url:      src.URL,
+			Score:    src.Score,
+			Metadata: src.Metadata,
+			Location: src.Location,
+		}
+	}
+
+	return &ragv1.QueryResponse{
+		Answer:  resp.Answer,
+		Sources: protoSources,
+		Confidence: resp.Confidence,
+		Metadata: &ragv1.QueryMetadata{
+			ProcessingTimeMs: resp.Metadata.ProcessingTimeMs,
+			ChunksRetrieved:  int32(resp.Metadata.ChunksRetrieved),
+			TokensUsed:       int32(resp.Metadata.TokensUsed),
+			CacheHit:         resp.Metadata.CacheHit,
+			RoutingStrategy:  resp.Metadata.RoutingStrategy,
+			TraceId:          resp.Metadata.TraceID,
+		},
+		FollowUpQuestions: resp.FollowUpQuestions,
+	}
+}
+
+// protoRoleToString converts proto MessageRole to string
+func (s *Server) protoRoleToString(role ragv1.MessageRole) string {
+	switch role {
+	case ragv1.MessageRole_MESSAGE_ROLE_USER:
+		return "user"
+	case ragv1.MessageRole_MESSAGE_ROLE_ASSISTANT:
+		return "assistant"
+	case ragv1.MessageRole_MESSAGE_ROLE_SYSTEM:
+		return "system"
+	default:
+		return "user"
+	}
+}
+
+// RegisterAgentServiceServer registers the server with gRPC using generated code
+func RegisterAgentServiceServer(s *grpc.Server, srv *Server) {
+	ragv1.RegisterAgentServiceServer(s, srv)
+}
+
+// Helper functions
+
+func generateAgentID() string {
+	b := make([]byte, 16)
+	rand.Read(b)
+	return "agent_" + hex.EncodeToString(b)
+}
+
+func currentTimestamp() int64 {
+	return time.Now().Unix()
+}
+

internal/cache/cache.go

@@ -0,0 +1,310 @@
+// Package cache provides multi-tier caching implementation with local LRU and Redis
+package cache
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// MultiTierCache implements a two-tier caching system with local LRU and Redis
+type MultiTierCache struct {
+	local      *LRUCache
+	redis      *redis.Client
+	ttl        time.Duration
+	metrics    *CacheMetrics
+}
+
+// CacheMetrics tracks cache performance
+type CacheMetrics struct {
+	mu          sync.RWMutex
+	LocalHits   int64
+	LocalMisses int64
+	RedisHits   int64
+	RedisMisses int64
+}
+
+// Config for cache initialization
+type Config struct {
+	RedisURL   string
+	LocalSize  int
+	TTL        time.Duration
+	MaxRetries int
+	PoolSize   int
+}
+
+// New creates a new multi-tier cache
+func New(cfg Config) (*MultiTierCache, error) {
+	// Parse Redis URL
+	opt, err := redis.ParseURL(cfg.RedisURL)
+	if err != nil {
+		return nil, err
+	}
+	opt.MaxRetries = cfg.MaxRetries
+	opt.PoolSize = cfg.PoolSize
+
+	redisClient := redis.NewClient(opt)
+
+	// Test Redis connection
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := redisClient.Ping(ctx).Err(); err != nil {
+		// Redis not available, continue with local cache only
+		redisClient = nil
+	}
+
+	return &MultiTierCache{
+		local:   NewLRUCache(cfg.LocalSize),
+		redis:   redisClient,
+		ttl:     cfg.TTL,
+		metrics: &CacheMetrics{},
+	}, nil
+}
+
+// Get retrieves a value from cache, checking local first then Redis
+func (c *MultiTierCache) Get(ctx context.Context, key string) ([]byte, error) {
+	hashedKey := c.hashKey(key)
+
+	// Check local cache first (sub-millisecond)
+	if value, found := c.local.Get(hashedKey); found {
+		c.metrics.mu.Lock()
+		c.metrics.LocalHits++
+		c.metrics.mu.Unlock()
+		return value, nil
+	}
+	c.metrics.mu.Lock()
+	c.metrics.LocalMisses++
+	c.metrics.mu.Unlock()
+
+	// Check Redis if available (1-5ms)
+	if c.redis != nil {
+		value, err := c.redis.Get(ctx, hashedKey).Bytes()
+		if err == nil {
+			c.metrics.mu.Lock()
+			c.metrics.RedisHits++
+			c.metrics.mu.Unlock()
+			// Backfill local cache
+			c.local.Set(hashedKey, value)
+			return value, nil
+		}
+		if err != redis.Nil {
+			// Log error but continue
+		}
+		c.metrics.mu.Lock()
+		c.metrics.RedisMisses++
+		c.metrics.mu.Unlock()
+	}
+
+	return nil, ErrCacheMiss
+}
+
+// Set stores a value in both cache tiers
+func (c *MultiTierCache) Set(ctx context.Context, key string, value []byte, ttlSeconds int) error {
+	hashedKey := c.hashKey(key)
+	ttl := time.Duration(ttlSeconds) * time.Second
+	if ttlSeconds == 0 {
+		ttl = c.ttl
+	}
+
+	// Set in local cache
+	c.local.Set(hashedKey, value)
+
+	// Set in Redis if available
+	if c.redis != nil {
+		if err := c.redis.Set(ctx, hashedKey, value, ttl).Err(); err != nil {
+			// Log error but don't fail - local cache is still valid
+			return nil
+		}
+	}
+
+	return nil
+}
+
+// Delete removes a value from both cache tiers
+func (c *MultiTierCache) Delete(ctx context.Context, key string) error {
+	hashedKey := c.hashKey(key)
+
+	// Delete from local cache
+	c.local.Delete(hashedKey)
+
+	// Delete from Redis if available
+	if c.redis != nil {
+		if err := c.redis.Del(ctx, hashedKey).Err(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// GetJSON retrieves and unmarshals a JSON value from cache
+func (c *MultiTierCache) GetJSON(ctx context.Context, key string, v interface{}) error {
+	data, err := c.Get(ctx, key)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(data, v)
+}
+
+// SetJSON marshals and stores a JSON value in cache
+func (c *MultiTierCache) SetJSON(ctx context.Context, key string, v interface{}, ttlSeconds int) error {
+	data, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	return c.Set(ctx, key, data, ttlSeconds)
+}
+
+// GetMetrics returns cache performance metrics
+func (c *MultiTierCache) GetMetrics() CacheMetrics {
+	c.metrics.mu.RLock()
+	defer c.metrics.mu.RUnlock()
+	return CacheMetrics{
+		LocalHits:   c.metrics.LocalHits,
+		LocalMisses: c.metrics.LocalMisses,
+		RedisHits:   c.metrics.RedisHits,
+		RedisMisses: c.metrics.RedisMisses,
+	}
+}
+
+// Close closes the cache connections
+func (c *MultiTierCache) Close() error {
+	if c.redis != nil {
+		return c.redis.Close()
+	}
+	return nil
+}
+
+func (c *MultiTierCache) hashKey(key string) string {
+	hash := sha256.Sum256([]byte(key))
+	return "amani:" + hex.EncodeToString(hash[:16])
+}
+
+// ErrCacheMiss indicates the key was not found in cache
+var ErrCacheMiss = &CacheMissError{}
+
+// CacheMissError represents a cache miss
+type CacheMissError struct{}
+
+func (e *CacheMissError) Error() string {
+	return "cache miss"
+}
+
+// LRUCache implements a simple LRU cache
+type LRUCache struct {
+	mu       sync.RWMutex
+	capacity int
+	items    map[string]*lruItem
+	head     *lruItem
+	tail     *lruItem
+}
+
+type lruItem struct {
+	key   string
+	value []byte
+	prev  *lruItem
+	next  *lruItem
+}
+
+// NewLRUCache creates a new LRU cache with the given capacity
+func NewLRUCache(capacity int) *LRUCache {
+	return &LRUCache{
+		capacity: capacity,
+		items:    make(map[string]*lruItem),
+	}
+}
+
+// Get retrieves a value from the LRU cache
+func (c *LRUCache) Get(key string) ([]byte, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	item, found := c.items[key]
+	if !found {
+		return nil, false
+	}
+
+	// Move to front (most recently used)
+	c.moveToFront(item)
+	return item.value, true
+}
+
+// Set stores a value in the LRU cache
+func (c *LRUCache) Set(key string, value []byte) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	// Check if item exists
+	if item, found := c.items[key]; found {
+		item.value = value
+		c.moveToFront(item)
+		return
+	}
+
+	// Create new item
+	item := &lruItem{key: key, value: value}
+	c.items[key] = item
+	c.addToFront(item)
+
+	// Evict if over capacity
+	if len(c.items) > c.capacity {
+		c.evictLRU()
+	}
+}
+
+// Delete removes a value from the LRU cache
+func (c *LRUCache) Delete(key string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if item, found := c.items[key]; found {
+		c.removeItem(item)
+		delete(c.items, key)
+	}
+}
+
+func (c *LRUCache) moveToFront(item *lruItem) {
+	if item == c.head {
+		return
+	}
+	c.removeItem(item)
+	c.addToFront(item)
+}
+
+func (c *LRUCache) addToFront(item *lruItem) {
+	item.prev = nil
+	item.next = c.head
+	if c.head != nil {
+		c.head.prev = item
+	}
+	c.head = item
+	if c.tail == nil {
+		c.tail = item
+	}
+}
+
+func (c *LRUCache) removeItem(item *lruItem) {
+	if item.prev != nil {
+		item.prev.next = item.next
+	} else {
+		c.head = item.next
+	}
+	if item.next != nil {
+		item.next.prev = item.prev
+	} else {
+		c.tail = item.prev
+	}
+}
+
+func (c *LRUCache) evictLRU() {
+	if c.tail == nil {
+		return
+	}
+	delete(c.items, c.tail.key)
+	c.removeItem(c.tail)
+}

internal/cache/cache_test.go

@@ -0,0 +1,310 @@
+package cache_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/AmaniQuery/amaniquery/internal/cache"
+)
+
+// TestLRUCache_SetGet verifies basic set/get operations
+func TestLRUCache_SetGet(t *testing.T) {
+	lru := cache.NewLRUCache(100)
+
+	// Test set and get
+	lru.Set("key1", []byte("value1"))
+	
+	value, found := lru.Get("key1")
+	if !found {
+		t.Fatal("Expected to find key1")
+	}
+	if string(value) != "value1" {
+		t.Errorf("Expected 'value1', got '%s'", string(value))
+	}
+
+	// Test missing key
+	_, found = lru.Get("nonexistent")
+	if found {
+		t.Error("Expected not to find nonexistent key")
+	}
+}
+
+// TestLRUCache_Update verifies updating existing keys
+func TestLRUCache_Update(t *testing.T) {
+	lru := cache.NewLRUCache(100)
+
+	lru.Set("key1", []byte("original"))
+	lru.Set("key1", []byte("updated"))
+
+	value, found := lru.Get("key1")
+	if !found {
+		t.Fatal("Expected to find key1")
+	}
+	if string(value) != "updated" {
+		t.Errorf("Expected 'updated', got '%s'", string(value))
+	}
+}
+
+// TestLRUCache_Eviction verifies LRU eviction when over capacity
+func TestLRUCache_Eviction(t *testing.T) {
+	lru := cache.NewLRUCache(3)
+
+	// Fill cache to capacity
+	lru.Set("key1", []byte("value1"))
+	lru.Set("key2", []byte("value2"))
+	lru.Set("key3", []byte("value3"))
+
+	// Access key1 to make it recently used
+	lru.Get("key1")
+
+	// Add new key, should evict key2 (least recently used)
+	lru.Set("key4", []byte("value4"))
+
+	// key2 should be evicted
+	_, found := lru.Get("key2")
+	if found {
+		t.Error("Expected key2 to be evicted")
+	}
+
+	// key1 should still exist (was accessed recently)
+	_, found = lru.Get("key1")
+	if !found {
+		t.Error("Expected key1 to still exist")
+	}
+
+	// key3 and key4 should exist
+	_, found = lru.Get("key3")
+	if !found {
+		t.Error("Expected key3 to exist")
+	}
+	_, found = lru.Get("key4")
+	if !found {
+		t.Error("Expected key4 to exist")
+	}
+}
+
+// TestLRUCache_Delete verifies deletion operations
+func TestLRUCache_Delete(t *testing.T) {
+	lru := cache.NewLRUCache(100)
+
+	lru.Set("key1", []byte("value1"))
+	lru.Set("key2", []byte("value2"))
+
+	lru.Delete("key1")
+
+	_, found := lru.Get("key1")
+	if found {
+		t.Error("Expected key1 to be deleted")
+	}
+
+	// key2 should still exist
+	_, found = lru.Get("key2")
+	if !found {
+		t.Error("Expected key2 to still exist")
+	}
+}
+
+// TestLRUCache_DeleteNonexistent verifies deleting nonexistent keys doesn't panic
+func TestLRUCache_DeleteNonexistent(t *testing.T) {
+	lru := cache.NewLRUCache(100)
+
+	// Should not panic
+	lru.Delete("nonexistent")
+}
+
+// TestCacheMissError tests the error type
+func TestCacheMissError(t *testing.T) {
+	err := cache.ErrCacheMiss
+	if err.Error() != "cache miss" {
+		t.Errorf("Expected 'cache miss', got '%s'", err.Error())
+	}
+}
+
+// TestMultiTierCache_LocalOnly tests cache without Redis connection
+func TestMultiTierCache_LocalOnly(t *testing.T) {
+	// Create cache with invalid Redis URL to ensure Redis is not used
+	cfg := cache.Config{
+		RedisURL:   "redis://invalid:6379", // Will fail connection
+		LocalSize:  100,
+		TTL:        time.Hour,
+		MaxRetries: 1,
+		PoolSize:   1,
+	}
+
+	c, err := cache.New(cfg)
+	if err != nil {
+		t.Fatalf("Failed to create cache: %v", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+
+	// Set and get should work with local cache
+	err = c.Set(ctx, "key1", []byte("value1"), 0)
+	if err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	value, err := c.Get(ctx, "key1")
+	if err != nil {
+		t.Fatalf("Get failed: %v", err)
+	}
+	if string(value) != "value1" {
+		t.Errorf("Expected 'value1', got '%s'", string(value))
+	}
+}
+
+// TestMultiTierCache_CacheMiss tests cache miss behavior
+func TestMultiTierCache_CacheMiss(t *testing.T) {
+	cfg := cache.Config{
+		RedisURL:   "redis://invalid:6379",
+		LocalSize:  100,
+		TTL:        time.Hour,
+		MaxRetries: 1,
+		PoolSize:   1,
+	}
+
+	c, err := cache.New(cfg)
+	if err != nil {
+		t.Fatalf("Failed to create cache: %v", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+
+	_, err = c.Get(ctx, "nonexistent")
+	if err == nil {
+		t.Error("Expected cache miss error")
+	}
+}
+
+// TestMultiTierCache_Delete tests deletion
+func TestMultiTierCache_Delete(t *testing.T) {
+	cfg := cache.Config{
+		RedisURL:   "redis://invalid:6379",
+		LocalSize:  100,
+		TTL:        time.Hour,
+		MaxRetries: 1,
+		PoolSize:   1,
+	}
+
+	c, err := cache.New(cfg)
+	if err != nil {
+		t.Fatalf("Failed to create cache: %v", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+
+	// Set then delete
+	c.Set(ctx, "key1", []byte("value1"), 0)
+	err = c.Delete(ctx, "key1")
+	if err != nil {
+		t.Fatalf("Delete failed: %v", err)
+	}
+
+	// Should be gone
+	_, err = c.Get(ctx, "key1")
+	if err == nil {
+		t.Error("Expected cache miss after delete")
+	}
+}
+
+// TestMultiTierCache_JSON tests JSON operations
+func TestMultiTierCache_JSON(t *testing.T) {
+	cfg := cache.Config{
+		RedisURL:   "redis://invalid:6379",
+		LocalSize:  100,
+		TTL:        time.Hour,
+		MaxRetries: 1,
+		PoolSize:   1,
+	}
+
+	c, err := cache.New(cfg)
+	if err != nil {
+		t.Fatalf("Failed to create cache: %v", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+
+	type testData struct {
+		Name  string `json:"name"`
+		Value int    `json:"value"`
+	}
+
+	original := testData{Name: "test", Value: 42}
+
+	err = c.SetJSON(ctx, "json-key", original, 0)
+	if err != nil {
+		t.Fatalf("SetJSON failed: %v", err)
+	}
+
+	var result testData
+	err = c.GetJSON(ctx, "json-key", &result)
+	if err != nil {
+		t.Fatalf("GetJSON failed: %v", err)
+	}
+
+	if result.Name != original.Name || result.Value != original.Value {
+		t.Errorf("JSON mismatch: expected %+v, got %+v", original, result)
+	}
+}
+
+// TestMultiTierCache_Metrics tests metrics tracking
+func TestMultiTierCache_Metrics(t *testing.T) {
+	cfg := cache.Config{
+		RedisURL:   "redis://invalid:6379",
+		LocalSize:  100,
+		TTL:        time.Hour,
+		MaxRetries: 1,
+		PoolSize:   1,
+	}
+
+	c, err := cache.New(cfg)
+	if err != nil {
+		t.Fatalf("Failed to create cache: %v", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+
+	// Set and get to generate metrics
+	c.Set(ctx, "key1", []byte("value1"), 0)
+	c.Get(ctx, "key1") // Hit
+	c.Get(ctx, "key2") // Miss
+
+	metrics := c.GetMetrics()
+	if metrics.LocalHits != 1 {
+		t.Errorf("Expected 1 local hit, got %d", metrics.LocalHits)
+	}
+	if metrics.LocalMisses != 1 {
+		t.Errorf("Expected 1 local miss, got %d", metrics.LocalMisses)
+	}
+}
+
+// BenchmarkLRUCache_Set benchmarks LRU set operations
+func BenchmarkLRUCache_Set(b *testing.B) {
+	lru := cache.NewLRUCache(10000)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		lru.Set("key"+string(rune(i%1000)), []byte("value"))
+	}
+}
+
+// BenchmarkLRUCache_Get benchmarks LRU get operations
+func BenchmarkLRUCache_Get(b *testing.B) {
+	lru := cache.NewLRUCache(10000)
+
+	// Pre-populate
+	for i := 0; i < 1000; i++ {
+		lru.Set("key"+string(rune(i)), []byte("value"))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		lru.Get("key" + string(rune(i%1000)))
+	}
+}

internal/gateway/cache/cache.go

@@ -0,0 +1,100 @@
+// Package cache provides caching for the API Gateway.
+package cache
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// Config for cache manager
+type Config struct {
+	RedisAddr     string
+	RedisPassword string
+	RedisDB       int
+	DefaultTTL    time.Duration
+	MaxEntrySize  int
+	KeyPrefix     string
+}
+
+// Manager handles caching operations
+type Manager struct {
+	client *redis.Client
+	config Config
+	logger *zap.Logger
+}
+
+// NewManager creates a cache manager
+func NewManager(cfg Config, logger *zap.Logger) (*Manager, error) {
+	client := redis.NewClient(&redis.Options{
+		Addr:     cfg.RedisAddr,
+		Password: cfg.RedisPassword,
+		DB:       cfg.RedisDB,
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err := client.Ping(ctx).Err(); err != nil {
+		return nil, err
+	}
+
+	return &Manager{
+		client: client,
+		config: cfg,
+		logger: logger,
+	}, nil
+}
+
+// GenerateKey creates cache key from request
+func (m *Manager) GenerateKey(parts ...string) string {
+	h := sha256.New()
+	for _, p := range parts {
+		h.Write([]byte(p))
+	}
+	return m.config.KeyPrefix + hex.EncodeToString(h.Sum(nil))
+}
+
+// Get retrieves cached value
+func (m *Manager) Get(ctx context.Context, key string) (interface{}, bool) {
+	data, err := m.client.Get(ctx, key).Bytes()
+	if err != nil {
+		return nil, false
+	}
+	var result interface{}
+	if err := json.Unmarshal(data, &result); err != nil {
+		return nil, false
+	}
+	return result, true
+}
+
+// Set stores value in cache
+func (m *Manager) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return err
+	}
+	if len(data) > m.config.MaxEntrySize {
+		m.logger.Warn("Cache entry exceeds max size", zap.String("key", key))
+		return nil
+	}
+	if ttl == 0 {
+		ttl = m.config.DefaultTTL
+	}
+	return m.client.Set(ctx, key, data, ttl).Err()
+}
+
+// Delete removes value from cache
+func (m *Manager) Delete(ctx context.Context, key string) error {
+	return m.client.Del(ctx, key).Err()
+}
+
+// Close closes Redis connection
+func (m *Manager) Close() error {
+	return m.client.Close()
+}

internal/gateway/cmd/main.go

@@ -0,0 +1,65 @@
+// Gateway entry point
+package main
+
+import (
+	"flag"
+	"os"
+
+	"github.com/spf13/viper"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway"
+)
+
+func main() {
+	configPath := flag.String("config", "gateway.yaml", "Path to config file")
+	flag.Parse()
+
+	// Initialize logger
+	logger, _ := zap.NewProduction()
+	defer logger.Sync()
+
+	// Load configuration
+	cfg, err := loadConfig(*configPath)
+	if err != nil {
+		logger.Fatal("Failed to load config", zap.Error(err))
+	}
+
+	// Create and start gateway
+	gw, err := gateway.New(cfg, logger)
+	if err != nil {
+		logger.Fatal("Failed to create gateway", zap.Error(err))
+	}
+
+	logger.Info("Starting API Gateway", zap.String("addr", cfg.Server.BindAddr))
+	if err := gw.Start(); err != nil {
+		logger.Fatal("Gateway error", zap.Error(err))
+	}
+}
+
+func loadConfig(path string) (*gateway.Config, error) {
+	v := viper.New()
+	v.SetConfigFile(path)
+	v.SetConfigType("yaml")
+	
+	// Environment variable overrides
+	v.AutomaticEnv()
+	v.SetEnvPrefix("GATEWAY")
+
+	// Set defaults
+	cfg := gateway.DefaultConfig()
+
+	if err := v.ReadInConfig(); err != nil {
+		if !os.IsNotExist(err) {
+			return nil, err
+		}
+		// Use defaults if config file doesn't exist
+		return cfg, nil
+	}
+
+	if err := v.Unmarshal(cfg); err != nil {
+		return nil, err
+	}
+
+	return cfg, nil
+}

internal/gateway/config.go

@@ -0,0 +1,204 @@
+// Package gateway provides the API Gateway for the RAG Agent Framework.
+// It implements a multi-protocol gateway supporting REST, GraphQL, WebSocket, and SSE,
+// with comprehensive middleware for security, observability, and performance.
+package gateway
+
+import (
+	"time"
+)
+
+// Config holds all gateway configuration
+type Config struct {
+	Server           ServerConfig           `yaml:"server"`
+	TLS              TLSConfig              `yaml:"tls"`
+	RateLimit        RateLimitConfig        `yaml:"rateLimit"`
+	CORS             CORSConfig             `yaml:"cors"`
+	Auth             AuthConfig             `yaml:"auth"`
+	Cache            CacheConfig            `yaml:"cache"`
+	ServiceDiscovery ServiceDiscoveryConfig `yaml:"serviceDiscovery"`
+	CircuitBreaker   CircuitBreakerConfig   `yaml:"circuitBreaker"`
+	Observability    ObservabilityConfig    `yaml:"observability"`
+	WebSocket        WebSocketConfig        `yaml:"websocket"`
+}
+
+// ServerConfig contains HTTP server settings
+type ServerConfig struct {
+	BindAddr        string        `yaml:"bindAddr"`
+	ReadTimeout     time.Duration `yaml:"readTimeout"`
+	WriteTimeout    time.Duration `yaml:"writeTimeout"`
+	IdleTimeout     time.Duration `yaml:"idleTimeout"`
+	ShutdownTimeout time.Duration `yaml:"shutdownTimeout"`
+	MaxHeaderBytes  int           `yaml:"maxHeaderBytes"`
+	EnableHTTP2     bool          `yaml:"enableHttp2"`
+}
+
+// TLSConfig holds TLS certificate settings
+type TLSConfig struct {
+	Enabled           bool   `yaml:"enabled"`
+	CertFile          string `yaml:"certFile"`
+	KeyFile           string `yaml:"keyFile"`
+	MinVersion        string `yaml:"minVersion"`
+	ClientCAFile      string `yaml:"clientCaFile"`
+	RequireClientCert bool   `yaml:"requireClientCert"`
+}
+
+// RateLimitConfig specifies rate limiting parameters
+type RateLimitConfig struct {
+	Enabled         bool          `yaml:"enabled"`
+	RequestsPerSec  float64       `yaml:"requestsPerSec"`
+	BurstSize       int           `yaml:"burstSize"`
+	PerTenant       bool          `yaml:"perTenant"`
+	PerUser         bool          `yaml:"perUser"`
+	RedisEnabled    bool          `yaml:"redisEnabled"`
+	CleanupInterval time.Duration `yaml:"cleanupInterval"`
+}
+
+// CORSConfig specifies CORS settings
+type CORSConfig struct {
+	AllowedOrigins   []string      `yaml:"allowedOrigins"`
+	AllowedMethods   []string      `yaml:"allowedMethods"`
+	AllowedHeaders   []string      `yaml:"allowedHeaders"`
+	ExposedHeaders   []string      `yaml:"exposedHeaders"`
+	AllowCredentials bool          `yaml:"allowCredentials"`
+	MaxAge           time.Duration `yaml:"maxAge"`
+}
+
+// AuthConfig contains authentication settings
+type AuthConfig struct {
+	JWTSecret        string        `yaml:"jwtSecret"`
+	JWTPublicKeyFile string        `yaml:"jwtPublicKeyFile"`
+	JWTIssuer        string        `yaml:"jwtIssuer"`
+	JWTAudience      string        `yaml:"jwtAudience"`
+	TokenDuration    time.Duration `yaml:"tokenDuration"`
+	OPAEnabled       bool          `yaml:"opaEnabled"`
+	OPAAddr          string        `yaml:"opaAddr"`
+	OPAPolicy        string        `yaml:"opaPolicy"`
+	SkipPaths        []string      `yaml:"skipPaths"`
+}
+
+// CacheConfig specifies caching settings
+type CacheConfig struct {
+	Enabled       bool          `yaml:"enabled"`
+	RedisAddr     string        `yaml:"redisAddr"`
+	RedisPassword string        `yaml:"redisPassword"`
+	RedisDB       int           `yaml:"redisDb"`
+	DefaultTTL    time.Duration `yaml:"defaultTtl"`
+	MaxEntrySize  int           `yaml:"maxEntrySize"`
+	KeyPrefix     string        `yaml:"keyPrefix"`
+}
+
+// ServiceDiscoveryConfig for Consul-based service discovery
+type ServiceDiscoveryConfig struct {
+	Enabled                bool          `yaml:"enabled"`
+	ConsulAddr             string        `yaml:"consulAddr"`
+	ConsulToken            string        `yaml:"consulToken"`
+	ConsulDatacenter       string        `yaml:"consulDatacenter"`
+	ServiceRefreshInterval time.Duration `yaml:"serviceRefreshInterval"`
+	// Direct service addresses (when Consul is disabled)
+	AgentServiceAddr     string `yaml:"agentServiceAddr"`
+	RetrieverServiceAddr string `yaml:"retrieverServiceAddr"`
+	GeneratorServiceAddr string `yaml:"generatorServiceAddr"`
+	MemoryServiceAddr    string `yaml:"memoryServiceAddr"`
+}
+
+// CircuitBreakerConfig for per-service circuit breakers
+type CircuitBreakerConfig struct {
+	MaxRequests      uint32        `yaml:"maxRequests"`
+	Interval         time.Duration `yaml:"interval"`
+	Timeout          time.Duration `yaml:"timeout"`
+	FailureThreshold uint32        `yaml:"failureThreshold"`
+}
+
+// ObservabilityConfig for tracing and metrics
+type ObservabilityConfig struct {
+	MetricsEnabled  bool   `yaml:"metricsEnabled"`
+	MetricsPath     string `yaml:"metricsPath"`
+	TracingEnabled  bool   `yaml:"tracingEnabled"`
+	TracingEndpoint string `yaml:"tracingEndpoint"`
+	ServiceName     string `yaml:"serviceName"`
+	AuditLogEnabled bool   `yaml:"auditLogEnabled"`
+}
+
+// WebSocketConfig for WebSocket connections
+type WebSocketConfig struct {
+	ReadBufferSize  int           `yaml:"readBufferSize"`
+	WriteBufferSize int           `yaml:"writeBufferSize"`
+	PingInterval    time.Duration `yaml:"pingInterval"`
+	PongWait        time.Duration `yaml:"pongWait"`
+	WriteWait       time.Duration `yaml:"writeWait"`
+	MaxMessageSize  int64         `yaml:"maxMessageSize"`
+}
+
+// DefaultConfig returns a configuration with sensible defaults
+func DefaultConfig() *Config {
+	return &Config{
+		Server: ServerConfig{
+			BindAddr:        ":8443",
+			ReadTimeout:     30 * time.Second,
+			WriteTimeout:    60 * time.Second,
+			IdleTimeout:     120 * time.Second,
+			ShutdownTimeout: 30 * time.Second,
+			MaxHeaderBytes:  1 << 20, // 1MB
+			EnableHTTP2:     true,
+		},
+		TLS: TLSConfig{
+			Enabled:    false,
+			MinVersion: "1.2",
+		},
+		RateLimit: RateLimitConfig{
+			Enabled:         true,
+			RequestsPerSec:  100,
+			BurstSize:       200,
+			PerTenant:       true,
+			PerUser:         true,
+			CleanupInterval: 10 * time.Minute,
+		},
+		CORS: CORSConfig{
+			AllowedOrigins:   []string{"*"},
+			AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
+			AllowedHeaders:   []string{"Authorization", "Content-Type", "X-Request-ID", "X-Client-Version"},
+			ExposedHeaders:   []string{"X-Request-ID", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"},
+			AllowCredentials: true,
+			MaxAge:           3600 * time.Second,
+		},
+		Auth: AuthConfig{
+			TokenDuration: 24 * time.Hour,
+			OPAPolicy:     "authz/allow",
+			SkipPaths:     []string{"/admin/health", "/admin/metrics"},
+		},
+		Cache: CacheConfig{
+			Enabled:      true,
+			DefaultTTL:   5 * time.Minute,
+			MaxEntrySize: 1 << 20, // 1MB
+			KeyPrefix:    "rag:gateway:",
+		},
+		ServiceDiscovery: ServiceDiscoveryConfig{
+			ServiceRefreshInterval: 30 * time.Second,
+			AgentServiceAddr:       "localhost:9090",
+			RetrieverServiceAddr:   "localhost:9091",
+			GeneratorServiceAddr:   "localhost:9092",
+			MemoryServiceAddr:      "localhost:9093",
+		},
+		CircuitBreaker: CircuitBreakerConfig{
+			MaxRequests:      5,
+			Interval:         60 * time.Second,
+			Timeout:          30 * time.Second,
+			FailureThreshold: 3,
+		},
+		Observability: ObservabilityConfig{
+			MetricsEnabled:  true,
+			MetricsPath:     "/admin/metrics",
+			TracingEnabled:  true,
+			ServiceName:     "api-gateway",
+			AuditLogEnabled: true,
+		},
+		WebSocket: WebSocketConfig{
+			ReadBufferSize:  1024,
+			WriteBufferSize: 1024,
+			PingInterval:    30 * time.Second,
+			PongWait:        60 * time.Second,
+			WriteWait:       10 * time.Second,
+			MaxMessageSize:  512 * 1024, // 512KB
+		},
+	}
+}

internal/gateway/gateway.go

@@ -0,0 +1,457 @@
+package gateway
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"sync"
+	"syscall"
+
+	"github.com/gorilla/mux"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+
+	gatewaycache "github.com/AmaniQuery/amaniquery/internal/gateway/cache"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/handlers"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// Gateway is the main API Gateway server
+type Gateway struct {
+	config *Config
+	router *mux.Router
+	server *http.Server
+	logger *zap.Logger
+	tracer trace.Tracer
+
+	// Middleware
+	corsMiddleware      *middleware.CORSMiddleware
+	rateLimitMiddleware *middleware.RateLimitMiddleware
+	authMiddleware      *middleware.AuthMiddleware
+	auditMiddleware     *middleware.AuditMiddleware
+	tracingMiddleware   *middleware.TracingMiddleware
+
+	// Services
+	serviceRegistry *services.Registry
+	cacheManager    *gatewaycache.Manager
+
+	// Handlers
+	queryHandler   *handlers.QueryHandler
+	memoryHandler  *handlers.MemoryHandler
+	agentHandler   *handlers.AgentHandler
+	wsHandler      *handlers.WebSocketHandler
+	adminHandler   *handlers.AdminHandler
+	authHandler    *handlers.AuthHandler
+	graphqlHandler *handlers.GraphQLHandler
+
+	// Lifecycle
+	wg       sync.WaitGroup
+	shutdown chan struct{}
+}
+
+// New creates a new Gateway instance
+func New(cfg *Config, logger *zap.Logger) (*Gateway, error) {
+	if cfg == nil {
+		cfg = DefaultConfig()
+	}
+	if logger == nil {
+		var err error
+		logger, err = zap.NewProduction()
+		if err != nil {
+			return nil, fmt.Errorf("failed to create logger: %w", err)
+		}
+	}
+
+	g := &Gateway{
+		config:   cfg,
+		router:   mux.NewRouter(),
+		logger:   logger,
+		tracer:   otel.Tracer(cfg.Observability.ServiceName),
+		shutdown: make(chan struct{}),
+	}
+
+	// Initialize components
+	if err := g.initializeMiddleware(); err != nil {
+		return nil, fmt.Errorf("failed to initialize middleware: %w", err)
+	}
+
+	if err := g.initializeServices(); err != nil {
+		return nil, fmt.Errorf("failed to initialize services: %w", err)
+	}
+
+	if err := g.initializeHandlers(); err != nil {
+		return nil, fmt.Errorf("failed to initialize handlers: %w", err)
+	}
+
+	g.setupRoutes()
+
+	return g, nil
+}
+
+// initializeMiddleware sets up all middleware components
+func (g *Gateway) initializeMiddleware() error {
+	// CORS middleware
+	g.corsMiddleware = middleware.NewCORSMiddleware(middleware.CORSConfig{
+		AllowedOrigins:   g.config.CORS.AllowedOrigins,
+		AllowedMethods:   g.config.CORS.AllowedMethods,
+		AllowedHeaders:   g.config.CORS.AllowedHeaders,
+		ExposedHeaders:   g.config.CORS.ExposedHeaders,
+		AllowCredentials: g.config.CORS.AllowCredentials,
+		MaxAge:           int(g.config.CORS.MaxAge.Seconds()),
+	})
+
+	// Rate limiting middleware
+	if g.config.RateLimit.Enabled {
+		var err error
+		g.rateLimitMiddleware, err = middleware.NewRateLimitMiddleware(middleware.RateLimitConfig{
+			RequestsPerSec:  g.config.RateLimit.RequestsPerSec,
+			BurstSize:       g.config.RateLimit.BurstSize,
+			PerTenant:       g.config.RateLimit.PerTenant,
+			PerUser:         g.config.RateLimit.PerUser,
+			RedisAddr:       g.config.Cache.RedisAddr,
+			RedisEnabled:    g.config.RateLimit.RedisEnabled,
+			CleanupInterval: g.config.RateLimit.CleanupInterval,
+		}, g.logger)
+		if err != nil {
+			return fmt.Errorf("failed to create rate limit middleware: %w", err)
+		}
+	}
+
+	// Auth middleware
+	g.authMiddleware = middleware.NewAuthMiddleware(middleware.AuthConfig{
+		JWTSecret:   g.config.Auth.JWTSecret,
+		JWTIssuer:   g.config.Auth.JWTIssuer,
+		JWTAudience: g.config.Auth.JWTAudience,
+		OPAEnabled:  g.config.Auth.OPAEnabled,
+		OPAAddr:     g.config.Auth.OPAAddr,
+		OPAPolicy:   g.config.Auth.OPAPolicy,
+		SkipPaths:   g.config.Auth.SkipPaths,
+	}, g.logger)
+
+	// Audit middleware
+	if g.config.Observability.AuditLogEnabled {
+		g.auditMiddleware = middleware.NewAuditMiddleware(g.logger)
+	}
+
+	// Tracing middleware
+	if g.config.Observability.TracingEnabled {
+		g.tracingMiddleware = middleware.NewTracingMiddleware(g.tracer)
+	}
+
+	return nil
+}
+
+// initializeServices sets up backend service connections
+func (g *Gateway) initializeServices() error {
+	var err error
+
+	// Service registry
+	g.serviceRegistry, err = services.NewRegistry(services.RegistryConfig{
+		ConsulEnabled:     g.config.ServiceDiscovery.Enabled,
+		ConsulAddr:        g.config.ServiceDiscovery.ConsulAddr,
+		ConsulToken:       g.config.ServiceDiscovery.ConsulToken,
+		RefreshInterval:   g.config.ServiceDiscovery.ServiceRefreshInterval,
+		AgentAddr:         g.config.ServiceDiscovery.AgentServiceAddr,
+		RetrieverAddr:     g.config.ServiceDiscovery.RetrieverServiceAddr,
+		GeneratorAddr:     g.config.ServiceDiscovery.GeneratorServiceAddr,
+		MemoryAddr:        g.config.ServiceDiscovery.MemoryServiceAddr,
+		CircuitBreakerCfg: services.CircuitBreakerConfig{
+			MaxRequests:      g.config.CircuitBreaker.MaxRequests,
+			Interval:         g.config.CircuitBreaker.Interval,
+			Timeout:          g.config.CircuitBreaker.Timeout,
+			FailureThreshold: g.config.CircuitBreaker.FailureThreshold,
+		},
+	}, g.logger)
+	if err != nil {
+		return fmt.Errorf("failed to create service registry: %w", err)
+	}
+
+	// Cache manager
+	if g.config.Cache.Enabled {
+		g.cacheManager, err = gatewaycache.NewManager(gatewaycache.Config{
+			RedisAddr:     g.config.Cache.RedisAddr,
+			RedisPassword: g.config.Cache.RedisPassword,
+			RedisDB:       g.config.Cache.RedisDB,
+			DefaultTTL:    g.config.Cache.DefaultTTL,
+			MaxEntrySize:  g.config.Cache.MaxEntrySize,
+			KeyPrefix:     g.config.Cache.KeyPrefix,
+		}, g.logger)
+		if err != nil {
+			g.logger.Warn("Failed to create cache manager, caching disabled", zap.Error(err))
+		}
+	}
+
+	return nil
+}
+
+// initializeHandlers sets up all request handlers
+func (g *Gateway) initializeHandlers() error {
+	// Query handler
+	g.queryHandler = handlers.NewQueryHandler(
+		g.serviceRegistry,
+		g.cacheManager,
+		g.logger,
+	)
+
+	// Memory handler
+	g.memoryHandler = handlers.NewMemoryHandler(
+		g.serviceRegistry,
+		g.logger,
+	)
+
+	// Agent handler
+	g.agentHandler = handlers.NewAgentHandler(
+		g.serviceRegistry,
+		g.logger,
+	)
+
+	// WebSocket handler
+	g.wsHandler = handlers.NewWebSocketHandler(
+		g.serviceRegistry,
+		gwtypes.WebSocketConfig{
+			ReadBufferSize:  g.config.WebSocket.ReadBufferSize,
+			WriteBufferSize: g.config.WebSocket.WriteBufferSize,
+			PingInterval:    g.config.WebSocket.PingInterval,
+			PongWait:        g.config.WebSocket.PongWait,
+			WriteWait:       g.config.WebSocket.WriteWait,
+			MaxMessageSize:  g.config.WebSocket.MaxMessageSize,
+		},
+		g.logger,
+	)
+
+	// Admin handler
+	g.adminHandler = handlers.NewAdminHandler(
+		g.serviceRegistry,
+		g.logger,
+	)
+
+	// Auth handler
+	g.authHandler = handlers.NewAuthHandler(
+		middleware.AuthConfig{
+			JWTSecret:   g.config.Auth.JWTSecret,
+			JWTIssuer:   g.config.Auth.JWTIssuer,
+			JWTAudience: g.config.Auth.JWTAudience,
+		},
+		g.logger,
+	)
+
+	// GraphQL handler
+	g.graphqlHandler = handlers.NewGraphQLHandler(
+		g.serviceRegistry,
+		g.logger,
+	)
+
+	return nil
+}
+
+// setupRoutes configures all API routes
+func (g *Gateway) setupRoutes() {
+	// Global middleware
+	g.router.Use(middleware.Recovery(g.logger))
+	g.router.Use(middleware.RequestID())
+	g.router.Use(g.corsMiddleware.Handler)
+
+	if g.tracingMiddleware != nil {
+		g.router.Use(g.tracingMiddleware.Handler)
+	}
+
+	// Public routes (no auth required)
+	g.router.HandleFunc("/admin/health", g.adminHandler.HealthCheck).Methods("GET")
+	g.router.Handle("/admin/metrics", promhttp.Handler()).Methods("GET")
+
+	// API v2 routes
+	v2 := g.router.PathPrefix("/v2").Subrouter()
+
+	// Apply rate limiting
+	if g.rateLimitMiddleware != nil {
+		v2.Use(g.rateLimitMiddleware.Handler)
+	}
+
+	// Apply authentication
+	v2.Use(g.authMiddleware.Handler)
+
+	// Apply audit logging
+	if g.auditMiddleware != nil {
+		v2.Use(g.auditMiddleware.Handler)
+	}
+
+	// Query routes
+	queries := v2.PathPrefix("/queries").Subrouter()
+	queries.HandleFunc("", g.queryHandler.ExecuteQuery).Methods("POST")
+	queries.HandleFunc("/stream", g.wsHandler.HandleStream)
+	queries.HandleFunc("/{queryId}", g.queryHandler.GetQueryResult).Methods("GET")
+
+	// Memory routes
+	memory := v2.PathPrefix("/memory").Subrouter()
+	memory.HandleFunc("/context", g.memoryHandler.GetContextWindow).Methods("GET")
+	memory.HandleFunc("/sessions/{sessionId}/consolidate", g.memoryHandler.ConsolidateMemory).Methods("POST")
+
+	// Agent routes
+	agents := v2.PathPrefix("/agents").Subrouter()
+	agents.HandleFunc("", g.agentHandler.CreateAgent).Methods("POST")
+	agents.HandleFunc("/{agentId}", g.agentHandler.GetAgent).Methods("GET")
+	agents.HandleFunc("/{agentId}", g.agentHandler.DeleteAgent).Methods("DELETE")
+	agents.HandleFunc("/{agentId}/execute", g.agentHandler.ExecutePlan).Methods("POST")
+
+	// Auth routes
+	v2.HandleFunc("/auth/token", g.authHandler.Token).Methods("POST")
+
+	// GraphQL route
+	v2.Handle("/graphql", g.graphqlHandler).Methods("POST", "GET")
+
+	// CORS preflight handler
+	g.router.Methods("OPTIONS").HandlerFunc(g.corsMiddleware.HandlePreflight)
+}
+
+// Start starts the gateway server
+func (g *Gateway) Start() error {
+	// Build TLS config if enabled
+	var tlsConfig *tls.Config
+	if g.config.TLS.Enabled {
+		var err error
+		tlsConfig, err = g.buildTLSConfig()
+		if err != nil {
+			return fmt.Errorf("failed to build TLS config: %w", err)
+		}
+	}
+
+	// Create HTTP server
+	g.server = &http.Server{
+		Addr:           g.config.Server.BindAddr,
+		Handler:        g.router,
+		ReadTimeout:    g.config.Server.ReadTimeout,
+		WriteTimeout:   g.config.Server.WriteTimeout,
+		IdleTimeout:    g.config.Server.IdleTimeout,
+		MaxHeaderBytes: g.config.Server.MaxHeaderBytes,
+		TLSConfig:      tlsConfig,
+	}
+
+	// Start server in goroutine
+	g.wg.Add(1)
+	go func() {
+		defer g.wg.Done()
+
+		g.logger.Info("Gateway starting",
+			zap.String("addr", g.config.Server.BindAddr),
+			zap.Bool("tls", g.config.TLS.Enabled),
+		)
+
+		var err error
+		if g.config.TLS.Enabled {
+			err = g.server.ListenAndServeTLS(g.config.TLS.CertFile, g.config.TLS.KeyFile)
+		} else {
+			err = g.server.ListenAndServe()
+		}
+
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			g.logger.Error("Server error", zap.Error(err))
+		}
+	}()
+
+	// Wait for shutdown signal
+	g.handleShutdown()
+
+	return nil
+}
+
+// handleShutdown gracefully stops the server on interrupt signals
+func (g *Gateway) handleShutdown() {
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
+
+	select {
+	case sig := <-sigChan:
+		g.logger.Info("Received shutdown signal", zap.String("signal", sig.String()))
+	case <-g.shutdown:
+		g.logger.Info("Shutdown requested")
+	}
+
+	g.Stop()
+}
+
+// Stop gracefully stops the gateway
+func (g *Gateway) Stop() {
+	ctx, cancel := context.WithTimeout(context.Background(), g.config.Server.ShutdownTimeout)
+	defer cancel()
+
+	g.logger.Info("Shutting down gateway...")
+
+	// Shutdown HTTP server
+	if g.server != nil {
+		if err := g.server.Shutdown(ctx); err != nil {
+			g.logger.Error("Server shutdown error", zap.Error(err))
+		}
+	}
+
+	// Close service connections
+	if g.serviceRegistry != nil {
+		g.serviceRegistry.Close()
+	}
+
+	// Close cache manager
+	if g.cacheManager != nil {
+		g.cacheManager.Close()
+	}
+
+	// Close WebSocket connections
+	if g.wsHandler != nil {
+		g.wsHandler.CloseAll()
+	}
+
+	// Wait for goroutines
+	g.wg.Wait()
+
+	g.logger.Info("Gateway stopped")
+}
+
+// Shutdown requests a graceful shutdown
+func (g *Gateway) Shutdown() {
+	close(g.shutdown)
+}
+
+// buildTLSConfig creates TLS configuration
+func (g *Gateway) buildTLSConfig() (*tls.Config, error) {
+	tlsConfig := &tls.Config{
+		MinVersion: tls.VersionTLS12,
+	}
+
+	// Set minimum TLS version
+	switch g.config.TLS.MinVersion {
+	case "1.2":
+		tlsConfig.MinVersion = tls.VersionTLS12
+	case "1.3":
+		tlsConfig.MinVersion = tls.VersionTLS13
+	}
+
+	// Load client CA if mTLS is required
+	if g.config.TLS.RequireClientCert && g.config.TLS.ClientCAFile != "" {
+		caCert, err := os.ReadFile(g.config.TLS.ClientCAFile)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read client CA file: %w", err)
+		}
+
+		caCertPool := x509.NewCertPool()
+		if !caCertPool.AppendCertsFromPEM(caCert) {
+			return nil, errors.New("failed to parse client CA certificate")
+		}
+
+		tlsConfig.ClientCAs = caCertPool
+		tlsConfig.ClientAuth = tls.RequireAndVerifyClientCert
+	}
+
+	return tlsConfig, nil
+}
+
+// Router returns the underlying router for testing
+func (g *Gateway) Router() *mux.Router {
+	return g.router
+}

internal/gateway/gwtypes/types.go

@@ -0,0 +1,196 @@
+// Package gwtypes provides shared types for the gateway and handlers.
+package gwtypes
+
+import "time"
+
+// WebSocketConfig for WebSocket connections
+type WebSocketConfig struct {
+	ReadBufferSize  int           `yaml:"readBufferSize"`
+	WriteBufferSize int           `yaml:"writeBufferSize"`
+	PingInterval    time.Duration `yaml:"pingInterval"`
+	PongWait        time.Duration `yaml:"pongWait"`
+	WriteWait       time.Duration `yaml:"writeWait"`
+	MaxMessageSize  int64         `yaml:"maxMessageSize"`
+}
+
+// REST API request/response types matching OpenAPI spec
+
+// QueryRequest represents a RAG query request
+type QueryRequest struct {
+	Query     string        `json:"query"`
+	UserID    string        `json:"userId"`
+	SessionID string        `json:"sessionId,omitempty"`
+	AgentID   string        `json:"agentId,omitempty"`
+	Context   *QueryContext `json:"context,omitempty"`
+	Streaming bool          `json:"streaming,omitempty"`
+	Options   *QueryOptions `json:"options,omitempty"`
+}
+
+// QueryContext specifies context retrieval options
+type QueryContext struct {
+	MaxTurns    int      `json:"maxTurns,omitempty"`
+	MemoryTypes []string `json:"memoryTypes,omitempty"`
+}
+
+// QueryOptions specifies query processing options
+type QueryOptions struct {
+	Temperature float64 `json:"temperature,omitempty"`
+	MaxTokens   int     `json:"maxTokens,omitempty"`
+}
+
+// QueryResponse contains the query result
+type QueryResponse struct {
+	QueryID  string            `json:"queryId"`
+	Answer   string            `json:"answer"`
+	Sources  []Source          `json:"sources,omitempty"`
+	Metadata *ResponseMetadata `json:"metadata,omitempty"`
+}
+
+// Source represents a retrieved document source
+type Source struct {
+	DocumentID string            `json:"documentId"`
+	Score      float64           `json:"score"`
+	Content    string            `json:"content"`
+	Metadata   map[string]string `json:"metadata,omitempty"`
+}
+
+// ResponseMetadata contains query processing info
+type ResponseMetadata struct {
+	LatencyMs  int64 `json:"latencyMs"`
+	TokensUsed int   `json:"tokensUsed"`
+	CacheHit   bool  `json:"cacheHit"`
+}
+
+// StreamChunk represents a streaming response chunk
+type StreamChunk struct {
+	Type      string                 `json:"type"` // chunk, sources, metadata, done, error
+	Data      string                 `json:"data,omitempty"`
+	Timestamp string                 `json:"timestamp"`
+	Metadata  map[string]interface{} `json:"metadata,omitempty"`
+}
+
+// CreateAgentRequest for creating new agents
+type CreateAgentRequest struct {
+	Name   string                 `json:"name"`
+	Type   string                 `json:"type"` // rag, agentic, custom
+	Config map[string]interface{} `json:"config,omitempty"`
+}
+
+// Agent represents an agent instance
+type Agent struct {
+	ID        string                 `json:"id"`
+	Name      string                 `json:"name"`
+	Status    string                 `json:"status"` // active, idle, error
+	CreatedAt string                 `json:"createdAt"`
+	Config    map[string]interface{} `json:"config,omitempty"`
+}
+
+// ExecutionPlan for multi-step execution
+type ExecutionPlan struct {
+	ID    string          `json:"id"`
+	Query string          `json:"query"`
+	Steps []ExecutionStep `json:"steps"`
+}
+
+// ExecutionStep represents a single execution step
+type ExecutionStep struct {
+	ID           string   `json:"id"`
+	Type         string   `json:"type"`
+	Description  string   `json:"description"`
+	Tool         string   `json:"tool"`
+	Input        string   `json:"input"`
+	Dependencies []string `json:"dependencies,omitempty"`
+}
+
+// PlanResult contains execution results
+type PlanResult struct {
+	PlanID          string       `json:"planId"`
+	Status          string       `json:"status"`
+	StepResults     []StepResult `json:"stepResults"`
+	FinalAnswer     string       `json:"finalAnswer"`
+	ExecutionTimeMs int64        `json:"executionTimeMs"`
+}
+
+// StepResult contains individual step results
+type StepResult struct {
+	StepID          string `json:"stepId"`
+	Status          string `json:"status"`
+	Output          string `json:"output"`
+	Error           string `json:"error,omitempty"`
+	ExecutionTimeMs int64  `json:"executionTimeMs"`
+}
+
+// ContextWindow represents memory context
+type ContextWindow struct {
+	SessionID   string         `json:"sessionId"`
+	Entries     []ContextEntry `json:"entries"`
+	TotalTokens int            `json:"totalTokens"`
+}
+
+// ContextEntry represents a single context entry
+type ContextEntry struct {
+	ID        string  `json:"id"`
+	Type      string  `json:"type"`
+	Content   string  `json:"content"`
+	Timestamp string  `json:"timestamp"`
+	Score     float64 `json:"score,omitempty"`
+}
+
+// TokenRequest for OAuth2 token endpoint
+type TokenRequest struct {
+	GrantType    string `json:"grant_type" form:"grant_type"`
+	ClientID     string `json:"client_id" form:"client_id"`
+	ClientSecret string `json:"client_secret" form:"client_secret"`
+	Username     string `json:"username,omitempty" form:"username"`
+	Password     string `json:"password,omitempty" form:"password"`
+	RefreshToken string `json:"refresh_token,omitempty" form:"refresh_token"`
+}
+
+// TokenResponse for OAuth2 token response
+type TokenResponse struct {
+	AccessToken  string `json:"access_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int    `json:"expires_in"`
+	RefreshToken string `json:"refresh_token,omitempty"`
+	Scope        string `json:"scope,omitempty"`
+}
+
+// HealthResponse for health check
+type HealthResponse struct {
+	Status    string            `json:"status"`
+	Timestamp string            `json:"timestamp"`
+	Services  map[string]string `json:"services"`
+}
+
+// ErrorResponse for API errors
+type ErrorResponse struct {
+	Error     string `json:"error"`
+	Message   string `json:"message"`
+	Code      string `json:"code,omitempty"`
+	RequestID string `json:"requestId,omitempty"`
+}
+
+// WebSocketMessage represents client WebSocket messages
+type WebSocketMessage struct {
+	Type    string      `json:"type"` // query, ping, cancel
+	Payload interface{} `json:"payload,omitempty"`
+}
+
+// WebSocketQueryPayload for WebSocket query messages
+type WebSocketQueryPayload struct {
+	QueryID   string        `json:"queryId,omitempty"`
+	Query     string        `json:"query"`
+	UserID    string        `json:"userId"`
+	SessionID string        `json:"sessionId,omitempty"`
+	AgentID   string        `json:"agentId,omitempty"`
+	Streaming bool          `json:"streaming"`
+	Options   *QueryOptions `json:"options,omitempty"`
+}
+
+// WebSocketServerMessage represents server WebSocket messages
+type WebSocketServerMessage struct {
+	Type      string                 `json:"type"`
+	Timestamp string                 `json:"timestamp"`
+	Data      interface{}            `json:"data,omitempty"`
+	Metadata  map[string]interface{} `json:"metadata,omitempty"`
+}

internal/gateway/handlers/admin.go

@@ -0,0 +1,93 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// AdminHandler handles admin endpoints
+type AdminHandler struct {
+	registry *services.Registry
+	logger   *zap.Logger
+}
+
+// NewAdminHandler creates a new admin handler
+func NewAdminHandler(registry *services.Registry, logger *zap.Logger) *AdminHandler {
+	return &AdminHandler{
+		registry: registry,
+		logger:   logger,
+	}
+}
+
+// HealthCheck handles GET /admin/health
+func (h *AdminHandler) HealthCheck(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	// Check all backend services
+	serviceStatus := make(map[string]string)
+
+	// Check agent service
+	if h.registry != nil {
+		if _, err := h.registry.GetAgentClient(ctx); err != nil {
+			serviceStatus["agent"] = "unhealthy"
+		} else {
+			status := h.registry.HealthCheck(ctx, "agent")
+			serviceStatus["agent"] = status
+		}
+
+		// Check retriever service
+		if _, err := h.registry.GetRetrieverClient(ctx); err != nil {
+			serviceStatus["retriever"] = "unhealthy"
+		} else {
+			status := h.registry.HealthCheck(ctx, "retriever")
+			serviceStatus["retriever"] = status
+		}
+
+		// Check generator service
+		if _, err := h.registry.GetGeneratorClient(ctx); err != nil {
+			serviceStatus["generator"] = "unhealthy"
+		} else {
+			status := h.registry.HealthCheck(ctx, "generator")
+			serviceStatus["generator"] = status
+		}
+
+		// Check memory service
+		if _, err := h.registry.GetMemoryClient(ctx); err != nil {
+			serviceStatus["memory"] = "unhealthy"
+		} else {
+			status := h.registry.HealthCheck(ctx, "memory")
+			serviceStatus["memory"] = status
+		}
+	}
+
+	// Determine overall status
+	overallStatus := "healthy"
+	for _, status := range serviceStatus {
+		if status != "healthy" && status != "SERVING" {
+			overallStatus = "degraded"
+			break
+		}
+	}
+
+	response := gwtypes.HealthResponse{
+		Status:    overallStatus,
+		Timestamp: time.Now().Format(time.RFC3339),
+		Services:  serviceStatus,
+	}
+
+	// Set status code based on health
+	statusCode := http.StatusOK
+	if overallStatus != "healthy" {
+		statusCode = http.StatusServiceUnavailable
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	json.NewEncoder(w).Encode(response)
+}

internal/gateway/handlers/agent.go

@@ -0,0 +1,270 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/gorilla/mux"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// AgentHandler handles agent-related endpoints
+type AgentHandler struct {
+	registry *services.Registry
+	logger   *zap.Logger
+}
+
+// NewAgentHandler creates a new agent handler
+func NewAgentHandler(registry *services.Registry, logger *zap.Logger) *AgentHandler {
+	return &AgentHandler{
+		registry: registry,
+		logger:   logger,
+	}
+}
+
+// CreateAgent handles POST /v2/agents
+func (h *AgentHandler) CreateAgent(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	// Parse request
+	var req gwtypes.CreateAgentRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		h.errorResponse(w, http.StatusBadRequest, "Invalid request body", err.Error())
+		return
+	}
+
+	// Validate required fields
+	if req.Name == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Agent name is required", "")
+		return
+	}
+	if req.Type == "" {
+		req.Type = "rag" // Default type
+	}
+
+	// Get user info from context
+	userID := middleware.UserIDFromContext(ctx)
+	tenantID := middleware.TenantIDFromContext(ctx)
+
+	// Get agent client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Generate agent ID
+	agentID := uuid.New().String()
+
+	// Create agent
+	agent, err := agentClient.CreateAgent(ctx, &services.CreateAgentRequest{
+		ID:       agentID,
+		Name:     req.Name,
+		Type:     req.Type,
+		Config:   req.Config,
+		UserID:   userID,
+		TenantID: tenantID,
+	})
+	if err != nil {
+		h.logger.Error("Failed to create agent", zap.Error(err))
+		h.errorResponse(w, http.StatusInternalServerError, "Failed to create agent", err.Error())
+		return
+	}
+
+	// Build response
+	response := gwtypes.Agent{
+		ID:        agent.ID,
+		Name:      agent.Name,
+		Status:    agent.Status,
+		CreatedAt: time.Now().Format(time.RFC3339),
+		Config:    agent.Config,
+	}
+
+	h.jsonResponse(w, http.StatusCreated, response)
+}
+
+// GetAgent handles GET /v2/agents/{agentId}
+func (h *AgentHandler) GetAgent(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	vars := mux.Vars(r)
+	agentID := vars["agentId"]
+
+	if agentID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Agent ID is required", "")
+		return
+	}
+
+	// Get agent client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Get agent
+	agent, err := agentClient.GetAgent(ctx, agentID)
+	if err != nil {
+		h.logger.Error("Failed to get agent", zap.Error(err), zap.String("agent_id", agentID))
+		h.errorResponse(w, http.StatusNotFound, "Agent not found", "")
+		return
+	}
+
+	// Build response
+	response := gwtypes.Agent{
+		ID:        agent.ID,
+		Name:      agent.Name,
+		Status:    agent.Status,
+		CreatedAt: agent.CreatedAt,
+		Config:    agent.Config,
+	}
+
+	h.jsonResponse(w, http.StatusOK, response)
+}
+
+// DeleteAgent handles DELETE /v2/agents/{agentId}
+func (h *AgentHandler) DeleteAgent(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	vars := mux.Vars(r)
+	agentID := vars["agentId"]
+
+	if agentID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Agent ID is required", "")
+		return
+	}
+
+	// Get agent client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Delete agent
+	err = agentClient.DeleteAgent(ctx, agentID)
+	if err != nil {
+		h.logger.Error("Failed to delete agent", zap.Error(err), zap.String("agent_id", agentID))
+		h.errorResponse(w, http.StatusInternalServerError, "Failed to delete agent", err.Error())
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// ExecutePlan handles POST /v2/agents/{agentId}/execute
+func (h *AgentHandler) ExecutePlan(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	vars := mux.Vars(r)
+	agentID := vars["agentId"]
+
+	if agentID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Agent ID is required", "")
+		return
+	}
+
+	// Parse request
+	var plan gwtypes.ExecutionPlan
+	if err := json.NewDecoder(r.Body).Decode(&plan); err != nil {
+		h.errorResponse(w, http.StatusBadRequest, "Invalid request body", err.Error())
+		return
+	}
+
+	// Get user info from context
+	userID := middleware.UserIDFromContext(ctx)
+
+	// Get agent client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Generate plan ID if not provided
+	if plan.ID == "" {
+		plan.ID = uuid.New().String()
+	}
+
+	// Execute plan
+	start := time.Now()
+	result, err := agentClient.ExecutePlan(ctx, &services.ExecutePlanRequest{
+		AgentID: agentID,
+		PlanID:  plan.ID,
+		Query:   plan.Query,
+		Steps:   h.convertSteps(plan.Steps),
+		UserID:  userID,
+	})
+	if err != nil {
+		h.logger.Error("Failed to execute plan", zap.Error(err), zap.String("plan_id", plan.ID))
+		h.errorResponse(w, http.StatusInternalServerError, "Plan execution failed", err.Error())
+		return
+	}
+
+	// Build response
+	response := gwtypes.PlanResult{
+		PlanID:          plan.ID,
+		Status:          result.Status,
+		StepResults:     h.convertStepResults(result.StepResults),
+		FinalAnswer:     result.FinalAnswer,
+		ExecutionTimeMs: time.Since(start).Milliseconds(),
+	}
+
+	h.jsonResponse(w, http.StatusOK, response)
+}
+
+func (h *AgentHandler) convertSteps(steps []gwtypes.ExecutionStep) []*services.ExecutionStep {
+	result := make([]*services.ExecutionStep, len(steps))
+	for i, step := range steps {
+		result[i] = &services.ExecutionStep{
+			ID:           step.ID,
+			Type:         step.Type,
+			Description:  step.Description,
+			Tool:         step.Tool,
+			Input:        step.Input,
+			Dependencies: step.Dependencies,
+		}
+	}
+	return result
+}
+
+func (h *AgentHandler) convertStepResults(results []*services.StepResult) []gwtypes.StepResult {
+	converted := make([]gwtypes.StepResult, len(results))
+	for i, r := range results {
+		converted[i] = gwtypes.StepResult{
+			StepID:          r.StepID,
+			Status:          r.Status,
+			Output:          r.Output,
+			Error:           r.Error,
+			ExecutionTimeMs: r.ExecutionTimeMs,
+		}
+	}
+	return converted
+}
+
+func (h *AgentHandler) jsonResponse(w http.ResponseWriter, status int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(data)
+}
+
+func (h *AgentHandler) errorResponse(w http.ResponseWriter, status int, message, detail string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	resp := gwtypes.ErrorResponse{
+		Error:     http.StatusText(status),
+		Message:   message,
+		RequestID: w.Header().Get("X-Request-ID"),
+	}
+	if detail != "" {
+		resp.Code = detail
+	}
+	json.NewEncoder(w).Encode(resp)
+}

internal/gateway/handlers/auth.go

@@ -0,0 +1,115 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+)
+
+// AuthHandler handles authentication endpoints
+type AuthHandler struct {
+	config middleware.AuthConfig
+	logger *zap.Logger
+}
+
+// NewAuthHandler creates a new auth handler
+func NewAuthHandler(cfg middleware.AuthConfig, logger *zap.Logger) *AuthHandler {
+	return &AuthHandler{
+		config: middleware.AuthConfig{
+			JWTSecret:   cfg.JWTSecret,
+			JWTIssuer:   cfg.JWTIssuer,
+			JWTAudience: cfg.JWTAudience,
+		},
+		logger: logger,
+	}
+}
+
+// Token handles POST /v2/auth/token
+func (h *AuthHandler) Token(w http.ResponseWriter, r *http.Request) {
+	if err := r.ParseForm(); err != nil {
+		h.errorResponse(w, http.StatusBadRequest, "Invalid request")
+		return
+	}
+
+	grantType := r.FormValue("grant_type")
+	clientID := r.FormValue("client_id")
+	clientSecret := r.FormValue("client_secret")
+
+	if !h.validateClient(clientID, clientSecret) {
+		h.errorResponse(w, http.StatusUnauthorized, "Invalid client credentials")
+		return
+	}
+
+	switch grantType {
+	case "client_credentials":
+		token, expiresIn, err := h.generateToken(clientID, []string{"service"})
+		if err != nil {
+			h.errorResponse(w, http.StatusInternalServerError, "Token generation failed")
+			return
+		}
+		h.tokenResponse(w, token, "", expiresIn)
+
+	case "password":
+		username := r.FormValue("username")
+		password := r.FormValue("password")
+		if !h.validateUser(username, password) {
+			h.errorResponse(w, http.StatusUnauthorized, "Invalid credentials")
+			return
+		}
+		token, expiresIn, _ := h.generateToken(username, []string{"user"})
+		refresh, _, _ := h.generateToken(username, []string{"refresh"})
+		h.tokenResponse(w, token, refresh, expiresIn)
+
+	default:
+		h.errorResponse(w, http.StatusBadRequest, "Unsupported grant type")
+	}
+}
+
+func (h *AuthHandler) validateClient(id, secret string) bool {
+	return id != "" && secret != ""
+}
+
+func (h *AuthHandler) validateUser(username, password string) bool {
+	return username != "" && password != ""
+}
+
+func (h *AuthHandler) generateToken(subject string, roles []string) (string, int, error) {
+	now := time.Now()
+	expiresIn := 3600
+	claims := &middleware.JWTClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			Issuer:    h.config.JWTIssuer,
+			Subject:   subject,
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(time.Duration(expiresIn) * time.Second)),
+		},
+		UserID: subject,
+		Roles:  roles,
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	tokenString, err := token.SignedString([]byte(h.config.JWTSecret))
+	return tokenString, expiresIn, err
+}
+
+func (h *AuthHandler) tokenResponse(w http.ResponseWriter, access, refresh string, expiresIn int) {
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	json.NewEncoder(w).Encode(gwtypes.TokenResponse{
+		AccessToken:  access,
+		TokenType:    "Bearer",
+		ExpiresIn:    expiresIn,
+		RefreshToken: refresh,
+	})
+}
+
+func (h *AuthHandler) errorResponse(w http.ResponseWriter, status int, message string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(map[string]string{"error": message})
+}

internal/gateway/handlers/graphql.go

@@ -0,0 +1,620 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/google/uuid"
+	graphql "github.com/graph-gophers/graphql-go"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// GraphQL Schema Definition
+const schemaString = `
+	schema {
+		query: Query
+		mutation: Mutation
+	}
+
+	type Query {
+		# Execute a RAG query and get the response
+		query(input: QueryInput!): QueryResponse!
+		
+		# Get a specific query result by ID
+		queryResult(queryId: ID!): QueryResponse
+		
+		# Get an agent by ID
+		agent(id: ID!): Agent
+		
+		# List all agents for the current user
+		agents: [Agent!]!
+		
+		# Get memory context for a session
+		contextWindow(sessionId: ID!, maxTurns: Int): ContextWindow!
+		
+		# Health check
+		health: HealthStatus!
+	}
+
+	type Mutation {
+		# Execute a RAG query
+		executeQuery(input: QueryInput!): QueryResponse!
+		
+		# Create a new agent
+		createAgent(input: CreateAgentInput!): Agent!
+		
+		# Delete an agent
+		deleteAgent(id: ID!): Boolean!
+		
+		# Execute an agent plan
+		executePlan(agentId: ID!, input: ExecutionPlanInput!): PlanResult!
+		
+		# Consolidate memory for a session
+		consolidateMemory(sessionId: ID!): Boolean!
+	}
+
+	input QueryInput {
+		query: String!
+		sessionId: String
+		agentId: String
+		temperature: Float
+		maxTokens: Int
+	}
+
+	input CreateAgentInput {
+		name: String!
+		type: AgentType!
+		systemPrompt: String
+	}
+
+	input ExecutionPlanInput {
+		query: String!
+		steps: [ExecutionStepInput!]
+	}
+
+	input ExecutionStepInput {
+		type: String!
+		description: String!
+		tool: String
+		input: String
+	}
+
+	type QueryResponse {
+		queryId: ID!
+		answer: String!
+		sources: [Source!]!
+		metadata: QueryMetadata!
+	}
+
+	type Source {
+		documentId: ID!
+		score: Float!
+		content: String!
+	}
+
+	type QueryMetadata {
+		latencyMs: Int!
+		tokensUsed: Int!
+		cacheHit: Boolean!
+	}
+
+	type Agent {
+		id: ID!
+		name: String!
+		type: AgentType!
+		status: AgentStatus!
+		createdAt: String!
+	}
+
+	enum AgentType {
+		RAG
+		AGENTIC
+		CUSTOM
+	}
+
+	enum AgentStatus {
+		ACTIVE
+		IDLE
+		ERROR
+	}
+
+	type PlanResult {
+		planId: ID!
+		status: String!
+		finalAnswer: String!
+		executionTimeMs: Int!
+		stepResults: [StepResult!]!
+	}
+
+	type StepResult {
+		stepId: ID!
+		status: String!
+		output: String!
+		error: String
+	}
+
+	type ContextWindow {
+		sessionId: ID!
+		entries: [ContextEntry!]!
+		totalTokens: Int!
+	}
+
+	type ContextEntry {
+		id: ID!
+		type: String!
+		content: String!
+		timestamp: String!
+		score: Float
+	}
+
+	type HealthStatus {
+		status: String!
+		timestamp: String!
+		services: [ServiceHealth!]!
+	}
+
+	type ServiceHealth {
+		name: String!
+		status: String!
+	}
+`
+
+// GraphQLHandler handles GraphQL requests
+type GraphQLHandler struct {
+	schema   *graphql.Schema
+	registry *services.Registry
+	logger   *zap.Logger
+}
+
+// NewGraphQLHandler creates a new GraphQL handler
+func NewGraphQLHandler(registry *services.Registry, logger *zap.Logger) *GraphQLHandler {
+	resolver := &Resolver{
+		registry: registry,
+		logger:   logger,
+	}
+
+	schema := graphql.MustParseSchema(schemaString, resolver,
+		graphql.UseFieldResolvers(),
+		graphql.MaxParallelism(20),
+	)
+
+	return &GraphQLHandler{
+		schema:   schema,
+		registry: registry,
+		logger:   logger,
+	}
+}
+
+// ServeHTTP implements http.Handler for GraphQL
+func (h *GraphQLHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	var params struct {
+		Query         string                 `json:"query"`
+		OperationName string                 `json:"operationName"`
+		Variables     map[string]interface{} `json:"variables"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&params); err != nil {
+		h.errorResponse(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	ctx := r.Context()
+	response := h.schema.Exec(ctx, params.Query, params.OperationName, params.Variables)
+
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		h.logger.Error("Failed to encode GraphQL response", zap.Error(err))
+	}
+}
+
+func (h *GraphQLHandler) errorResponse(w http.ResponseWriter, message string, status int) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(map[string]interface{}{
+		"errors": []map[string]string{{"message": message}},
+	})
+}
+
+// Resolver implements GraphQL resolvers
+type Resolver struct {
+	registry *services.Registry
+	logger   *zap.Logger
+}
+
+// Query resolvers
+
+func (r *Resolver) Query(ctx context.Context, args struct{ Input QueryInputArgs }) (*QueryResponseResolver, error) {
+	return r.ExecuteQuery(ctx, args)
+}
+
+func (r *Resolver) QueryResult(ctx context.Context, args struct{ QueryId graphql.ID }) (*QueryResponseResolver, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	status, err := agentClient.GetQueryStatus(ctx, string(args.QueryId))
+	if err != nil {
+		return nil, err
+	}
+
+	return &QueryResponseResolver{
+		queryId: string(args.QueryId),
+		answer:  status.Status,
+	}, nil
+}
+
+func (r *Resolver) Agent(ctx context.Context, args struct{ Id graphql.ID }) (*AgentResolver, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	agent, err := agentClient.GetAgent(ctx, string(args.Id))
+	if err != nil {
+		return nil, err
+	}
+
+	return &AgentResolver{agent: agent}, nil
+}
+
+func (r *Resolver) Agents(ctx context.Context) ([]*AgentResolver, error) {
+	// Return empty list - would query user's agents
+	return []*AgentResolver{}, nil
+}
+
+func (r *Resolver) ContextWindow(ctx context.Context, args struct {
+	SessionId graphql.ID
+	MaxTurns  *int32
+}) (*ContextWindowResolver, error) {
+	memoryClient, err := r.registry.GetMemoryClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	maxTurns := 50
+	if args.MaxTurns != nil {
+		maxTurns = int(*args.MaxTurns)
+	}
+
+	userID := middleware.UserIDFromContext(ctx)
+	window, err := memoryClient.GetContextWindow(ctx, &services.ContextWindowRequest{
+		SessionID: string(args.SessionId),
+		UserID:    userID,
+		MaxTurns:  maxTurns,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return &ContextWindowResolver{
+		sessionId: string(args.SessionId),
+		window:    window,
+	}, nil
+}
+
+func (r *Resolver) Health(ctx context.Context) (*HealthStatusResolver, error) {
+	serviceStatuses := []ServiceHealthResolver{}
+
+	for _, svc := range []string{"agent", "retriever", "generator", "memory"} {
+		status := r.registry.HealthCheck(ctx, svc)
+		serviceStatuses = append(serviceStatuses, ServiceHealthResolver{
+			name:   svc,
+			status: status,
+		})
+	}
+
+	return &HealthStatusResolver{
+		status:    "healthy",
+		timestamp: time.Now().Format(time.RFC3339),
+		services:  serviceStatuses,
+	}, nil
+}
+
+// Mutation resolvers
+
+func (r *Resolver) ExecuteQuery(ctx context.Context, args struct{ Input QueryInputArgs }) (*QueryResponseResolver, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	userID := middleware.UserIDFromContext(ctx)
+	queryID := uuid.New().String()
+
+	req := &services.QueryRequest{
+		QueryID:   queryID,
+		Query:     args.Input.Query,
+		UserID:    userID,
+		SessionID: stringVal(args.Input.SessionId),
+		AgentID:   stringVal(args.Input.AgentId),
+	}
+
+	if args.Input.Temperature != nil {
+		req.Temperature = *args.Input.Temperature
+	}
+	if args.Input.MaxTokens != nil {
+		req.MaxTokens = int(*args.Input.MaxTokens)
+	}
+
+	resp, err := agentClient.ProcessQuery(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+
+	sources := make([]SourceResolver, len(resp.Sources))
+	for i, src := range resp.Sources {
+		sources[i] = SourceResolver{
+			documentId: src.ID,
+			score:      src.Score,
+			content:    src.Content,
+		}
+	}
+
+	return &QueryResponseResolver{
+		queryId:    queryID,
+		answer:     resp.Answer,
+		sources:    sources,
+		tokensUsed: resp.TokensUsed,
+	}, nil
+}
+
+func (r *Resolver) CreateAgent(ctx context.Context, args struct{ Input CreateAgentInputArgs }) (*AgentResolver, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	userID := middleware.UserIDFromContext(ctx)
+	tenantID := middleware.TenantIDFromContext(ctx)
+
+	agent, err := agentClient.CreateAgent(ctx, &services.CreateAgentRequest{
+		ID:       uuid.New().String(),
+		Name:     args.Input.Name,
+		Type:     string(args.Input.Type),
+		UserID:   userID,
+		TenantID: tenantID,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return &AgentResolver{agent: agent}, nil
+}
+
+func (r *Resolver) DeleteAgent(ctx context.Context, args struct{ Id graphql.ID }) (bool, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return false, err
+	}
+
+	err = agentClient.DeleteAgent(ctx, string(args.Id))
+	return err == nil, err
+}
+
+func (r *Resolver) ExecutePlan(ctx context.Context, args struct {
+	AgentId graphql.ID
+	Input   ExecutionPlanInputArgs
+}) (*PlanResultResolver, error) {
+	agentClient, err := r.registry.GetAgentClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	userID := middleware.UserIDFromContext(ctx)
+	planID := uuid.New().String()
+
+	steps := make([]*services.ExecutionStep, len(args.Input.Steps))
+	for i, s := range args.Input.Steps {
+		steps[i] = &services.ExecutionStep{
+			ID:          uuid.New().String(),
+			Type:        s.Type,
+			Description: s.Description,
+			Tool:        stringVal(s.Tool),
+			Input:       stringVal(s.Input),
+		}
+	}
+
+	result, err := agentClient.ExecutePlan(ctx, &services.ExecutePlanRequest{
+		AgentID: string(args.AgentId),
+		PlanID:  planID,
+		Query:   args.Input.Query,
+		Steps:   steps,
+		UserID:  userID,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	stepResults := make([]StepResultResolver, len(result.StepResults))
+	for i, sr := range result.StepResults {
+		stepResults[i] = StepResultResolver{
+			stepId: sr.StepID,
+			status: sr.Status,
+			output: sr.Output,
+			err:    sr.Error,
+		}
+	}
+
+	return &PlanResultResolver{
+		planId:      planID,
+		status:      result.Status,
+		finalAnswer: result.FinalAnswer,
+		stepResults: stepResults,
+	}, nil
+}
+
+func (r *Resolver) ConsolidateMemory(ctx context.Context, args struct{ SessionId graphql.ID }) (bool, error) {
+	memoryClient, err := r.registry.GetMemoryClient(ctx)
+	if err != nil {
+		return false, err
+	}
+
+	userID := middleware.UserIDFromContext(ctx)
+	err = memoryClient.ConsolidateMemory(ctx, &services.ConsolidateRequest{
+		SessionID: string(args.SessionId),
+		UserID:    userID,
+	})
+	return err == nil, err
+}
+
+// Input args types
+
+type QueryInputArgs struct {
+	Query       string
+	SessionId   *string
+	AgentId     *string
+	Temperature *float64
+	MaxTokens   *int32
+}
+
+type CreateAgentInputArgs struct {
+	Name         string
+	Type         string
+	SystemPrompt *string
+}
+
+type ExecutionPlanInputArgs struct {
+	Query string
+	Steps []ExecutionStepInputArgs
+}
+
+type ExecutionStepInputArgs struct {
+	Type        string
+	Description string
+	Tool        *string
+	Input       *string
+}
+
+// Resolver types
+
+type QueryResponseResolver struct {
+	queryId    string
+	answer     string
+	sources    []SourceResolver
+	tokensUsed int
+}
+
+func (r *QueryResponseResolver) QueryId() graphql.ID { return graphql.ID(r.queryId) }
+func (r *QueryResponseResolver) Answer() string      { return r.answer }
+func (r *QueryResponseResolver) Sources() []SourceResolver {
+	return r.sources
+}
+func (r *QueryResponseResolver) Metadata() *QueryMetadataResolver {
+	return &QueryMetadataResolver{latencyMs: 100, tokensUsed: r.tokensUsed}
+}
+
+type SourceResolver struct {
+	documentId string
+	score      float64
+	content    string
+}
+
+func (r SourceResolver) DocumentId() graphql.ID { return graphql.ID(r.documentId) }
+func (r SourceResolver) Score() float64         { return r.score }
+func (r SourceResolver) Content() string        { return r.content }
+
+type QueryMetadataResolver struct {
+	latencyMs  int
+	tokensUsed int
+}
+
+func (r *QueryMetadataResolver) LatencyMs() int32  { return int32(r.latencyMs) }
+func (r *QueryMetadataResolver) TokensUsed() int32 { return int32(r.tokensUsed) }
+func (r *QueryMetadataResolver) CacheHit() bool    { return false }
+
+type AgentResolver struct {
+	agent *services.AgentInfo
+}
+
+func (r *AgentResolver) Id() graphql.ID    { return graphql.ID(r.agent.ID) }
+func (r *AgentResolver) Name() string      { return r.agent.Name }
+func (r *AgentResolver) Type() string      { return "RAG" }
+func (r *AgentResolver) Status() string    { return r.agent.Status }
+func (r *AgentResolver) CreatedAt() string { return r.agent.CreatedAt }
+
+type PlanResultResolver struct {
+	planId      string
+	status      string
+	finalAnswer string
+	stepResults []StepResultResolver
+}
+
+func (r *PlanResultResolver) PlanId() graphql.ID                { return graphql.ID(r.planId) }
+func (r *PlanResultResolver) Status() string                    { return r.status }
+func (r *PlanResultResolver) FinalAnswer() string               { return r.finalAnswer }
+func (r *PlanResultResolver) ExecutionTimeMs() int32            { return 1000 }
+func (r *PlanResultResolver) StepResults() []StepResultResolver { return r.stepResults }
+
+type StepResultResolver struct {
+	stepId string
+	status string
+	output string
+	err    string
+}
+
+func (r StepResultResolver) StepId() graphql.ID { return graphql.ID(r.stepId) }
+func (r StepResultResolver) Status() string     { return r.status }
+func (r StepResultResolver) Output() string     { return r.output }
+func (r StepResultResolver) Error() *string {
+	if r.err == "" {
+		return nil
+	}
+	return &r.err
+}
+
+type ContextWindowResolver struct {
+	sessionId string
+	window    *services.ContextWindowResponse
+}
+
+func (r *ContextWindowResolver) SessionId() graphql.ID { return graphql.ID(r.sessionId) }
+func (r *ContextWindowResolver) TotalTokens() int32    { return int32(r.window.TotalTokens) }
+func (r *ContextWindowResolver) Entries() []ContextEntryResolver {
+	entries := make([]ContextEntryResolver, len(r.window.Entries))
+	for i, e := range r.window.Entries {
+		entries[i] = ContextEntryResolver{entry: e}
+	}
+	return entries
+}
+
+type ContextEntryResolver struct {
+	entry *services.ContextEntry
+}
+
+func (r ContextEntryResolver) Id() graphql.ID    { return graphql.ID(r.entry.ID) }
+func (r ContextEntryResolver) Type() string      { return r.entry.Type }
+func (r ContextEntryResolver) Content() string   { return r.entry.Content }
+func (r ContextEntryResolver) Timestamp() string { return r.entry.Timestamp }
+func (r ContextEntryResolver) Score() *float64   { return &r.entry.Score }
+
+type HealthStatusResolver struct {
+	status    string
+	timestamp string
+	services  []ServiceHealthResolver
+}
+
+func (r *HealthStatusResolver) Status() string                    { return r.status }
+func (r *HealthStatusResolver) Timestamp() string                 { return r.timestamp }
+func (r *HealthStatusResolver) Services() []ServiceHealthResolver { return r.services }
+
+type ServiceHealthResolver struct {
+	name   string
+	status string
+}
+
+func (r ServiceHealthResolver) Name() string   { return r.name }
+func (r ServiceHealthResolver) Status() string { return r.status }
+
+// Helper functions
+func stringVal(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}

internal/gateway/handlers/handlers_test.go

@@ -0,0 +1,292 @@
+package handlers_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"go.uber.org/zap"
+)
+
+// TestQueryRequest_JSONParsing tests JSON parsing of query requests
+func TestQueryRequest_JSONParsing(t *testing.T) {
+	jsonData := `{
+		"query": "What is negligence in tort law?",
+		"userId": "user-123",
+		"sessionId": "session-456"
+	}`
+
+	var req gwtypes.QueryRequest
+	err := json.Unmarshal([]byte(jsonData), &req)
+	if err != nil {
+		t.Fatalf("Failed to parse JSON: %v", err)
+	}
+
+	if req.Query != "What is negligence in tort law?" {
+		t.Errorf("Query mismatch: got '%s'", req.Query)
+	}
+	if req.UserID != "user-123" {
+		t.Errorf("UserID mismatch: got '%s'", req.UserID)
+	}
+}
+
+// TestQueryResponse_JSONSerialization tests JSON serialization of query responses
+func TestQueryResponse_JSONSerialization(t *testing.T) {
+	resp := gwtypes.QueryResponse{
+		QueryID: "query-123",
+		Answer:  "Negligence is a failure to exercise reasonable care.",
+		Sources: []gwtypes.Source{
+			{
+				DocumentID: "doc-1",
+				Score:      0.95,
+				Content:    "Source content",
+			},
+		},
+		Metadata: &gwtypes.ResponseMetadata{
+			LatencyMs:  150,
+			TokensUsed: 200,
+			CacheHit:   false,
+		},
+	}
+
+	data, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatalf("Failed to serialize JSON: %v", err)
+	}
+
+	if len(data) == 0 {
+		t.Error("Expected non-empty JSON")
+	}
+
+	// Verify round-trip
+	var parsed gwtypes.QueryResponse
+	err = json.Unmarshal(data, &parsed)
+	if err != nil {
+		t.Fatalf("Failed to parse serialized JSON: %v", err)
+	}
+
+	if parsed.QueryID != resp.QueryID {
+		t.Error("QueryID mismatch after round-trip")
+	}
+}
+
+// TestErrorResponse_Structure tests error response structure
+func TestErrorResponse_Structure(t *testing.T) {
+	resp := gwtypes.ErrorResponse{
+		Error:     "Bad Request",
+		Message:   "Query is required",
+		Code:      "VALIDATION_ERROR",
+		RequestID: "req-123",
+	}
+
+	data, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatalf("Failed to serialize: %v", err)
+	}
+
+	if len(data) == 0 {
+		t.Error("Expected non-empty JSON")
+	}
+}
+
+// TestSource_Structure tests source structure
+func TestSource_Structure(t *testing.T) {
+	source := gwtypes.Source{
+		DocumentID: "doc-123",
+		Score:      0.87,
+		Content:    "This is the source content.",
+		Metadata: map[string]string{
+			"author": "John Doe",
+			"date":   "2024-01-15",
+		},
+	}
+
+	if source.DocumentID != "doc-123" {
+		t.Error("DocumentID mismatch")
+	}
+	if source.Score != 0.87 {
+		t.Error("Score mismatch")
+	}
+	if source.Metadata["author"] != "John Doe" {
+		t.Error("Metadata mismatch")
+	}
+}
+
+// TestQueryRequest_EmptyValidation tests that empty query is detected
+func TestQueryRequest_EmptyValidation(t *testing.T) {
+	req := gwtypes.QueryRequest{
+		Query:  "",
+		UserID: "user-123",
+	}
+
+	if req.Query != "" {
+		t.Error("Query should be empty for this test")
+	}
+
+	// This simulates what the handler would check
+	isValid := req.Query != ""
+	if isValid {
+		t.Error("Empty query should be invalid")
+	}
+}
+
+// TestResponseMetadata_Structure tests response metadata
+func TestResponseMetadata_Structure(t *testing.T) {
+	meta := gwtypes.ResponseMetadata{
+		LatencyMs:  250,
+		TokensUsed: 1500,
+		CacheHit:   true,
+	}
+
+	if meta.LatencyMs != 250 {
+		t.Error("LatencyMs mismatch")
+	}
+	if meta.TokensUsed != 1500 {
+		t.Error("TokensUsed mismatch")
+	}
+	if !meta.CacheHit {
+		t.Error("CacheHit should be true")
+	}
+}
+
+// TestHTTPStatusCodes tests status codes are correctly used
+func TestHTTPStatusCodes(t *testing.T) {
+	testCases := []struct {
+		name     string
+		status   int
+		expected string
+	}{
+		{"OK", http.StatusOK, "OK"},
+		{"BadRequest", http.StatusBadRequest, "Bad Request"},
+		{"NotFound", http.StatusNotFound, "Not Found"},
+		{"ServiceUnavailable", http.StatusServiceUnavailable, "Service Unavailable"},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			text := http.StatusText(tc.status)
+			if text != tc.expected {
+				t.Errorf("Expected '%s', got '%s'", tc.expected, text)
+			}
+		})
+	}
+}
+
+// TestJSONContentType tests content type header
+func TestJSONContentType(t *testing.T) {
+	rec := httptest.NewRecorder()
+	rec.Header().Set("Content-Type", "application/json")
+
+	if rec.Header().Get("Content-Type") != "application/json" {
+		t.Error("Content-Type header not set correctly")
+	}
+}
+
+// TestQueryOptionsDefaults tests query options defaults
+func TestQueryOptionsDefaults(t *testing.T) {
+	opts := gwtypes.QueryOptions{
+		Temperature: 0.7,
+		MaxTokens:   4096,
+	}
+
+	if opts.Temperature != 0.7 {
+		t.Errorf("Temperature mismatch: got %f", opts.Temperature)
+	}
+	if opts.MaxTokens != 4096 {
+		t.Errorf("MaxTokens mismatch: got %d", opts.MaxTokens)
+	}
+}
+
+// TestQueryContext tests query context options
+func TestQueryContext(t *testing.T) {
+	ctx := gwtypes.QueryContext{
+		MaxTurns:    5,
+		MemoryTypes: []string{"semantic", "episodic"},
+	}
+
+	if ctx.MaxTurns != 5 {
+		t.Error("MaxTurns mismatch")
+	}
+	if len(ctx.MemoryTypes) != 2 {
+		t.Error("MemoryTypes length mismatch")
+	}
+}
+
+// MockHandler for testing HTTP handling patterns
+type MockHandler struct {
+	logger *zap.Logger
+}
+
+func (h *MockHandler) jsonResponse(w http.ResponseWriter, status int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(data)
+}
+
+// TestMockHandler_JSONResponse tests JSON response helper
+func TestMockHandler_JSONResponse(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	h := &MockHandler{logger: logger}
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	rec := httptest.NewRecorder()
+
+	h.jsonResponse(rec, http.StatusOK, map[string]string{"status": "ok"})
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("Expected status %d, got %d", http.StatusOK, rec.Code)
+	}
+
+	if rec.Header().Get("Content-Type") != "application/json" {
+		t.Error("Expected JSON content type")
+	}
+	_ = req
+}
+
+// TestRequestParsing tests request body parsing
+func TestRequestParsing(t *testing.T) {
+	body := bytes.NewBufferString(`{"query": "test query"}`)
+	req := httptest.NewRequest(http.MethodPost, "/query", body)
+	req.Header.Set("Content-Type", "application/json")
+
+	var parsed gwtypes.QueryRequest
+	err := json.NewDecoder(req.Body).Decode(&parsed)
+	if err != nil {
+		t.Fatalf("Failed to decode: %v", err)
+	}
+
+	if parsed.Query != "test query" {
+		t.Errorf("Query mismatch: got '%s'", parsed.Query)
+	}
+}
+
+// BenchmarkJSONMarshal benchmarks JSON marshaling
+func BenchmarkJSONMarshal(b *testing.B) {
+	resp := gwtypes.QueryResponse{
+		QueryID: "query-123",
+		Answer:  "This is a test answer with some content.",
+		Sources: []gwtypes.Source{
+			{DocumentID: "doc-1", Score: 0.9, Content: "Content 1"},
+			{DocumentID: "doc-2", Score: 0.8, Content: "Content 2"},
+		},
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		json.Marshal(resp)
+	}
+}
+
+// BenchmarkJSONUnmarshal benchmarks JSON unmarshaling
+func BenchmarkJSONUnmarshal(b *testing.B) {
+	data := []byte(`{"query": "test query", "userId": "user-123", "sessionId": "session-456"}`)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		var req gwtypes.QueryRequest
+		json.Unmarshal(data, &req)
+	}
+}

internal/gateway/handlers/memory.go

@@ -0,0 +1,152 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+
+	"github.com/gorilla/mux"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// MemoryHandler handles memory-related endpoints
+type MemoryHandler struct {
+	registry *services.Registry
+	logger   *zap.Logger
+}
+
+// NewMemoryHandler creates a new memory handler
+func NewMemoryHandler(registry *services.Registry, logger *zap.Logger) *MemoryHandler {
+	return &MemoryHandler{
+		registry: registry,
+		logger:   logger,
+	}
+}
+
+// GetContextWindow handles GET /v2/memory/context
+func (h *MemoryHandler) GetContextWindow(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	// Get session ID from query params
+	sessionID := r.URL.Query().Get("sessionId")
+	if sessionID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Session ID is required", "")
+		return
+	}
+
+	// Get max turns
+	maxTurns := 50
+	if mt := r.URL.Query().Get("maxTurns"); mt != "" {
+		if parsed, err := strconv.Atoi(mt); err == nil && parsed > 0 {
+			maxTurns = parsed
+		}
+	}
+
+	// Get user ID from context
+	userID := middleware.UserIDFromContext(ctx)
+
+	// Get memory client
+	memoryClient, err := h.registry.GetMemoryClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get memory client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Get context window from memory service
+	contextWindow, err := memoryClient.GetContextWindow(ctx, &services.ContextWindowRequest{
+		SessionID: sessionID,
+		UserID:    userID,
+		MaxTurns:  maxTurns,
+	})
+	if err != nil {
+		h.logger.Error("Failed to get context window", zap.Error(err))
+		h.errorResponse(w, http.StatusInternalServerError, "Failed to retrieve context", err.Error())
+		return
+	}
+
+	// Build response
+	response := gwtypes.ContextWindow{
+		SessionID:   sessionID,
+		Entries:     make([]gwtypes.ContextEntry, len(contextWindow.Entries)),
+		TotalTokens: contextWindow.TotalTokens,
+	}
+
+	for i, entry := range contextWindow.Entries {
+		response.Entries[i] = gwtypes.ContextEntry{
+			ID:        entry.ID,
+			Type:      entry.Type,
+			Content:   entry.Content,
+			Timestamp: entry.Timestamp,
+			Score:     entry.Score,
+		}
+	}
+
+	h.jsonResponse(w, http.StatusOK, response)
+}
+
+// ConsolidateMemory handles POST /v2/memory/sessions/{sessionId}/consolidate
+func (h *MemoryHandler) ConsolidateMemory(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	vars := mux.Vars(r)
+	sessionID := vars["sessionId"]
+
+	if sessionID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Session ID is required", "")
+		return
+	}
+
+	// Get user ID from context
+	userID := middleware.UserIDFromContext(ctx)
+
+	// Get memory client
+	memoryClient, err := h.registry.GetMemoryClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get memory client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Trigger consolidation
+	err = memoryClient.ConsolidateMemory(ctx, &services.ConsolidateRequest{
+		SessionID: sessionID,
+		UserID:    userID,
+	})
+	if err != nil {
+		h.logger.Error("Failed to consolidate memory", zap.Error(err))
+		h.errorResponse(w, http.StatusInternalServerError, "Consolidation failed", err.Error())
+		return
+	}
+
+	// Return 202 Accepted
+	w.WriteHeader(http.StatusAccepted)
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":    "accepted",
+		"sessionId": sessionID,
+		"message":   "Memory consolidation started",
+	})
+}
+
+func (h *MemoryHandler) jsonResponse(w http.ResponseWriter, status int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(data)
+}
+
+func (h *MemoryHandler) errorResponse(w http.ResponseWriter, status int, message, detail string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	resp := gwtypes.ErrorResponse{
+		Error:     http.StatusText(status),
+		Message:   message,
+		RequestID: w.Header().Get("X-Request-ID"),
+	}
+	if detail != "" {
+		resp.Code = detail
+	}
+	json.NewEncoder(w).Encode(resp)
+}

internal/gateway/handlers/query.go

@@ -0,0 +1,224 @@
+// Package handlers provides HTTP request handlers for the API Gateway.
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/gorilla/mux"
+	"go.uber.org/zap"
+
+	gatewaycache "github.com/AmaniQuery/amaniquery/internal/gateway/cache"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// Ensure context package is used for request handling
+var _ context.Context
+
+// QueryHandler handles query-related endpoints
+type QueryHandler struct {
+	registry *services.Registry
+	cache    *gatewaycache.Manager
+	logger   *zap.Logger
+}
+
+// NewQueryHandler creates a new query handler
+func NewQueryHandler(registry *services.Registry, cache *gatewaycache.Manager, logger *zap.Logger) *QueryHandler {
+	return &QueryHandler{
+		registry: registry,
+		cache:    cache,
+		logger:   logger,
+	}
+}
+
+// ExecuteQuery handles POST /v2/queries
+func (h *QueryHandler) ExecuteQuery(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	start := time.Now()
+
+	// Parse request
+	var req gwtypes.QueryRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		h.errorResponse(w, http.StatusBadRequest, "Invalid request body", err.Error())
+		return
+	}
+
+	// Validate required fields
+	if req.Query == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Query is required", "")
+		return
+	}
+
+	// Get user info from context
+	userID := middleware.UserIDFromContext(ctx)
+	if req.UserID == "" {
+		req.UserID = userID
+	}
+
+	// Generate query ID
+	queryID := uuid.New().String()
+
+	// Check cache first
+	if h.cache != nil && !req.Streaming {
+		if cached, found := h.cache.Get(ctx, h.cacheKey(&req)); found {
+			w.Header().Set("X-Cache-Hit", "true")
+			h.jsonResponse(w, http.StatusOK, cached)
+			return
+		}
+	}
+
+	// Get agent service client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Execute query via gRPC
+	grpcReq := h.toGRPCRequest(&req, queryID)
+	grpcResp, err := agentClient.ProcessQuery(ctx, grpcReq)
+	if err != nil {
+		h.logger.Error("Query execution failed", zap.Error(err), zap.String("query_id", queryID))
+		h.errorResponse(w, http.StatusInternalServerError, "Query execution failed", err.Error())
+		return
+	}
+
+	// Build response
+	response := h.fromGRPCResponse(grpcResp, queryID, start)
+
+	// Cache response
+	if h.cache != nil && !req.Streaming {
+		h.cache.Set(ctx, h.cacheKey(&req), response, h.cacheTTL(&req))
+	}
+
+	w.Header().Set("X-Cache-Hit", "false")
+	h.jsonResponse(w, http.StatusOK, response)
+}
+
+// GetQueryResult handles GET /v2/queries/{queryId}
+func (h *QueryHandler) GetQueryResult(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	vars := mux.Vars(r)
+	queryID := vars["queryId"]
+
+	if queryID == "" {
+		h.errorResponse(w, http.StatusBadRequest, "Query ID is required", "")
+		return
+	}
+
+	// Get agent service client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.errorResponse(w, http.StatusServiceUnavailable, "Service unavailable", "")
+		return
+	}
+
+	// Check query status
+	status, err := agentClient.GetQueryStatus(ctx, queryID)
+	if err != nil {
+		h.logger.Error("Failed to get query status", zap.Error(err), zap.String("query_id", queryID))
+		h.errorResponse(w, http.StatusNotFound, "Query not found", "")
+		return
+	}
+
+	// If still processing, return 202
+	if status.Status == "processing" {
+		w.Header().Set("Retry-After", "5")
+		h.jsonResponse(w, http.StatusAccepted, map[string]interface{}{
+			"queryId":  queryID,
+			"status":   status.Status,
+			"progress": status.Progress,
+		})
+		return
+	}
+
+	// Return result
+	h.jsonResponse(w, http.StatusOK, status.Result)
+}
+
+func (h *QueryHandler) cacheKey(req *gwtypes.QueryRequest) string {
+	return req.Query + ":" + req.UserID
+}
+
+func (h *QueryHandler) cacheTTL(req *gwtypes.QueryRequest) time.Duration {
+	if req.Streaming {
+		return 30 * time.Second
+	}
+	if len(req.Query) < 100 {
+		return 5 * time.Minute
+	}
+	return 2 * time.Minute
+}
+
+func (h *QueryHandler) toGRPCRequest(req *gwtypes.QueryRequest, queryID string) *services.QueryRequest {
+	grpcReq := &services.QueryRequest{
+		QueryID:   queryID,
+		Query:     req.Query,
+		UserID:    req.UserID,
+		SessionID: req.SessionID,
+		AgentID:   req.AgentID,
+	}
+
+	if req.Options != nil {
+		grpcReq.Temperature = req.Options.Temperature
+		grpcReq.MaxTokens = req.Options.MaxTokens
+	}
+
+	if req.Context != nil {
+		grpcReq.MaxTurns = req.Context.MaxTurns
+		grpcReq.MemoryTypes = req.Context.MemoryTypes
+	}
+
+	return grpcReq
+}
+
+func (h *QueryHandler) fromGRPCResponse(resp *services.QueryResponse, queryID string, start time.Time) *gwtypes.QueryResponse {
+	response := &gwtypes.QueryResponse{
+		QueryID: queryID,
+		Answer:  resp.Answer,
+		Sources: make([]gwtypes.Source, len(resp.Sources)),
+		Metadata: &gwtypes.ResponseMetadata{
+			LatencyMs:  time.Since(start).Milliseconds(),
+			TokensUsed: resp.TokensUsed,
+			CacheHit:   false,
+		},
+	}
+
+	for i, src := range resp.Sources {
+		response.Sources[i] = gwtypes.Source{
+			DocumentID: src.ID,
+			Score:      src.Score,
+			Content:    src.Content,
+			Metadata:   src.Metadata,
+		}
+	}
+
+	return response
+}
+
+func (h *QueryHandler) jsonResponse(w http.ResponseWriter, status int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(data)
+}
+
+func (h *QueryHandler) errorResponse(w http.ResponseWriter, status int, message, detail string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	resp := gwtypes.ErrorResponse{
+		Error:     http.StatusText(status),
+		Message:   message,
+		RequestID: w.Header().Get("X-Request-ID"),
+	}
+	if detail != "" {
+		resp.Code = detail
+	}
+	json.NewEncoder(w).Encode(resp)
+}

internal/gateway/handlers/voice_files.go

@@ -0,0 +1,232 @@
+// Package handlers provides HTTP handlers for voice and file services
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/gorilla/mux"
+	"go.uber.org/zap"
+)
+
+// VoiceHandler handles voice-related requests
+type VoiceHandler struct {
+	voiceServiceURL string
+	logger          *zap.Logger
+	httpClient      *http.Client
+}
+
+// NewVoiceHandler creates a new voice handler
+func NewVoiceHandler(voiceServiceURL string, logger *zap.Logger) *VoiceHandler {
+	return &VoiceHandler{
+		voiceServiceURL: voiceServiceURL,
+		logger:          logger,
+		httpClient:      &http.Client{},
+	}
+}
+
+// RegisterRoutes registers voice routes
+func (h *VoiceHandler) RegisterRoutes(r *mux.Router) {
+	r.HandleFunc("/api/v1/voice/sessions", h.ListSessions).Methods("GET")
+	r.HandleFunc("/api/v1/voice/sessions/{sessionId}", h.GetSession).Methods("GET")
+	r.HandleFunc("/api/v1/voice/sessions/{sessionId}/end", h.EndSession).Methods("POST")
+	r.HandleFunc("/api/v1/voice/voices", h.ListVoices).Methods("GET")
+}
+
+// ListSessions lists active voice sessions
+func (h *VoiceHandler) ListSessions(w http.ResponseWriter, r *http.Request) {
+	h.proxyRequest(w, r, "/api/v1/voice/sessions")
+}
+
+// GetSession gets a voice session
+func (h *VoiceHandler) GetSession(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/voice/sessions/%s", vars["sessionId"]))
+}
+
+// EndSession ends a voice session
+func (h *VoiceHandler) EndSession(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/voice/sessions/%s/end", vars["sessionId"]))
+}
+
+// ListVoices lists available TTS voices
+func (h *VoiceHandler) ListVoices(w http.ResponseWriter, r *http.Request) {
+	voices := []map[string]string{
+		{"id": "nova", "name": "Nova", "gender": "female", "style": "natural"},
+		{"id": "alloy", "name": "Alloy", "gender": "female", "style": "professional"},
+		{"id": "echo", "name": "Echo", "gender": "male", "style": "natural"},
+		{"id": "onyx", "name": "Onyx", "gender": "male", "style": "deep"},
+		{"id": "shimmer", "name": "Shimmer", "gender": "female", "style": "soft"},
+		{"id": "swahili", "name": "Rafiki", "gender": "male", "style": "swahili"},
+	}
+	json.NewEncoder(w).Encode(voices)
+}
+
+func (h *VoiceHandler) proxyRequest(w http.ResponseWriter, r *http.Request, path string) {
+	req, err := http.NewRequest(r.Method, h.voiceServiceURL+path, r.Body)
+	if err != nil {
+		http.Error(w, "Failed to create request", http.StatusInternalServerError)
+		return
+	}
+
+	// Copy headers
+	for key, values := range r.Header {
+		for _, value := range values {
+			req.Header.Add(key, value)
+		}
+	}
+
+	resp, err := h.httpClient.Do(req)
+	if err != nil {
+		http.Error(w, "Voice service unavailable", http.StatusServiceUnavailable)
+		return
+	}
+	defer resp.Body.Close()
+
+	// Copy response
+	for key, values := range resp.Header {
+		for _, value := range values {
+			w.Header().Add(key, value)
+		}
+	}
+	w.WriteHeader(resp.StatusCode)
+	io.Copy(w, resp.Body)
+}
+
+// FileHandler handles file-related requests
+type FileHandler struct {
+	fileServiceURL string
+	logger         *zap.Logger
+	httpClient     *http.Client
+}
+
+// NewFileHandler creates a new file handler
+func NewFileHandler(fileServiceURL string, logger *zap.Logger) *FileHandler {
+	return &FileHandler{
+		fileServiceURL: fileServiceURL,
+		logger:         logger,
+		httpClient:     &http.Client{},
+	}
+}
+
+// RegisterRoutes registers file routes
+func (h *FileHandler) RegisterRoutes(r *mux.Router) {
+	// Upload routes
+	r.HandleFunc("/api/v1/files/upload", h.InitiateUpload).Methods("POST")
+	r.HandleFunc("/api/v1/files/upload/{fileId}/chunk/{chunkIndex}", h.UploadChunk).Methods("POST")
+	r.HandleFunc("/api/v1/files/upload/{fileId}/complete", h.CompleteUpload).Methods("POST")
+
+	// File management routes
+	r.HandleFunc("/api/v1/files", h.ListFiles).Methods("GET")
+	r.HandleFunc("/api/v1/files/{fileId}", h.GetFile).Methods("GET")
+	r.HandleFunc("/api/v1/files/{fileId}", h.DeleteFile).Methods("DELETE")
+	r.HandleFunc("/api/v1/files/{fileId}/download", h.DownloadFile).Methods("GET")
+	r.HandleFunc("/api/v1/files/{fileId}/preview", h.PreviewFile).Methods("GET")
+	r.HandleFunc("/api/v1/files/{fileId}/share", h.ShareFile).Methods("POST")
+
+	// Chat integration
+	r.HandleFunc("/api/v1/files/{fileId}/chat", h.GetFileChat).Methods("GET")
+	r.HandleFunc("/api/v1/files/{fileId}/chat/message", h.SendFileMessage).Methods("POST")
+}
+
+// InitiateUpload starts a file upload
+func (h *FileHandler) InitiateUpload(w http.ResponseWriter, r *http.Request) {
+	h.proxyRequest(w, r, "/api/v1/files/upload")
+}
+
+// UploadChunk handles chunk upload
+func (h *FileHandler) UploadChunk(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/upload/%s/chunk/%s", vars["fileId"], vars["chunkIndex"]))
+}
+
+// CompleteUpload completes a file upload
+func (h *FileHandler) CompleteUpload(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/upload/%s/complete", vars["fileId"]))
+}
+
+// ListFiles lists user files
+func (h *FileHandler) ListFiles(w http.ResponseWriter, r *http.Request) {
+	h.proxyRequest(w, r, "/api/v1/files")
+}
+
+// GetFile gets file details
+func (h *FileHandler) GetFile(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s", vars["fileId"]))
+}
+
+// DeleteFile deletes a file
+func (h *FileHandler) DeleteFile(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s", vars["fileId"]))
+}
+
+// DownloadFile downloads a file
+func (h *FileHandler) DownloadFile(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s/download", vars["fileId"]))
+}
+
+// PreviewFile previews a file
+func (h *FileHandler) PreviewFile(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s/preview", vars["fileId"]))
+}
+
+// ShareFile creates a share link
+func (h *FileHandler) ShareFile(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s/share", vars["fileId"]))
+}
+
+// GetFileChat gets chat messages for a file
+func (h *FileHandler) GetFileChat(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s/chat", vars["fileId"]))
+}
+
+// SendFileMessage sends a message about a file
+func (h *FileHandler) SendFileMessage(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	h.proxyRequest(w, r, fmt.Sprintf("/api/v1/files/%s/chat/message", vars["fileId"]))
+}
+
+func (h *FileHandler) proxyRequest(w http.ResponseWriter, r *http.Request, path string) {
+	req, err := http.NewRequest(r.Method, h.fileServiceURL+path, r.Body)
+	if err != nil {
+		http.Error(w, "Failed to create request", http.StatusInternalServerError)
+		return
+	}
+
+	// Copy headers
+	for key, values := range r.Header {
+		for _, value := range values {
+			req.Header.Add(key, value)
+		}
+	}
+
+	resp, err := h.httpClient.Do(req)
+	if err != nil {
+		http.Error(w, "File service unavailable", http.StatusServiceUnavailable)
+		return
+	}
+	defer resp.Body.Close()
+
+	// Copy response
+	for key, values := range resp.Header {
+		for _, value := range values {
+			w.Header().Add(key, value)
+		}
+	}
+	w.WriteHeader(resp.StatusCode)
+	io.Copy(w, resp.Body)
+}
+
+// Unused variable suppression
+var _ = strconv.Atoi

internal/gateway/handlers/websocket.go

@@ -0,0 +1,289 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/gorilla/websocket"
+	"go.uber.org/zap"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/gwtypes"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"github.com/AmaniQuery/amaniquery/internal/gateway/services"
+)
+
+// WebSocketHandler handles WebSocket connections for streaming queries
+type WebSocketHandler struct {
+	registry    *services.Registry
+	config      gwtypes.WebSocketConfig
+	upgrader    websocket.Upgrader
+	connections sync.Map // map[string]*wsConnection
+	logger      *zap.Logger
+}
+
+type wsConnection struct {
+	conn      *websocket.Conn
+	userID    string
+	sessionID string
+	createdAt time.Time
+	cancel    context.CancelFunc
+}
+
+// NewWebSocketHandler creates a new WebSocket handler
+func NewWebSocketHandler(registry *services.Registry, cfg gwtypes.WebSocketConfig, logger *zap.Logger) *WebSocketHandler {
+	return &WebSocketHandler{
+		registry: registry,
+		config:   cfg,
+		upgrader: websocket.Upgrader{
+			CheckOrigin: func(r *http.Request) bool {
+				// Allow all origins for now, configure in production
+				return true
+			},
+			ReadBufferSize:  cfg.ReadBufferSize,
+			WriteBufferSize: cfg.WriteBufferSize,
+			Subprotocols:    []string{"rag-agent-protocol"},
+		},
+		logger: logger,
+	}
+}
+
+// HandleStream handles WebSocket upgrade and streaming
+func (h *WebSocketHandler) HandleStream(w http.ResponseWriter, r *http.Request) {
+	// Upgrade connection
+	conn, err := h.upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		h.logger.Error("WebSocket upgrade failed", zap.Error(err))
+		return
+	}
+
+	// Create connection context with cancel
+	ctx, cancel := context.WithCancel(r.Context())
+
+	// Generate connection ID
+	connID := uuid.New().String()
+
+	// Get user info from context
+	userID := middleware.UserIDFromContext(r.Context())
+	sessionID := r.URL.Query().Get("sessionId")
+
+	// Store connection
+	wsConn := &wsConnection{
+		conn:      conn,
+		userID:    userID,
+		sessionID: sessionID,
+		createdAt: time.Now(),
+		cancel:    cancel,
+	}
+	h.connections.Store(connID, wsConn)
+
+	defer func() {
+		h.connections.Delete(connID)
+		cancel()
+		conn.Close()
+	}()
+
+	h.logger.Info("WebSocket connection established",
+		zap.String("conn_id", connID),
+		zap.String("user_id", userID),
+	)
+
+	// Start ping-pong keepalive
+	go h.keepalive(ctx, conn, connID)
+
+	// Message handling loop
+	h.messageLoop(ctx, conn, connID, userID, sessionID)
+}
+
+func (h *WebSocketHandler) messageLoop(ctx context.Context, conn *websocket.Conn, connID, userID, sessionID string) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+			// Set read deadline
+			conn.SetReadDeadline(time.Now().Add(h.config.PongWait))
+
+			// Read message
+			_, message, err := conn.ReadMessage()
+			if err != nil {
+				if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
+					h.logger.Error("WebSocket read error", zap.Error(err), zap.String("conn_id", connID))
+				}
+				return
+			}
+
+			// Parse message
+			var msg gwtypes.WebSocketMessage
+			if err := json.Unmarshal(message, &msg); err != nil {
+				h.sendError(conn, "Invalid message format")
+				continue
+			}
+
+			// Handle message
+			go h.handleMessage(ctx, conn, connID, userID, sessionID, msg)
+		}
+	}
+}
+
+func (h *WebSocketHandler) handleMessage(ctx context.Context, conn *websocket.Conn, connID, userID, sessionID string, msg gwtypes.WebSocketMessage) {
+	switch msg.Type {
+	case "query":
+		h.handleQuery(ctx, conn, connID, userID, sessionID, msg)
+	case "ping":
+		h.sendMessage(conn, gwtypes.WebSocketServerMessage{
+			Type:      "pong",
+			Timestamp: time.Now().Format(time.RFC3339),
+		})
+	case "cancel":
+		h.handleCancel(connID, msg)
+	default:
+		h.sendError(conn, "Unknown message type")
+	}
+}
+
+func (h *WebSocketHandler) handleQuery(ctx context.Context, conn *websocket.Conn, connID, userID, sessionID string, msg gwtypes.WebSocketMessage) {
+	// Parse query payload
+	payloadBytes, _ := json.Marshal(msg.Payload)
+	var payload gwtypes.WebSocketQueryPayload
+	if err := json.Unmarshal(payloadBytes, &payload); err != nil {
+		h.sendError(conn, "Invalid query payload")
+		return
+	}
+
+	// Set defaults
+	if payload.UserID == "" {
+		payload.UserID = userID
+	}
+	if payload.SessionID == "" {
+		payload.SessionID = sessionID
+	}
+	if payload.QueryID == "" {
+		payload.QueryID = uuid.New().String()
+	}
+
+	h.logger.Info("Processing streaming query",
+		zap.String("conn_id", connID),
+		zap.String("query_id", payload.QueryID),
+	)
+
+	// Get agent client
+	agentClient, err := h.registry.GetAgentClient(ctx)
+	if err != nil {
+		h.logger.Error("Failed to get agent client", zap.Error(err))
+		h.sendError(conn, "Service unavailable")
+		return
+	}
+
+	// Create streaming request
+	streamReq := &services.StreamQueryRequest{
+		QueryID:   payload.QueryID,
+		Query:     payload.Query,
+		UserID:    payload.UserID,
+		SessionID: payload.SessionID,
+		AgentID:   payload.AgentID,
+	}
+
+	if payload.Options != nil {
+		streamReq.Temperature = payload.Options.Temperature
+		streamReq.MaxTokens = payload.Options.MaxTokens
+	}
+
+	// Execute streaming query
+	streamChan, errChan := agentClient.ProcessQueryStream(ctx, streamReq)
+
+	// Stream results to client
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case err := <-errChan:
+			if err != nil {
+				h.logger.Error("Stream error", zap.Error(err), zap.String("query_id", payload.QueryID))
+				h.sendError(conn, err.Error())
+			}
+			return
+		case chunk, ok := <-streamChan:
+			if !ok {
+				h.sendMessage(conn, gwtypes.WebSocketServerMessage{
+					Type:      "done",
+					Timestamp: time.Now().Format(time.RFC3339),
+					Metadata: map[string]interface{}{
+						"queryId": payload.QueryID,
+					},
+				})
+				return
+			}
+
+			// Send chunk
+			h.sendMessage(conn, gwtypes.WebSocketServerMessage{
+				Type:      chunk.Type,
+				Timestamp: time.Now().Format(time.RFC3339),
+				Data:      chunk.Data,
+				Metadata:  chunk.Metadata,
+			})
+		}
+	}
+}
+
+func (h *WebSocketHandler) handleCancel(connID string, msg gwtypes.WebSocketMessage) {
+	if wsConn, ok := h.connections.Load(connID); ok {
+		wsConn.(*wsConnection).cancel()
+	}
+}
+
+func (h *WebSocketHandler) keepalive(ctx context.Context, conn *websocket.Conn, connID string) {
+	ticker := time.NewTicker(h.config.PingInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			conn.SetWriteDeadline(time.Now().Add(h.config.WriteWait))
+			if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+				h.logger.Debug("Ping failed", zap.String("conn_id", connID), zap.Error(err))
+				return
+			}
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+func (h *WebSocketHandler) sendMessage(conn *websocket.Conn, msg gwtypes.WebSocketServerMessage) {
+	conn.SetWriteDeadline(time.Now().Add(h.config.WriteWait))
+	if err := conn.WriteJSON(msg); err != nil {
+		h.logger.Error("Failed to send WebSocket message", zap.Error(err))
+	}
+}
+
+func (h *WebSocketHandler) sendError(conn *websocket.Conn, message string) {
+	h.sendMessage(conn, gwtypes.WebSocketServerMessage{
+		Type:      "error",
+		Timestamp: time.Now().Format(time.RFC3339),
+		Data:      message,
+	})
+}
+
+// CloseAll closes all active connections
+func (h *WebSocketHandler) CloseAll() {
+	h.connections.Range(func(key, value interface{}) bool {
+		wsConn := value.(*wsConnection)
+		wsConn.cancel()
+		wsConn.conn.Close()
+		return true
+	})
+}
+
+// ActiveConnections returns the number of active connections
+func (h *WebSocketHandler) ActiveConnections() int {
+	count := 0
+	h.connections.Range(func(key, value interface{}) bool {
+		count++
+		return true
+	})
+	return count
+}

internal/gateway/middleware/audit.go

@@ -0,0 +1,133 @@
+package middleware
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// AuditEvent represents an audit log entry
+type AuditEvent struct {
+	Timestamp    int64   `json:"timestamp"`
+	RequestID    string  `json:"request_id"`
+	UserID       string  `json:"user_id"`
+	TenantID     string  `json:"tenant_id"`
+	Method       string  `json:"method"`
+	Path         string  `json:"path"`
+	Query        string  `json:"query,omitempty"`
+	StatusCode   int     `json:"status_code"`
+	LatencyMs    float64 `json:"latency_ms"`
+	RequestSize  int64   `json:"request_size"`
+	ResponseSize int     `json:"response_size"`
+	UserAgent    string  `json:"user_agent"`
+	IP           string  `json:"ip"`
+	Error        string  `json:"error,omitempty"`
+}
+
+// AuditMiddleware logs all API requests for auditing
+type AuditMiddleware struct {
+	logger    *zap.Logger
+	skipPaths map[string]bool
+}
+
+// NewAuditMiddleware creates a new audit middleware
+func NewAuditMiddleware(logger *zap.Logger) *AuditMiddleware {
+	return &AuditMiddleware{
+		logger: logger,
+		skipPaths: map[string]bool{
+			"/admin/health":  true,
+			"/admin/metrics": true,
+		},
+	}
+}
+
+// Handler is the middleware handler function
+func (m *AuditMiddleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Skip audit for certain paths
+		if m.skipPaths[r.URL.Path] {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		start := time.Now()
+
+		// Wrap response writer to capture status code and size
+		rw := &responseWriter{
+			ResponseWriter: w,
+			statusCode:     http.StatusOK,
+		}
+
+		// Call next handler
+		next.ServeHTTP(rw, r)
+
+		// Calculate latency
+		latency := time.Since(start)
+
+		// Build audit event
+		event := AuditEvent{
+			Timestamp:    time.Now().UnixNano() / int64(time.Millisecond),
+			RequestID:    w.Header().Get("X-Request-ID"),
+			UserID:       UserIDFromContext(r.Context()),
+			TenantID:     TenantIDFromContext(r.Context()),
+			Method:       r.Method,
+			Path:         r.URL.Path,
+			Query:        r.URL.RawQuery,
+			StatusCode:   rw.statusCode,
+			LatencyMs:    float64(latency.Nanoseconds()) / float64(time.Millisecond),
+			RequestSize:  r.ContentLength,
+			ResponseSize: rw.size,
+			UserAgent:    r.UserAgent(),
+			IP:           getClientIP(r),
+		}
+
+		// Log the audit event
+		m.logEvent(event)
+	})
+}
+
+func (m *AuditMiddleware) logEvent(event AuditEvent) {
+	// Log as structured JSON
+	eventJSON, err := json.Marshal(event)
+	if err != nil {
+		m.logger.Error("Failed to marshal audit event", zap.Error(err))
+		return
+	}
+
+	m.logger.Info("audit",
+		zap.String("event", string(eventJSON)),
+		zap.String("request_id", event.RequestID),
+		zap.String("user_id", event.UserID),
+		zap.String("method", event.Method),
+		zap.String("path", event.Path),
+		zap.Int("status", event.StatusCode),
+		zap.Float64("latency_ms", event.LatencyMs),
+	)
+}
+
+// responseWriter wraps http.ResponseWriter to capture response details
+type responseWriter struct {
+	http.ResponseWriter
+	statusCode int
+	size       int
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	rw.ResponseWriter.WriteHeader(code)
+}
+
+func (rw *responseWriter) Write(b []byte) (int, error) {
+	size, err := rw.ResponseWriter.Write(b)
+	rw.size += size
+	return size, err
+}
+
+// Flush implements http.Flusher
+func (rw *responseWriter) Flush() {
+	if f, ok := rw.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}

internal/gateway/middleware/auth.go

@@ -0,0 +1,311 @@
+package middleware
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"go.uber.org/zap"
+)
+
+// Context keys for request values
+type contextKey string
+
+const (
+	ContextKeyUserID   contextKey = "userId"
+	ContextKeyTenantID contextKey = "tenantId"
+	ContextKeyClaims   contextKey = "claims"
+	ContextKeyRoles    contextKey = "roles"
+)
+
+// AuthConfig holds authentication configuration
+type AuthConfig struct {
+	JWTSecret   string
+	JWTIssuer   string
+	JWTAudience string
+	OPAEnabled  bool
+	OPAAddr     string
+	OPAPolicy   string
+	SkipPaths   []string
+}
+
+// JWTClaims represents JWT token claims
+type JWTClaims struct {
+	jwt.RegisteredClaims
+	UserID   string   `json:"user_id"`
+	Email    string   `json:"email"`
+	Roles    []string `json:"roles"`
+	TenantID string   `json:"tenant_id,omitempty"`
+}
+
+// AuthMiddleware handles JWT authentication and OPA authorization
+type AuthMiddleware struct {
+	config    AuthConfig
+	skipPaths map[string]bool
+	opaClient *OPAClient
+	logger    *zap.Logger
+}
+
+// NewAuthMiddleware creates a new authentication middleware
+func NewAuthMiddleware(cfg AuthConfig, logger *zap.Logger) *AuthMiddleware {
+	skipPaths := make(map[string]bool)
+	for _, path := range cfg.SkipPaths {
+		skipPaths[path] = true
+	}
+
+	m := &AuthMiddleware{
+		config:    cfg,
+		skipPaths: skipPaths,
+		logger:    logger,
+	}
+
+	if cfg.OPAEnabled && cfg.OPAAddr != "" {
+		m.opaClient = NewOPAClient(cfg.OPAAddr, cfg.OPAPolicy)
+	}
+
+	return m
+}
+
+// Handler is the middleware handler function
+func (m *AuthMiddleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Skip authentication for certain paths
+		if m.skipPaths[r.URL.Path] {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		// Extract token
+		token := m.extractToken(r)
+		if token == "" {
+			m.unauthorized(w, "Missing authorization token")
+			return
+		}
+
+		// Validate JWT
+		claims, err := m.validateToken(token)
+		if err != nil {
+			m.logger.Debug("Token validation failed", zap.Error(err))
+			m.unauthorized(w, "Invalid token")
+			return
+		}
+
+		// Check token expiration
+		if claims.ExpiresAt != nil && time.Now().After(claims.ExpiresAt.Time) {
+			m.unauthorized(w, "Token expired")
+			return
+		}
+
+		// OPA authorization
+		if m.opaClient != nil {
+			allowed, err := m.opaClient.Authorize(r.Context(), AuthzInput{
+				User:   claims.UserID,
+				Roles:  claims.Roles,
+				Action: r.Method,
+				Path:   r.URL.Path,
+				Tenant: claims.TenantID,
+			})
+			if err != nil {
+				m.logger.Error("OPA authorization failed", zap.Error(err))
+				m.forbidden(w, "Authorization service unavailable")
+				return
+			}
+			if !allowed {
+				m.forbidden(w, "Access denied")
+				return
+			}
+		}
+
+		// Add claims to context
+		ctx := r.Context()
+		ctx = context.WithValue(ctx, ContextKeyClaims, claims)
+		ctx = context.WithValue(ctx, ContextKeyUserID, claims.UserID)
+		ctx = context.WithValue(ctx, ContextKeyTenantID, claims.TenantID)
+		ctx = context.WithValue(ctx, ContextKeyRoles, claims.Roles)
+
+		next.ServeHTTP(w, r.WithContext(ctx))
+	})
+}
+
+func (m *AuthMiddleware) extractToken(r *http.Request) string {
+	// Check Authorization header
+	authHeader := r.Header.Get("Authorization")
+	if authHeader != "" {
+		if strings.HasPrefix(authHeader, "Bearer ") {
+			return strings.TrimPrefix(authHeader, "Bearer ")
+		}
+	}
+
+	// Check query parameter (for WebSocket connections)
+	if token := r.URL.Query().Get("token"); token != "" {
+		return token
+	}
+
+	return ""
+}
+
+func (m *AuthMiddleware) validateToken(tokenString string) (*JWTClaims, error) {
+	claims := &JWTClaims{}
+
+	token, err := jwt.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
+		// Validate signing method
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
+		}
+		return []byte(m.config.JWTSecret), nil
+	})
+
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse token: %w", err)
+	}
+
+	if !token.Valid {
+		return nil, errors.New("invalid token")
+	}
+
+	// Validate issuer
+	if m.config.JWTIssuer != "" && claims.Issuer != m.config.JWTIssuer {
+		return nil, fmt.Errorf("invalid issuer: expected %s, got %s", m.config.JWTIssuer, claims.Issuer)
+	}
+
+	// Validate audience
+	if m.config.JWTAudience != "" {
+		hasAudience := false
+		for _, aud := range claims.Audience {
+			if aud == m.config.JWTAudience {
+				hasAudience = true
+				break
+			}
+		}
+		if !hasAudience {
+			return nil, errors.New("invalid audience")
+		}
+	}
+
+	return claims, nil
+}
+
+func (m *AuthMiddleware) unauthorized(w http.ResponseWriter, message string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("WWW-Authenticate", "Bearer")
+	w.WriteHeader(http.StatusUnauthorized)
+	json.NewEncoder(w).Encode(map[string]string{
+		"error":   "unauthorized",
+		"message": message,
+	})
+}
+
+func (m *AuthMiddleware) forbidden(w http.ResponseWriter, message string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusForbidden)
+	json.NewEncoder(w).Encode(map[string]string{
+		"error":   "forbidden",
+		"message": message,
+	})
+}
+
+// UserIDFromContext extracts user ID from context
+func UserIDFromContext(ctx context.Context) string {
+	if userID, ok := ctx.Value(ContextKeyUserID).(string); ok {
+		return userID
+	}
+	return ""
+}
+
+// TenantIDFromContext extracts tenant ID from context
+func TenantIDFromContext(ctx context.Context) string {
+	if tenantID, ok := ctx.Value(ContextKeyTenantID).(string); ok {
+		return tenantID
+	}
+	return ""
+}
+
+// ClaimsFromContext extracts claims from context
+func ClaimsFromContext(ctx context.Context) *JWTClaims {
+	if claims, ok := ctx.Value(ContextKeyClaims).(*JWTClaims); ok {
+		return claims
+	}
+	return nil
+}
+
+// RolesFromContext extracts roles from context
+func RolesFromContext(ctx context.Context) []string {
+	if roles, ok := ctx.Value(ContextKeyRoles).([]string); ok {
+		return roles
+	}
+	return nil
+}
+
+// OPAClient is a client for Open Policy Agent
+type OPAClient struct {
+	addr   string
+	policy string
+	client *http.Client
+}
+
+// NewOPAClient creates a new OPA client
+func NewOPAClient(addr, policy string) *OPAClient {
+	return &OPAClient{
+		addr:   addr,
+		policy: policy,
+		client: &http.Client{
+			Timeout: 5 * time.Second,
+		},
+	}
+}
+
+// AuthzInput represents the input to OPA authorization
+type AuthzInput struct {
+	User   string   `json:"user"`
+	Roles  []string `json:"roles"`
+	Action string   `json:"action"`
+	Path   string   `json:"path"`
+	Tenant string   `json:"tenant,omitempty"`
+}
+
+// Authorize checks if the request is authorized
+func (c *OPAClient) Authorize(ctx context.Context, input AuthzInput) (bool, error) {
+	// Build OPA query URL
+	url := fmt.Sprintf("%s/v1/data/%s", c.addr, strings.ReplaceAll(c.policy, "/", "."))
+
+	// Create request body
+	body := map[string]interface{}{
+		"input": input,
+	}
+
+	jsonBody, err := json.Marshal(body)
+	if err != nil {
+		return false, fmt.Errorf("failed to marshal OPA input: %w", err)
+	}
+
+	// Create request
+	req, err := http.NewRequestWithContext(ctx, "POST", url, bytes.NewReader(jsonBody))
+	if err != nil {
+		return false, fmt.Errorf("failed to create OPA request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	// Send request
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return false, fmt.Errorf("OPA request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	// Parse response
+	var result struct {
+		Result bool `json:"result"`
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return false, fmt.Errorf("failed to decode OPA response: %w", err)
+	}
+
+	return result.Result, nil
+}

internal/gateway/middleware/common.go

@@ -0,0 +1,51 @@
+package middleware
+
+import (
+	"net/http"
+	"runtime/debug"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+// Recovery returns a middleware that recovers from panics
+func Recovery(logger *zap.Logger) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			defer func() {
+				if rec := recover(); rec != nil {
+					// Log the panic
+					logger.Error("Panic recovered",
+						zap.Any("panic", rec),
+						zap.String("path", r.URL.Path),
+						zap.String("method", r.Method),
+						zap.String("stack", string(debug.Stack())),
+					)
+
+					// Return 500 error
+					http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+				}
+			}()
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// RequestID returns a middleware that adds a unique request ID
+func RequestID() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Check if request ID already exists
+			requestID := r.Header.Get("X-Request-ID")
+			if requestID == "" {
+				requestID = uuid.New().String()
+			}
+
+			// Set request ID in response header
+			w.Header().Set("X-Request-ID", requestID)
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}

internal/gateway/middleware/cors.go

@@ -0,0 +1,143 @@
+// Package middleware provides HTTP middleware for the API Gateway.
+package middleware
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+// CORSConfig holds CORS middleware configuration
+type CORSConfig struct {
+	AllowedOrigins   []string
+	AllowedMethods   []string
+	AllowedHeaders   []string
+	ExposedHeaders   []string
+	AllowCredentials bool
+	MaxAge           int
+}
+
+// CORSMiddleware handles Cross-Origin Resource Sharing
+type CORSMiddleware struct {
+	config          CORSConfig
+	allowedOrigins  map[string]bool
+	allowAllOrigins bool
+}
+
+// NewCORSMiddleware creates a new CORS middleware
+func NewCORSMiddleware(cfg CORSConfig) *CORSMiddleware {
+	m := &CORSMiddleware{
+		config:         cfg,
+		allowedOrigins: make(map[string]bool),
+	}
+
+	for _, origin := range cfg.AllowedOrigins {
+		if origin == "*" {
+			m.allowAllOrigins = true
+			break
+		}
+		m.allowedOrigins[origin] = true
+	}
+
+	return m
+}
+
+// Handler is the middleware handler function
+func (m *CORSMiddleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		origin := r.Header.Get("Origin")
+
+		// Check if origin is allowed
+		if m.isOriginAllowed(origin) {
+			w.Header().Set("Access-Control-Allow-Origin", origin)
+		}
+
+		// Set CORS headers
+		if m.config.AllowCredentials {
+			w.Header().Set("Access-Control-Allow-Credentials", "true")
+		}
+
+		if len(m.config.ExposedHeaders) > 0 {
+			w.Header().Set("Access-Control-Expose-Headers", strings.Join(m.config.ExposedHeaders, ", "))
+		}
+
+		// Security headers
+		m.setSecurityHeaders(w)
+
+		// Handle preflight
+		if r.Method == http.MethodOptions {
+			m.handlePreflight(w, r)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+
+// HandlePreflight handles OPTIONS preflight requests
+func (m *CORSMiddleware) HandlePreflight(w http.ResponseWriter, r *http.Request) {
+	origin := r.Header.Get("Origin")
+
+	if m.isOriginAllowed(origin) {
+		w.Header().Set("Access-Control-Allow-Origin", origin)
+	}
+
+	m.handlePreflight(w, r)
+}
+
+func (m *CORSMiddleware) handlePreflight(w http.ResponseWriter, r *http.Request) {
+	// Allow methods
+	if len(m.config.AllowedMethods) > 0 {
+		w.Header().Set("Access-Control-Allow-Methods", strings.Join(m.config.AllowedMethods, ", "))
+	}
+
+	// Allow headers
+	if len(m.config.AllowedHeaders) > 0 {
+		w.Header().Set("Access-Control-Allow-Headers", strings.Join(m.config.AllowedHeaders, ", "))
+	}
+
+	// Max age
+	if m.config.MaxAge > 0 {
+		w.Header().Set("Access-Control-Max-Age", strconv.Itoa(m.config.MaxAge))
+	}
+
+	// Credentials
+	if m.config.AllowCredentials {
+		w.Header().Set("Access-Control-Allow-Credentials", "true")
+	}
+
+	// Security headers
+	m.setSecurityHeaders(w)
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (m *CORSMiddleware) isOriginAllowed(origin string) bool {
+	if origin == "" {
+		return false
+	}
+	if m.allowAllOrigins {
+		return true
+	}
+	return m.allowedOrigins[origin]
+}
+
+func (m *CORSMiddleware) setSecurityHeaders(w http.ResponseWriter) {
+	// Prevent MIME type sniffing
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+
+	// Prevent clickjacking
+	w.Header().Set("X-Frame-Options", "DENY")
+
+	// XSS protection
+	w.Header().Set("X-XSS-Protection", "1; mode=block")
+
+	// HSTS - force HTTPS
+	w.Header().Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
+
+	// Referrer policy
+	w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")
+
+	// Content Security Policy
+	w.Header().Set("Content-Security-Policy", "default-src 'self'")
+}

internal/gateway/middleware/middleware_test.go

@@ -0,0 +1,388 @@
+package middleware_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/AmaniQuery/amaniquery/internal/gateway/middleware"
+	"go.uber.org/zap"
+)
+
+// TestCORSMiddleware_AllowAllOrigins tests wildcard origin support
+func TestCORSMiddleware_AllowAllOrigins(t *testing.T) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins:   []string{"*"},
+		AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE"},
+		AllowedHeaders:   []string{"Content-Type", "Authorization"},
+		AllowCredentials: false,
+		MaxAge:           3600,
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.Header.Set("Origin", "https://example.com")
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	if rec.Header().Get("Access-Control-Allow-Origin") != "https://example.com" {
+		t.Errorf("Expected origin to be allowed, got: %s", rec.Header().Get("Access-Control-Allow-Origin"))
+	}
+}
+
+// TestCORSMiddleware_SpecificOrigins tests specific origin allowlist
+func TestCORSMiddleware_SpecificOrigins(t *testing.T) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins:   []string{"https://allowed.com", "https://another.com"},
+		AllowedMethods:   []string{"GET", "POST"},
+		AllowedHeaders:   []string{"Content-Type"},
+		AllowCredentials: true,
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	testCases := []struct {
+		name          string
+		origin        string
+		shouldAllow   bool
+	}{
+		{"allowed origin", "https://allowed.com", true},
+		{"another allowed", "https://another.com", true},
+		{"not allowed", "https://evil.com", false},
+		{"no origin", "", false},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, "/test", nil)
+			if tc.origin != "" {
+				req.Header.Set("Origin", tc.origin)
+			}
+			rec := httptest.NewRecorder()
+
+			handler.ServeHTTP(rec, req)
+
+			hasOrigin := rec.Header().Get("Access-Control-Allow-Origin") != ""
+			if hasOrigin != tc.shouldAllow {
+				t.Errorf("Origin %s: expected allowed=%v, got allowed=%v", tc.origin, tc.shouldAllow, hasOrigin)
+			}
+		})
+	}
+}
+
+// TestCORSMiddleware_Preflight tests OPTIONS preflight handling
+func TestCORSMiddleware_Preflight(t *testing.T) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins:   []string{"https://allowed.com"},
+		AllowedMethods:   []string{"GET", "POST", "PUT"},
+		AllowedHeaders:   []string{"Content-Type", "Authorization"},
+		AllowCredentials: true,
+		MaxAge:           7200,
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Error("Handler should not be called for OPTIONS request")
+	}))
+
+	req := httptest.NewRequest(http.MethodOptions, "/test", nil)
+	req.Header.Set("Origin", "https://allowed.com")
+	req.Header.Set("Access-Control-Request-Method", "POST")
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNoContent {
+		t.Errorf("Expected status %d, got %d", http.StatusNoContent, rec.Code)
+	}
+
+	// Check preflight headers
+	if rec.Header().Get("Access-Control-Allow-Methods") == "" {
+		t.Error("Expected Access-Control-Allow-Methods header")
+	}
+	if rec.Header().Get("Access-Control-Allow-Headers") == "" {
+		t.Error("Expected Access-Control-Allow-Headers header")
+	}
+	if rec.Header().Get("Access-Control-Max-Age") != "7200" {
+		t.Errorf("Expected Max-Age 7200, got %s", rec.Header().Get("Access-Control-Max-Age"))
+	}
+}
+
+// TestCORSMiddleware_SecurityHeaders tests security headers are set
+func TestCORSMiddleware_SecurityHeaders(t *testing.T) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins: []string{"*"},
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.Header.Set("Origin", "https://example.com")
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	securityHeaders := []string{
+		"X-Content-Type-Options",
+		"X-Frame-Options",
+		"X-XSS-Protection",
+		"Strict-Transport-Security",
+		"Referrer-Policy",
+		"Content-Security-Policy",
+	}
+
+	for _, header := range securityHeaders {
+		if rec.Header().Get(header) == "" {
+			t.Errorf("Expected security header %s to be set", header)
+		}
+	}
+}
+
+// TestCORSMiddleware_Credentials tests credentials header
+func TestCORSMiddleware_Credentials(t *testing.T) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins:   []string{"https://allowed.com"},
+		AllowCredentials: true,
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.Header.Set("Origin", "https://allowed.com")
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	if rec.Header().Get("Access-Control-Allow-Credentials") != "true" {
+		t.Error("Expected Access-Control-Allow-Credentials to be true")
+	}
+}
+
+// TestRateLimitMiddleware_LocalRateLimit tests local rate limiting
+func TestRateLimitMiddleware_LocalRateLimit(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	cfg := middleware.RateLimitConfig{
+		RequestsPerSec:  1, // 1 request per second
+		BurstSize:       1, // Allow 1 request burst
+		CleanupInterval: time.Minute,
+	}
+
+	rl, err := middleware.NewRateLimitMiddleware(cfg, logger)
+	if err != nil {
+		t.Fatalf("Failed to create rate limit middleware: %v", err)
+	}
+	defer rl.Close()
+
+	handler := rl.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	// First request should succeed (uses burst token)
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.RemoteAddr = "127.0.0.1:12345"
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("First request should be allowed, got status %d", rec.Code)
+	}
+
+	// Second request immediately after should be rate limited
+	req2 := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req2.RemoteAddr = "127.0.0.1:12345"
+	rec2 := httptest.NewRecorder()
+	handler.ServeHTTP(rec2, req2)
+
+	if rec2.Code != http.StatusTooManyRequests {
+		t.Errorf("Expected status %d (rate limited), got %d", http.StatusTooManyRequests, rec2.Code)
+	}
+}
+
+// TestRateLimitMiddleware_Headers tests rate limit headers
+func TestRateLimitMiddleware_Headers(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	cfg := middleware.RateLimitConfig{
+		RequestsPerSec:  10,
+		BurstSize:       10,
+		CleanupInterval: time.Minute,
+	}
+
+	rl, err := middleware.NewRateLimitMiddleware(cfg, logger)
+	if err != nil {
+		t.Fatalf("Failed to create rate limit middleware: %v", err)
+	}
+	defer rl.Close()
+
+	handler := rl.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.RemoteAddr = "127.0.0.1:12345"
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	// Check rate limit headers
+	if rec.Header().Get("X-RateLimit-Limit") == "" {
+		t.Error("Expected X-RateLimit-Limit header")
+	}
+	if rec.Header().Get("X-RateLimit-Remaining") == "" {
+		t.Error("Expected X-RateLimit-Remaining header")
+	}
+	if rec.Header().Get("X-RateLimit-Reset") == "" {
+		t.Error("Expected X-RateLimit-Reset header")
+	}
+}
+
+// TestRateLimitMiddleware_DifferentIPs tests per-IP rate limiting
+func TestRateLimitMiddleware_DifferentIPs(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	cfg := middleware.RateLimitConfig{
+		RequestsPerSec:  1,
+		BurstSize:       1,
+		CleanupInterval: time.Minute,
+	}
+
+	rl, err := middleware.NewRateLimitMiddleware(cfg, logger)
+	if err != nil {
+		t.Fatalf("Failed to create rate limit middleware: %v", err)
+	}
+	defer rl.Close()
+
+	handler := rl.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	// First IP exhausts its limit
+	req1 := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req1.RemoteAddr = "10.0.0.1:12345"
+	rec1 := httptest.NewRecorder()
+	handler.ServeHTTP(rec1, req1)
+
+	if rec1.Code != http.StatusOK {
+		t.Errorf("First request from IP1 should succeed, got %d", rec1.Code)
+	}
+
+	// Second request from same IP should be limited
+	req2 := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req2.RemoteAddr = "10.0.0.1:12345"
+	rec2 := httptest.NewRecorder()
+	handler.ServeHTTP(rec2, req2)
+
+	if rec2.Code != http.StatusTooManyRequests {
+		t.Errorf("Second request from IP1 should be limited, got %d", rec2.Code)
+	}
+
+	// Different IP should still be allowed
+	req3 := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req3.RemoteAddr = "10.0.0.2:12345"
+	rec3 := httptest.NewRecorder()
+	handler.ServeHTTP(rec3, req3)
+
+	if rec3.Code != http.StatusOK {
+		t.Errorf("First request from IP2 should succeed, got %d", rec3.Code)
+	}
+}
+
+// TestRateLimitMiddleware_XForwardedFor tests X-Forwarded-For handling
+func TestRateLimitMiddleware_XForwardedFor(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	cfg := middleware.RateLimitConfig{
+		RequestsPerSec:  1,
+		BurstSize:       1,
+		CleanupInterval: time.Minute,
+	}
+
+	rl, err := middleware.NewRateLimitMiddleware(cfg, logger)
+	if err != nil {
+		t.Fatalf("Failed to create rate limit middleware: %v", err)
+	}
+	defer rl.Close()
+
+	handler := rl.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	// Request with X-Forwarded-For header
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.RemoteAddr = "127.0.0.1:12345"
+	req.Header.Set("X-Forwarded-For", "203.0.113.195, 70.41.3.18, 150.172.238.178")
+	rec := httptest.NewRecorder()
+
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("Request should succeed, got %d", rec.Code)
+	}
+}
+
+// BenchmarkCORSMiddleware benchmarks CORS middleware
+func BenchmarkCORSMiddleware(b *testing.B) {
+	cfg := middleware.CORSConfig{
+		AllowedOrigins: []string{"https://example.com", "https://test.com"},
+		AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
+		AllowedHeaders: []string{"Content-Type", "Authorization"},
+	}
+
+	cors := middleware.NewCORSMiddleware(cfg)
+
+	handler := cors.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.Header.Set("Origin", "https://example.com")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		rec := httptest.NewRecorder()
+		handler.ServeHTTP(rec, req)
+	}
+}
+
+// BenchmarkRateLimitMiddleware benchmarks rate limit middleware
+func BenchmarkRateLimitMiddleware(b *testing.B) {
+	logger, _ := zap.NewProduction()
+	cfg := middleware.RateLimitConfig{
+		RequestsPerSec:  1000000, // High limit for benchmarking
+		BurstSize:       1000000,
+		CleanupInterval: time.Minute,
+	}
+
+	rl, _ := middleware.NewRateLimitMiddleware(cfg, logger)
+	defer rl.Close()
+
+	handler := rl.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	req.RemoteAddr = "127.0.0.1:12345"
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		rec := httptest.NewRecorder()
+		handler.ServeHTTP(rec, req)
+	}
+}

internal/gateway/middleware/ratelimit.go

@@ -0,0 +1,253 @@
+package middleware
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"golang.org/x/time/rate"
+)
+
+// RateLimitConfig holds rate limiting configuration
+type RateLimitConfig struct {
+	RequestsPerSec  float64
+	BurstSize       int
+	PerTenant       bool
+	PerUser         bool
+	RedisAddr       string
+	RedisEnabled    bool
+	CleanupInterval time.Duration
+}
+
+// RateLimitMiddleware implements token bucket rate limiting
+type RateLimitMiddleware struct {
+	config   RateLimitConfig
+	limiters sync.Map // map[string]*rate.Limiter
+	redis    *redis.Client
+	logger   *zap.Logger
+	stop     chan struct{}
+}
+
+// NewRateLimitMiddleware creates a new rate limit middleware
+func NewRateLimitMiddleware(cfg RateLimitConfig, logger *zap.Logger) (*RateLimitMiddleware, error) {
+	m := &RateLimitMiddleware{
+		config: cfg,
+		logger: logger,
+		stop:   make(chan struct{}),
+	}
+
+	// Initialize Redis if enabled
+	if cfg.RedisEnabled && cfg.RedisAddr != "" {
+		m.redis = redis.NewClient(&redis.Options{
+			Addr: cfg.RedisAddr,
+		})
+
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+
+		if err := m.redis.Ping(ctx).Err(); err != nil {
+			logger.Warn("Redis ping failed, using local rate limiting", zap.Error(err))
+			m.redis = nil
+		}
+	}
+
+	// Start cleanup goroutine for local limiters
+	if cfg.CleanupInterval > 0 {
+		go m.cleanupLoop()
+	}
+
+	return m, nil
+}
+
+// Handler is the middleware handler function
+func (m *RateLimitMiddleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Get rate limit key
+		key := m.getKey(r)
+
+		// Check rate limit
+		allowed, remaining, reset := m.checkLimit(r.Context(), key)
+
+		// Set rate limit headers
+		w.Header().Set("X-RateLimit-Limit", fmt.Sprintf("%.0f", m.config.RequestsPerSec))
+		w.Header().Set("X-RateLimit-Remaining", fmt.Sprintf("%d", remaining))
+		w.Header().Set("X-RateLimit-Reset", fmt.Sprintf("%d", reset))
+
+		if !allowed {
+			w.Header().Set("Retry-After", fmt.Sprintf("%d", reset-time.Now().Unix()))
+			http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (m *RateLimitMiddleware) getKey(r *http.Request) string {
+	var parts []string
+
+	// Get tenant from context
+	if m.config.PerTenant {
+		if tenantID := r.Context().Value(ContextKeyTenantID); tenantID != nil {
+			parts = append(parts, fmt.Sprintf("tenant:%s", tenantID))
+		}
+	}
+
+	// Get user from context
+	if m.config.PerUser {
+		if userID := r.Context().Value(ContextKeyUserID); userID != nil {
+			parts = append(parts, fmt.Sprintf("user:%s", userID))
+		}
+	}
+
+	// Fall back to IP if no tenant/user
+	if len(parts) == 0 {
+		parts = append(parts, fmt.Sprintf("ip:%s", getClientIP(r)))
+	}
+
+	key := ""
+	for i, part := range parts {
+		if i > 0 {
+			key += ":"
+		}
+		key += part
+	}
+
+	return key
+}
+
+func (m *RateLimitMiddleware) checkLimit(ctx context.Context, key string) (allowed bool, remaining int, reset int64) {
+	// Use Redis for distributed rate limiting if available
+	if m.redis != nil {
+		return m.checkRedisLimit(ctx, key)
+	}
+
+	// Fall back to local rate limiting
+	return m.checkLocalLimit(key)
+}
+
+func (m *RateLimitMiddleware) checkLocalLimit(key string) (allowed bool, remaining int, reset int64) {
+	// Get or create limiter for this key
+	limiterI, _ := m.limiters.LoadOrStore(key, &limiterEntry{
+		limiter:    rate.NewLimiter(rate.Limit(m.config.RequestsPerSec), m.config.BurstSize),
+		lastAccess: time.Now(),
+	})
+
+	entry := limiterI.(*limiterEntry)
+	entry.lastAccess = time.Now()
+
+	// Check if request is allowed
+	allowed = entry.limiter.Allow()
+
+	// Calculate remaining tokens (approximate)
+	tokens := entry.limiter.Tokens()
+	if tokens < 0 {
+		remaining = 0
+	} else {
+		remaining = int(tokens)
+	}
+
+	// Reset time is when a token will be available
+	reset = time.Now().Add(entry.limiter.Reserve().Delay()).Unix()
+
+	return allowed, remaining, reset
+}
+
+func (m *RateLimitMiddleware) checkRedisLimit(ctx context.Context, key string) (allowed bool, remaining int, reset int64) {
+	redisKey := fmt.Sprintf("ratelimit:%s", key)
+	now := time.Now()
+	windowStart := now.Truncate(time.Second)
+	windowEnd := windowStart.Add(time.Second)
+
+	// Use Redis MULTI/EXEC for atomic operations
+	pipe := m.redis.Pipeline()
+
+	// Increment counter
+	incrCmd := pipe.Incr(ctx, redisKey)
+	pipe.ExpireAt(ctx, redisKey, windowEnd.Add(time.Second))
+
+	_, err := pipe.Exec(ctx)
+	if err != nil {
+		m.logger.Warn("Redis rate limit check failed", zap.Error(err))
+		// Fall back to local limiting on Redis error
+		return m.checkLocalLimit(key)
+	}
+
+	count := incrCmd.Val()
+	limit := int64(m.config.RequestsPerSec)
+
+	allowed = count <= limit
+	remaining = int(limit - count)
+	if remaining < 0 {
+		remaining = 0
+	}
+	reset = windowEnd.Unix()
+
+	return allowed, remaining, reset
+}
+
+type limiterEntry struct {
+	limiter    *rate.Limiter
+	lastAccess time.Time
+}
+
+func (m *RateLimitMiddleware) cleanupLoop() {
+	ticker := time.NewTicker(m.config.CleanupInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			m.cleanup()
+		case <-m.stop:
+			return
+		}
+	}
+}
+
+func (m *RateLimitMiddleware) cleanup() {
+	expiry := time.Now().Add(-m.config.CleanupInterval * 2)
+
+	m.limiters.Range(func(key, value interface{}) bool {
+		entry := value.(*limiterEntry)
+		if entry.lastAccess.Before(expiry) {
+			m.limiters.Delete(key)
+		}
+		return true
+	})
+}
+
+// Close stops the cleanup goroutine
+func (m *RateLimitMiddleware) Close() {
+	close(m.stop)
+	if m.redis != nil {
+		m.redis.Close()
+	}
+}
+
+func getClientIP(r *http.Request) string {
+	// Check X-Forwarded-For header
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		// Take the first IP in the chain
+		if idx := len(xff); idx > 0 {
+			for i, c := range xff {
+				if c == ',' {
+					return xff[:i]
+				}
+			}
+			return xff
+		}
+	}
+
+	// Check X-Real-IP header
+	if xrip := r.Header.Get("X-Real-IP"); xrip != "" {
+		return xrip
+	}
+
+	// Fall back to remote address
+	return r.RemoteAddr
+}

internal/gateway/middleware/tracing.go

@@ -0,0 +1,96 @@
+package middleware
+
+import (
+	"net/http"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// TracingMiddleware adds OpenTelemetry tracing to requests
+type TracingMiddleware struct {
+	tracer trace.Tracer
+}
+
+// NewTracingMiddleware creates a new tracing middleware
+func NewTracingMiddleware(tracer trace.Tracer) *TracingMiddleware {
+	return &TracingMiddleware{
+		tracer: tracer,
+	}
+}
+
+// Handler is the middleware handler function
+func (m *TracingMiddleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Start span
+		ctx, span := m.tracer.Start(r.Context(), r.URL.Path,
+			trace.WithSpanKind(trace.SpanKindServer),
+		)
+		defer span.End()
+
+		// Add request attributes
+		span.SetAttributes(
+			attribute.String("http.method", r.Method),
+			attribute.String("http.url", r.URL.String()),
+			attribute.String("http.host", r.Host),
+			attribute.String("http.user_agent", r.UserAgent()),
+			attribute.String("http.remote_addr", r.RemoteAddr),
+		)
+
+		// Add request ID if present
+		if requestID := r.Header.Get("X-Request-ID"); requestID != "" {
+			span.SetAttributes(attribute.String("http.request_id", requestID))
+		}
+
+		// Wrap response writer to capture status
+		rw := &tracingResponseWriter{
+			ResponseWriter: w,
+			statusCode:     http.StatusOK,
+		}
+
+		// Call next handler with traced context
+		next.ServeHTTP(rw, r.WithContext(ctx))
+
+		// Add response attributes
+		span.SetAttributes(
+			attribute.Int("http.status_code", rw.statusCode),
+			attribute.Int("http.response_size", rw.size),
+		)
+
+		// Add user context if available
+		if userID := UserIDFromContext(ctx); userID != "" {
+			span.SetAttributes(attribute.String("user.id", userID))
+		}
+		if tenantID := TenantIDFromContext(ctx); tenantID != "" {
+			span.SetAttributes(attribute.String("tenant.id", tenantID))
+		}
+
+		// Mark error status
+		if rw.statusCode >= 400 {
+			span.SetAttributes(attribute.Bool("error", true))
+		}
+	})
+}
+
+type tracingResponseWriter struct {
+	http.ResponseWriter
+	statusCode int
+	size       int
+}
+
+func (rw *tracingResponseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	rw.ResponseWriter.WriteHeader(code)
+}
+
+func (rw *tracingResponseWriter) Write(b []byte) (int, error) {
+	size, err := rw.ResponseWriter.Write(b)
+	rw.size += size
+	return size, err
+}
+
+func (rw *tracingResponseWriter) Flush() {
+	if f, ok := rw.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}

internal/gateway/observability/metrics.go

@@ -0,0 +1,104 @@
+// Package observability provides metrics for the API Gateway.
+package observability
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+	// HTTPRequestsTotal counts total HTTP requests
+	HTTPRequestsTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "gateway_http_requests_total",
+		Help: "Total HTTP requests",
+	}, []string{"method", "path", "status", "cached"})
+
+	// HTTPRequestDuration tracks request latency
+	HTTPRequestDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "gateway_http_request_duration_seconds",
+		Help:    "HTTP request duration in seconds",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"method", "path"})
+
+	// WebSocketConnections tracks active connections
+	WebSocketConnections = promauto.NewGauge(prometheus.GaugeOpts{
+		Name: "gateway_websocket_connections_active",
+		Help: "Active WebSocket connections",
+	})
+
+	// RateLimitHits counts rate limit violations
+	RateLimitHits = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "gateway_rate_limit_hits_total",
+		Help: "Total rate limit hits",
+	}, []string{"tenant", "user"})
+
+	// CacheHits tracks cache performance
+	CacheHits = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "gateway_cache_hits_total",
+		Help: "Cache hit/miss counts",
+	}, []string{"hit"})
+
+	// CircuitBreakerState tracks circuit breaker states
+	CircuitBreakerState = promauto.NewGaugeVec(prometheus.GaugeOpts{
+		Name: "gateway_circuit_breaker_state",
+		Help: "Circuit breaker state (0=closed, 1=open, 2=half-open)",
+	}, []string{"service"})
+
+	// JWTValidationErrors counts auth failures
+	JWTValidationErrors = promauto.NewCounter(prometheus.CounterOpts{
+		Name: "gateway_jwt_validation_errors_total",
+		Help: "JWT validation errors",
+	})
+
+	// QueryLatency tracks query processing time
+	QueryLatency = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "gateway_query_latency_seconds",
+		Help:    "Query processing latency",
+		Buckets: []float64{.01, .05, .1, .25, .5, 1, 2.5, 5, 10},
+	}, []string{"agent_id", "cached"})
+
+	// StreamingChunks counts streamed chunks
+	StreamingChunks = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "gateway_streaming_chunks_total",
+		Help: "Total streaming chunks sent",
+	}, []string{"type"})
+)
+
+// RecordRequest records HTTP request metrics
+func RecordRequest(method, path, status string, cached bool, duration float64) {
+	cachedStr := "false"
+	if cached {
+		cachedStr = "true"
+	}
+	HTTPRequestsTotal.WithLabelValues(method, path, status, cachedStr).Inc()
+	HTTPRequestDuration.WithLabelValues(method, path).Observe(duration)
+}
+
+// RecordCacheHit records cache hit/miss
+func RecordCacheHit(hit bool) {
+	hitStr := "false"
+	if hit {
+		hitStr = "true"
+	}
+	CacheHits.WithLabelValues(hitStr).Inc()
+}
+
+// RecordRateLimit records rate limit event
+func RecordRateLimit(tenant, user string) {
+	RateLimitHits.WithLabelValues(tenant, user).Inc()
+}
+
+// SetCircuitBreakerState sets circuit breaker gauge
+func SetCircuitBreakerState(service string, state int) {
+	CircuitBreakerState.WithLabelValues(service).Set(float64(state))
+}
+
+// IncrementWSConnections increments active WS connections
+func IncrementWSConnections() {
+	WebSocketConnections.Inc()
+}
+
+// DecrementWSConnections decrements active WS connections
+func DecrementWSConnections() {
+	WebSocketConnections.Dec()
+}