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

# Working with Prompts

> Learn how to fetch, access, and use prompts from Claro

# Working with Prompts

Prompts are the core resource in Claro. Learn how to retrieve them, access their content, and understand their metadata.

## Getting a Prompt

Retrieve a prompt using its package name:

```python theme={null}
from baytos.claro import BaytClient

client = BaytClient(api_key="your_api_key")
prompt = client.get_prompt("@workspace/my-prompt:v1")
```

## Package Names

Prompts use a semantic naming convention:

```
@workspace/prompt-name:version
```

**Components:**

* `@workspace` - Your workspace slug (unique identifier)
* `prompt-name` - The prompt's URL-friendly name
* `version` - Version identifier (v0 for drafts, v1+ for published)

<Tip>
  Find your prompt's package name in the Claro dashboard under prompt settings or by clicking the "Share" button.
</Tip>

### Version Conventions

```python theme={null}
# Get draft version (always the latest unreleased changes)
draft = client.get_prompt("@workspace/my-prompt:v0")

# Get specific published version
v1 = client.get_prompt("@workspace/my-prompt:v1")
v2 = client.get_prompt("@workspace/my-prompt:v2")

# Get latest published version
latest = client.get_prompt("@workspace/my-prompt:latest")
```

<Note>
  Version `v0` is reserved for drafts. Published versions start at `v1`.
</Note>

## Prompt Content Fields

Prompts contain three types of content:

### Generator Prompt

The main prompt content:

```python theme={null}
prompt = client.get_prompt("@workspace/assistant:v1")
print(prompt.generator)  # Main prompt content
```

Use this with your LLM provider:

```python theme={null}
from openai import OpenAI

openai_client = OpenAI()
response = openai_client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": prompt.generator}
    ]
)
```

### System Prompt

Optional system-level instructions:

```python theme={null}
if prompt.has_system_prompt():
    print(prompt.system)
```

### Critique Prompt

Optional prompt for evaluating outputs:

```python theme={null}
if prompt.has_critique_prompt():
    print(prompt.critique)
    # Use this to evaluate LLM responses
```

## Prompt Metadata

Access metadata about the prompt:

```python theme={null}
prompt = client.get_prompt("@workspace/my-prompt:v1")

# Basic info
print(f"Title: {prompt.title}")
print(f"Description: {prompt.description}")

# Package information
print(f"Workspace: {prompt.namespace}")
print(f"Slug: {prompt.slug}")
print(f"Version: {prompt.version}")
print(f"Full package name: {prompt.package_name}")

# Version status
if prompt.is_draft:
    print("This is a draft version")
else:
    print("This is a published version")
```

### Available Metadata

| Property       | Type   | Description                    |                      |
| -------------- | ------ | ------------------------------ | -------------------- |
| `id`           | `str`  | Unique prompt identifier       |                      |
| `title`        | `str`  | Human-readable title           |                      |
| `description`  | \`str  | None\`                         | Optional description |
| `generator`    | `str`  | Main prompt content            |                      |
| `system`       | `str`  | System prompt (may be empty)   |                      |
| `critique`     | `str`  | Critique prompt (may be empty) |                      |
| `namespace`    | `str`  | Workspace slug                 |                      |
| `slug`         | `str`  | Prompt slug                    |                      |
| `version`      | `str`  | Version string (e.g., "v1")    |                      |
| `package_name` | `str`  | Full package name              |                      |
| `is_draft`     | `bool` | True if version is v0          |                      |
| `category`     | `str`  | Prompt category                |                      |

## Dictionary-Style Access

Prompts support both attribute and dictionary access:

```python theme={null}
prompt = client.get_prompt("@workspace/test:v1")

# Attribute access (recommended)
print(prompt.title)
print(prompt.generator)

# Dictionary access
print(prompt['title'])
print(prompt.get('description', 'No description'))

# Check if field exists
if 'system' in prompt:
    print(prompt['system'])

# Get all data as dict
data = prompt.to_dict()
```

## Working with Multiple Prompts

### Fetching Different Versions

```python theme={null}
client = BaytClient(api_key="your_api_key")

# Compare versions
v1 = client.get_prompt("@workspace/support:v1")
v2 = client.get_prompt("@workspace/support:v2")

if v1.generator != v2.generator:
    print("Content changed between versions")
    print(f"v1 length: {len(v1.generator)}")
    print(f"v2 length: {len(v2.generator)}")
```

### Version Migration

```python theme={null}
def migrate_to_latest(package_base: str):
    """Migrate from current version to latest"""
    current = client.get_prompt(f"{package_base}:v1")
    latest = client.get_prompt(f"{package_base}:latest")

    if current.version != latest.version:
        print(f"New version available: {latest.version}")
        print(f"Title: {latest.title}")
        return latest

    return current

# Usage
prompt = migrate_to_latest("@workspace/customer-support")
```

## Using with Different LLM Providers

### OpenAI

```python theme={null}
from baytos.claro import BaytClient
from openai import OpenAI

claro = BaytClient(api_key="...")
openai = OpenAI(api_key="...")

prompt = claro.get_prompt("@workspace/assistant:v1")

response = openai.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": prompt.generator},
        {"role": "user", "content": "Hello!"}
    ]
)
```

### Anthropic Claude

```python theme={null}
from baytos.claro import BaytClient
import anthropic

claro = BaytClient(api_key="...")
claude = anthropic.Anthropic(api_key="...")

prompt = claro.get_prompt("@workspace/assistant:v1")

response = claude.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system=prompt.generator,
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)
```

### Google Gemini

```python theme={null}
from baytos.claro import BaytClient
import google.generativeai as genai

claro = BaytClient(api_key="...")
genai.configure(api_key="...")

prompt = claro.get_prompt("@workspace/assistant:v1")
model = genai.GenerativeModel("gemini-pro")

response = model.generate_content(
    f"{prompt.generator}\n\nUser: Hello!"
)
```

## Caching Prompts

For frequently accessed prompts, consider caching:

```python theme={null}
from functools import lru_cache
from baytos.claro import BaytClient

client = BaytClient(api_key="...")

@lru_cache(maxsize=100)
def get_cached_prompt(package_name: str):
    """Cache prompts to reduce API calls"""
    return client.get_prompt(package_name)

# First call - fetches from API
prompt1 = get_cached_prompt("@workspace/support:v1")

# Second call - returns cached version
prompt2 = get_cached_prompt("@workspace/support:v1")
```

<Warning>
  Be careful with caching. If a prompt is updated, your cache may return stale data. Consider cache invalidation strategies.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Specific Versions in Production" icon="lock">
    Always use specific versions (v1, v2) in production code:

    ```python theme={null}
    # ✅ Good: Pinned version
    prompt = client.get_prompt("@workspace/support:v1")

    # ❌ Risky: Latest version
    prompt = client.get_prompt("@workspace/support:latest")
    ```

    Using `latest` in production means your application behavior changes when prompts are updated.
  </Accordion>

  <Accordion title="Test Drafts Before Publishing" icon="flask">
    Use v0 (draft) for development and testing:

    ```python theme={null}
    import os

    ENV = os.getenv("ENVIRONMENT", "production")

    if ENV == "development":
        # Use draft in development
        prompt = client.get_prompt("@workspace/support:v0")
    else:
        # Use specific version in production
        prompt = client.get_prompt("@workspace/support:v1")
    ```
  </Accordion>

  <Accordion title="Handle Missing Optional Fields" icon="shield">
    Not all prompts have system or critique prompts:

    ```python theme={null}
    # ✅ Good: Check before using
    if prompt.has_system_prompt():
        system = prompt.system
    else:
        system = "You are a helpful assistant."

    # ✅ Good: Use .get() with default
    critique = prompt.get('critique', '')

    # ❌ Bad: Assume field exists
    system = prompt.system  # May be empty string
    ```
  </Accordion>

  <Accordion title="Validate Package Names" icon="check">
    Validate package names before fetching:

    ```python theme={null}
    import re
    from baytos.claro import BaytClient, BaytValidationError

    def is_valid_package_name(name: str) -> bool:
        pattern = r'^@[\w-]+/[\w-]+:v\d+$'
        return bool(re.match(pattern, name))

    package = "@workspace/support:v1"

    if is_valid_package_name(package):
        prompt = client.get_prompt(package)
    else:
        print(f"Invalid package name: {package}")
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Context Files" icon="paperclip" href="/sdk/python/context">
    Work with file attachments and URLs
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/sdk/python/variables">
    Extract and validate variables in prompts
  </Card>

  <Card title="Listing Prompts" icon="list" href="/sdk/python/pagination">
    Browse and paginate through prompts
  </Card>

  <Card title="Error Handling" icon="shield" href="/sdk/python/error-handling">
    Handle errors when fetching prompts
  </Card>
</CardGroup>