Update README.md

README.md

@@ -9,4 +9,176 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 RAG Agent Workbench — Backend API (FastAPI on Docker Spaces)
+
+A production-style Retrieval-Augmented Generation (RAG) backend deployed on **Hugging Face Spaces (Docker)**.
+
+- **Vector DB:** Pinecone (serverless)  
+- **LLM:** Groq (OpenAI-compatible)  
+- **Web fallback:** Tavily (optional)  
+- **Orchestration:** LangGraph / LangChain  
+- **Observability:** LangSmith tracing (optional)  
+- **Security:** API Key required (Swagger + OpenAPI + endpoints)
+
+> This Space is public, but the API is protected via `X-API-Key` so it can’t be used without your key.
+
+---
+
+## ✅ API Endpoints
+
+Typical endpoints you can expect:
+
+- `GET /health` — health check  
+- `POST /chat` — RAG chat (optionally web fallback)  
+- `POST /search` — semantic retrieval  
+- `POST /documents/upload-text` — upload raw text for indexing  
+- `POST /ingest/wiki` — ingest from Wikipedia REST API  
+- `POST /ingest/arxiv` — ingest from arXiv API  
+- `POST /ingest/openalex` — ingest from OpenAlex API  
+- `GET /documents/stats` — namespace/vector stats  
+- `GET /metrics` — in-app metrics (latency, counts, cache hits, etc.)
+
+Swagger/OpenAPI:
+- `/docs` (Swagger UI)
+- `/openapi.json`
+
+> If API key protection is enabled, `/docs` and `/openapi.json` are also protected.
+
+---
+
+## 🔐 Authentication (API Key)
+
+All protected endpoints require:
+
+- Header: `X-API-Key: <YOUR_API_KEY>`
+
+If `API_KEY` is set in Space secrets, anonymous access is blocked.
+
+---
+
+## ⚙️ Configuration (Space Secrets & Variables)
+
+Hugging Face Spaces lets you set **Secrets/Variables in Space Settings**; inside the container they are available as environment variables. :contentReference[oaicite:1]{index=1}
+
+Go to:
+**Space → Settings → Variables and secrets**
+
+### Required (Pinecone)
+- `PINECONE_API_KEY` (Secret)
+- `PINECONE_HOST` (Secret or Variable)
+- `PINECONE_INDEX_NAME` (Variable) — e.g. `rag-agent-workbench`
+- `PINECONE_NAMESPACE` (Variable) — e.g. `dev`
+- `PINECONE_TEXT_FIELD` (Variable) — `content` (for integrated embedding field mapping)
+
+### Required (Groq)
+Groq supports OpenAI-compatible clients via `base_url = https://api.groq.com/openai/v1`. :contentReference[oaicite:2]{index=2}
+
+- `GROQ_API_KEY` (Secret)
+- `GROQ_BASE_URL` (Variable) — `https://api.groq.com/openai/v1`
+- `GROQ_MODEL` (Variable) — choose your Groq model (e.g., `llama-3.1-8b-instant`)
+
+### Optional (Tavily web fallback)
+- `TAVILY_API_KEY` (Secret)
+
+### Optional (LangSmith tracing)
+LangSmith commonly uses environment variables like `LANGCHAIN_API_KEY` and `LANGCHAIN_TRACING_V2=true`; project can be set via `LANGCHAIN_PROJECT` (or `LANGSMITH_PROJECT` depending on SDK usage). :contentReference[oaicite:3]{index=3}
+
+- `LANGCHAIN_TRACING_V2` (Variable) — `true`
+- `LANGCHAIN_API_KEY` (Secret)
+- `LANGCHAIN_PROJECT` (Variable) — e.g. `rag-agent-workbench`
+
+### Strongly recommended (Security)
+- `API_KEY` (Secret) — required to call API endpoints
+
+### Optional (Ops toggles)
+- `LOG_LEVEL` — `INFO`
+- `CACHE_ENABLED` — `true/false`
+- `RATE_LIMIT_ENABLED` — `true/false`
+- `ALLOWED_ORIGINS` — comma-separated list (if you need strict CORS)
+
+> Any change to Space secrets/variables triggers a restart. :contentReference[oaicite:4]{index=4}
+
+---
+
+## 🚀 How to Test This Space
+
+Replace:
+- `SPACE_URL = https://<your-space-subdomain>.hf.space`
+- `KEY = your API key`
+
+### 1) Health
+curl -i "$SPACE_URL/health"
+
+### 2) OpenAPI / Swagger (requires key if protected)
+curl -i "$SPACE_URL/openapi.json" -H "X-API-Key: $KEY"
+
+### 3) Search
+curl -X POST "$SPACE_URL/search" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"query":"What is RAG?","top_k":5,"namespace":"dev"}'
+
+### 4) Chat
+curl -X POST "$SPACE_URL/chat" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"query":"Explain RAG in 5 bullets.","namespace":"dev","top_k":5,"use_web_fallback":false}'
+
+### 5) Upload text document
+curl -X POST "$SPACE_URL/documents/upload-text" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{
+        "title":"Demo doc",
+        "source":"space-readme",
+        "namespace":"dev",
+        "text":"RAG = retrieval augmented generation ...",
+        "metadata":{"tag":"demo"}
+      }'
+
+---
+
+## 🐳 Local Docker Run (same image behavior as Spaces)
+
+Docker Spaces is configured via YAML front-matter (`sdk: docker`, `app_port`) and expects the app to listen on the configured port (commonly 7860). :contentReference[oaicite:5]{index=5}
+
+Build:
+docker build -t rag-agent-workbench-api:local .
+
+Run:
+docker run --rm -p 7860:7860 \
+  -e API_KEY="your_key" \
+  -e PINECONE_API_KEY="..." \
+  -e PINECONE_HOST="..." \
+  -e PINECONE_INDEX_NAME="rag-agent-workbench" \
+  -e PINECONE_NAMESPACE="dev" \
+  -e PINECONE_TEXT_FIELD="content" \
+  -e GROQ_API_KEY="..." \
+  -e GROQ_BASE_URL="https://api.groq.com/openai/v1" \
+  -e GROQ_MODEL="llama-3.1-8b-instant" \
+  rag-agent-workbench-api:local
+
+Then open:
+- http://127.0.0.1:7860/health
+- http://127.0.0.1:7860/docs (add X-API-Key if protected)
+
+---
+
+## 🧯 Troubleshooting
+
+### Space starts but endpoints 404 / not reachable
+- Confirm `app_port: 7860` in YAML and container listens on that port. :contentReference[oaicite:6]{index=6}
+
+### 403 on everything
+- You enabled `API_KEY` but forgot to send `X-API-Key` header.
+
+### Web fallback not working
+- Ensure `TAVILY_API_KEY` is set in Space secrets.
+
+### LangSmith traces missing
+- Ensure `LANGCHAIN_TRACING_V2=true` and `LANGCHAIN_API_KEY` are set. :contentReference[oaicite:7]{index=7}
+
+---
+
+## 📄 License
+MIT recommended for open-source portfolios