4.1 KiB

Raw Blame History

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

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

# 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

# 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

Ramble - Type your unstructured thoughts in the blue input box
Generate - Click "Generate / Update" to extract fields
Refine - Add more detail or edit fields directly
Lock - Check "Lock" on fields you like (they become authoritative context)
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

License

MIT

4.1 KiB Raw Blame History