ORRA RAG AGENT

orra-rag-agent is a hybrid enterprise AI agent built for ORRA. It utilizes a robust, RAGAS-evaluated retrieval pipeline and features a FastAPI API to allow seamless querying of ORRA documents and FAQs.

I built this to help improve how users interact with ORRA documentation and FAQ retrieval but you can absolutely use it for your own projects

It combines:

• local docs in docs
• LanceDB hybrid search for indexed documentation
• live FAQ/context retrieval from a GitHub Gist JSON payload
• optional Gemini answer generation for frontend-facing responses

API shape

• GET /health
• GET /v1/health
• POST /v1/retrieve
• POST /v1/query
• POST /v1/index/rebuild
• POST /v1/ragas/test

Project structure

The live API now lives entirely under api:

• api/main.py
• api/routers/
• api/services/
• api/schemas.py
• api/config.py

File-level documentation for the runtime path is in:

• docs/fastapi-runtime-files.md
• docs/api-file-guide.md

When a query is made from the ORRA UI search, it calls POST /v1/query with a JSON body like:

{
  "query": "How does ORRA work?",
  "top_k_docs": 5,
  "top_k_gist": 5,
  "include_context": false
}

Environment

You can adapt this to your own project.

Create a local .env file from .env.example.

Required for full functionality:

• GOOGLE_API_KEY
• APP_GIST_RAW_URL

Optional:

• APP_GIST_RECORDS_PATH
• ALLOWED_ORIGINS
• PORT

Run with uv

Install dependencies:

uv sync

Install the optional RAGAS dependency when you want to use the evaluation endpoint:

uv sync --extra eval

Start the API:

uv run orra-rag

Or with Uvicorn directly:

uv run uvicorn api.main:app --host 0.0.0.0 --port 8080 --reload

Indexing

At startup, the service creates the LanceDB index from files inside docs/ if the table does not exist.

To force a rebuild:

curl -X POST http://localhost:8080/v1/index/rebuild

RAGAS testing

POST /v1/ragas/test evaluates one or more samples against the live pipeline.

Example:

{
  "samples": [
    {
      "query": "How does ORRA work?",
      "reference": "ORRA coordinates AI agents and tools through workflows.",
      "top_k_docs": 5,
      "top_k_gist": 5
    }
  ],
  "auto_generate_response": true,
  "include_prepared_samples": true
}

Notes

• If GOOGLE_API_KEY is missing, retrieval still works but answer generation returns a configuration warning.
• POST /v1/ragas/test returns 503 until the optional eval extra is installed.