API Reference

Core Functions

llm_call

Synchronous structured LLM call with schema validation and auto-repair.

from promptguard import llm_call

result = llm_call(
    model="gpt-4o",
    prompt="Extract the person's info",
    schema=Person,
    max_retries=3,       # repair attempts on validation failure
    temperature=0.0,
)

Parameters:

Parameter	Type	Description
model	str	Model identifier (e.g. "gpt-4o", "claude-3-sonnet")
prompt	str	The prompt to send
schema	type	Pydantic model, TypedDict, dataclass, or JSON schema dict
max_retries	int	Number of repair attempts (default: 3)
temperature	float	Sampling temperature

Returns: LLMResult with .data (validated instance) and .metadata.

---

allm_call

Async version of llm_call. Same parameters and behavior.

from promptguard import allm_call

result = await allm_call(
    model="gpt-4o",
    prompt="Extract info",
    schema=Person,
)

---

Schema Types

PromptGuard accepts four schema types:

Pydantic BaseModel

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

TypedDict

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int

dataclass

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int

JSON Schema (dict)

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name", "age"]
}

---

Configuration

PromptGuard auto-detects providers from model names. Provider-specific API keys are read from environment variables:

Provider	Environment Variable
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Google	GOOGLE_API_KEY
Local	LOCAL_LLM_BASE_URL (for compatible servers)

---

Logging

PromptGuard is silent by default. Enable logging with configure_logging:

from promptguard import configure_logging

# Enable INFO level logging to stderr
configure_logging(level="INFO")

# Enable DEBUG for detailed request/response info
configure_logging(level="DEBUG")

# JSON format for production/log aggregation
configure_logging(level="INFO", format_style="json")

Log levels: - DEBUG — Detailed request/response info - INFO — Repair attempts, successful operations - WARNING — Validation failures, retries - ERROR — Provider errors, repair exhaustion

---

Exceptions

PromptGuard provides specific exception types for error handling:

from promptguard import (
    PromptGuardError,      # Base exception
    ValidationError,       # Schema validation failed
    RepairExhaustedError,  # Max repair attempts reached
    ProviderError,         # Generic provider error
    AuthenticationError,   # Invalid API key (401)
    RateLimitError,        # Rate limit exceeded (429)
    TimeoutError,          # Request timed out
    ModelNotFoundError,    # Model doesn't exist (404)
    ContextLengthExceededError,  # Prompt too long
    ContentFilteredError,  # Content blocked by safety filters
)

Example error handling:

from promptguard import llm_call, RateLimitError, AuthenticationError
import time

try:
    result = llm_call(prompt="...", model="gpt-4o", schema=MySchema)
except AuthenticationError:
    print("Check your OPENAI_API_KEY")
except RateLimitError as e:
    if e.retry_after:
        time.sleep(e.retry_after)
    # retry...