Python Client

Learn how to integrate dot-prompt into your Python application using the dotprompt-client package.

1. Installation

Install the Python client package from PyPI:

pip install dotprompt-client

Requirements

Requires Python >=3.10 and a running dot-prompt server (Docker container).

2. Quick Start

First, make sure you have the dot-prompt server running. You can use Docker Compose:

docker compose -f docker-compose.headless.yml up -d

This starts the API server at http://localhost:4000.

Basic Usage

Import and use the client with a context manager:

from dotprompt import DotPromptClient

with DotPromptClient() as client:
    prompts = client.list_prompts()
    print(prompts)

Async Client

For async applications, use the async client:

import asyncio
from dotprompt import DotPromptAsyncClient

async def main():
    client = DotPromptAsyncClient()
    
    # List all prompts
    prompts = await client.list_prompts()
    print(prompts)
    
    # Render a prompt
    result = await client.render('explain', {
        'level': 'expert',
        'user_message': 'What is an atom?'
    })
    print(result.prompt)
    
    await client.close()

asyncio.run(main())

3. Rendering Prompts

Use the render method to compile a prompt with runtime parameters:

from dotprompt import DotPromptClient

with DotPromptClient() as client:
    result = client.render('explain', {
        'level': 'expert',
        'user_message': 'What is an atom?'
    })
    
    print(result.prompt)
    # Output: "Explain this with technical detail: What is an atom?"

The result includes the compiled prompt string and any response contract information.

4. Exported Modules

The package provides the following imports:

from dotprompt.async_client import DotPromptAsyncClient
from dotprompt.client import DotPromptClient
from dotprompt.events import Event
from dotprompt.exceptions import (
    APIClientError,
    ConnectionError,
    DotPromptError,
    MissingRequiredParamsError,
    PromptNotFoundError,
    ServerError,
    TimeoutError,
    ValidationError,
)
from dotprompt.models import (
    CompileResult,
    ContractField,
    FragmentSpec,
    InjectResult,
    ParamSpec,
    PromptSchema,
    RenderResult,
    ResponseContract,
)

5. Key Classes

DotPromptClient

Synchronous wrapper around the async client. Use with context manager for proper cleanup.

DotPromptAsyncClient

Async client using httpx. Recommended for async applications and servers.

6. Context Manager Usage

Always use the context manager to ensure proper connection handling:

from dotprompt import DotPromptClient

# Using context manager ensures proper cleanup
with DotPromptClient(base_url='http://localhost:4000') as client:
    prompts = client.list_prompts()
    # Connection automatically closed when exiting context

The context manager automatically handles connection setup and teardown.

7. Error Handling

The package provides specific exceptions for different error types:

from dotprompt import DotPromptClient
from dotprompt.exceptions import (
    PromptNotFoundError,
    ValidationError,
    ServerError
)

try:
    with DotPromptClient() as client:
        result = client.render('my-prompt', params)
except PromptNotFoundError:
    print("The prompt was not found on the server")
except ValidationError as e:
    print(f"Validation failed: {e}")
except ServerError as e:
    print(f"Server error: {e}")

Exception Types:

DotPromptError - Base exception class
APIClientError - General API client errors
ConnectionError - Connection issues
MissingRequiredParamsError - Missing required parameters
PromptNotFoundError - Prompt doesn't exist
ServerError - Server-side errors
TimeoutError - Request timeouts
ValidationError - Validation failures

8. Dependencies

Runtime Dependencies

httpx (>=0.24.0) - HTTP client library
pydantic (>=2.0.0) - Data validation using Python type annotations

Development Dependencies

pytest (>=7.0.0)
pytest-asyncio
pytest-mock
ruff
mypy