---
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:

```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