dotpromptz-py 1.5.0

Dotpromptz is a language-neutral executable prompt template file format for Generative AI.

LLM Adapters & CLI (Fork Extension)

This fork adds LLM API adapters and a command-line tool so you can run .prompt files directly against OpenAI, Anthropic, Google Gemini, or any third-party compatible service (all adapters support custom base_url).

Quick Start (CLI)

# Install (all adapters included by default)
uv add "dotpromptz-py"

# Set API key
export OPENAI_API_KEY="sk-..."

# Run a prompt (input configured in frontmatter)
runprompt my_prompt.prompt

# Batch mode (auto-detected from frontmatter input)
runprompt my_prompt.prompt

Adapter and model are configured in the .prompt file frontmatter:

---
adapter: openai          # optional — auto-inferred from config.model name
config:
  model: gpt-4o
runtime:
  max_workers: 10       # Concurrent workers for batch processing
output:
  output_dir: ./results # Optional directory for output files
  jsonl: true           # Output in JSONL format
input:
  topic: "AI"
---
Tell me about {{topic}}.

For third-party compatible services (e.g. DeepSeek, Ollama):

---
adapter:
  name: openai
  base_url: https://api.deepseek.com
config:
  model: deepseek-chat
---
Tell me about {{topic}}.

Input Formats

Input data is configured in the .prompt file frontmatter using the input field. The CLI no longer takes a separate input file argument.

1. Inline data (single record):

---
input:
  name: "Alice"
  age: 30
---
Hello {{name}}!

2. File reference (auto-detects single vs batch):

---
input: "data.json"  # Relative to .prompt file
---
Process {{field1}} and {{field2}}.

3. Batch mode (list of records):

---
input:
  - {name: "Alice", age: 30}
  - {name: "Bob", age: 25}
---
Hello {{name}}!

4. JSONL file (always batch):

---
input: "batch.jsonl"
---
Process {{item}}.

5. Defaults (shared values for batch records):

When running batch mode, you often have values that stay the same across all records (e.g. language, tone, model parameters). Use input.defaults to avoid repeating them:

---
input:
  defaults:
    language: "Chinese"
    tone: "formal"
  data:
    - {name: "Alice"}
    - {name: "Bob", tone: "casual"}  # overrides defaults
---
Translate a greeting for {{name}} in {{language}} with a {{tone}} tone.

This is equivalent to writing:

input:
  - {name: "Alice", language: "Chinese", tone: "formal"}
  - {name: "Bob", language: "Chinese", tone: "casual"}

• defaults: dict of fixed values merged into every record
• data: the variable data (supports all existing formats: dict, list, string file path)
• Per-record values in data override defaults when keys conflict
• defaults without data produces a single record containing just the defaults

File paths: All relative file paths are resolved relative to the .prompt file directory. Absolute paths are also supported.

Quick Start (Python)

import asyncio
from dotpromptz import Dotprompt
from dotpromptz.typing import DataArgument
from dotpromptz.adapters import get_adapter

async def main():
    dp = Dotprompt()
    # Option 1: Use frontmatter input (auto-loaded from .prompt file)
    rendered = dp.render(source)
    
    # Option 2: Override with caller data
    # rendered = dp.render(source, data=DataArgument(input={"topic": "AI"}))
    adapter = get_adapter("openai")
    response = await adapter.generate(rendered)
    print(response.text)

asyncio.run(main())

Supported Adapters

Adapter	Env Var
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Google Gemini	GOOGLE_API_KEY

All adapters and their SDK dependencies (openai, anthropic, google-genai) are included as core dependencies — no extras needed. All adapters support base_url for third-party compatible endpoints (e.g. DeepSeek, vLLM, Ollama). Configure via frontmatter adapter.base_url or env vars (OPENAI_BASE_URL / ANTHROPIC_BASE_URL / GOOGLE_BASE_URL).

Image Generation (Google Gemini)

Dotprompt supports native image generation via Gemini's generateContent API with response_modalities=["IMAGE"]. To use it, set output.format: image and output.save_path in the frontmatter.

Text-to-image example (draw_cat.prompt):

---
adapter: google
config:
  model: gemini-2.0-flash-exp
output:
  format: image
  save_path: output/cat.png
input:
  style: "watercolor"
---
Draw a {{style}} cat sitting on a windowsill.

runprompt draw_cat.prompt
# → Image saved to: output/cat.png

Image-to-image example (using {{media}} helper for input):

---
adapter: google
config:
  model: gemini-2.0-flash-exp
output:
  format: image
  save_path: output/edited.png
input:
  image_url: "https://example.com/photo.jpg"
  instruction: "Make it black and white"
---
{{media url=image_url}}
{{instruction}}

runprompt edit_image.prompt

Notes:

• output.save_path is required when format is image. Omitting it raises a validation error at parse time.
• save_path is validated against path traversal attacks (e.g. ../../etc/passwd) — only paths within the current working directory are allowed.
• Currently only the Google adapter supports image generation. Only the first generated image is saved.
• The parent directory of save_path is created automatically if it does not exist.