trulens.core.prompt

trulens.core.prompt

Prompt-management operations over the configured TruLens database.

These functions back the TruSession prompt methods. They read and write prompt definitions, versions, and labels; they never render with a model and never need credentials.

Label lookups always resolve from the database. The process-local LabelCache only skips repeated reads within its time-to-live, so correctness never depends on it.

Attributes

DEFAULT_LABEL_CACHE_TTL module-attribute

DEFAULT_LABEL_CACHE_TTL: float = 0.0

Default time-to-live in seconds. Zero means every lookup hits the database.

Classes

LabelCache

A process-local time-to-live cache of label to exact version.

This is an optimisation only. Entries expire after ttl seconds and any caller can bypass or clear it.

Functions

get

get(
    prompt_id: PromptID, label: str
) -> Optional[PromptVersionID]

Get a cached version id, or None when absent or expired.

set

set(
    prompt_id: PromptID,
    label: str,
    version_id: PromptVersionID,
) -> None

Store a version id for a label.

invalidate

invalidate(
    prompt_id: Optional[PromptID] = None,
    label: Optional[str] = None,
) -> None

Drop one entry, every entry of one prompt, or the whole cache.

Functions

create_prompt

create_prompt(
    db: DB,
    slug: str,
    name: Optional[str] = None,
    prompt_type: Union[PromptType, str] = TEXT,
    description: Optional[str] = None,
    tags: Optional[Sequence[str]] = None,
) -> Prompt

Create a prompt, or update the metadata of an existing slug.

PARAMETER	DESCRIPTION
db	The database to write to. TYPE: DB
slug	Stable key such as support-assistant. TYPE: str
name	Display name. Defaults to the slug. TYPE: Optional[str] DEFAULT: None
prompt_type	text or chat. Fixed after creation. TYPE: Union[PromptType, str] DEFAULT: TEXT
description	Free-text description. TYPE: Optional[str] DEFAULT: None
tags	Tags for grouping. TYPE: Optional[Sequence[str]] DEFAULT: None

RETURNS	DESCRIPTION
Prompt	The stored prompt.

create_prompt_version

create_prompt_version(
    db: DB,
    prompt: Union[Prompt, PromptID, str],
    text: Optional[str] = None,
    messages: Optional[
        Sequence[Union[PromptMessage, Dict[str, Any]]]
    ] = None,
    variables: Optional[Sequence[str]] = None,
    model_defaults: Optional[Dict[str, Any]] = None,
    response_format: Optional[Dict[str, Any]] = None,
    change_note: Optional[str] = None,
    parent_version_id: Optional[PromptVersionID] = None,
    created_by: Optional[str] = None,
    cache: Optional[LabelCache] = None,
) -> PromptVersion

Create an immutable version and move latest onto it.

Creating the same content twice returns the same version.

PARAMETER	DESCRIPTION
db	The database to write to. TYPE: DB
prompt	A prompt, prompt id, or slug. TYPE: Union[Prompt, PromptID, str]
text	Template string for a text prompt. TYPE: Optional[str] DEFAULT: None
messages	Ordered messages for a chat prompt. TYPE: Optional[Sequence[Union[PromptMessage, Dict[str, Any]]]] DEFAULT: None
variables	Declared variable names. Inferred from the content when omitted. TYPE: Optional[Sequence[str]] DEFAULT: None
model_defaults	Provider-neutral model settings. TYPE: Optional[Dict[str, Any]] DEFAULT: None
response_format	Response-format metadata for provider adapters. TYPE: Optional[Dict[str, Any]] DEFAULT: None
change_note	Why the version was created. TYPE: Optional[str] DEFAULT: None
parent_version_id	The version this one derives from. Defaults to whatever latest currently points at. TYPE: Optional[PromptVersionID] DEFAULT: None
created_by	Who created the version. TYPE: Optional[str] DEFAULT: None
cache	Cache to invalidate for the moved latest label. TYPE: Optional[LabelCache] DEFAULT: None

RETURNS	DESCRIPTION
PromptVersion	The stored version.

set_prompt_label

set_prompt_label(
    db: DB,
    prompt: Union[Prompt, PromptID, str],
    label: str,
    version: Union[PromptVersion, PromptVersionID],
    moved_by: Optional[str] = None,
    cache: Optional[LabelCache] = None,
) -> PromptLabel

Point a label at one exact version.

Rolling back is the same call with an older version.

PARAMETER	DESCRIPTION
db	The database to write to. TYPE: DB
prompt	A prompt, prompt id, or slug. TYPE: Union[Prompt, PromptID, str]
label	The label name, for example production. TYPE: str
version	The version or version id to point at. TYPE: Union[PromptVersion, PromptVersionID]
moved_by	Caller label written to the history entry. TYPE: Optional[str] DEFAULT: None
cache	Cache to invalidate for this label. TYPE: Optional[LabelCache] DEFAULT: None

RETURNS	DESCRIPTION
PromptLabel	The resulting label pointer.

resolve_prompt

resolve_prompt(
    db: DB,
    prompt: Union[Prompt, PromptID, str],
    label: Optional[str] = None,
    version_id: Optional[PromptVersionID] = None,
    cache: Optional[LabelCache] = None,
    use_cache: bool = True,
) -> ResolvedPrompt

Resolve a prompt to one exact version.

PARAMETER	DESCRIPTION
db	The database to read from. TYPE: DB
prompt	A prompt, prompt id, or slug. TYPE: Union[Prompt, PromptID, str]
label	Label to resolve. Defaults to latest when no version_id is given. TYPE: Optional[str] DEFAULT: None
version_id	Exact version to load. Wins over label. TYPE: Optional[PromptVersionID] DEFAULT: None
cache	Optional label cache. TYPE: Optional[LabelCache] DEFAULT: None
use_cache	Set false to bypass cache for this call. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
ResolvedPrompt	A ResolvedPrompt.

RAISES	DESCRIPTION
ValueError	If the prompt, label, or version does not exist.

as_prompt

as_prompt(
    db: DB, prompt: Union[Prompt, PromptID, str]
) -> Prompt

Accept a prompt, a prompt id, or a slug and return the stored prompt.

PARAMETER	DESCRIPTION
db	The database to read from. TYPE: DB
prompt	A prompt, prompt id, or slug. TYPE: Union[Prompt, PromptID, str]

RETURNS	DESCRIPTION
Prompt	The stored prompt.

RAISES	DESCRIPTION
ValueError	If no such prompt exists.