README.md

metadata

title: FGAO API
emoji: 🧭
colorFrom: indigo
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
short_description: HTTP API for training-free FGAO orchestration of RAG

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:

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:

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