README.md

metadata

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