Per-Call Environment Override

PromptManager is constructed with a default environment. Every get_active_prompt_version call uses that default. Sometimes you need to fetch under a different environment for a single call — that's what get_active_prompt_version_for_environment is for.

pm = PromptManager(..., environment="development")

# Default call - uses environment="development":
dev_prompt = pm.get_active_prompt_version("welcome_email")

# Per-call override - uses environment="production":
prod_prompt = pm.get_active_prompt_version_for_environment(
    "welcome_email",
    environment="production",
)

Signature

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

Identical to get_active_prompt_version except for the explicit environment argument. Validation, response shape, and error semantics are the same.

When to use it

Internal tooling

A diff tool that compares the same prompt across dev / testing / production. Or an audit script that asks "what prompt is in production right now?" from a non-production runtime.

A/B testing

Release the experimental version to a custom env (e.g. "experiment_b"); your code fetches both branches by env name and runs the experiment.

Eval pipelines

Replay a production case in development. Fetch the production version explicitly so you're evaluating exactly what customers saw.

Migrations

Verify a prompt has been released to a new environment before flipping traffic to code that uses it.

When not to use it

If you find yourself overriding the environment on every call, you've probably mis-configured the SDK. The default environment should match the actual runtime — your production binary should be initialized with environment="production", not with "development" and per-call overrides.

The override is for exceptions, not the norm.

Example — diff tool

A small script that prints the active version's SHA across all environments:

import os
from dotenv import load_dotenv
from elsai_prompts.prompt_manager import (
    PromptManager,
    PromptNotReleasedInEnvironmentError,
)

load_dotenv()

pm = PromptManager(
    api_key=os.environ["ELSAI_API_KEY"],
    project_id=os.environ["ELSAI_PROJECT_ID"],
    environment="development",
)

prompt_name = "welcome_email"

for env in ("development", "testing", "production"):
    try:
        prompt = pm.get_active_prompt_version_for_environment(prompt_name, environment=env)
        print(f"{env:>12}: {prompt.sha}  (label={prompt.version_label})")
    except PromptNotReleasedInEnvironmentError as e:
        print(f"{env:>12}: NOT RELEASED  (available: {e.available_environments})")

Sample output:

 development: 47be37f69681  (label=v1.2)
     testing: 47be37f69681  (label=v1.2)
  production: 2d917f00aa11  (label=v1.0)

You can immediately tell: v1.2 is out in dev+testing but production is still on v1.0.

Example — A/B testing

Release version A to production and version B to a custom env experiment_b. In code, flip on a feature flag:

def get_welcome_prompt(user_id):
    is_experiment = is_user_in_experiment(user_id, "welcome_v2")
    env = "experiment_b" if is_experiment else "production"
    return pm.get_active_prompt_version_for_environment("welcome_email", environment=env)

When B wins, promote it to production and remove the branch.

Validation

environment must be non-empty; otherwise ValueError is raised:

pm.get_active_prompt_version_for_environment("welcome_email", environment="")
# ValueError: environment is required.