PromptManager

from elsai_prompts.prompt_manager import PromptManager

The client for fetching prompts from your elsai Prompt Manager instance. Construct one per process; thread-safe.

Constructor

PromptManager(
    api_key: str,
    project_id: str,
    environment: str,
    base_url: str | None = None,
    timeout: int = 20,
)

api_key — str

API key issued by the Prompt Manager. Created in the console (API Keys page). Format elsai_<32 chars>. Must be non-empty; raises ValueError otherwise.

project_id — str

UUID of the project to read prompts from. Must be non-empty; raises ValueError otherwise.

environment — str

Runtime environment of the calling code (e.g. "development", "testing", "production"). Every fetch checks that the active version has been released to this environment. Must be non-empty; raises ValueError otherwise.

base_url — str | None (default: None)

On-prem only. Base URL of your on-prem deployment. If None, falls back to the PROMPT_MANAGER_API_URL environment variable. On the SaaS build, this argument is ignored — the URL is hardcoded. On the on-prem build, if neither argument nor env var is set, raises ValueError.

timeout — int (default: 20)

HTTP timeout in seconds per request.

Validation: all four required arguments are checked for non-emptiness at construction time. No network call is made; credentials are validated lazily on the first method call.

Raises: ValueError if any required argument is missing or empty.

Methods

Fetch active version

PromptManager.get_active_prompt_version(
    prompt_name: str,
    headers: dict | None = None,
) -> PromptContent

Fetch the active version of the named prompt for the SDK's configured environment.

prompt_name — str — Name of the prompt within the project. Case-sensitive.

headers — dict | None (default: None) — Optional HTTP headers to attach to the outgoing request. See Custom headers(.

Returns: PromptContent(

Raises:

Exception	When
PromptNotReleasedInEnvironmentError	409 — active version exists, not released to the SDK's env
requests.exceptions.HTTPError	404 (key/project/prompt missing, no active version, not a member) or other HTTP error
requests.exceptions.Timeout	Request exceeded timeout seconds
requests.exceptions.ConnectionError	Network failure
requests.exceptions.RequestException	Any other request-layer failure
KeyError	Response missing the content field (server-side bug)

Example:

pm = PromptManager(
    api_key="elsai_xxx",
    project_id="c8bcaabe-b577-49a4-85da-e37d67652d0c",
    environment="development",
)

prompt = pm.get_active_prompt_version("welcome_email")
print(prompt.kind)              # "f_string"
print(prompt.sha)               # "47be37f69681"
print(prompt.render({"name": "Ada"}))

Per-call environment override

PromptManager.get_active_prompt_version_for_environment(
    prompt_name: str,
    environment: str,
    headers: dict | None = None,
) -> PromptContent

Same as get_active_prompt_version but overrides the SDK's configured environment for this call only.

prompt_name — str — Name of the prompt within the project.

environment — str — The environment to fetch under for this call. Must be non-empty.

headers — dict | None (default: None) — Same as get_active_prompt_version.

Returns: PromptContent(

Raises: same as get_active_prompt_version, plus ValueError if environment is empty.

Example:

prod_prompt = pm.get_active_prompt_version_for_environment(
    "welcome_email",
    environment="production",
)

See Per-call environment( for use cases.

Instance attributes

Attribute	Type	Description
base_url	str	Resolved base URL (constructor arg or env var, right-stripped of trailing /)
api_key	str	The API key
project_id	str	The project ID
environment	str	The default environment
timeout	int	Configured timeout

Endpoint hit by the SDK

For reference — you should not need to call this directly:

GET {base_url}/prompts/active-prompt-version
    ?api_key={api_key}
    &project_id={project_id}
    &prompt_name={prompt_name}
    &environment={environment}

Response on 200:

{
  "prompt_id":     "uuid",
  "prompt_name":   "...",
  "kind":          "instruction | f_string | chat | structured",
  "sha":           "12 hex chars",
  "version_label": "v1.0",
  "content":       { "...kind-specific..." },
  "environments":  ["development"]
}

Response on 409 (PromptNotReleasedInEnvironmentError):

{
  "detail": {
    "message": "Active version is not released to the requested environment.",
    "available_environments": ["development", "testing"]
  }
}

Response on 404:

{ "detail": "Not found" }