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

# Product Prompts

<Note>
  **Internal Service** — This is not an HTTP endpoint. It's called directly by the `generate-all` orchestrator.
</Note>

## Purpose

Generates visibility prompts for each discovered product. These are product-specific search queries that potential customers might use to find products like this.

Runs in **GROUP 2b** (starts when GROUP 1a + 1b + 1d complete, runs in parallel with GROUP 2a and 2c).

## Function Signature

```python theme={null}
async def run_product_prompts(
    url: str,
    org_slug: str,
    discovered_products: list,
    pages: list,
    prompts_per_product: int = 5
) -> Optional[StepResult]
```

## Parameters

| Parameter             | Type   | Description                                            |
| --------------------- | ------ | ------------------------------------------------------ |
| `url`                 | `str`  | The Shopify store URL                                  |
| `org_slug`            | `str`  | The Clerk organization slug                            |
| `discovered_products` | `list` | Products from GROUP 1d                                 |
| `pages`               | `list` | Pre-scraped pages from GROUP 1b                        |
| `prompts_per_product` | `int`  | Prompts per product (may be increased to meet minimum) |

## Returns

```json theme={null}
{
  "name": "product_prompts",
  "status": "success",
  "data": {
    "products_processed": 8,
    "total_prompts": 56,
    "prompts_per_product": 7
  }
}
```

## Prompt Generation Strategy

All prompts are tied to products:

| Metric                          | Value                             |
| ------------------------------- | --------------------------------- |
| **Default prompts per product** | 5                                 |
| **Minimum total prompts**       | 50 during onboarding              |
| **New products (via cron)**     | 5 prompts each                    |
| **Daily sampling**              | 10 prompts for visibility scoring |

### Minimum 50 Logic

During onboarding, if `products × 5 < 50`, prompts per product is increased:

```python theme={null}
# Example: 3 products
# Base: 3 × 5 = 15 prompts (below minimum)
# Adjusted: ceil(50 / 3) = 17 prompts per product
# Result: 3 × 17 = 51 total prompts

# Example: 12 products
# Base: 12 × 5 = 60 prompts (above minimum)
# No adjustment needed: 5 prompts per product
# Result: 12 × 5 = 60 total prompts
```

## Execution Flow

```mermaid theme={null}
flowchart TD
    A[GROUP 1d: Products discovered] --> B{Products found?}
    B -->|Yes| C[Calculate prompts per product]
    C --> D[GROUP 2b: Product Prompts]
    C --> E[GROUP 2c: Product LLMs]
    D --> F[For each product]
    F --> G[Generate prompts with Gemini]
    G --> H[Save to database]
    H --> F
    B -->|No| I[Skip GROUP 2b and 2c]
```

## Product-Specific Prompts

Uses Gemini with product context:

```python theme={null}
prompt = f"""
Generate {count} search queries for this specific product: {product_name}

Requirements:
- Queries should be specific to this product
- Include feature-specific queries
- Include comparison queries with alternatives
- Sound like something a real person would type into ChatGPT or Google
"""
```

## Database Storage

Prompts are linked to the product entity:

```sql theme={null}
INSERT INTO entity_prompts_tracker (
  entity_id,  -- Product entity ID
  prompt
) VALUES (
  'product-uuid-...',
  'Best tool for X feature'
);
```

## Code Location

```
src/app/apis/onboarding/generate_all/tasks/prompts.py
```

Contains `run_product_prompts()` for GROUP 2b.

## Skipped Scenarios

Product prompts are skipped if:

1. No products were discovered in GROUP 1d
2. Product discovery failed
3. Products don't have valid entity IDs

```json theme={null}
{
  "name": "product_prompts",
  "status": "skipped",
  "error": "No products discovered"
}
```