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

**macOS / Linux**

```bash theme={null}
source .venv/bin/activate
```

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

**macOS / Linux**

```bash theme={null}
cp .env.example .env
```

**PowerShell**

```powershell theme={null}
Copy-Item .env.example .env
```

Choose a provider configuration in `.env`:

**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.

**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.