> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Expansion

> Expand short prompts into detailed, actionable prompts

The `--expand-prompt` flag expands short prompts into detailed, actionable prompts using the PromptExpanderAgent.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "write a movie script in 3 lines" --expand-prompt
```

![Expand Prompt Adds Detail](https://mintcdn.com/praisonai/pFBcVNzCyPC2mUmz/cli/prompt-expansion-expand-prompt-adds-detail-to-s.gif?s=5afff5b341424afdc154d1a489491339)

## Usage

### Basic Expansion

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "write a movie script in 3 lines" --expand-prompt
```

**Expected Output:**

```
✨ Expanding prompt...

╭─ Original Prompt ────────────────────────────────────────────────────────────╮
│  write a movie script in 3 lines                                            │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ Expanded Prompt ────────────────────────────────────────────────────────────╮
│  Write a compelling 3-line movie script that includes:                      │
│  1. A hook that establishes the setting and protagonist                     │
│  2. A conflict or turning point that creates tension                        │
│  3. A resolution or cliffhanger that leaves an impact                       │
│                                                                              │
│  Format: Each line should be a complete scene description with dialogue     │
│  if appropriate. Use present tense and vivid imagery.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### With Verbose Output

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "blog about AI" --expand-prompt -v
```

### With Tools for Context

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Tools file
praisonai "latest AI trends" --expand-prompt --expand-tools tools.py

# Built-in SDK tool
praisonai "draft a coding plan" --expand-prompt --expand-tools "internet_search"

# praisonai-tools / entry-point plugin
praisonai "draft a coding plan" --expand-prompt --expand-tools "duckduckgo_search"
```

> [!NOTE]
>
> `--expand-tools` now accepts any name reachable by `praisonai tools list` — the same resolver chain used by `praisonai research --tools` and `--rewrite-tools`. See [Tool Resolution](https://praison.ai/docs/cli/deep-research.md#which-tool-names-work) for the full chain.

### Combine with Query Rewrite

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "AI news" --query-rewrite --expand-prompt
```

## Key Difference

| Flag | Purpose | Best For |
| - | - | - |
| `--query-rewrite` | Optimizes queries for search/retrieval (RAG) | Search, RAG, retrieval |
| `--expand-prompt` | Expands prompts for detailed task execution | Content creation, coding |

## Expansion Strategies

| Strategy | Description |
| - | - |
| BASIC | Simple expansion with context |
| DETAILED | Comprehensive expansion with structure |
| STRUCTURED | Adds formatting and organization |
| CREATIVE | Adds creative elements and suggestions |
| AUTO | Automatically selects best strategy |

## Examples

### Content Creation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "blog about AI" --expand-prompt
```

**Expanded to:** "Write a comprehensive blog post about Artificial Intelligence that includes: an engaging introduction, key concepts explained for beginners, current trends and applications, future predictions, and a conclusion with actionable takeaways. Use headers, bullet points, and examples."

### Code Generation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "REST API" --expand-prompt
```

**Expanded to:** "Create a REST API with the following specifications: endpoints for CRUD operations, proper HTTP methods (GET, POST, PUT, DELETE), error handling with appropriate status codes, input validation, authentication middleware, and documentation comments."

### Research Task

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "quantum computing" --expand-prompt
```

**Expanded to:** "Research quantum computing covering: fundamental principles (qubits, superposition, entanglement), current hardware implementations, major players and their approaches, practical applications, challenges and limitations, and future outlook."

## Choosing the expander's model

The CLI's `--expand-prompt` step honours the standard cascade — CLI flag wins, env vars next, `gpt-4o-mini` fallback last:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Expander uses claude-3-5-sonnet-latest, matching the main agent
praisonai "write a movie script in 3 lines" --expand-prompt --llm claude-3-5-sonnet-latest
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[--llm CLI flag] --> B{Set?}
    B -->|yes| Use[Use it]
    B -->|no| C[MODEL_NAME env]
    C --> D{Set?}
    D -->|yes| Use
    D -->|no| E[OPENAI_MODEL_NAME env]
    E --> F{Set?}
    F -->|yes| Use
    F -->|no| G[gpt-4o-mini]

    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class B,D,F check
    class A,C,E,G input
    class Use output
```

To keep a cheap expander regardless of the main model, pin it explicitly with `OPENAI_MODEL_NAME=gpt-4o-mini` while `--llm` drives the main agent — but the recommended pattern is running the expander and main agent on the same model.

## Programmatic Usage

The `model=` kwarg on `PromptExpanderAgent` is unchanged — the cascade above applies only to the CLI path.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import PromptExpanderAgent, ExpandStrategy

# Basic usage
agent = PromptExpanderAgent()
result = agent.expand("write a movie script in 3 lines")
print(result.expanded_prompt)

# With specific strategy
result = agent.expand("blog about AI", strategy=ExpandStrategy.DETAILED)

# Available strategies: BASIC, DETAILED, STRUCTURED, CREATIVE, AUTO
```

## How It Works

1. **Analyze**: PromptExpanderAgent analyzes the short prompt
2. **Strategy**: Selects appropriate expansion strategy
3. **Expand**: Generates detailed, actionable prompt
4. **Execute**: Uses expanded prompt for the task

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    A[Short Prompt] --> B[PromptExpanderAgent]
    B --> C{Strategy}
    C -->|BASIC| D[Add Context]
    C -->|DETAILED| E[Full Structure]
    C -->|STRUCTURED| F[Format & Organize]
    C -->|CREATIVE| G[Creative Elements]
    D --> H[Expanded Prompt]
    E --> H
    F --> H
    G --> H
    H --> I[Execute Task]
```

## Best Practices

> [!TIP]
>
> Use `--expand-prompt` for content creation and coding tasks where detailed instructions improve output quality.

> [!WARNING]
>
> Prompt expansion adds an LLM call. Use `--metrics` to monitor token usage.

| Do | Don't |
| - | - |
| Use for vague or short prompts | Use for already detailed prompts |
| Combine with `--query-rewrite` for research | Use alone for simple lookups |
| Use `--expand-tools` for context | Skip context for complex topics |

## Related

* [Prompt Expander Agent](https://praison.ai/docs/agents/prompt-expander.md)
* [Query Rewrite CLI](https://praison.ai/docs/cli/query-rewrite.md)
* [Planning CLI](https://praison.ai/docs/cli/planning.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.