> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Framework recipes

> Copyable EvalGate setup paths for Node, Next.js, Python, FastAPI, LangChain, and RAG applications.

# Framework recipes

Use these recipes after the [quick start](/docs/quickstart). Each path keeps the same operating loop: create a baseline, capture traces, promote reviewed failures into eval coverage, and gate regressions in CI.

## Pick the shortest path

| Runtime           | Start here                                         | Proof you should see                              |
| ----------------- | -------------------------------------------------- | ------------------------------------------------- |
| Node or Next.js   | Local gate plus API trace                          | `evals/regression-report.json` and a trace record |
| Python or FastAPI | Python SDK and bundled CLI                         | `evalgate gate` result and async trace code       |
| LangChain or RAG  | Trace retrieval, label misses, synthesize coverage | Clustered failure modes and promoted golden cases |

## Node or Next.js

Use this when your app already has `npm test`, `pnpm test`, or a similar quality command.

```bash theme={null} theme={null}
npx @evalgate/sdk init
npx @evalgate/sdk init --apply
npx @evalgate/sdk baseline update
npx @evalgate/sdk gate
```

Add a trace around the code path you want reviewers to inspect:

```ts app/api/support/route.ts theme={null} theme={null}
import { AIEvalClient } from "@evalgate/sdk";

const evalgate = AIEvalClient.init();

export async function POST(request: Request) {
  const { message } = await request.json();
  const traceId = `support-${Date.now()}`;

  const answer = await answerSupportQuestion(message);

  const trace = await evalgate.traces.create({
    name: "support-chat",
    traceId,
    metadata: {
      runtime: "nextjs",
      model: "configured-by-app",
    },
  });

  await evalgate.traces.createSpan(trace.id, {
    name: "answerSupportQuestion",
    spanId: `${traceId}-llm`,
    startTime: new Date().toISOString(),
    metadata: {
      inputLength: message.length,
      outputLength: answer.length,
    },
  });

  return Response.json({ answer, traceId });
}
```

Gate the same behavior in CI:

```bash theme={null} theme={null}
npx @evalgate/sdk ci --format github --write-results --base main
```

## Python or FastAPI

Install the SDK and bundled CLI:

```bash theme={null} theme={null}
pip install evalgate-sdk
evalgate init
evalgate init --apply
evalgate baseline update
evalgate gate
```

Add an async trace in the request path:

```python app.py theme={null} theme={null}
from datetime import datetime, timezone

from evalgate_sdk import AIEvalClient
from evalgate_sdk.types import CreateSpanParams, CreateTraceParams
from fastapi import FastAPI

app = FastAPI()
evalgate = AIEvalClient.init()


@app.post("/support")
async def support(payload: dict):
    message = payload["message"]
    trace_id = f"support-{int(datetime.now(timezone.utc).timestamp())}"

    answer = await answer_support_question(message)

    trace = await evalgate.traces.create(
        CreateTraceParams(
            name="support-chat",
            trace_id=trace_id,
            metadata={"runtime": "fastapi", "model": "configured-by-app"},
        )
    )

    await evalgate.traces.create_span(
        trace.id,
        CreateSpanParams(
            name="answer_support_question",
            span_id=f"{trace_id}-llm",
            start_time=datetime.now(timezone.utc).isoformat(),
            metadata={
                "input_length": len(message),
                "output_length": len(answer),
            },
        ),
    )

    return {"answer": answer, "trace_id": trace_id}
```

Run the local proof before opening a PR:

```bash theme={null} theme={null}
evalgate doctor --quick
evalgate gate
```

## LangChain or RAG

For agents, chains, and retrieval systems, start by tracing the workflow shape. Then label the traces that reveal missed intent, wrong tool use, unsupported claims, stale retrieval, or unsafe output.

```bash theme={null} theme={null}
npx @evalgate/sdk label
npx @evalgate/sdk analyze
npx @evalgate/sdk cluster --run .evalgate/runs/latest.json
npx @evalgate/sdk synthesize \
  --dataset .evalgate/golden/labeled.jsonl \
  --output .evalgate/golden/synthetic.jsonl
```

Use the generated cases as drafts. Keep them quarantined until a reviewer promotes them:

```bash theme={null} theme={null}
npx @evalgate/sdk gate --format github
```

## The proof packet

Every recipe should produce the same reviewer packet before a change merges:

| Artifact                       | Why it matters                                              |
| ------------------------------ | ----------------------------------------------------------- |
| `evalgate.config.json`         | Defines the command, baseline, thresholds, and judge policy |
| `evals/baseline.json`          | Captures the current approved behavior                      |
| `.evalgate/runs/latest.json`   | Shows the latest case-level result and metadata             |
| `evals/regression-report.json` | Summarizes the local gate outcome                           |
| GitHub step summary            | Puts pass/fail evidence where reviewers already work        |

If one of those artifacts is missing, run:

```bash theme={null} theme={null}
npx @evalgate/sdk doctor --quick
npx @evalgate/sdk gate --format json
```