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

# Prompting reference

> Copy-paste prompts and code for each SDK primitive on Isaac 0.1.

<Callout type="info">
  Isaac 0.1 triggers grounding through `<hint>...</hint>` system messages. Reasoning and Focus are not supported on Isaac 0.1 — see [Isaac 0.2](/isaac-0.2) for those capabilities. See the [API reference](/isaac-0.1/api-reference/endpoint/chat-completions) for details.
</Callout>

## Quick reference

| Task                  | SDK Helper                  | Optimal Prompt                                                                                                |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Concise caption**   | `caption(style="concise")`  | `Provide a concise, human-friendly caption for the upcoming image.`                                           |
| **Detailed caption**  | `caption(style="detailed")` | `Provide a detailed caption describing key objects, relationships, and context in the upcoming image.`        |
| **OCR**               | `ocr()`                     | System: `You are an OCR system. Accurately detect, extract, and transcribe all readable text from the image.` |
| **General detection** | `detect()`                  | `Your goal is to segment out the objects in the scene`                                                        |
| **Class detection**   | `detect(classes=[...])`     | `Your goal is to segment out the following categories: {categories}`                                          |
| **Visual Q\&A**       | `question()`                | Pass your question directly as user content                                                                   |
| **Grounded Q\&A**     | `question(expects="box")`   | Same question, model returns boxes with answers                                                               |
| **Counting**          | `question()`                | `How many {objects} are there? Point to each.`                                                                |

***

## Grounding on Isaac 0.1 (`<hint>` syntax)

Place hint values inside a system-role message.

| Hint                   | Output         |
| ---------------------- | -------------- |
| `<hint>BOX</hint>`     | Bounding boxes |
| `<hint>POINT</hint>`   | Points         |
| `<hint>POLYGON</hint>` | Polygons       |

### Example: boxes

```bash theme={null}
curl -X POST "https://api.perceptron.inc/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
  "model": "isaac-0.1",
  "messages": [
    { "role": "system", "content": [{"type": "text", "text": "<hint>BOX</hint>"}] },
    { "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "<image-url>"}},
        {"type": "text", "text": "Find all the safety equipment"}
      ]
    }
  ]
}'
```

### Example: points

```bash theme={null}
curl -X POST "https://api.perceptron.inc/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
  "model": "isaac-0.1",
  "messages": [
    { "role": "system", "content": [{"type": "text", "text": "<hint>POINT</hint>"}] },
    { "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "<image-url>"}},
        {"type": "text", "text": "Point at each visible helmet"}
      ]
    }
  ]
}'
```

***

## Advanced: `@perceive` decorator

The Python SDK wraps the chat-completions endpoint with a typed decorator that handles hint setup and result parsing for you.

### Basic usage

```python theme={null}
from perceptron import configure, perceive, image, text

configure(provider="perceptron", api_key="YOUR_API_KEY")

@perceive(model="isaac-0.1")
def analyze(photo):
    return image(photo) + text("Identify the dominant colors in this scene")

result = analyze("scene.jpg")
print(result.text)
```

### With structured output (Pydantic)

```python theme={null}
from pydantic import BaseModel
from perceptron import configure, perceive, pydantic_format, image, text

configure(provider="perceptron", api_key="YOUR_API_KEY")

class SceneAnalysis(BaseModel):
    primary_color: str
    object_count: int
    description: str

@perceive(model="isaac-0.1", response_format=pydantic_format(SceneAnalysis))
def analyze_scene(photo):
    return image(photo) + text("Analyze this image and return the structured result.")

scene = analyze_scene("photo.jpg")
print(scene.primary_color, scene.object_count)
```