Configuration Management SDK

This document provides a detailed reference for the Configuration Management SDK, which allows users to manage application configurations, variants, versions, and deployments using custom Pydantic models.

ConfigManager

The ConfigManager class provides methods to retrieve and load configuration parameters for applications and variants.

get_from_registry

get_from_registry(schema=None, *, app_id=None, app_slug=None, variant_id=None, variant_slug=None, variant_version=None, environment_id=None, environment_slug=None, environment_version=None)

Pulls configuration parameters from the server registry.

• Parameters:

  • schema (Optional[Type[T]]): A Pydantic model class defining the configuration structure.
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.
  • variant_id (Optional[str]): The unique identifier of the variant.
  • variant_slug (Optional[str]): The slug of the variant.
  • variant_version (Optional[int]): The version number of the variant.
  • environment_id (Optional[str]): The unique identifier of the environment.
  • environment_slug (Optional[str]): The slug of the environment.
  • environment_version (Optional[int]): The version number of the environment.

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

get_from_route

get_from_route(schema=None) Retrieves configuration from the route context.

• Parameters:

  • schema (Optional[Type[T]]): A Pydantic model class defining the configuration structure.

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

get_from_yaml

get_from_yaml(filename, schema=None)

Loads configuration from a YAML file.

• Parameters:

  • filename (str): The path to the YAML file.
  • schema (Optional[Type[T]]): A Pydantic model class defining the configuration structure.

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

get_from_json

get_from_json(filename, schema=None)

Loads configuration from a JSON file.

• Parameters:

  • filename (str): The path to the JSON file.
  • schema (Optional[Type[T]]): A Pydantic model class defining the configuration structure.

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

aget_from_registry

aget_from_registry(schema=None, *, app_id=None, app_slug=None, variant_id=None, variant_slug=None, variant_version=None, environment_id=None, environment_slug=None, environment_version=None)

Asynchronously pulls configuration parameters from the server registry.

• Parameters: Same as get_from_registry().

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

aget_from_route

aget_from_route(schema=None)

Asynchronously retrieves configuration from the route context.

• Parameters: Same as get_from_route().

• Returns: An instance of the specified schema populated with configuration data, or a dictionary if no schema is provided.

VariantManager

The VariantManager class provides methods to manage application variants, including creation, committing changes, deletion, and listing.

create

create(*, parameters, variant_slug, app_id=None, app_slug=None)

Creates a new variant and commits the initial parameters.

• Parameters:

  • parameters (dict): A dictionary containing the initial configuration parameters.
  • variant_slug (str): The slug of the new variant.
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.

• Returns: A variant object containing details of the created variant.

commit

commit(*, parameters, variant_slug, app_id=None, app_slug=None)

Commits changes to an existing variant, creating a new version.

• Parameters:

  • parameters (dict): A dictionary containing the configuration parameters to commit.
  • variant_slug (str): The slug of the variant.
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.

• Returns: A variant object containing details of the committed version.

delete

delete(*, variant_slug, app_id=None, app_slug=None)

Deletes a variant and all its versions.

• Parameters:

  • variant_slug (str): The slug of the variant to delete.
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.

• Returns: A message confirming deletion.

• Note: Deletion is irreversible and will fail if the variant is deployed to an environment.

list

list(*, app_id=None, app_slug=None)

Lists all variants of an application.

• Parameters:

  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.

• Returns: A list of variant objects.

history

history(*, variant_slug, app_id=None, app_slug=None)

Retrieves the version history of a variant.

• Parameters:

  • variant_slug (str): The slug of the variant.
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.

• Returns: A list of variant version objects.

acreate

acreate(*, parameters, variant_slug, app_id=None, app_slug=None)

Asynchronously creates a new variant and commits the initial parameters.

• Parameters: Same as create().

• Returns: A variant object containing details of the created variant.

acommit

acommit(*, parameters, variant_slug, app_id=None, app_slug=None)

Asynchronously commits changes to an existing variant.

• Parameters: Same as commit().

• Returns: A variant object containing details of the committed version.

adelete

adelete(*, variant_slug, app_id=None, app_slug=None)

Asynchronously deletes a variant.

• Parameters: Same as delete().

• Returns: A message confirming deletion.

alist

alist(*, app_id=None, app_slug=None)

Asynchronously lists all variants of an application.

• Parameters: Same as list().

• Returns: A list of variant objects.

ahistory

ahistory(*, variant_slug, app_id=None, app_slug=None)

Asynchronously retrieves the version history of a variant.

• Parameters: Same as history().

• Returns: A list of variant version objects.

DeploymentManager

The DeploymentManager class provides methods to deploy variants to environments.

deploy

deploy(*, variant_slug, environment_slug, app_id=None, app_slug=None, variant_version=None)

Deploys a variant to a specified environment.

• Parameters:

  • variant_slug (str): The slug of the variant to deploy.
  • environment_slug (str): The slug of the environment (development, staging, or production).
  • app_id (Optional[str]): The unique identifier of the application.
  • app_slug (Optional[str]): The slug of the application.
  • variant_version (Optional[int]): The version number of the variant to deploy; if not provided, deploys the latest version.

• Returns: A deployment object containing details of the deployment.

• Note: Only predefined environments (development, staging, production) are supported.

adeploy

adeploy(*, variant_slug, environment_slug, app_id=None, app_slug=None, variant_version=None)

Asynchronously deploys a variant to a specified environment.

• Parameters: Same as deploy().

• Returns: A deployment object containing details of the deployment.

Data Formats

Configuration Overview

Configurations in Agenta store application parameters. An application can be:

• A simple prompt (completion or chat application)
• A more complex custom workflow application

For custom workflows, users define the configuration schema. For completion or chat applications, Agenta provides the schema.

warning

The variant creation and update endpoints currently don't validate configuration schemas. Invalid configurations can be created but won't work in the playground.

Prompt Configuration Schema

For completion or chat applications, configurations follow this schema:

info

This schema extends OpenAI's ChatCompletion API schema. See the implementation in agenta.sdk.types.

warning

All configuration data must be nested under the prompt key.

Field	Type	Description
prompt.messages	array	List of message objects with role and content
prompt.messages[].role	string	Message role: system, user, assistant, function, or tool
prompt.messages[].content	string	Message content
prompt.template_format	string	Template variable format: fstring {var}, jinja2 {{ var }}, or curly {{var}}
prompt.input_keys	array or null	Optional input key validation list. If omitted, accepts any inputs
prompt.llm_config	object	Model configuration parameters
prompt.llm_config.model	string	Model identifier in LiteLLM naming format
prompt.llm_config.temperature	number or null	Sampling temperature (0-2). Higher values increase randomness
prompt.llm_config.max_tokens	integer or null	Maximum tokens in the response
prompt.llm_config.top_p	number or null	Nucleus sampling parameter (alternative to temperature)
prompt.llm_config.frequency_penalty	number or null	Penalty for token frequency (-2.0 to 2.0)
prompt.llm_config.presence_penalty	number or null	Penalty for token presence (-2.0 to 2.0)
prompt.llm_config.response_format	object or null	Output format specification
prompt.llm_config.response_format.type	string	Format type: text, json_object, or json_schema
prompt.llm_config.response_format.json_schema	object	Schema definition (required when type is json_schema)
prompt.llm_config.response_format.json_schema.name	string	Schema name
prompt.llm_config.response_format.json_schema.description	string or null	Optional schema description
prompt.llm_config.response_format.json_schema.schema	object	JSON Schema object defining the structure
prompt.llm_config.response_format.json_schema.strict	boolean or null	Enable strict schema adherence
prompt.llm_config.stream	boolean or null	Enable partial message streaming
prompt.llm_config.tools	array or null	List of available tools (currently only functions supported)

Example Prompt Configuration

{
  "prompt": {
    "messages": [
      {
        "role": "system",
        "content": "You are an assistant that provides concise answers"
      },
      {
        "role": "user",
        "content": "Explain {{topic}} in simple terms"
      }
    ],
    "llm_config": {
      "model": "gpt-3.5-turbo",
      "temperature": 0.7,
      "max_tokens": 150,
      "top_p": 1.0,
      "frequency_penalty": 0.0,
      "presence_penalty": 0.0
    },
    "template_format": "curly"
  }
}

note

You can use the PromptTemplate class in the SDK to create and validate a prompt configuration. See how to commit a variant.

Available Environments

A list of available environment slugs.

AVAILABLE_ENVIRONMENTS = ["development", "production", "staging"]

Notes

• Variant Immutability: Each commit to a variant creates a new, immutable version.
• Error Handling: Methods may raise exceptions if resources are not found or if operations fail.
• Asynchronous Methods: Asynchronous versions of methods are provided (prefixed with a) for integration with async applications.
• Identifiers: Either app_id or app_slug must be provided where required; similarly for variant_id and variant_slug.
• Environment Restrictions: Deployment is limited to the predefined environments.

Examples

Creating a Variant

from pydantic import BaseModel
import agenta as ag

class MyConfig(BaseModel):
    temperature: float
    model: str
    max_tokens: int

config = MyConfig(
    temperature=0.7,
    model="gpt-3.5-turbo",
    max_tokens=150
)

variant = ag.VariantManager.create(
    parameters=config.dict(),
    app_slug="my-app",
    variant_slug="my-variant"
)

Committing Changes to a Variant

updated_config = MyConfig(
    temperature=1.0,
    model="gpt-4",
    max_tokens=200
)

variant = ag.VariantManager.commit(
    parameters=updated_config.dict(),
    app_slug="my-app",
    variant_slug="my-variant"
)

Deploying a Variant

deployment = ag.DeploymentManager.deploy(
    app_slug="my-app",
    variant_slug="my-variant",
    environment_slug="staging"
)

Fetching Configuration

config = ag.ConfigManager.get_from_registry(
    schema=MyConfig,
    app_slug="my-app",
    variant_slug="my-variant",
    variant_version=2
)

Deleting a Variant

ag.VariantManager.delete(
    app_slug="my-app",
    variant_slug="obsolete-variant"
)

Listing Variants

variants = ag.VariantManager.list(
    app_slug="my-app"
)

Retrieving Variant History

history = ag.VariantManager.history(
    app_slug="my-app",
    variant_slug="my-variant"
)