Metadata-Version: 2.4
Name: ai-magic-prompt
Version: 0.1.2
Summary: TUI app that enriches prompts using Groq API and project context
Project-URL: Homepage, https://github.com/arterialist/magic-prompt
Project-URL: Repository, https://github.com/arterialist/magic-prompt
Project-URL: Issues, https://github.com/arterialist/magic-prompt/issues
Author: arterialist
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: ai,cli,groq,llm,prompt,prompt-engineering,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: groq>=0.11.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: textual>=0.89.0
Description-Content-Type: text/markdown

# Magic Prompt

[![PyPI version](https://badge.fury.io/py/ai-magic-prompt.svg)](https://pypi.org/project/ai-magic-prompt/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A TUI and CLI tool that enriches short, vague prompts into detailed, structured prompts using Groq API and your project's actual file structure and codebase.

## Features

- 📁 **Project-Aware**: Scans your project's file structure, config files, and extracts code signatures
- 🧠 **AI-Powered**: Uses Groq's fast LLM API to intelligently expand prompts
- ⚡ **Real-Time Streaming**: Watch the enriched prompt generate in real-time
- 🖥️ **Dual Mode**: Interactive TUI or headless CLI for shell scripting

## Installation

### From PyPI

```bash
pip install ai-magic-prompt
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv tool install ai-magic-prompt
```

### From Source

```bash
git clone https://github.com/arterialist/magic-prompt.git
cd magic-prompt
pip install -e .
```

## Setup

Get your Groq API key from [console.groq.com/keys](https://console.groq.com/keys).

Set it as an environment variable:

```bash
export GROQ_API_KEY=gsk_...
```

Or create a `.env` file in your project directory:

```bash
GROQ_API_KEY=your_api_key_here
```

## Usage

### Headless CLI Mode

Run from anywhere as a shell command:

```bash
# Basic usage - enrich a prompt
magic-prompt "add user authentication"

# Pipe prompt from stdin
echo "add logging" | magic-prompt

# Specify project directory
magic-prompt -d /path/to/project "refactor the API"

# Quiet mode - only output result (good for piping)
magic-prompt -q "add tests" > enriched.md
```

#### CLI Options

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `-d, --directory` | Project directory (default: from config or cwd) |
| `-t, --tui`       | Launch interactive TUI mode                     |
| `-q, --quiet`     | Only output result, no progress                 |
| `--debounce MS`   | Set debounce time for real-time mode            |
| `--save-dir DIR`  | Save default directory for future runs          |
| `--show-config`   | Show current configuration                      |

### Interactive TUI Mode

```bash
magic-prompt --tui
# OR just run without arguments:
magic-prompt
```

1. Enter your project's root directory path
2. Type a short prompt (e.g., "add user authentication")
3. Watch the enriched, project-aware prompt stream in real-time
4. Press `Ctrl+Y` to copy the enriched prompt

#### TUI Keyboard Shortcuts

| Key      | Action            |
| -------- | ----------------- |
| `Enter`  | Submit prompt     |
| `Ctrl+T` | Toggle real-time  |
| `Ctrl+Y` | Copy to clipboard |
| `Ctrl+L` | Clear output      |
| `Ctrl+R` | Rescan project    |
| `Ctrl+Q` | Quit              |

## How It Works

1. **Scans** your project directory structure
2. **Extracts** docstrings, function signatures, and imports
3. **Sends** context + your prompt to Groq's LLM
4. **Streams** an enriched version that references actual files and APIs

## License

MIT License - see [LICENSE](LICENSE) for details.
