Metadata-Version: 2.4
Name: doloopio
Version: 0.1.0
Summary: The doloop resistance machine: deterministic checks for AI output, from the CLI.
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# doloop machine

An external, **deterministic** check you put between your AI and your users. Send it an output, get back an **objective verdict** — the same verdict every time. You bring your own model; the machine never touches it.

> Docs only. No product code lives here — just how to call the machine and copy-paste examples.

**Base URL:** `https://api.doloop.io`

## Use doloop when…

| Your problem | Call | What you get |
|---|---|---|
| Your agent **loops** or repeats itself | `POST /v1/check` | findings flag the repetition; `verdict: fail` (a model in a loop can't see its own loop — doloop can) |
| Output **drifts** or slides back to a bug it just fixed | `POST /v1/check` | the drift caught from outside |
| The model pads with **slop**, hedges, jargon | `POST /v1/check` | each tell flagged with a line |
| A **number isn't in the source**, a total won't reconcile | `documents` donkey | tie-out failure |
| You need the **same verdict every time** (audit) | `POST /v1/check` | `input_sha256` — reproducible, provable |
| You want a human to review **only the failures** | gate on `verdict` | triage, not every line |

## The four donkeys

A donkey is a deterministic check for one kind of output.

| Donkey | Catches | Surface |
|---|---|---|
| `writing` | de-slop: dead prose, jargon, self-management tics, flat cadence | https://writing.doloop.io |
| `conversations` | de-sycophant, de-loop: agreement drift, dialogue going in circles | https://conversations.doloop.io |
| `presentations` | land-the-finding: slides that bury the point or don't match the data | https://presentations.doloop.io |
| `documents` | tie-out: a number not in the source, a total that won't reconcile | https://documents.doloop.io |

```bash
curl https://api.doloop.io/v1/donkeys
```

## Quickstart

```bash
curl https://api.doloop.io/v1/check \
  -H 'content-type: application/json' \
  -d '{"text": "the answer your model just produced"}'
```

```json
{ "verdict": "pass", "finding_count": 0, "findings": [], "input_sha256": "..." }
```

Same text in, same verdict out, every time. `input_sha256` proves it: identical input gives an identical hash gives an identical verdict. **Objective, not subjective** — unlike an AI judge that scores the same answer 77% one run and 63% the next.

## How people use it

1. **Gate before ship** — check the output; if `verdict: fail`, don't ship it.
2. **Self-heal loop** (the "doloop") — check → on fail, feed `findings` back to your model → re-check → ship on pass. See [`examples/loop.py`](examples/loop.py).
3. **In-agent self-check** — the agent checks its own step output to catch the loop/drift it can't see itself. See [`examples/agent_check.py`](examples/agent_check.py).
4. **BYOL proxy** — point an OpenAI-compatible `base_url` at the machine; the verdict rides back on every response. See [`examples/proxy.py`](examples/proxy.py).
5. **CI gate** — run a corpus through the donkeys; fail the build on a regression. See [`examples/ci_check.sh`](examples/ci_check.sh).

## Endpoints

| Method | Path | Does |
|---|---|---|
| `POST` | `/v1/check` | deterministic verdict on text |
| `GET` | `/v1/donkeys` | list the four donkeys |
| `POST` | `/v1/chat/completions` | OpenAI-compatible BYOL proxy with the verdict attached |
| `GET` | `/health` | liveness |

Machine-readable spec: [`openapi.json`](openapi.json). LLM index: [`llms.txt`](llms.txt). Pricing and the loop calculator: [`PRICING.md`](PRICING.md).

## What it is

doloop is the **Deterministic Objective Loop**: the external checker a model can't be for itself, because a model in a loop can't see its own loop. Bring your model; doloop returns the verdict it can't give itself.
