README.md

---
title: Rag Agent Workbench Api
emoji: 👁
colorFrom: indigo
colorTo: red
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# 🧠 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