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

> ## Agent Instructions
> LoopGuard is a Python runtime guardrail SDK. Install loopguard-runtime and import loopguard. Use /getting-started and /guides/integration for application code.
> Use the Concepts section for agent loops, tests versus traces versus evals, and trajectory/convergence. The convergence helper compares counts without checking success; LoopGuard events are not OpenTelemetry spans. Distinguish these general concepts from implemented SDK features.
> The exact, semantic, calc, and trap UI examples illustrate Python SDK detection behavior. Read /demo/scenarios for runnable SDK examples and /guides/integration to attach callbacks or inspect streamed updates.
> These docs follow the checkout. PyPI 0.2.1 lacks Gemini support, controlled demo scenarios, and additional decision display fields; check /development/status before describing release capabilities.
> Repetition alone does not force STOP. REPLAN and PAUSE are recorded recommendations. Observe-only mode records decisions without raising. Follow /guides/integration for interrupt propagation.
> Use the Python API, CLI, and configuration references for supported names and flags. Screenshots illustrate observed runs, not guaranteed stop counts or benchmark results.

# Run the demo UI

> Start the local backend and frontend, then compare healthy and stuck runs.

The demo runs on your machine: a FastAPI backend streams events over WebSocket,
and a Next.js frontend displays the graph, decisions, event log, and metrics.
Start with `exact`; it needs no provider credentials.

## Set up the checkout

You need Python 3.11+, pip, Git, and Node.js with npm. The UI uses Next.js 16;
use a supported Node.js version for that release.

```bash theme={null}
git clone https://github.com/mahimathacker/loopguard.git
cd loopguard
python -m venv .venv
```

Activate the environment:

> [tab] macOS / Linux
>
> ```bash theme={null}
> source .venv/bin/activate
> ```

> [tab] PowerShell
>
> ```powershell theme={null}
> .\.venv\Scripts\Activate.ps1
> ```

Install the source checkout and demo dependencies:

```bash theme={null}
pip install -e ".[demo,server]"
```

The base PyPI install doesn't include the backend, model SDKs, or frontend.
`requirements.txt` is another supported source-demo installation path.

## Choose an offline or provider-backed run

For `exact`, leave credentials unset. For other scenarios, create a root `.env`
file using `.env.example` as a starting point:

> [tab] macOS / Linux
>
> ```bash theme={null}
> cp .env.example .env
> ```

> [tab] PowerShell
>
> ```powershell theme={null}
> Copy-Item .env.example .env
> ```

Choose a provider configuration in `.env`:

> [tab] OpenAI
>
> ```dotenv theme={null}
> OPENAI_API_KEY=your-key
> LOOPGUARD_MODEL_PROVIDER=openai
> LOOPGUARD_EMBEDDING_PROVIDER=openai
> ```
>
> The demo chat-model default is `gpt-4o-mini`.
> `LOOPGUARD_OPENAI_MODEL` overrides it.

> [tab] Gemini
>
> ```dotenv theme={null}
> GOOGLE_API_KEY=your-key
> LOOPGUARD_MODEL_PROVIDER=gemini
> LOOPGUARD_EMBEDDING_PROVIDER=gemini
> ```
>
> `GEMINI_API_KEY` is also accepted. The source chat-model default is
> `gemini-3.6-flash`; `LOOPGUARD_GEMINI_MODEL` overrides it. Confirm that the
> configured model and the embedding model are available to your account.

Set both provider selectors explicitly. The embedding library defaults independently
to OpenAI, even if the chat-model selector is Gemini. Restart the backend after
editing `.env`; existing process environment values take precedence over the file.

> [!NOTE]
>
> `semantic` needs embeddings but no chat model. `controlled_progress`,
> `controlled_503`, and `controlled_401` need a chat model but no embeddings.
> `controlled_empty`, `calc`, and `trap` need both. Provider-backed runs may incur
> API charges; the `trap` scenario also performs real web searches.

## Start the backend

In a terminal at the repository root with the Python environment active:

```bash theme={null}
uvicorn server:app --reload --port 8000
```

Check `http://localhost:8000/runtime` to see the selected providers and chat model.
This endpoint does not test credentials or model access.

## Start the frontend

In a second terminal at the repository root:

```bash theme={null}
cd ui
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). Choose **Scripted: identical
tool loop**, then select **Run**. Watch repeated empty results build evidence until
the run stops.

![LoopGuard demo main interface with an agent-tool graph, repeated tool observations, and metrics](https://mintcdn.com/loopguard/XpzeUOn7Yfd_-2Y1/images/exact-loop.png?fit=max\&auto=format\&n=XpzeUOn7Yfd_-2Y1\&q=85\&s=a83a57d59d6367ef991f704247894c34)

The graph, event log, and metrics show a stuck LoopGuard demo run.

## Change the backend address

The frontend defaults to `http://localhost:8000` and derives the WebSocket address
from it. To use a different backend, set `NEXT_PUBLIC_LOOPGUARD_API` in
`ui/.env.local`, then restart the frontend:

```dotenv theme={null}
NEXT_PUBLIC_LOOPGUARD_API=http://localhost:8000
```

The browser must be able to reach that address. See
[connection troubleshooting](https://loopguard.mintlify.site/troubleshooting.md#ui-cannot-connect-to-the-backend).

## Use the terminal instead

With the Python environment active, from the repository root:

```bash theme={null}
python main.py exact
python main.py controlled_503
```

The backend and browser use the same scenario definitions as this CLI. See
[demo scenarios](https://loopguard.mintlify.site/demo/scenarios.md) for expected behavior and provider requirements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.