# Manage Prompt with the SDK

In this guide, we'll explore all actions performed through the SDK: creating variants, committing changes, deploying changes, and fetching configurations. For a simpler introduction, please refer to the prompt mangement tutorial.\
\
Before starting, we recommend to get acquainted with how versioning works in Lexica. You can find more details on the concepts page, or read the quick summary below.

<figure><img src="https://4234609497-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXAWgkVP83JndLwakfEzF%2Fuploads%2FPTSM6I4xjNJ7awsDvBZ7%2Ftaxonomy-concepts.f58eb18.1100.png?alt=media&#x26;token=58d333c8-f22f-4355-874f-e9c3b5442779" alt=""><figcaption><p>Add alt text and captions to your images</p></figcaption></figure>

Lexica follows a structure similar to **git** for prompt versioning. Instead of a single commit history, you can create multiple branches—called **variants**. Each variant represents a distinct approach or solution you're exploring.

To move from experimentation to deployment, Lexica uses **environments** like **development**, **staging**, and **production**. You can deploy specific versions of your **variants** to these **environments**, controlling what gets tested and what goes live.

The workflow of deploying something to production is therefore as follows:

1. (optionally) Create a new **variant** (branch)
2. Commit a change to that **variant**
3. Deploy that **commit** (**variant**/**version**) to an **environment**

## Setup <a href="#setup" id="setup"></a>

Before using the SDK, you need to initialize it using the `ag.init()` method.

```typescript
import os
import Lexica as ag


# Initialize the SDK with your API key
os.environ["Lexica_API_KEY"] = "xxx" # Only needs setting in oss
os.environ["Lexica_HOST"] = "https://cloud.Lexica.ai" # default value no need setting explicitly

ag.init()
```

## Creating a new prompt <a href="#creating-a-new-prompt" id="creating-a-new-prompt"></a>

Each prompt in Lexica is a unique application. Currently creating a prompt is only available in the web UI. To create a new prompt, just click on create a new prompt and select whether it's a chat or completion prompt in the web UI.

## Committing changes <a href="#committing-changes" id="committing-changes"></a>

### Creating a New Variant <a href="#creating-a-new-variant" id="creating-a-new-variant"></a>

To create a new variant, use the `VariantManager.create` method.

```typescript

from Lexica import Prompt

# Prompt is a pydantic BaseModel we created for common prompt settings. 
# To add more fields or validations, create your own custom model.
my_prompt = Prompt(
    temperature=0.7,
    model="gpt-3.5-turbo",
    max_tokens=150,
    prompt_system="You are an assistant that provides concise answers",
    prompt_user="Explain {topic} in simple terms",
    top_p=1.0,
    frequency_penalty=0.0,
    presence_penalty=0.0
)

# Create a new variant
variant = ag.VariantManager.create(
    parameters=my_prompt.model_dump(),
    app_slug="my-app-slug",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="my-variant-slug",
)

print("Created variant:")
print(variant)

# Create a new version asynchronously (optional)
# async def create_variant():
#     variant = await ag.VariantManager.acreate(
#         parameters=my_prompt.model_dump(),
#         app_slug="my-app-slug",
#         app_id="my-app-id",  # you can also use `app_id`
#         variant_slug="my-variant-slug",
#     )

#     print("Created variant (async):")
#     print(variant)
```

This command will create a new variant and initialize it with the first commit containing the parameters provided

* **Parameters:**
  * `app_slug`: The slug of your application.
  * `variant_slug`: The slug of the new variant.
  * `parameters`: A dictionary containing the initial configuration parameters.

**Note:** If a variant with the same `slug` and `version` already exists, the SDK will raise an exception.

**Sample Output:**

```python
Created variant:
{
    'parameters': {
        'temperature': 0.7,
        'model': 'gpt-3.5-turbo',
        'max_tokens': 150,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    },
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'new-variant-id',
    'variant_slug': 'my-variant-slug',
    'variant_version': 1,
    'committed_at': 'current-datetime',
    'committed_by': 'my-email-address',
    'committed_by_id': 'my-user-id',
}
```

#### Committing Changes to a Variant[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#committing-changes-to-a-variant) <a href="#committing-changes-to-a-variant" id="committing-changes-to-a-variant"></a>

To save changes to a variant (creating a new version), use the `VariantManager.commit` method with explicit parameters.

```python
my_prompt2 = Prompt(
    temperature=1.0,
    model="gpt-4",
    max_tokens=150,
    prompt_system="You are an assistant that provides concise answers",
    prompt_user="Explain {topic} in simple terms",
    top_p=1.0,
    frequency_penalty=0.0,
    presence_penalty=0.0
)

# Commit the new version
variant = ag.VariantManager.commit(
    parameters=my_prompt2.model_dump(),
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
)

print("Committed new version of variant:")
print(variant)

# Commit the new version asynchronously (optional)
# async def commit_variant():
#     variant = await ag.VariantManager.acommit(
#         parameters=my_prompt2.model_dump(),
#         app_slug="my-app-slug",
#         variant_slug="my-variant-slug",
#     )

#     print("Committed new version of variant (async):")
#     print(variant)
```

{% hint style="info" %}
**IMMUTABILITY**

Each commit creates a new version of the variant. Versions are immutable once created.
{% endhint %}

**Sample Output:**

```python
Committed new version of variant:
{
    'parameters': {
        'temperature': 1.0,
        'model': 'gpt-4',
        'max_tokens': 150,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    }
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'updated-variant-id',
    'variant_slug': 'my-variant-slug',
    'variant_version': 2,
    'committed_at': 'current-datetime',
    'committed_by': 'my-email-address',
    'committed_by_id': 'my-user-id',
}
```

### Deploying to an Environment[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#deploying-to-an-environment) <a href="#deploying-to-an-environment" id="deploying-to-an-environment"></a>

To deploy a variant to an environment, use the `DeploymentManager.deploy` method with the variant reference and `environment_slug`: The slug of the environment (`development`, `staging`, or `production`).

```python
# Deploy the variant to the staging environment
deployment = ag.DeploymentManager.deploy(
    app_slug="my-app-slug",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="my-variant-slug",
    variant_version=None,  # Optional: If not provided, deploys the latest version
    environment_slug="staging"
)

print("Deployed variant to environment:")
print(deployment)

# Deploy the variant to the staging environment asynchronously (optional)
# async def deploy_variant():
#     deployment = await ag.DeploymentManager.adeploy(
#         app_slug="my-app-slug",
#         # app_id="my-app-id",  # you can also use `app_id`
#         variant_slug="my-variant-slug",
#         variant_version=None,  # Optional: If not provided, deploys the latest version
#         environment_slug="staging"
#     )

#     print("Deployed variant to environment (async):")
#     print(deployment)
```

**Sample Output:**

```python
Deployed variant to environment:
{
    'parameters': {
        'temperature': 0.7,
        'model': 'gpt-3.5-turbo',
        'max_tokens': 150,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    },
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'new-variant-id',
    'variant_slug': 'my-variant-slug',
    'variant_version': 1,
    'environment_id': 'staging-enviroment-id',
    'environment_slug': 'staging',
    'environment_version': 1,
    'deployed_at': 'current-datetime',
    'deployed_by': 'my-email-address',
    'deployed_by_id': 'my-user-id',
}
```

### Fetching Configurations[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#fetching-configurations) <a href="#fetching-configurations" id="fetching-configurations"></a>

You can fetch the configurations from a variant reference (`app_slug`, `variant_slug`, `variant_version`) or an environment reference (`app_slug`, `environment_slug`). The default behavior when fetching is to fetch the latest configuration from the `production` environment. If you don't provide a `_version` parameter but only a `variant_slug` or an `environment_slug`, the SDK will fetch the latest version of the variant from the specified **environment/variant**.

#### Default Behavior when fetching[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#default-behavior-when-fetching) <a href="#default-behavior-when-fetching" id="default-behavior-when-fetching"></a>

If you don't provide either `variant` or `environment` identifiers, the SDK fetches the latest configuration deployed to the `production` environment.

```python
# Fetch configuration from the latest version in production (default)
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug"
    # app_id="my-app-id",  # you can also use `app_id`
)

print("Fetched configuration from production:")
print(config)
```

#### Fetching by Variant Reference[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#fetching-by-variant-reference) <a href="#fetching-by-variant-reference" id="fetching-by-variant-reference"></a>

```python
# Fetch configuration by variant
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="my-variant-slug",
    variant_version=2  # Optional: If not provided, fetches the latest version
)

print("Fetched configuration:")
print(config)
```

**Sample Output:**

```python
Fetched configuration:
{
    'temperature': 1.0,
    'model': 'gpt-4',
    'max_tokens': 150,
    'prompt_system': 'You are an assistant that provides concise answers.',
    'prompt_user': 'Explain {topic} in simple terms.',
    'top_p': 1.0,
    'frequency_penalty': 0.0,
    'presence_penalty': 0.0
}
```

#### Fetching by Environment Reference[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#fetching-by-environment-reference) <a href="#fetching-by-environment-reference" id="fetching-by-environment-reference"></a>

```python
# Fetch the latest configuration from the staging environment
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app",
    environment_slug="staging"
    environment_version=1  # Optional: If not provided, fetches the latest version
)

print("Fetched configuration from staging:")
print(config)
```

**Sample Output:**

```python
Fetched configuration from staging:
{
    'temperature': 0.7,
    'model': 'gpt-3.5-turbo',
    'max_tokens': 150,
    'prompt_system': 'You are an assistant that provides concise answers.',
    'prompt_user': 'Explain {topic} in simple terms.',
    'top_p': 1.0,
    'frequency_penalty': 0.0,
    'presence_penalty': 0.0
}
```

### Deleting a Variant[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#deleting-a-variant) <a href="#deleting-a-variant" id="deleting-a-variant"></a>

To delete a variant, use the `VariantManager.delete` method.

```python
# Delete a variant
ag.VariantManager.delete(
    app_slug="my-app",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="obsolete-variant"
)

# Delete a variant asynchronously (optional)
# async def delete_variant():
#     versions = await ag.VariantManager.adelete(
#         app_slug="my-app",
#         # app_id="my-app-id",  # you can also use `app_id`
#         variant_slug="obsolete-variant",
#     )

print("Variant deleted successfully.")
```

### Listing All Variants[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#listing-all-variants) <a href="#listing-all-variants" id="listing-all-variants"></a>

To list all variants of an application, use the `VariantManager.list` method.

```python
# List all variants (syncrhonously)
variants = ag.VariantManager.list(
    app_slug="my-app"
    # app_id="my-app-id",  # you can also use `app_id`
)

print("List of variants:")
for variant in variants:
    print(variant)

# List all variants asynchronously (optional)
# async def list_variants():
#     variants = await ag.VariantManager.alist(
#         app_slug="my-app"
#         # app_id="my-app-id",  # you can also use `app_id`
#     )

#     print("List of variants (async):")
#     for variant in variants:
#         print(variant)
```

**Sample Output:**

```python
List of variants:
{
    'parameters': {
        'temperature': 1.0,
        'model': 'gpt-4',
        'max_tokens': 150,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    }
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'updated-variant-id',
    'variant_slug': 'my-variant-slug',
    'variant_version': 2,
    'committed_at': 'current-datetime',
    'committed_by': 'my-email-address',
    'committed_by_id': 'my-user-id',
}
{
    'parameters': {
        'temperature': 0.5,
        'model': 'gpt-3.5-turbo',
        'max_tokens': 100,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    }
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'another-variant-id',
    'variant_slug': 'another-variant-slug',
    'variant_version': 1,
    'committed_at': 'another-datetime',
    'committed_by': 'another-email-address',
    'committed_by_id': 'another-user-id',
}
```

### Fetching a Variant's history[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#fetching-a-variants-history) <a href="#fetching-a-variants-history" id="fetching-a-variants-history"></a>

To list all versions for a variant of an application, use the `VariantManager.list` method.

```python
# List all variant versions/history (synchronously)
versions = ag.VariantManager.history(
    variant_slug="variant-slug",
    app_slug="my-app"
    # app_id="my-app-id",  # you can also use `app_id`
)

print("History of variant:")
for version in versions:
    print(version)

# List all variant versions/history asynchronously (optional)
# async def fetch_variant_history():
#     versions = await ag.VariantManager.ahistory(
#         variant_slug="variant-slug",
#         app_slug="my-app"
#         # app_id="my-app-id",  # you can also use `app_id`
#     )

#     print("History of variant:")
#     for version in versions:
#         print(version)
```

**Sample Output:**

```typescript
History of variants:
{
    'parameters': {
        'temperature': 1.0,
        'model': 'gpt-4',
        'max_tokens': 150,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    }
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'updated-variant-id',
    'variant_slug': 'my-variant-slug',
    'variant_version': 2,
    'committed_at': 'current-datetime',
    'committed_by': 'my-email-address',
    'committed_by_id': 'my-user-id',
}
{
    'parameters': {
        'temperature': 0.5,
        'model': 'gpt-3.5-turbo',
        'max_tokens': 100,
        'prompt_system': 'You are an assistant that provides concise answers.',
        'prompt_user': 'Explain {topic} in simple terms.',
        'top_p': 1.0,
        'frequency_penalty': 0.0,
        'presence_penalty': 0.0
    }
    'app_id': 'my-app-id',
    'app_slug': 'my-app-slug',
    'variant_id': 'another-variant-id',
    'variant_slug': 'another-variant-slug',
    'variant_version': 1,
    'committed_at': 'another-datetime',
    'committed_by': 'another-email-address',
    'committed_by_id': 'another-user-id',
}
```

### Asynchronous Operations[​](https://docs.agenta.ai/prompt-management/prompt-management-sdk#asynchronous-operations) <a href="#asynchronous-operations" id="asynchronous-operations"></a>

If your application uses asynchronous programming, you can use the async versions of the methods (see the `a` prefix in the function name).

```python
# Asynchronous fetching of configuration
config = await ag.ConfigManager.aget_from_registry(
    app_slug="my-app",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="my-variant-slug",
    variant_version=2
)

print("Fetched configuration asynchronously:")
print(config)
```
