<div align="center">

# Verified Regex Generator

[![Typing SVG](https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&duration=2600&pause=900&color=FFA24D&center=true&vCenter=true&width=560&lines=Generate+%2B+verify%2C+not+generate+%2B+hope;Real+test+strings.+Real+re+engine.+Real+proof.;MCP+tool+%2B+CLI-free+web+demo)](https://git.io/typing-svg)

[![Python](https://img.shields.io/badge/python-3.12-blue?logo=python&logoColor=white)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-64%20passing-34d399)](./tests)
[![MCP](https://img.shields.io/badge/protocol-MCP-6f42c1)](https://modelcontextprotocol.io)
[![FastAPI](https://img.shields.io/badge/web-FastAPI-009688?logo=fastapi&logoColor=white)](./web)
[![Groq](https://img.shields.io/badge/LLM-Groq%20%2F%20gpt--oss--120b-F55036)](https://console.groq.com/)

</div>

> **MCP → Verified Regex Generator.** The user describes a pattern in plain English. An LLM
> generates the regex. An agent generates real sample strings (positive + negative examples),
> tests the regex against them with the actual `re` engine, and iterates if it's wrong.
> Regex is infamous for *looking* right while being subtly wrong — verification is the whole
> value here, not the generation.

Runs on [Groq](https://console.groq.com) (`openai/gpt-oss-120b` by default) — fast and free-tier
friendly, so it's cheap to demo publicly.

This isn't "ask an LLM for a regex and hope." It's a closed verification loop:

```
description  ──►  LLM writes a candidate regex
                        │
description  ──►  LLM writes real test strings (incl. tricky near-misses)
                        │
                        ▼
              Python's `re` engine checks the candidate
              against every test string — ground truth,
              not the model's opinion of itself
                        │
              ┌─────────┴─────────┐
          all pass             something failed
              │                     │
              ▼                     ▼
           done               feed the exact failures
                               back to the model, try again
```

## Demo

A real run: "US phone number" → the agent writes 16 test strings, proposes a candidate regex,
checks it against Python's real `re` engine, and converges on a verified pattern in 2 iterations.

![Demo](.github/assets/demo.gif)

<details>
<summary>Full page + live tester screenshot</summary>

![Screenshot](.github/assets/screenshot.png)

</details>

## What's in here

- **`regex_agent/core.py`** — the actual agent loop (model-agnostic of transport). Everything
  else is a thin wrapper around this.
- **`mcp_server/`** — a real [MCP](https://modelcontextprotocol.io) server exposing
  `generate_verified_regex` as a tool, so it can be used directly from Claude Desktop or
  Claude Code.
- **`web/`** — a FastAPI + vanilla-JS demo with two parts:
  1. A live, animated view of the agent's reasoning: test cases, each candidate regex, and
     the pass/fail table per iteration.
  2. A **regex101-style live tester** underneath — an editable pattern field with flags
     (`g`/`i`/`m`/`s`/full-match), live match highlighting against your own test string, a
     match list with capture groups, and a plain-English token-by-token breakdown of the
     regex (all client-side, no API calls). It auto-fills with whatever the agent just
     verified, but works standalone for any regex you paste in — useful even if you already
     know regex and just want to test one.

  No MCP client required — runs in a browser.

## Setup

```bash
pip install -r requirements.txt
cp .env.example .env   # then add your GROQ_API_KEY
```

## Run the web demo

```bash
cd web
python server.py
```

Open http://127.0.0.1:8000.

## Run the MCP server

Add this to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`,
or `.claude/settings.json` for Claude Code):

```json
{
  "mcpServers": {
    "verified-regex-generator": {
      "command": "python",
      "args": ["/absolute/path/to/2 project/mcp_server/server.py"]
    }
  }
}
```

Then ask Claude something like *"Use the verified regex generator to build me a regex for a
US phone number."* — it will call the tool, which runs the full generate → test → verify loop
server-side and returns a JSON report.

## Why this is a good showcase

Most "AI writes code" demos stop at generation. This one treats the LLM's first answer as a
*hypothesis*, not an answer — and only claims success once it's checked against ground truth
(the real regex engine, on real strings, including adversarial near-misses the model itself
proposes). That loop — generate → verify → revise — is the core pattern behind reliable
agentic tools, and it's small enough to read end-to-end in `regex_agent/core.py`.