Initializing the SDK

PromptManager is the only class you need to construct. It holds your credentials and makes HTTP calls to the Prompt Manager API.

from elsai_prompts.prompt_manager import PromptManager

pm = PromptManager(
    api_key="elsai_xxx...",
    project_id="c8bcaabe-b577-49a4-85da-e37d67652d0c",
    environment="development",
    base_url="https://prompts.your-company.com",   # on-prem only
    timeout=20,
)

Arguments

api_key — str

Your API key. Created in the console (API Keys page). Format elsai_<32 chars>. Plaintext is only shown once at creation — store it securely.

project_id — str

UUID of the project that owns the prompts you'll fetch. Find it in the project URL or the project settings page.

environment — str

The runtime environment of this code — typically "development", "testing", or "production". The SDK enforces that the active version has been released to this environment; otherwise it raises PromptNotReleasedInEnvironmentError. See Environments(.

base_url — str (on-prem only)

The URL of your on-prem deployment (e.g. https://prompts.your-company.com). Falls back to the PROMPT_MANAGER_API_URL environment variable. SaaS users leave this empty — the SaaS build hardcodes the hosted URL.

timeout — int

HTTP timeout in seconds. Each get_active_prompt_version call waits at most this long before raising requests.exceptions.Timeout.

Validation behavior

The constructor fails fast on missing required arguments:

PromptManager(api_key="", project_id="x", environment="dev")
# ValueError: api_key is required.

PromptManager(api_key="x", project_id="", environment="dev")
# ValueError: project_id is required.

PromptManager(api_key="x", project_id="x", environment="")
# ValueError: environment is required. Pass the runtime environment of this code (e.g. 'development', 'testing', 'production').

# On-prem only - base_url missing AND PROMPT_MANAGER_API_URL not set:
PromptManager(api_key="x", project_id="x", environment="dev")
# ValueError: Base URL for Prompt Manager API is not set. Pass base_url= or set the PROMPT_MANAGER_API_URL environment variable.

The constructor does not make a network call — credentials are validated lazily on the first get_active_prompt_version call. This means startup is fast and you can construct the client even if the API is temporarily unreachable.

Loading credentials from .env

The recommended pattern. Install python-dotenv:

pip install python-dotenv

.env file (gitignored):

ELSAI_API_KEY=elsai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELSAI_PROJECT_ID=c8bcaabe-b577-49a4-85da-e37d67652d0c
ELSAI_ENVIRONMENT=development
# On-prem only:
PROMPT_MANAGER_API_URL=https://prompts.your-company.com

Loader:

import os
from dotenv import load_dotenv
from elsai_prompts.prompt_manager import PromptManager

load_dotenv()

pm = PromptManager(
    api_key=os.environ["ELSAI_API_KEY"],
    project_id=os.environ["ELSAI_PROJECT_ID"],
    environment=os.environ["ELSAI_ENVIRONMENT"],
    # base_url is auto-read from PROMPT_MANAGER_API_URL on on-prem
)

One client per process

PromptManager is cheap to construct, but there's no benefit to constructing more than one per process. Recommended pattern: construct once at startup, inject everywhere.

FastAPI

# app/deps.py
import os
from dotenv import load_dotenv
from elsai_prompts.prompt_manager import PromptManager

load_dotenv()

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

# app/routes.py
from fastapi import FastAPI
from app.deps import pm

app = FastAPI()

@app.get("/welcome")
def welcome():
    prompt = pm.get_active_prompt_version("welcome_email")
    return {"text": prompt.render({"name": "Ada"})}

Django

# myapp/services.py
import os
from elsai_prompts.prompt_manager import PromptManager

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

# myapp/views.py
from django.http import JsonResponse
from .services import pm

def welcome(request):
    prompt = pm.get_active_prompt_version("welcome_email")
    return JsonResponse({"text": prompt.render({"name": "Ada"})})

Plain script

import os
from dotenv import load_dotenv
from elsai_prompts.prompt_manager import PromptManager

load_dotenv()

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

if __name__ == "__main__":
    prompt = pm.get_active_prompt_version("welcome_email")
    print(prompt.render({"name": "Ada"}))

Thread safety

PromptManager is safe to share across threads. It holds no mutable state — every method call constructs its own HTTP request. No locking is needed.

Multiple projects

If you need to read from multiple projects, construct one PromptManager per project:

pm_marketing = PromptManager(api_key=KEY, project_id=PROJECT_MARKETING, environment=ENV)
pm_support   = PromptManager(api_key=KEY, project_id=PROJECT_SUPPORT,   environment=ENV)

welcome = pm_marketing.get_active_prompt_version("welcome_email")
triage  = pm_support.get_active_prompt_version("triage_intent")

The same API key works across all projects the key's owner has access to.