Use with OpenAI

Prerequisites

Python

pip install prompty[jinja2,openai]

TypeScript

npm install @prompty/core @prompty/openai

C#

dotnet add package Prompty.Core --prerelease
dotnet add package Prompty.OpenAI --prerelease

Rust

cargo add prompty prompty-openai

You also need an OpenAI API key.

---

1. Write the .prompty File

Create chat.prompty:

---
name: openai-chat
description: Simple chat completion with OpenAI
model:
  id: gpt-4o-mini
  provider: openai
  apiType: chat
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
  options:
    temperature: 0.7
    maxOutputTokens: 1024
inputs:
  - name: question
    kind: string
    default: What is Prompty?
---
system:
You are a helpful assistant. Answer concisely.

user:
{{question}}

Note

${env:OPENAI_API_KEY} is resolved at load time from your environment or .env file. The key never appears in your prompt file.

---

2. Run It

Python

import prompty

# One-liner: load → render → call LLM → return result
result = prompty.invoke("chat.prompty", inputs={"question": "What is Prompty?"})
print(result)

For more control, use the pipeline stages individually:

import prompty

# Step 1 — Load the .prompty file → Prompty
agent = prompty.load("chat.prompty")

# Step 2 — Render template + parse role markers → list[Message]
messages = prompty.prepare(agent, inputs={"question": "Explain async/await"})

# Step 3 — Call OpenAI + process response → string
result = prompty.run(agent, messages)
print(result)

Async variant:

import asyncio
import prompty

async def main():
    result = await prompty.invoke_async(
        "chat.prompty",
        inputs={"question": "What is Prompty?"},
    )
    print(result)

asyncio.run(main())

TypeScript

import { invoke } from "@prompty/core";
import "@prompty/openai";

const result = await invoke("chat.prompty", {
  question: "What is Prompty?",
});

console.log(result);

C#

using Prompty.Core;

// One-liner: load → render → call LLM → return result
var result = await Pipeline.InvokeAsync("chat.prompty", new() { ["question"] = "What is Prompty?" });
Console.WriteLine(result);

For more control, use the pipeline stages individually:

using Prompty.Core;

// Step 1 — Load the .prompty file → Prompty
var agent = PromptyLoader.Load("chat.prompty");

// Step 2 — Render template + parse role markers → messages
var messages = await Pipeline.PrepareAsync(agent, new() { ["question"] = "Explain async/await" });

// Step 3 — Call OpenAI + process response → string
var result = await Pipeline.RunAsync(agent, messages);
Console.WriteLine(result);

Rust

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_openai::register();

    // One-liner: load → render → call LLM → return result
    let result = prompty::invoke_from_path(
        "chat.prompty",
        Some(&json!({ "question": "What is Prompty?" })),
    ).await?;
    println!("{result}");
    Ok(())
}

For more control, use the pipeline stages individually:

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_openai::register();

    // Step 1 — Load the .prompty file → Prompty
    let agent = prompty::load("chat.prompty")?;

    // Step 2 — Render template + parse role markers → Vec<Message>
    let inputs = json!({ "question": "Explain async/await" });
    let messages = prompty::prepare(&agent, Some(&inputs)).await?;

    // Step 3 — Call OpenAI + process response → string
    let result = prompty::run(&agent, &messages).await?;
    println!("{result}");
    Ok(())
}

---

3. Switch Models

Change model.id in the frontmatter — no code changes needed:

model:
  id: gpt-4o          # GPT-4o (default, fast + capable)
  # id: gpt-4o-mini   # Cheaper, good for simple tasks
  # id: o1            # Reasoning model (higher latency)
  # id: gpt-4-turbo   # 128K context window

Caution

Reasoning models like o1 don’t support temperature or system role messages. Remove those from your .prompty file if you switch to o1.

---

4. Environment Setup

Create a .env file in the same directory as your script:

.env

OPENAI_API_KEY=sk-your-key-here

Prompty uses python-dotenv to load .env automatically. Make sure .env is in your .gitignore:

echo ".env" >> .gitignore

---

5. Tune Model Options

All options go under model.options: in the frontmatter:

model:
  id: gpt-4o-mini
  provider: openai
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
  options:
    temperature: 0.3        # Lower = more deterministic
    maxOutputTokens: 2048   # Max tokens in the response
    topP: 0.9               # Nucleus sampling
    frequencyPenalty: 0.2    # Reduce repetition
    presencePenalty: 0.1     # Encourage new topics
    seed: 42                 # Reproducible outputs
    stopSequences:           # Stop generation at these strings
      - "END"

Tip

Start with temperature: 0.7 for creative tasks and temperature: 0 for factual extraction or classification.