Automated deployment update

README.md

@@ -1,467 +1,31 @@
-# 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
-```
-
----
-
-## 📡 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 |
-
+title: AmaniQuery Agent
+emoji: ⚖️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
 ---
 
-## 🔒 Security
+## AmaniQuery Agent on Hugging Face Spaces
 
-AmaniQuery implements enterprise-grade security:
+This Space hosts the AmaniQuery Agent API, a Go-based RAG service for legal and civic information in Kenya.
 
-- **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
+## Configuration
 
----
-
-## 📈 Observability
-
-- **Metrics**: Prometheus + Grafana dashboards
-- **Tracing**: Jaeger distributed tracing
-- **Logging**: Structured JSON logs with correlation IDs
-- **Alerting**: PagerDuty/Slack integration
-
----
+This Space is configured using the Docker SDK. The Dockerfile is located at root.
 
-## 🤝 Contributing
+### Environment Variables
 
-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
-
----
+The following secrets must be set in the Space settings:
 
-<p align="center">
-  <b>AmaniQuery</b> - Democratizing Access to Legal Knowledge
-</p>
+- `OPENAI_API_KEY`: API key for OpenAI (if using OpenAI models)
+- `QDRANT_URL`: URL for Qdrant vector database (e.g., Qdrant Cloud)
+- `QDRANT_API_KEY`: API key for Qdrant
+- `REDIS_URL`: URL for Redis cache (e.g., Upstash)
+- `DB_HOST`: PostgreSQL host (e.g., Neon.tech)
+- `DB_PORT`: PostgreSQL port
+- `DB_USER`: PostgreSQL user
+- `DB_PASSWORD`: PostgreSQL password
+- `DB_NAME`: PostgreSQL database name

scripts/deploy_hf.py

@@ -113,11 +113,8 @@ def deploy_service(service_type):
         print("Configuring deployment artifacts...")
         shutil.copy2(project_root / dockerfile_src, Path(temp_dir) / "Dockerfile")
         
-        # Only copy README if it doesn't exist or we want to force update (usually we want to keep Space metadata)
-        # For first deploy we absolutely need it.
-        target_readme = Path(temp_dir) / "README.md"
-        if not target_readme.exists():
-             shutil.copy2(project_root / readme_src, target_readme)
+        # Always overwrite README to ensure correct configuration
+        shutil.copy2(project_root / readme_src, Path(temp_dir) / "README.md")
         
         # Commit and push
         print("Pushing changes...")