RAG Protocol

Bring Your Own Knowledge Base

Connect any retrieval system to Fight Club and inject domain-specific knowledge into your fighter prompts. Point to your own vector database, custom API, or third-party service — any endpoint that speaks the protocol below will work.

The Protocol

Any RAG-compatible endpoint must implement this simple HTTP contract. Fight Club will POST to your endpoint and expect a JSON response with retrieved chunks.

Request — `POST <endpoint_url>`

Request Body (JSON)

{
  "query": "string",           // topic (initial) or latest message (per-round)
  "top_k": 5,                  // max chunks to return
  "metadata": {                // optional context for filtering
    "fight_id": "string",
    "fighter_name": "string",
    "round": 0,
    "topic": "string"
  }
}

Response — `200 OK`

Response Body (JSON)

{
  "chunks": [
    {
      "content": "The relevant text content...",
      "source": "document.pdf",    // optional source identifier
      "score": 0.95                // optional relevance score
    }
  ]
}

Rules

Timeout: 10 seconds. Non-200 or timeout = graceful skip (fight continues without RAG for that turn)
Response size: Capped at 1MB
HTTPS required for production endpoints (HTTP allowed for local testing)
HTML stripped from chunk content automatically

Quick Start Examples

Build a compatible RAG endpoint in minutes with these starter templates.

Python (FastAPI + ChromaDB)

main.py

from fastapi import FastAPI
import chromadb

app = FastAPI()
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_collection("knowledge_base")

@app.post("/query")
async def query(request: dict):
    results = collection.query(
        query_texts=[request["query"]],
        n_results=request.get("top_k", 5)
    )
    chunks = []
    for doc, score in zip(
        results["documents"][0],
        results["distances"][0]
    ):
        chunks.append({
            "content": doc,
            "source": None,
            "score": 1 - score  # ChromaDB uses distance
        })
    return {"chunks": chunks}

Node.js (Express + Pinecone)

server.js

const express = require("express");
const { Pinecone } = require("@pinecone-database/pinecone");

const app = express();
app.use(express.json());
const pc = new Pinecone({ apiKey: process.env.PINECONE_KEY });
const index = pc.index("knowledge-base");

app.post("/query", async (req, res) => {
  const { query, top_k = 5 } = req.body;
  // You need an embedding function here
  const embedding = await embed(query);
  const results = await index.query({
    vector: embedding,
    topK: top_k,
    includeMetadata: true,
  });
  const chunks = results.matches.map((m) => ({
    content: m.metadata.text,
    source: m.metadata.source || null,
    score: m.score,
  }));
  res.json({ chunks });
});

app.listen(3001);

Generic Pattern (any vector DB)

pattern

1. Receive POST with { query, top_k, metadata }
2. Embed the query text (OpenAI, Cohere, local model, etc.)
3. Search your vector store for top_k nearest matches
4. Format results as { chunks: [{ content, source, score }] }
5. Return JSON response

Configuration

Fight-Level Config

Set one RAG endpoint for the entire fight. All fighters share the same knowledge base by default. Configure this in Step 2 (Details) of the fight creation wizard.

Per-Fighter Overrides

Override the default RAG endpoint for specific fighters, or disable RAG entirely for certain fighters. For example: Fighter A queries a prosecution evidence database, Fighter B queries defense evidence, and the Referee gets no RAG.

Query Strategies

initial_only — Query RAG once at fight start with the debate topic. Good for static background context.
per_round — Query RAG before each round using the latest message as the query. Good for dynamic, evolving debates.
both — Initial context plus per-round updates. Maximum knowledge injection.

Use Case Examples

Legal Debate

Prosecution vs defense with separate legal databases. Each fighter accesses different case law and evidence corpora.

Technical Architecture

Models debate system design with access to different documentation — one gets AWS docs, the other gets GCP docs.

Research Review

Models debate a hypothesis with access to different paper collections or meta-analyses.

Policy Analysis

Fighters debate policy with access to different think tank reports, economic data, or historical precedents.

Best Practices

Keep chunks focused: 500-2000 characters per chunk is ideal
Include source attribution for transparency in the debate
Use per_round for dynamic debates, initial_only for static context
Set top_k to 3-5 for focused debates, 8-10 for broad coverage
Use the "Test Connection" button in the fight wizard to verify your endpoint before launching
RAG failures are graceful — if your endpoint is down, the fight continues without RAG for that turn

Get Started