Metadata-Version: 2.4
Name: promptstudio_sdk
Version: 1.0.255
Summary: A Python SDK for PromptStudio
Home-page: https://github.com/promptstudio-dev/promptstudio-sdk-python
Author: PromptStudio
Author-email: support@promptstudio.dev
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pymongo
Requires-Dist: openai
Requires-Dist: anthropic
Requires-Dist: google-genai
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: author-email
Dynamic: home-page
Dynamic: requires-python

# PromptStudio Python SDK

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

## Installation

### From PyPI

```bash
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(...)`.

```python
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:

```python
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:

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

File (image/file URL):

```python
user_message = [
    {
        "type": "file",
        "file_url": {"url": "https://example.com/image.jpg"}
    }
]
```
### Role-based format (ONLY when `bypass=True`)

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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)

```python
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
```
