promptstudio-sdk 1.0.255

A Python SDK for PromptStudio

PromptStudio Python SDK

A Python SDK for interacting with PromptStudio and and AI platforms directly.

Installation

From PyPI

pip install promptstudio-sdk

Quickstart (Async)

Most SDK methods are async (including chat_with_prompt, get_session, get_prompt_identifier, get_prompt_data), so run them using asyncio.run(...).

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({
        "api_key": "YOUR_API_KEY",  # Promptstudio API KEY
        "env": "test",              # "test" or "prod"
        "bypass": True,             # True = direct provider call; False = route through PromptStudio 
        "is_logging": True,     
        "timeout": 25,              # seconds
    })

    # Non-role message format (works in both bypass=True and bypass=False)
    resp = await client.chat_with_prompt(
        prompt_id="YOUR_PROMPT_ID",
        user_message=[{"type": "text", "text": "Hello!"}],
        memory_type="fullMemory",  # "fullMemory" | "windowMemory" | "summarizedMemory"
        window_size=0,
        session_id="",             # "" starts a new session
        variables={},              # pass prompt variables here
        version=1.0,                 # optional
        is_session_enabled=True,   # set False when you don't want to maintain session/history (each call is a single stateless message)
        shot=-1,                   # -1 = include all prompt messages; 0 = none; n>0 = first n pairs
        tag = {
            "userId": "680b5b825149777520281b5b",
            "userName":"Roshni",
            "Location":"India"
        }                          # optional; to include custom metadata such as user identifiers
        grounding=False,           # optional; mainly relevant for Gemini
        verbose=False,
    )

    print(resp)

asyncio.run(main())

Configuration

Create the client like this:

from promptstudio_sdk import PromptStudio

client = PromptStudio({
    "api_key": "YOUR_API_KEY",
    "env": "test",     
    "bypass": True,    
    "is_logging": True,
    "timeout": 25,    
})

env

• "test": use this for testing / sandbox usage. Make sure you use an API key that belongs to the test environment in PromptStudio.
• "prod": use this for live / production usage. Make sure you use an API key that belongs to the production environment in PromptStudio.

bypass

Controls where the request goes:

• bypass=True: makes a direct AI-platform call using the prompt’s published platform configuration
• bypass=False: routes requests through PromptStudio’s API endpoints.

Important constraint:

• Role-based message format is only allowed when bypass=True.
• When bypass=False, pass a plain content list like [{"type":"text","text":"hello"}].

Message formats

Non-role format (recommended; works in both bypass modes)

Text:

user_message = [
    {"type": "text", "text": "Hello"}
]

File (image/file URL):

user_message = [
    {
        "type": "file",
        "file_url": {"url": "https://example.com/image.jpg"}
    }
]

Role-based format (ONLY when bypass=True)

user_message = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Hi"},
        ],
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "Hello! How can I help?"},
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Can you describe this image?"},
            {
                "type": "file",
                "file_url": {
                    "url": "https://example.com/my-image.jpg"
                },
            },
        ],
    },
]

chat_with_prompt (complete examples)

Example: full memory

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({
        "api_key": "YOUR_API_KEY", 
        "env": "test", 
        "bypass": True
        })

    resp = await client.chat_with_prompt(
        prompt_id="YOUR_PROMPT_ID",
        user_message=[{"type": "text", "text": "Tell me a joke"}],
        memory_type="fullMemory",
        window_size=0,
        session_id="",
        variables={},
        version=1,
        is_session_enabled=True,
        shot=-1,
        tag={"feature": "readme-example"},
        grounding=False,
        verbose=False,
    )
    print(resp)

asyncio.run(main())

Example: window memory

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({"api_key": "YOUR_API_KEY", "env": "test", "bypass": True})

    resp = await client.chat_with_prompt(
        prompt_id="YOUR_PROMPT_ID",
        user_message=[{"type": "text", "text": "Summarize what we discussed so far"}],
        memory_type="windowMemory",
        window_size=6,
        session_id="",
        variables={},
    )
    print(resp)

asyncio.run(main())

Example: summarized memory

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({"api_key": "YOUR_API_KEY", "env": "test", "bypass": True})

    resp = await client.chat_with_prompt(
        prompt_id="YOUR_PROMPT_ID",
        user_message=[{"type": "text", "text": "Continue from our previous context"}],
        memory_type="summarizedMemory",
        window_size=0,
        session_id="",
        variables={},
    )
    print(resp)

asyncio.run(main())

Parameters reference (chat_with_prompt)

Required:

• prompt_id (str): Prompt identifier or prompt ID. Example: a direct prompt ID like "687a268dc5719cee58471230" or a folder-style identifier like "folder/subfolder/prompt".
• user_message (list):
  • Non-role list: {"type":"text","text":"..."} / {"type":"file","file_url":{"url":"..."}}
  • Role-based list: {"role":"user","content":[...]}
• memory_type (str): "fullMemory" | "windowMemory" | "summarizedMemory"
• window_size (int): used when memory_type="windowMemory"
• session_id (str): pass "" for a new session or an existing session id to continue
• variables (dict): prompt variables key/value mapping (use {} if none)

Optional:

• version (number): version of the prompt (e.g.1.2)

• is_session_enabled (bool, default True):

  • When True, the SDK maintains session/history for the conversation.
  • When False, no session is maintained and each call is treated as a single, stateless message (no previous context).

• shot (int, default -1) Controls how many message pairs to include from the beginning of the conversation:

  • -1: include all previous messages
  • 0: include no previous messages
  • n > 0: include first n message pairs (2n messages)

• tag (dict): arbitrary metadata

• base_url (str): Override endpoint for custom / external providers (for example, a local Ollama URL or a Vertex model path).

• format (str): Integration type / protocol for custom providers (for example, "ollama" or "vertexAi").

• credentials (dict): Credentials or service-account info required by some custom providers (for example, Google Vertex AI service account JSON as a dict).

• grounding (bool): enables/disables grounding (mainly relevant for Gemini; if omitted, the prompt’s grounding config is used)

• verbose (bool, default False): prints extra debug logs

Utilities (Async)

Get session

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({
        "api_key": "YOUR_API_KEY", 
        "env": "test", 
        "bypass": True
    })

    session = await client.get_session(session_id="YOUR_SESSION_ID")
    print(session)

asyncio.run(main())

Get prompt identifier

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({
        "api_key": "YOUR_API_KEY", 
        "env": "test", 
        "bypass": True
    })

    ident = await client.get_prompt_identifier(prompt_id="YOUR_PROMPT_ID")
    print(ident)

asyncio.run(main())

Get prompt data (details)

import asyncio
from promptstudio_sdk import PromptStudio

async def main():
    client = PromptStudio({
        "api_key": "YOUR_API_KEY", 
        "env": "test", 
        "bypass": True
    })
    
    details = await client.get_prompt_data(prompt_id="YOUR_PROMPT_ID", version=1.0)
    print(details)

asyncio.run(main())

License

MIT