Upload 4 files

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1
+RUN useradd --create-home --uid 1000 user
+WORKDIR /home/user/app
+
+COPY --chown=user pyproject.toml ./
+COPY --chown=user src ./src
+RUN pip install ".[server,openai]"
+COPY --chown=user fgao.yaml ./
+COPY --chown=user data ./data
+
+USER user
+EXPOSE 7860
+CMD ["fgao", "serve", "--config", "fgao.yaml", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,15 +1,69 @@
 ---
 title: FGAO API
-emoji: 🐢
-colorFrom: blue
-colorTo: pink
-sdk: gradio
-sdk_version: 6.31.0
-python_version: '3.13'
-app_file: app.py
+emoji: 🧭
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+app_port: 7860
 pinned: false
-license: apache-2.0
-short_description: Feedback-Greedy Agentic Orchestration
+short_description: HTTP API for training-free FGAO orchestration of RAG
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FGAO API
+
+FGAO (Feedback-Greedy Agentic Orchestration) is a **retrieval-augmented question-answering API**.
+
+## What it does
+
+For each question, FGAO decides step by step which retrieval and LLM operations to run:
+- **Sources:** which source to query, and how deep to search it.
+- **Grading:** whether to grade the passages first.
+- **Fallback:** when to fall back to a second source.
+- **Checking:** when to check the answer against the passage it came from.
+- **Abstaining:** when to stop and give no answer.
+
+It returns an answer only if that answer is **grounded** in a retrieved passage and **passed a support check**; otherwise it returns `answer: null`. Every response includes the decision trace.
+
+## Why it is supposed to be better
+
+- **No LLM decides the control flow.** Each step is chosen by an explicit score: predicted progress on checkable goals, minus cost, plus a one-step lookahead. Decisions are cheap, deterministic and inspectable. A prompt cannot talk the pipeline out of verifying.
+- **Feedback within the question.** When an operation fails, FGAO's estimate for it and for similar operations drops, so it escalates instead of repeating itself. Fixed pipelines such as CRAG and Self-RAG hard-code those rules.
+- **Budget-aware.** Each operation has a cost. FGAO stops when nothing left is worth its cost, rather than running a fixed sequence.
+- **Abstains when unsure.** An answer that is not grounded and supported is never returned.
+- **Training-free.** There are no learned weights, so any LLM and any retriever can be swapped in.
+
+## How to use
+
+1. Add a Space secret `HF_TOKEN` (Settings → Variables and secrets). The LLM is called through Hugging Face Inference Providers; change `model` in `fgao.yaml` to use another model.
+2. Optionally add `FGAO_API_KEYS=key1,key2` to require `Authorization: Bearer <key>`.
+
+Ask with your own passages:
+
+```bash
+curl -X POST https://<space-host>/v1/answer -H "Content-Type: application/json" -d '{
+  "question": "What is the capital of Peru?",
+  "documents": ["Lima is the capital of Peru.", {"title": "Chile", "text": "Santiago is the capital of Chile."}],
+  "trace": false
+}'
+```
+
+To ask over the built-in corpus instead (`data/kb.jsonl`, one `{"text", "title", "id"}` per line; replace it with your own), omit `documents`.
+
+From Python:
+
+```python
+import requests
+r = requests.post("https://<space-host>/v1/answer", json={"question": "...", "documents": [...]}).json()
+r["answer"], r["support_passage"], r["trace"]
+```
+
+| endpoint | |
+|---|---|
+| `POST /v1/answer` | `question`, plus optional `documents`, `web_documents`, `budget`, `trace` |
+| `POST /v1/answer/stream` | the same, as Server-Sent Events: one `step` per decision, then `result` |
+| `POST /v1/batch` | `questions: [...]`, plus optional `documents` |
+| `GET /v1/info`, `/health`, `/metrics`, `/docs` | configuration, health, Prometheus metrics, interactive API docs |
+
+The `<space-host>` is shown under "Embed this Space" → "Direct URL", for example `angshul-fgao-api.hf.space`.
+
+Library and source: https://github.com/AngshulMajumdar/FGAO

fgao.yaml

@@ -0,0 +1,14 @@
+# FGAO API configuration. Paths are relative to this file.
+llm:
+  provider: openai                         # any OpenAI-compatible endpoint
+  base_url: https://router.huggingface.co/v1
+  model: Qwen/Qwen2.5-7B-Instruct          # any chat model served by Hugging Face Inference Providers
+  api_key_env: HF_TOKEN                    # Space secret
+  temperature: 0
+  max_tokens: 128
+  timeout: 60
+resilience: {attempts: 3, backoff: 0.5, timeout: 60, max_concurrency: 32}
+kb: {type: bm25, path: data/kb.jsonl}      # default corpus; requests may send their own "documents"
+budget: 16
+on_error: record
+server: {max_inflight: 32, max_queue: 256, request_timeout: 300, max_batch: 64, max_documents: 500}

pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fgao"
+version = "1.0.0"
+description = "Feedback-Greedy Agentic Orchestration: a training-free numerical controller for RAG and tool-using pipelines"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Angshul Majumdar", email = "angshul@iiitd.ac.in" }]
+keywords = ["rag", "orchestration", "agents", "retrieval-augmented-generation", "langchain", "langgraph", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://angshulmajumdar.github.io/FGAO/"
+Repository = "https://github.com/AngshulMajumdar/FGAO"
+Documentation = "https://github.com/AngshulMajumdar/FGAO/tree/main/docs"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+langgraph = ["langgraph>=0.2", "langchain-core>=0.3"]
+huggingface = ["huggingface_hub>=0.24"]
+transformers = ["transformers>=4.40"]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+demo = ["gradio>=4.44", "huggingface_hub>=0.24"]
+server = ["fastapi>=0.110", "uvicorn[standard]>=0.29", "pyyaml>=6", "httpx>=0.27"]
+mcp = ["mcp>=1.0"]
+all = ["langchain-core>=0.3", "langgraph>=0.2", "huggingface_hub>=0.24", "openai>=1.0", "anthropic>=0.30",
+       "fastapi>=0.110", "uvicorn[standard]>=0.29", "pyyaml>=6", "httpx>=0.27", "mcp>=1.0"]
+dev = ["pytest>=7"]
+
+[project.scripts]
+fgao = "fgao.server.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fgao = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]