sherpa_ai.prompts package

Overview

The prompts package provides a comprehensive system for creating, loading, and formatting prompts for language models. It supports text-based, chat-based, and JSON-structured prompts with features for variable substitution, template rendering, validation, and managing prompt collections organized into groups.

Key Components

• Base: Core classes for representing different prompt types and organizing them into groups

• PromptLoader: Utilities for loading, validating, and querying prompts from JSON files

• PromptTemplate: Tools for formatting prompts with variable substitution and metadata retrieval

JSON Structure Requirements

Prompts must be organized in JSON files following this hierarchical structure:

Root Structure - Array of prompt groups:

[
  {
    "prompt_parent_id": "group_name",
    "description": "Description of the prompt group",
    "prompts": [...]
  }
]

Prompt Structure - Each prompt contains metadata and versions:

{
  "prompt_id": "unique_prompt_identifier",
  "description": "What this prompt does",
  "versions": [...]
}

Version Structure - Each version defines the actual prompt content:

{
  "version": "1.0",
  "change_log": "Description of changes in this version",
  "type": "text|chat|json",
  "content": "varies by type",
  "variables": {"var_name": "default_value"},
  "response_format": {
    "type": "json_schema",
    "json_schema": {...}
  }
}

Content Types:

• Text prompts: "content": "Simple text with {variables}"

• Chat prompts: "content": [{"role": "system|user|assistant", "content": "message"}]

• JSON prompts: "content": {"structured": "data with {variables}"}

Variable Substitution: Variables are defined with curly braces {variable_name} and can be replaced during formatting.

Complete Example

[
  {
    "prompt_parent_id": "math_operations",
    "description": "Prompts for mathematical calculations",
    "prompts": [
      {
        "prompt_id": "add_numbers",
        "description": "Prompt to add two numbers with structured output",
        "versions": [
          {
            "version": "1.0",
            "change_log": "Initial version",
            "type": "text",
            "content": "Add {first_num} and {second_num}",
            "variables": {
              "first_num": 5,
              "second_num": 10
            },
            "response_format": {
              "type": "json_schema",
              "json_schema": {
                "name": "addition_result",
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {"type": "number"},
                    "explanation": {"type": "string"}
                  },
                  "required": ["result", "explanation"]
                }
              }
            }
          }
        ]
      }
    ]
  }
]

Usage Examples

Basic Prompt Loading and Formatting:

from sherpa_ai.prompts.prompt_template_loader import PromptTemplate

# Initialize with JSON file
template = PromptTemplate("prompts.json")

# Format a text prompt with custom variables
formatted = template.format_prompt(
    prompt_parent_id="math_operations",
    prompt_id="add_numbers",
    version="1.0",
    variables={"first_num": 15, "second_num": 25}
)
print(formatted)  # "Add 15 and 25"

Working with Chat Prompts:

# Format a chat prompt (returns list of message dicts)
chat_prompt = template.format_prompt(
    prompt_parent_id="conversation",
    prompt_id="greeting_chat",
    version="1.0",
    variables={"name": "Alice"}
)
# Returns: [{"role": "system", "content": "..."}, {"role": "user", "content": "Hello Alice"}]

Getting Complete Prompt Information:

# Get formatted prompt with metadata and output schema
full_prompt = template.get_full_formatted_prompt(
    prompt_parent_id="math_operations",
    prompt_id="add_numbers",
    version="1.0",
    variables={"first_num": 100, "second_num": 200}
)

print(full_prompt["description"])     # Prompt description
print(full_prompt["content"])         # Formatted content
print(full_prompt["output_schema"])   # Expected response format

Direct Access Methods:

from sherpa_ai.prompts.prompt_loader import PromptLoader

loader = PromptLoader("prompts.json")

# Get specific prompt version object
version_obj = loader.get_prompt_version("math_operations", "add_numbers", "1.0")

# Get just the content
content = loader.get_prompt_content("math_operations", "add_numbers", "1.0")

# Get output schema for response validation
schema = loader.get_prompt_output_schema("math_operations", "add_numbers", "1.0")

Error Handling

The system includes robust validation and error handling:

from sherpa_ai.prompts.prompt_loader import InvalidPromptContentError

try:
    loader = PromptLoader("invalid_prompts.json")
except InvalidPromptContentError as e:
    print(f"Prompt validation failed: {e}")
except FileNotFoundError as e:
    print(f"Prompt file not found: {e}")

Key Features

• Hierarchical Organization: Prompts are organized into groups for better management

• Version Control: Multiple versions of prompts with change logs

• Type Safety: Validation ensures prompt structure matches declared types

• Variable Substitution: Dynamic content replacement with default values

• Multiple Content Types: Support for text, chat, and JSON-structured prompts

• Response Schema: Define expected output formats for structured responses

• Resource Loading: Automatic detection of package resources vs. filesystem paths

Submodules

Module	Description
sherpa_ai.prompts.Base	Core Pydantic models for prompt types, versions, and groups with validation
sherpa_ai.prompts.prompt_loader	Loading, validation, and querying of prompt definitions from JSON files
sherpa_ai.prompts.prompt_template_loader	Template formatting with variable substitution and complete prompt retrieval

sherpa_ai.prompts.Base module

This module defines the core data structures for the prompt system using Pydantic models for validation.

Core Classes:

• PromptVersion: Base class for all prompt versions with common attributes

• TextPromptVersion: Specialized for simple text-based prompts

• ChatPromptVersion: Specialized for conversation-style prompts with role/content pairs

• JsonPromptVersion: Specialized for structured JSON prompts

• Prompt: Container for prompt metadata and its versions

• PromptGroup: Organizes related prompts under a common identifier

Base prompt classes for Sherpa AI.

This module provides base classes for defining different types of prompts. It includes classes for text, chat, and JSON prompts, as well as prompt groups for organizing related prompts.

class sherpa_ai.prompts.Base.PromptVersion(**data)

Bases: BaseModel

Base class for all prompt versions.

This class defines the common structure for all prompts in the system, including metadata and content.

version

Version identifier for the prompt.

Type:

str

change_log

Description of changes in this version.

Type:

str

type

The type of prompt (e.g., “text”, “chat”, “json”).

Type:

str

content

The actual prompt content.

Type:

Union[str, List[Dict[str, str]], Dict]

variables

Variables that can be substituted in the prompt.

Type:

Dict

response_format

Expected format of responses to this prompt.

Type:

Dict

Example

>>> prompt = PromptVersion(

...     version="1.0",

...     change_log="Prompt for search queries",

...     type="text",

...     content="Search for {query}",

...     variables={"query"

“”},

...     response_format={"type"

“string”}

... )

version: str

change_log: str

type: str

content: str | List[Dict[str, str]] | Dict

variables: Dict

response_format: Dict

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sherpa_ai.prompts.Base.ChatPromptVersion(**data)

Bases: PromptVersion

Prompt version class for chat-based interactions.

This class represents prompts that consist of a sequence of chat messages, typically with alternating roles (e.g., system, user, assistant).

content

List of chat messages, each with role and content.

Type:

List[Dict[str, str]]

Example

>>> chat = ChatPromptVersion(
...     name="greeting",
...     description="Chat greeting",
...     version="1.0",
...     content=[
...         {"role": "system", "content": "You are a helpful assistant"},
...         {"role": "user", "content": "Hello {name}"}
...     ],
...     variables={"name": ""},
...     response_format={"type": "string"}
... )

content: List[Dict[str, str]]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sherpa_ai.prompts.Base.TextPromptVersion(**data)

Bases: PromptVersion

Prompt version class for simple text-based prompts.

This class represents a specific version of a prompt that consists of a single text string or a list of strings that will be joined.

content

The text content of the prompt, either as a string or as a list of strings that will be joined with spaces.

Type:

Union[str, List[str]]

Example

>>> text = TextPromptVersion(
...     name="query",
...     description="Search query prompt",
...     version="1.0",
...     content="Find information about {topic}",
...     variables={"topic": ""},
...     response_format={"type": "string"}
... )

content: str | List[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sherpa_ai.prompts.Base.JsonPromptVersion(**data)

Bases: PromptVersion

Prompt version class for JSON-structured prompts.

This class represents prompts that have a structured JSON format, useful for complex templates or structured data.

content

The JSON content of the prompt.

Type:

Dict

Example

>>> json = JsonPromptVersion(
...     name="api_request",
...     description="API request template",
...     version="1.0",
...     content={"endpoint": "/api/{version}/search"},
...     variables={"version": "v1"},
...     response_format={"type": "object"}
... )

content: Dict

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sherpa_ai.prompts.Base.Prompt(**data)

Bases: BaseModel

Base class for all prompt types.

This class defines the common structure for all prompts in the system, including metadata and a list of its versions.

prompt_id

Unique identifier for the prompt.

Type:

str

description

Human-readable description of the prompt’s purpose.

Type:

str

versions

A list of different versions of this prompt.

Type:

List[PromptVersion]

prompt_id: str

description: str

versions: List[PromptVersion]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sherpa_ai.prompts.Base.PromptGroup(**data)

Bases: BaseModel

Group of related prompts.

This class organizes related prompts into a logical group, making it easier to manage and retrieve sets of related prompts.

prompt_parent_id

Name of the prompt group.

Type:

str

description

Description of the group’s purpose.

Type:

str

prompts

List of prompts in this group.

Type:

List[Prompt]

Example

>>> group = PromptGroup(
...     prompt_parent_id="search_prompts",
...     description="Prompts for search operations",
...     prompts=[text_prompt, chat_prompt]
... )

prompt_parent_id: str

description: str

prompts: List[Prompt]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sherpa_ai.prompts.prompt_loader module

This module handles loading prompts from JSON files and provides access methods for retrieving specific prompts and their components.

Key Classes:

• PromptLoader: Main class for loading and validating prompt collections

• JsonToObject: Utility for converting JSON data to Python objects

• InvalidPromptContentError: Exception for validation failures

Key Functions:

• load_json(): Loads JSON from package resources or filesystem

• get_prompts(): Extracts prompt data from loaded JSON

Prompt loading and validation module for Sherpa AI.

This module provides functionality for loading and validating prompts from JSON files. It includes classes and functions for converting JSON data into prompt objects, validating their structure, and managing prompt collections.

class sherpa_ai.prompts.prompt_loader.JsonToObject(json_data)

Bases: object

Utility class for converting JSON data to Python objects.

This class recursively converts JSON data into Python objects with attributes matching the JSON structure.

Example

>>> data = {"name": "test", "config": {"value": 42}}
>>> obj = JsonToObject(data)
>>> print(obj.name)
'test'
>>> print(obj.config.value)
42

sherpa_ai.prompts.prompt_loader.load_json(file_path)

Load JSON data from a file path or package resource.

This function attempts to load JSON data first from the package resources, then from the filesystem if not found in resources.

Parameters:

file_path (str) – Path to JSON file (relative to sherpa_ai or absolute).

Returns:

Loaded JSON data as a dictionary or list.

Return type:

Union[Dict, List]

Raises:

FileNotFoundError – If file not found in resources or filesystem.

Example

>>> data = load_json("prompts/templates.json")
>>> print(data["version"])
'1.0'

sherpa_ai.prompts.prompt_loader.get_prompts(data)

Extract prompts from loaded JSON data.

This function processes the JSON data structure to extract all prompts, organizing them by their wrapper names.

Parameters:

data (Union[Dict, List]) – JSON data containing prompt definitions.

Returns:

Dictionary mapping wrapper names to prompt lists.

Return type:

Dict[str, List[Dict]]

Example

>>> data = {"wrapper1": [{"prompts": [{"name": "p1"}, {"name": "p2"}]}]}
>>> prompts = get_prompts(data)
>>> print(len(prompts["wrapper1"]))
2

exception sherpa_ai.prompts.prompt_loader.InvalidPromptContentError

Bases: Exception

Exception for invalid prompt content.

This exception is raised when prompt content doesn’t match the expected structure or types.

Example

>>> try:
...     raise InvalidPromptContentError("Missing 'content' field")
... except InvalidPromptContentError as e:
...     print(str(e))
'Missing 'content' field'

class sherpa_ai.prompts.prompt_loader.PromptLoader(json_file_path)

Bases: object

Loader class for managing prompt collections.

This class handles loading prompts from JSON files, validating their structure, and providing access to individual prompts.

data

Raw JSON data.

Type:

Union[Dict, List]

prompts

Validated prompt groups.

Type:

List[PromptGroup]

Example

>>> loader = PromptLoader("prompts.json")
>>> prompt = loader.get_prompt("prompt_parent_id", "prompt_id", "1.0")
>>> print(prompt.content)
'Hello {name}!'

get_prompt_version(prompt_parent_id, prompt_id, version)

Get a specific prompt version by its identifiers.

Parameters:

• prompt_parent_id (str) – Prompt group ID.

• prompt_id (str) – Unique identifier for the prompt.

• version (str) – Specific version of the prompt.

Returns:

The requested prompt version if found, None otherwise.

Return type:

Optional[PromptVersion]

get_prompt_content(prompt_parent_id, prompt_id, version)

Get the content of a specific prompt version.

Parameters:

• prompt_parent_id (str) – Prompt group ID.

• prompt_id (str) – Unique identifier for the prompt.

• version (str) – Specific version of the prompt.

Returns:

The prompt version’s content if found, None otherwise.

Return type:

Optional[Any]

get_prompt_output_schema(prompt_parent_id, prompt_id, version)

Get the output schema of a specific prompt version.

Parameters:

• prompt_parent_id (str) – Prompt group ID.

• prompt_id (str) – Unique identifier for the prompt.

• version (str) – Specific version of the prompt.

Returns:

The prompt version’s response format (output schema) if found, None otherwise.

Return type:

Optional[Dict]

Example

>>> content = loader.get_prompt_content("chat", "greeting", "1.0")
>>> print(content)
'Hello {name}!'

sherpa_ai.prompts.prompt_template_loader module

This module extends the base loader to provide template formatting capabilities with variable substitution.

Key Class:

• PromptTemplate: Extends PromptLoader with formatting methods for variable substitution across all prompt types

Key Methods:

• format_prompt(): Formats prompts by replacing variables with provided values

• get_full_formatted_prompt(): Returns formatted content along with metadata and output schema

Prompt template loading and formatting module for Sherpa AI.

This module provides functionality for loading prompt templates and formatting them with variables. It extends the base PromptLoader to add variable substitution capabilities for different prompt types.

class sherpa_ai.prompts.prompt_template_loader.PromptTemplate(json_file_path)

Bases: PromptLoader

Template loader and formatter for prompts.

This class extends PromptLoader to add variable substitution capabilities. It can format text, chat, and JSON prompts by replacing placeholders with actual values.

Example

>>> template = PromptTemplate("prompts.json")
>>> formatted = template.format_prompt(
...     prompt_parent_id="chat",
...     prompt_id="greeting",
...     version="1.0",
...     variables={"name": "Alice"}
... )
>>> print(formatted[0]["content"])
'Hello Alice!'

format_prompt(prompt_parent_id, prompt_id, version, variables=None)

Format a prompt by replacing variables with values.

This method loads a prompt template and replaces any variable placeholders with provided values. It handles different prompt types (text, chat, JSON) appropriately.

Parameters:

• prompt_parent_id (str) – Name of the wrapper containing the prompt.

• prompt_id (str) – ID of the prompt to format.

• version (str) – Version of the prompt to format.

• variables (Optional[Dict[str, Union[str, int, float]]]) – Values to substitute in the prompt. If None, uses defaults from JSON.

Returns:

Formatted prompt

content if found and successfully formatted, None otherwise.

Return type:

Optional[Union[str, List[Dict[str, str]], Dict]]

Example

>>> template = PromptTemplate("prompts.json")
>>> formatted = template.format_prompt(
...     prompt_parent_id="text",
...     prompt_id="search",
...     version="1.0",
...     variables={"query": "python programming"}
... )
>>> print(formatted)
'Search for: python programming'

format_response_format_for_provider(prompt_parent_id, prompt_id, version, llm, variables=None)

Format response format schema for a specific LLM provider.

This method detects the provider from the LLM instance and returns the response format in the appropriate format for that provider.

Parameters:

• prompt_parent_id (str) – Name of the wrapper containing the prompt.

• prompt_id (str) – ID of the prompt to format.

• version (str) – Version of the prompt to format.

• llm (Optional[BaseChatModel]) – LLM instance to detect provider from.

• variables (Optional[Dict[str, Union[str, int, float, List]]]) – Values to substitute in the schema. If None, uses defaults from JSON.

Returns:

Provider-specific format: - OpenAI: Pydantic model class - Anthropic: Tool definition dict - Google: responseSchema dict - Cohere: response_format dict - None/Unknown: JSON Schema dict (fallback)

Return type:

Optional[Union[Dict[str, Any], Type[BaseModel]]]

Example

>>> template = PromptTemplate("prompts.json")
>>> llm = ChatOpenAI()
>>> formatted = template.format_response_format_for_provider(
...     prompt_parent_id="addition_prompts",
...     prompt_id="add_numbers_text",
...     version="1.0",
...     llm=llm
... )
>>> # Returns Pydantic model for OpenAI

format_response_format(prompt_parent_id, prompt_id, version, variables=None)

Format the response format schema by replacing variables with values.

This method specifically handles variable substitution in response format schemas, including enum values in JSON schemas.

Parameters:

• prompt_parent_id (str) – Name of the wrapper containing the prompt.

• prompt_id (str) – ID of the prompt to format.

• version (str) – Version of the prompt to format.

• variables (Optional[Dict[str, Union[str, int, float, List]]]) – Values to substitute in the schema. If None, uses defaults from JSON.

Returns:

Formatted response format schema if found and successfully

formatted, None otherwise.

Return type:

Optional[Dict]

Example

>>> template = PromptTemplate("prompts.json")
>>> formatted_schema = template.format_response_format(
...     prompt_parent_id="supplement",
...     prompt_id="recommendation",
...     version="1.0",
...     variables={"available_skus": ["SKU-001", "SKU-002", "SKU-003"]}
... )

get_full_formatted_prompt(prompt_parent_id, prompt_id, version, variables=None, llm=None)

Get a formatted prompt with metadata.

This method formats a prompt and returns it along with its description and output schema. It’s useful when you need the complete prompt context, not just the formatted content.

Parameters:

• prompt_parent_id (str) – Name of the wrapper containing the prompt.

• prompt_id (str) – ID of the prompt to format.

• version (str) – Version of the prompt to format.

• variables (Optional[Dict[str, Union[str, int, float, List]]]) – Values to substitute in the prompt. If None, uses defaults from JSON.

• llm (Optional[BaseChatModel]) – Optional LLM instance for provider-specific schema formatting. If provided, output_schema will be formatted for the detected provider.

Returns:

Dictionary containing formatted content, description, and schema, or None if prompt not found. The output_schema will be provider-specific if llm is provided, otherwise it will be JSON Schema.

Return type:

Optional[Dict[str, Union[str, List[Dict[str, str]], Dict, Type[BaseModel]]]]

Example

>>> template = PromptTemplate("prompts.json")
>>> result = template.get_full_formatted_prompt(
...     prompt_parent_id="text",
...     prompt_id="search",
...     version="1.0",
...     variables={"query": "python"}
... )
>>> print(result["description"])
'Search query template'
>>> # With provider-specific formatting:
>>> llm = ChatOpenAI()
>>> result = template.get_full_formatted_prompt(
...     prompt_parent_id="addition_prompts",
...     prompt_id="add_numbers_text",
...     version="1.0",
...     llm=llm
... )
>>> # output_schema will be a Pydantic model for OpenAI

Module contents