# Ramble

**AI-powered structured field extraction from unstructured text.**

A configurable GUI tool that lets users "ramble" about an idea and extracts structured fields using AI. Just type your thoughts freely, and Ramble generates organized, structured data.

## Features

- **Ramble freely** - Type unstructured thoughts in the input box
- **AI extraction** - Generates structured fields from your ramble
- **Configurable fields** - Define any fields you want to capture
- **Field criteria** - Set validation/formatting rules per field
- **Lock mechanism** - Lock fields you like; they become context for next generation
- **PlantUML diagrams** - Auto-generates and renders diagrams
- **Multiple providers** - Claude, Codex, Gemini, or mock for testing
- **Headless mode** - Skip GUI, pass values directly via CLI

## Installation

```bash
# Clone and install
git clone https://gitea.brrd.tech/rob/ramble.git
cd ramble
pip install -e .

# Requirements
sudo apt install plantuml  # For diagram rendering
```

## Docker

Run without installing anything locally:

```bash
# Clone the repo
git clone https://gitea.brrd.tech/rob/ramble.git
cd ramble

# Build
docker-compose build

# Launch GUI (requires: xhost +local:docker)
docker-compose run --rm gui

# Headless mode
docker-compose run --rm cli ramble --field-values '{"Title":"MyApp","Summary":"A cool app"}'
```

## Usage

### Launch the GUI

```bash
# With mock provider (no AI calls)
ramble --provider mock

# With Claude
ramble --provider claude

# Custom fields
ramble --fields Title Summary Intent "Problem it solves" "Target audience"

# With field criteria
ramble --fields Title Summary --criteria '{"Title":"camelCase, <=20 chars","Summary":"<=2 sentences"}'
```

### Headless Mode

Skip the GUI and provide values directly:

```bash
ramble --field-values '{"Title":"mouseRacingGame","Summary":"Fun racing with mice"}'
```

### Programmatic Use

```python
from ramble import open_ramble_dialog, ClaudeCLIProvider

# With mock provider
result = open_ramble_dialog(
    prompt="Describe your feature idea",
    fields=["Title", "Summary", "Intent"],
    field_criteria={"Title": "camelCase, <=20 chars"},
)

if result:
    print(result["summary"])
    print(result["fields"])

# With Claude
provider = ClaudeCLIProvider(cmd="claude", timeout_s=60)
result = open_ramble_dialog(
    prompt="Describe your idea",
    fields=["Title", "Summary"],
    provider=provider,
)
```

## How It Works

1. **Ramble** - Type your unstructured thoughts in the blue input box
2. **Generate** - Click "Generate / Update" to extract fields
3. **Refine** - Add more detail or edit fields directly
4. **Lock** - Check "Lock" on fields you like (they become authoritative context)
5. **Submit** - Click Submit to output structured JSON

The locked fields become "ground truth" for subsequent generations, allowing iterative refinement.

## CLI Options

| Option | Description |
|--------|-------------|
| `--provider` | AI provider: mock, claude, codex, gemini |
| `--cmd` | Path to CLI command |
| `--model` | Model to use |
| `--fields` | Fields to extract |
| `--criteria` | JSON mapping of field -> criteria |
| `--hints` | JSON list of hint strings |
| `--field-values` | JSON values for headless mode |
| `--timeout` | Provider timeout in seconds |
| `--debug` | Enable debug logging |

## Providers

| Provider | Description |
|----------|-------------|
| `mock` | No AI calls, returns placeholder data |
| `claude` | Anthropic Claude CLI |
| `codex` | OpenAI Codex CLI |
| `gemini` | Google Gemini CLI |

## Output Format

```json
{
  "summary": "A brief summary of the idea",
  "fields": {
    "Title": "mouseRacingGame",
    "Summary": "Fun arcade racing with mice driving cars",
    "Intent": "Entertainment",
    "ProblemItSolves": "Unique gameplay experience"
  }
}
```

## Architecture

```
ramble/
├── src/ramble/
│   ├── __init__.py      # Public API
│   ├── cli.py           # CLI entry point
│   ├── dialog.py        # PySide6/PyQt5 GUI
│   └── providers.py     # AI provider implementations
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```

## License

MIT