164 lines
4.1 KiB
Markdown
164 lines
4.1 KiB
Markdown
# 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
|