API Reference

This document covers the core interface, CLI commands, and integration patterns of the prompt-inspector package.

---

Python API

prompt_inspector.inspect()

Initializes the background visualization server and auto-patches all supported SDKs (OpenAI, Anthropic, Google GenAI, and legacy Generative AI).

def inspect(port: int = 8989, host: str = "127.0.0.1", auto_open: bool = True):
    """
    Spins up the FastAPI server on a background daemon thread (if not already running)
    and patches all client SDKs to intercept and capture outgoing LLM prompts.

    Args:
        port (int): Local port to start the visualization server on. Defaults to 8989.
        host (str): Bind address for the local server. Defaults to "127.0.0.1".
        auto_open (bool): Automatically open the web browser to the dashboard UI. Defaults to True.
    """

---

Command Line Interface (CLI)

prompt-inspector start

Starts a persistent, standalone visualization server in your terminal. This is useful for keeping your trace logs active across multiple runs of different scripts.

# Start on default port 8989
prompt-inspector start

# Start on a custom port
prompt-inspector start --port 9090

---

Framework Integration Examples

1. OpenAI, Groq, and Azure OpenAI

Both Groq and Azure OpenAI SDK clients extend standard OpenAI classes. They are patched natively:

import prompt_inspector
from openai import OpenAI, AzureOpenAI

prompt_inspector.inspect()

# 1. Groq Client Call
groq_client = OpenAI(
    base_url="https://api.groq.com/openai/v1",
    api_key="gsk_..."
)
groq_client.chat.completions.create(
    model="llama3-8b-8192",
    messages=[{"role": "user", "content": "Hello!"}]
)

# 2. Azure OpenAI Client Call
azure_client = AzureOpenAI(
    api_key="...",
    api_version="2024-02-01",
    azure_endpoint="https://your-endpoint.openai.azure.com/"
)
azure_client.chat.completions.create(
    model="gpt-4o-deployment",
    messages=[{"role": "user", "content": "Explain vector embeddings."}]
)

2. LangChain & LangGraph

LangChain wraps client libraries inside runnable components. They are intercepted pre-flight:

import prompt_inspector
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

prompt_inspector.inspect()

llm = ChatOpenAI(model="gpt-4o")
llm.invoke([HumanMessage(content="Hello LangChain!")])

3. Google GenAI (Gemini)

Supports text, PIL Images, and PDF/Word documents passed directly as inline bytes:

import prompt_inspector
from PIL import Image
from google import genai
from google.genai import types

prompt_inspector.inspect()

client = genai.Client()

# Construct multimodal contents
contents = [
    "Identify the flowchart steps:",
    Image.open("flowchart.png"),
    types.Part.from_bytes(
        data=open("document.pdf", "rb").read(),
        mime_type="application/pdf"
    )
]

client.models.generate_content(
    model="gemini-2.5-flash",
    contents=contents
)

4. LlamaIndex

Integrates via standard LLM client objects:

import prompt_inspector
from llama_index.llms.openai import OpenAI

prompt_inspector.inspect()

llm = OpenAI(model="gpt-4")
response = llm.complete("LlamaIndex verification query.")

5. Anthropic (Claude)

Intercepts messages and system prompts:

import prompt_inspector
import anthropic

prompt_inspector.inspect()

client = anthropic.Anthropic()
client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=500,
    messages=[{"role": "user", "content": "Explain quantum entanglement."}]
)

---

Multimodal Payload Examples (Audio, Video, PDF, Word & Combinations)

prompt-inspector fully extracts and visualizes various document and media formats. Here is how you can send them using different SDKs and model providers.

1. Google GenAI (Gemini)

Gemini models support native multimodal inputs. You can send images (using PIL), audio, video, PDFs, and Word docs as inline bytes:

import base64
import prompt_inspector
from PIL import Image
from google import genai
from google.genai import types

prompt_inspector.inspect()
client = genai.Client()

# Helper to read file bytes
def read_bytes(path):
    with open(path, "rb") as f:
        return f.read()

# --- Example A: Sending an Audio File ---
audio_contents = [
    "Analyze the sound cue in this clip:",
    types.Part.from_bytes(data=read_bytes("instructions.wav"), mime_type="audio/wav")
]
client.models.generate_content(model="gemini-2.5-flash", contents=audio_contents)

# --- Example B: Sending a Video File ---
video_contents = [
    "Provide a summary of the activity in this video:",
    types.Part.from_bytes(data=read_bytes("screen_recording.mp4"), mime_type="video/mp4")
]
client.models.generate_content(model="gemini-2.5-flash", contents=video_contents)

# --- Example C: Sending a PDF Document ---
pdf_contents = [
    "Verify the ranking equations in this PDF:",
    types.Part.from_bytes(data=read_bytes("equations.pdf"), mime_type="application/pdf")
]
client.models.generate_content(model="gemini-2.5-flash", contents=pdf_contents)

# --- Example D: Sending a Word Document (.docx) ---
docx_contents = [
    "Summarize this project brief:",
    types.Part.from_bytes(
        data=read_bytes("project_brief.docx"), 
        mime_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
]
client.models.generate_content(model="gemini-2.5-flash", contents=docx_contents)

# --- Example E: Combination Payload (Text + Image + Audio + PDF) ---
complex_contents = [
    "Review the flowchart, listen to the audio instructions, and verify with the pdf sheet:",
    Image.open("flowchart.png"),
    types.Part.from_bytes(data=read_bytes("instructions.wav"), mime_type="audio/wav"),
    types.Part.from_bytes(data=read_bytes("formulas.pdf"), mime_type="application/pdf")
]
client.models.generate_content(model="gemini-2.5-flash", contents=complex_contents)

2. OpenAI / Groq / Compatible Endpoints

For OpenAI-compatible endpoints, you pass multimodal structures inside the messages array:

import base64
import prompt_inspector
from openai import OpenAI

prompt_inspector.inspect()
client = OpenAI()

def encode_b64(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

# --- Combination Payload (Text + Image + Audio + Document) ---
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text", 
                "text": "Analyze the diagram, hear the sound, and verify with the PDF document:"
            },
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/png;base64,{encode_b64('diagram.png')}"}
            },
            {
                "type": "input_audio",
                "input_audio": {
                    "data": encode_b64("instructions.wav"),
                    "format": "wav"
                }
            },
            {
                "type": "document",
                "document": {
                    "data": {
                        "base64": encode_b64("reference.pdf")
                    },
                    "mime_type": "application/pdf"
                }
            }
        ]
    }
]

client.chat.completions.create(
    model="gpt-4o",
    messages=messages
)