Implementation:Evidentlyai Evidently SDK Prompts

Knowledge Sources	Evidentlyai_Evidently
Domains	SDK, Prompts, LLM, Versioning
Last Updated	2026-02-14 12:00 GMT

Overview

Defines the SDK prompt management system including versioned prompt models, metadata tracking, the abstract PromptAPI interface, the RemotePrompt entity with API binding, and the cloud-specific CloudPromptAPI implementation.

Description

The SDK prompts module provides the data models and API abstractions for managing versioned prompt templates used in LLM interactions within the Evidently system.

Prompt and PromptMetadata: The Prompt model represents a named prompt entity within a project, carrying an ID, project ID, name, and metadata. PromptMetadata tracks creation/update timestamps and optional author information.

PromptVersion and PromptVersionMetadata: Each prompt can have multiple sequential versions (starting from 1). Each version stores a PromptContent instance (from evidently.llm.prompts.content) and its PromptContentType. The constructor automatically parses raw content into the appropriate PromptContent subclass (trying parse_obj_as first, then PromptContent.parse) and validates content type consistency.

RemotePrompt: Extends Prompt with API binding capabilities. Once bound to a PromptAPI instance via bind(), it provides convenience methods:

list_versions(): List all versions of this prompt
get_version(version): Get a specific version (by number or "latest")
bump_version(content): Create a new version with auto-incremented number
delete(): Delete the prompt and all versions
save(): Persist metadata changes

PromptAPI: Abstract base class defining the full CRUD interface for prompts and versions. Operations include list, get, create, update, delete for prompts and their versions, plus bump_prompt_version for auto-incrementing version numbers.

CloudPromptAPI: Concrete implementation of PromptAPI that communicates with the cloud /api/prompts REST endpoint via a CloudWorkspace. The bump_prompt_version method fetches the latest version number and increments it, starting at 1 if no versions exist.

Usage

Use this module for managing LLM prompt templates in the Evidently Cloud deployment. For OSS deployments, prompts are managed through the artifact system with the PromptArtifactAdapter (see sdk.adapters). For local usage without a service, use LocalPromptAPI (see sdk.local).

Code Reference

Source Location

Repository: Evidentlyai_Evidently
File: src/evidently/sdk/prompts.py

Signature

PromptID = uuid.UUID
PromptVersionID = uuid.UUID

class PromptMetadata(BaseModel):
    created_at: datetime
    updated_at: datetime
    author: Optional[UserID] = None

class Prompt(BaseModel):
    id: PromptID
    project_id: ProjectID
    name: str
    metadata: PromptMetadata

class PromptVersionMetadata(BaseModel):
    created_at: datetime
    updated_at: datetime
    author: Optional[UserID] = None

class PromptVersion(BaseModel):
    id: PromptVersionID
    prompt_id: PromptID
    version: int
    metadata: PromptVersionMetadata
    content: PromptContent
    content_type: PromptContentType

class RemotePrompt(Prompt):
    def bind(self, api: "PromptAPI") -> "RemotePrompt": ...
    def list_versions(self) -> List[PromptVersion]: ...
    def get_version(self, version: VersionOrLatest = "latest") -> PromptVersion: ...
    def bump_version(self, content: Any): ...
    def delete(self): ...
    def save(self): ...

class PromptAPI(ABC):
    def list_prompts(self, project_id: STR_UUID) -> List[RemotePrompt]: ...
    def get_or_create_prompt(self, project_id: STR_UUID, name: str) -> RemotePrompt: ...
    def get_prompt(self, project_id: STR_UUID, name: str) -> RemotePrompt: ...
    def create_prompt(self, project_id: STR_UUID, name: str) -> RemotePrompt: ...
    def bump_prompt_version(self, prompt_id, content: Any) -> PromptVersion: ...

class CloudPromptAPI(PromptAPI):
    def __init__(self, workspace: "CloudWorkspace"): ...

Import

from evidently.sdk.prompts import Prompt, PromptMetadata
from evidently.sdk.prompts import PromptVersion, PromptVersionMetadata
from evidently.sdk.prompts import RemotePrompt
from evidently.sdk.prompts import PromptAPI, CloudPromptAPI
from evidently.sdk.prompts import PromptID, PromptVersionID
from evidently.sdk.prompts import VersionOrLatest

I/O Contract

Prompt

Field	Type	Description
id	`PromptID (uuid.UUID)`	Unique prompt identifier
project_id	`ProjectID (uuid.UUID)`	Parent project identifier
name	`str`	Human-readable prompt name
metadata	`PromptMetadata`	Timestamps and author info

PromptVersion

Field	Type	Description
id	`PromptVersionID`	Unique version identifier
prompt_id	`PromptID`	Parent prompt identifier
version	`int`	Sequential version number (1, 2, 3, ...)
content	`PromptContent`	Prompt template content
content_type	`PromptContentType`	Type discriminator for content
metadata	`PromptVersionMetadata`	Timestamps and author info

CloudPromptAPI Endpoints

Method	HTTP	Endpoint
list_prompts	GET	`/api/prompts?project_id={id}`
get_prompt	GET	`/api/prompts/by-name/{name}?project_id={id}`
get_prompt_by_id	GET	`/api/prompts/{prompt_id}`
create_prompt	POST	`/api/prompts/?project_id={id}`
delete_prompt	DELETE	`/api/prompts/{prompt_id}`
update_prompt	PUT	`/api/prompts/{prompt_id}`
list_versions	GET	`/api/prompts/{prompt_id}/versions`
get_version	GET	`/api/prompts/{prompt_id}/versions/{version}`
create_version	POST	`/api/prompts/{prompt_id}/versions`

Usage Examples

from evidently.sdk.prompts import CloudPromptAPI

# Initialize with cloud workspace
api = CloudPromptAPI(cloud_workspace)

# Get or create a prompt
prompt = api.get_or_create_prompt(project_id, "sentiment-analysis-prompt")

# Create a new version with prompt content
from evidently.llm.prompts.content import PromptContent
version = prompt.bump_version(prompt_content)

# Get the latest version
latest = prompt.get_version("latest")
content = latest.content  # PromptContent instance

# List all versions
all_versions = prompt.list_versions()

# Delete the prompt
prompt.delete()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment