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

Quick Start

Option 1: Pre-built Docker Container

# Allow X11 access
xhost +local:docker

# Run the GUI with mock provider (no AI required)
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  gitea.brrd.tech/rob/ramble --provider mock

Option 2: Native Install

git clone https://gitea.brrd.tech/rob/ramble.git
cd ramble
pip install -e .

# Requirements
sudo apt install plantuml  # For diagram rendering

Docker

Pre-built Image

# Pull the pre-built container
docker pull gitea.brrd.tech/rob/ramble:latest

# Run GUI (requires: xhost +local:docker)
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  gitea.brrd.tech/rob/ramble --provider mock

# Headless mode
docker run -it --rm gitea.brrd.tech/rob/ramble \
  --field-values '{"Title":"MyApp","Summary":"A cool app"}'

Build from Source

git clone https://gitea.brrd.tech/rob/ramble.git
cd ramble
docker-compose build

# Launch GUI
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

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

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

Programmatic Use

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

{
  "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

Links

• Repository: https://gitea.brrd.tech/rob/ramble
• Docker Image: gitea.brrd.tech/rob/ramble:latest
• Issues: https://gitea.brrd.tech/rob/ramble/issues

License

MIT