Comprehensive Guide to PromptL and the Its Python Library (promptl-py)

Working with LLMs is powerful, but crafting and managing the prompts that drive them can quickly become complex. As you move beyond simple questions, you start juggling system messages, user inputs, example dialogues (few-shot prompting), tool definitions, desired output structures, and even multi-step conversations. How do you keep all this organized, maintainable, and reusable, especially across different LLM providers?

Enter PromptL, a templating language built specifically for the world of LLM prompting. And to bring its power into your Python applications, we have the promptl-py library.

This guide will walk you through everything you need to know, from the basics of PromptL syntax to advanced chaining and error handling using the Python library. We'll cover every detail from the original documentation, ensuring you have a complete picture.

Let's Dive In! Here’s What We'll Cover:

1. What Exactly is PromptL? (And why you need it)
2. Introducing promptl-py: Your Python Bridge
3. Core Ideas: Templates, Parameters, Rendering, Chains, Adapters
4. Installation: Getting Set Up
5. Quick Start: Rendering Your First Prompt & Running a Simple Chain
6. The PromptL Language: A Deep Dive
   • Anatomy of a .promptl File
   • Front Matter Magic (--- ... ---): Configuration, Tools, Schemas
   • The Prompt Body: Crafting Your Messages
   • Message Roles (, , etc.)
   • Beyond Text: Content Types
   • Dynamic Prompts: Variables & Templating ({{ ... }})
   • Adding Logic: Control Flow (if, for)
   • Multi-Turn Conversations: Steps () & Attributes (as, schema)
   • Keeping it Clean: Comments & Includes
7. Using promptl-py Like a Pro
   • Getting Started: Promptl Class & Options
   • Validating Templates: Scanning Prompts (promptl.prompts.scan)
   • Bringing Prompts to Life: Rendering (promptl.prompts.render)
   • Managing Conversations: Working with Chains (promptl.chains)
   • Speaking the LLM's Language: Adapters (OpenAI, Anthropic, Default)
   • Under the Hood: Key Data Types
   • Handling Hiccups: Error Management (PromptlError, RPCError)
8. Real-World Scenarios: Complex Examples
   • Multi-Step Chains with Tools, Schema & Logic
   • Conditional Prompts Based on Inputs
   • Leveraging Complex Data Structures
   • Graceful Error Handling
9. Quick Reference: API Summary
10. For Contributors: Development Setup
11. The Fine Print: License

1. What Exactly is PromptL?

PromptL is not just another templating engine; it's a domain-specific language meticulously designed for defining and managing LLM prompts. Think of it like Jinja or Handlebars, but supercharged for AI interactions. It provides a clear, human-readable syntax to:

• Define both static text and dynamic content using variables.
• Structure prompts using standard roles (system, user, assistant, tool).
• Incorporate logic with conditionals (if) and loops (for).
• Specify LLM configurations (like model name, temperature) right alongside the prompt.
• Define tools (functions) the LLM can use and specify required output formats using JSON Schema.
• Orchestrate complex, multi-step conversations (chains).
• Optionally abstract away the specific formatting details required by different LLM providers.

Its goal is to make prompt engineering more systematic, maintainable, and less error-prone.

2. Introducing promptl-py: Your Python Bridge

The promptl-py library is the official way to use PromptL within your Python applications. It acts as the interface to the core PromptL engine, allowing you to:

• Parse & Validate: Read .promptl files or strings and check them for correctness.
• Render: Inject your data (parameters) into PromptL templates to generate the structured message lists that LLM APIs expect.
• Execute Chains: Run multi-step prompts step-by-step, managing the conversation flow.
• Integrate Seamlessly: Fit PromptL into your existing Python workflows for interacting with LLMs.

Interestingly, promptl-py uses a WebAssembly (WASM) module (promptl.wasm) under the hood. This contains the core PromptL parser and runtime. The Python library communicates with this WASM module via Remote Procedure Calls (RPC). This architecture ensures that the core PromptL logic remains consistent, regardless of the host language (Python, in this case).

3. Core Ideas

Before we jump into code, let's clarify a few key concepts:

• Template: A string or .promptl file written using PromptL syntax.
• Parameters: A Python dictionary containing data you want to inject into your template (e.g., user names, context, lists of items).
• Rendering: The process of combining a Template and Parameters to produce a final output, usually a list of messages and LLM configuration settings.
• Chain: A prompt template designed for multi-step interactions, using tags. Execution proceeds step-by-step.
• Adapter: A setting that tells promptl-py how to format the rendered messages. This ensures compatibility with specific LLM provider APIs (like OpenAI or Anthropic).
• Messages: Structured objects representing parts of the conversation (e.g., a system instruction, a user query, an assistant's reply, a tool's output).

4. Installation: Getting Set Up

Getting promptl-py is straightforward using pip. Make sure you have Python 3.9 or higher.

pip install promptl-py

Easy peasy! Now, let's write some code.

5. Quick Start: Rendering Your First Prompt & Running a Simple Chain

Basic Rendering

Let's take a simple PromptL template and render it with some data.

# examples/render_prompt.py
from pprint import pprint
from promptl_ai import Promptl, Adapter # Import Adapter too

# 1. Initialize the PromptL engine
promptl = Promptl() # Uses default settings

# 2. Define your PromptL template as a string
prompt_template = """
---
provider: OpenAI   # Hint for configuration, affects defaults/adapters
model: gpt-4o-mini # Specify the LLM model
---

# This text before the first tag often becomes a system message or part of the first message.
Answer succinctly yet complete.

 # Start of a user message
    Taking into account this context: {{context}} # Inject 'context' variable
    I have the following question: {{question}} # Inject 'question' variable

"""

# 3. Prepare your data (parameters) as a Python dictionary
parameters = {
    "context": "PromptL is a templating language specifically designed for LLM prompting.",
    "question": "What is PromptL?",
}

# 4. Render the prompt!
# By default, it uses the OpenAI adapter format.
result = promptl.prompts.render(
    prompt=prompt_template,
    parameters=parameters,
    # adapter=Adapter.OpenAI # Explicitly stating the default
)

# 5. Check the output
print("--- Rendered Prompt Output ---")
pprint(result.model_dump())
# Expected Output (structure):
# {
#  'messages': [ # List of messages ready for an LLM API
#      {'role': 'system', 'content': 'Answer succinctly yet complete.'},
#      {'role': 'user',
#       'content': 'Taking into account this context: PromptL is a templating language specifically designed for LLM prompting.\n'
#                  'I have the following question: What is PromptL?'}
#      ],
#  'config': { # Configuration extracted from front matter
#      'provider': 'OpenAI',
#      'model': 'gpt-4o-mini'
#      }
# }

See how the variables {{context}} and {{question}} were replaced, and the output is structured into messages with roles and content, plus the configuration? That's the magic of rendering!

Basic Chain Execution

Now, let's see how PromptL handles a simple back-and-forth conversation using tags.

# examples/run_chain.py
from pprint import pprint
from promptl_ai import Promptl

promptl = Promptl()

# Define a multi-step template
chain_prompt = """
 # Defines the first turn of the conversation
  
    You are a helpful assistant.
  
  
    Say hello.
  


 # Defines the second turn, executed after the first response
  
    Now say goodbye.
  

"""

# 1. Create a chain instance from the template
chain = promptl.chains.create(chain_prompt)
print(f"Chain created. Is it complete yet? {chain.completed}") # Output: False

print("\n--- Executing Step 1 ---")
# 2. Execute the first step. No input response needed here.
# This renders messages up to the end of the first .
step1_result = chain.step()
pprint(step1_result.model_dump(exclude={'chain'})) # Exclude chain object for brevity
# Expected Output (structure):
# {'messages': [{'role': 'system', 'content': 'You are a helpful assistant.'},
#               {'role': 'user', 'content': 'Say hello.'}],
#  'config': {}, # No specific config in this template
#  'completed': False} # The chain isn't finished

print(f"\nChain completed after step 1? {chain.completed}") # Output: False

# 3. Simulate the LLM responding to the first step
llm_response_step1 = "Hello there! How can I help?"

print("\n--- Executing Step 2 (with LLM response) ---")
# 4. Execute the second step, providing the assistant's previous response.
# This appends the assistant's response and then renders the content of the second .
step2_result = chain.step(llm_response_step1)
pprint(step2_result.model_dump(exclude={'chain'}))
# Expected Output (structure):
# {'messages': [{'role': 'system', 'content': 'You are a helpful assistant.'},
#               {'role': 'user', 'content': 'Say hello.'},
#               {'role': 'assistant', 'content': 'Hello there! How can I help?'}, # <-- Added response
#               {'role': 'user', 'content': 'Now say goodbye.'}], # <-- From second step
#  'config': {},
#  'completed': False} # Still waiting for the final response

print(f"\nChain completed after step 2? {chain.completed}") # Output: False

# 5. Simulate the LLM responding to the second step
llm_response_step2 = "Goodbye! Have a great day!"

print("\n--- Executing Final Step (with LLM response) ---")
# 6. Execute the chain again with the final response.
# Since there are no more  tags, the chain completes.
final_result = chain.step(llm_response_step2)
pprint(final_result.model_dump(exclude={'chain'}))
# Expected Output (structure):
# {'messages': [{'role': 'system', 'content': 'You are a helpful assistant.'},
#               {'role': 'user', 'content': 'Say hello.'},
#               {'role': 'assistant', 'content': 'Hello there! How can I help?'},
#               {'role': 'user', 'content': 'Now say goodbye.'},
#               {'role': 'assistant', 'content': 'Goodbye! Have a great day!'}], # <-- Added final response
#  'config': {},
#  'completed': True} # Chain is now finished!

print(f"\nChain completed finally? {chain.completed}") # Output: True
assert chain.completed
assert final_result.completed

print("\n--- Final Conversation History ---")
pprint([msg.model_dump() for msg in final_result.messages]) # Display all messages

This demonstrates the core loop: create the chain, then repeatedly call chain.step(llm_response) until chain.completed is True.

6. The PromptL Language: A Deep Dive

Now that you've seen it in action, let's break down the PromptL syntax systematically.

Anatomy of a .promptl File

A typical PromptL template (.promptl file or string) has two main sections:

---
# 1. Optional Front Matter (YAML-like configuration)
provider: OpenAI
model: gpt-4o-mini
temperature: 0.5
# ... other settings, tools, schemas ...
---

# 2. Prompt Body (The actual message content and logic)
This text might be treated as a system message.

  Hello, {{ user_name }}!
  {{#if show_details}}
    Here are the details...
  {{/if}}


   Okay, processing step 1. 

Front Matter Magic (--- ... ---)

This optional block at the very top, enclosed by triple dashes (---), uses a YAML-like syntax (keys and values, indentation for nesting) to define metadata and configuration.

• Common Configuration: These directly influence how the LLM should behave.

  • provider: (String, e.g., "OpenAI", "Anthropic") Hints at the target LLM provider, influencing defaults and adapter behavior.
  • model: (String, e.g., "gpt-4o-mini", "claude-3-opus-20240229") Specifies the exact LLM model.
  • temperature: (Number, e.g., 0.7) Controls response randomness.
  • max_tokens: (Integer) Limits the length of the generated response.
  • Other Parameters: You can often include other API parameters supported by the provider (like top_p, stop_sequences).

  ---
  provider: Anthropic
  model: claude-3-sonnet-20240229
  temperature: 0.2
  max_tokens: 1000
  ---
  

• Tool Definitions (tools): Define functions the LLM can call. This structure closely mirrors the OpenAI function calling/tool definition format.

  • It's an object (dictionary) where keys are tool names.
  • Each tool has a description (String) and parameters (a JSON Schema object describing the arguments).

  ---
  tools:
    get_weather:
      description: Fetches the current weather for a location.
      parameters:
        type: object
        properties:
          location:
            type: string
            description: The city and state (e.g., "Boston, MA").
          unit:
            type: string
            enum: ["celsius", "fahrenheit"]
            default: "celsius"
        required:
          - location
    send_email:
      description: Sends an email.
      parameters: # ... schema for recipient, subject, body ...
  ---
  

• Output Schema (schema): Define a required structure (using JSON Schema) for the LLM's final response message content. This is incredibly useful for forcing the LLM to output structured data (like JSON) reliably.
  

  ---
  schema:
    type: object
    properties:
      summary:
        type: string
        description: A concise summary of the input text.
      keywords:
        type: array
        items:
          type: string
        description: A list of relevant keywords.
    required:
      - summary
      - keywords
    additionalProperties: false # Don't allow extra fields in the output
  ---
  

The Prompt Body: Crafting Your Messages

This is where the core content of your prompt lives, using tags, variables, and logic.

• Message Roles (, , , ): These tags structure the conversation, mirroring typical chat roles.

  • ...: High-level instructions, persona setting, or context for the AI. Often placed first.
  • ...: Represents input from the human user.
  • ...: Represents responses from the AI. Used for few-shot examples or to capture the AI's actual response in chains.
  • ...: Represents the result returned from executing a tool call. Requires specific content (see below).
  • Implicit System Message: Text placed in the body before any other tag is often treated as a system message or merged into the first message.

  You are a Shakespearean pirate bot. # Implicit system message
  
  
    Always respond in iambic pentameter. Use pirate slang.
  
  
    Ahoy! Tell me about the weather in Tortuga. Use the weather tool if ye must.
  
   # Example response (few-shot)
    Aye, the skies be clear, the sun doth shine so bright! But let me check the charts...
    {{ tool_call(id="weather_call_1", name="get_weather", args={location: "Tortuga"}) }}
  
   # Example tool result
    {{ tool_result(id="weather_call_1", name="get_weather", result={temp: 28, condition: "Sunny", unit: "celsius"}) }}
  
   # Example final response
    Hark, the charts say Tortuga's warmth delights the soul, 'Tis twenty-eight degrees, a sunny toll!
  
  

• Beyond Text: Content Types: While text is the default, PromptL understands richer content types, especially important for multi-modal models and tool use. The promptl-py library maps these to specific Python data models after rendering.

  • Text: Simple text within tags. (TextContent in Python)
  • Image: Handling varies by provider. Often passed via parameters containing image data (e.g., base64 string or URL) rather than directly embedded in PromptL syntax itself. Check specific adapter documentation. (ImageContent in Python)
  • File/Document: Similar to images, usually handled via parameters. (FileContent in Python)
  • Tool Call: Represents the LLM's decision to call a tool. Typically generated by the LLM, but can be included in tags for few-shot examples. The syntax might involve helpers like {{ tool_call(...) }} or be implicit. (ToolCallContent in Python)
  • Tool Result: Represents the data returned to the LLM after a tool has been executed. Placed within tags. Often uses a helper like {{ tool_result(...) }}. (ToolResultContent in Python)

• Dynamic Prompts: Variables & Templating ({{ ... }}): Uses Handlebars-like syntax.

  • {{ variable }}: Inserts the value of variable from the parameters dict.
  • {{ object.property }}: Accesses nested data.
  • {{ list[index] }}: Accesses elements in a list.
  • Whitespace Control: {{- ... }} or {{ ... -}} might be available to remove adjacent whitespace (check PromptL specification details).
  • Escaping: To get literal {{, you might need \{{ or similar (check PromptL specs).

  
    Order details for {{ customer.name }} (ID: {{ customer.id }}):
    Items:
    {{#each customer.orders[0].items }}
      - {{ this.name }} ({{ this.quantity }})
    {{/each}}
    Total: {{ customer.orders[0].total_price }}
  
  

• Adding Logic: Control Flow:

  • {{ if condition }}: Conditionally include content. Supports {{ else }} and potentially {{ else if }}. Remember {{ endif }}!
    

    
      {{ if task == "summarize" }}
        Provide a brief summary.
      {{ else if task == "translate" }}
        Translate the text accurately.
      {{ else }}
        Follow the user's specific instruction.
      {{ endif }}
      Target audience: {{ audience }}.
    
    

  • {{ for item, index in list }}: Loop over items in a list (or keys/values in a dictionary). index is optional. Remember {{ endfor }}!
    

    
      Here are the discussion points:
      {{ for point, idx in points_list }}
        {{ idx + 1 }}. {{ point }}
      {{ endfor }}
      Please synthesize them.
    
    

• Multi-Turn Conversations: Steps () & Attributes (as, schema):

  • tags define distinct turns in a conversation (a chain). The Python library's chain.step() method progresses through these. Execution pauses conceptually at the end of a step, waiting for the assistant's response.
  • as="var_name": An attribute on the tag. It captures the assistant's response for that specific step into a PromptL variable named var_name. This variable can then be used in later steps.
  • schema={{ ... }}: An attribute on the tag. It defines an inline JSON schema that the assistant's response for this step must conform to. The schema itself is often defined using JSON-like syntax within the {{ }}.

   # Capture response as 'initial_request'
    Suggest three blog post titles about PromptL.
  
  
  # Assume assistant responds with a list of titles, captured in 'initial_request'
  
   # Capture selection, enforce schema
    
      Okay, here are the titles you suggested:
      {{ initial_request }} # Use the captured response
  
      Which one is the best? Respond with JSON: {"chosen_title": "Your Choice"}
    
  
  
  # Assume assistant responds with {"chosen_title": "Title 2"} captured in 'selection'
  
  
    
      Great! Let's go with "{{ selection.chosen_title }}". # Use the captured selection
      Now, write an outline for it.
    
  
  

• Keeping it Clean: Comments:

  • Multi-line: Enclose in /* ... */.
  • Single-line: Often start with # (especially within front matter or at the beginning of lines in the body).

  ---
  # Model configuration section
  model: gpt-4o
  /* Temperature controls creativity.
     Lower is more focused. */
  temperature: 0.3
  ---
  /* Main prompt body starts here */
   # System instructions
    Be helpful and concise.
  
  

• Includes (Conceptual): PromptL aims for modularity. While the specific implementation details might depend on the core engine version, the concept involves including content from other .promptl files. This might look something like . The included_prompt_paths field in ScanPromptResult hints at this capability.

7. Using promptl-py Like a Pro

Now let's focus on the Python library itself.

Getting Started: Promptl Class & Options

You interact with PromptL via the Promptl class.

from promptl_ai import Promptl, PromptlOptions, Adapter

# Simplest way: uses defaults (bundled WASM, temp dir, OpenAI adapter)
promptl_default = Promptl()

# Customize it:
options = PromptlOptions(
    # Path to the promptl.wasm file (if not using the one bundled with the lib)
    module_path="/path/to/custom/promptl.wasm",
    # Directory for temporary files used by WASM communication
    working_dir="/app/temp/promptl_cache",
    # Set the default adapter for all operations on this instance
    adapter=Adapter.Anthropic
)
promptl_custom = Promptl(options=options)

# Access prompts and chains submodules
prompts_api = promptl_custom.prompts
chains_api = promptl_custom.chains

PromptlOptions allows you to configure:

• adapter: Default output format (Adapter.OpenAI (default), Adapter.Anthropic, Adapter.Default).
• module_path: Location of promptl.wasm.
• working_dir: Temporary storage directory.

Validating Templates: Scanning Prompts (promptl.prompts.scan)

Before rendering, you might want to check a template for errors, see what parameters it expects, or extract its configuration without providing any data. That's what scan is for.

• Input: prompt: str (the template content).
• Output: ScanPromptResult (a Pydantic model) containing:
  • hash: A unique identifier for the scanned prompt string.
  • resolved_prompt: The template text after processing includes, etc.
  • config: The parsed front matter dictionary.
  • errors: A list of Error objects if issues were found (empty list if valid).
  • parameters: A list of variable names (like {{variable}}) found in the template.
  • is_chain: Boolean, True if tags are present.
  • included_prompt_paths: List of any included file paths (if feature is used).

from promptl_ai import Promptl
from pprint import pprint

promptl = Promptl()

valid_prompt = """
---
model: gpt-4
max_tokens: 100
---
Hello {{name}}!
"""

scan_result = promptl.prompts.scan(valid_prompt)
print("--- Scan Result (Valid Prompt) ---")
pprint(scan_result.model_dump())
# Expected Output (structure):
# {'hash': '...', 'resolved_prompt': '...', 'config': {'model': 'gpt-4', 'max_tokens': 100},
#  'errors': [], 'parameters': ['name'], 'is_chain': False, 'included_prompt_paths': ['']}

invalid_prompt = "Hello {{ name  "
scan_result_error = promptl.prompts.scan(invalid_prompt)
print("\n--- Scan Result (Invalid Prompt) ---")
pprint(scan_result_error.model_dump())
# Expected Output (structure):
# { ... 'errors': [{'name': 'ParseError', 'message': 'Expected "}}" ...', ...}], ... }

Bringing Prompts to Life: Rendering (promptl.prompts.render)

This is the core function for single-turn prompts (or getting the first step of a chain). It takes the template, injects parameters, and produces the final output.

• Input:
  • prompt: str: The template string.
  • parameters: Optional[Dict[str, Any]]: Your data dictionary.
  • adapter: Optional[Adapter]: Override the default adapter for this call (e.g., Adapter.Anthropic).
  • options: Optional[RenderPromptOptions]: Fine-tuning (rarely needed): default_role for untagged text, include_source_map.
• Output: RenderPromptResult (Pydantic model) containing:
  • messages: List[MessageLike]: The list of generated message objects, formatted according to the specified adapter.
  • config: Dict[str, Any]: The final LLM configuration (from front matter, potentially merged with step-specific settings).

from promptl_ai import Promptl, Adapter
from pprint import pprint

promptl = Promptl() # Defaulting to OpenAI adapter

prompt = """
---
model: gpt-3.5-turbo
---
Translate '{{text}}' to {{language}}.
"""
parameters = {"text": "hello world", "language": "Spanish"}

# Render for OpenAI (default)
render_openai = promptl.prompts.render(prompt, parameters)
print("--- Rendered (OpenAI Adapter) ---")
pprint(render_openai.model_dump())
# Expected: {'messages': [{'role': 'user', 'content': "Translate 'hello world' to Spanish."}], 'config': {'model': 'gpt-3.5-turbo'}}

# Render specifically for Anthropic
render_anthropic = promptl.prompts.render(prompt, parameters, adapter=Adapter.Anthropic)
print("\n--- Rendered (Anthropic Adapter) ---")
pprint(render_anthropic.model_dump())
# Expected: {'messages': [{'role': 'user', 'content': "Translate 'hello world' to Spanish."}], 'config': {'model': 'gpt-3.5-turbo'}}
# Note: For simple text, output looks similar. Differences are more apparent with tools, images, etc.

Generating Objects for LLM Libraries (e.g., OpenAI)

Since the default adapter is OpenAI, the output messages and config are often directly usable with libraries like openai.

import os
# Ensure: pip install openai
# Requires OPENAI_API_KEY env var for actual API call
# from openai import OpenAI
# client = OpenAI()

from promptl_ai import Promptl, Adapter
from pprint import pprint

promptl = Promptl() # Uses OpenAI adapter by default

weather_prompt = """
---
provider: OpenAI
model: gpt-4o-mini
tools:
  get_current_weather:
    description: Get the current weather in a given location
    parameters:
      type: object
      properties:
        location: { type: string, description: "City, State" }
        unit: { type: string, enum: [celsius, fahrenheit] }
      required: [location]
---
You are a helpful weather bot. Use tools if necessary.
What's the weather like in San Francisco today?
"""

# Render the prompt
render_result = promptl.prompts.render(prompt=weather_prompt)

print("--- Rendered Output (Ready for OpenAI Client) ---")
pprint(render_result.model_dump())

# How you'd use it with the OpenAI client:
messages_for_api = [msg.model_dump() for msg in render_result.messages] # Convert Pydantic models to dicts
tools_for_api = [{"type": "function", "function": v} for k, v in render_result.config.get("tools", {}).items()] # Format tools
model_name = render_result.config.get("model")

# print(f"\n--- Simulating OpenAI Call (Model: {model_name}) ---")
# try:
#    response = client.chat.completions.create(
#        model=model_name,
#        messages=messages_for_api,
#        tools=tools_for_api if tools_for_api else None,
#        tool_choice="auto",
#    )
#    pprint(response.choices[0].message.model_dump())
# except Exception as e:
#    print(f"OpenAI API call would fail here (ensure API key is set): {e}")

# Expected Rendered Output Structure:
# {'messages': [{'role': 'system', 'content': '...'}, {'role': 'user', 'content': '...'}],
#  'config': {'provider': 'OpenAI', 'model': 'gpt-4o-mini', 'tools': {'get_current_weather': {...}}}}

Managing Conversations: Working with Chains (promptl.chains)

This submodule is dedicated to handling multi-step prompts defined with .

• Creating Chains (promptl.chains.create)

  • Initializes the state for a chain execution.
  • Input: prompt: str, parameters: Optional[Dict], adapter: Optional[Adapter], options: Optional[CreateChainOptions].
  • Output: A Chain object, representing the stateful conversation.

  from promptl_ai import Promptl
  
  promptl = Promptl()
  two_step_prompt = """
  Ask question 1 about {{topic}}.
  Ask question 2 about {{topic}}.
  """
  params = {"topic": "PromptL"}
  
  chain_instance = promptl.chains.create(two_step_prompt, params)
  print(f"Chain ready. Completed: {chain_instance.completed}") # False
  

• Stepping Through Chains (chain.step)

  • Executes the next step in the sequence. You call this method directly on the Chain object.
  • Input: response: Optional[Union[str, MessageLike, Sequence[MessageLike]]]. This is crucial: it's the assistant's response from the previous step.
    • Pass a str for simple text replies.
    • Pass a MessageLike object (or list of them) for structured replies (like including tool calls the LLM made). See Data Types below.
    • It's None only for the very first call to step().
  • Output: StepChainResult containing the state after executing the current step.

• The Chain Object:

  • Holds the state. Returned by create and included in StepChainResult.
  • Properties: adapter, completed (bool), global_messages_count, raw_text, _chain (internal state).
  • Methods: step(response=...) is the primary way to interact.

• The StepChainResult Object:

  • The result of calling chain.step().
  • Properties:
    • messages: List[MessageLike]: The complete list of messages up to the end of the executed step (including the response you provided). Format depends on the adapter.
    • config: Dict[str, Any]: Configuration applicable at this stage.
    • completed: bool: True if this was the last step and its response was provided.
    • chain: Chain: The updated Chain object. Use this for the next call to step().

  Let's continue the two_step_prompt example:
  

  # Continuing from chain_instance creation above...
  
  # --- First step ---
  print("\n--- Step 1 ---")
  step1_result = chain_instance.step() # No response needed yet
  pprint(step1_result.model_dump(exclude={'chain'}))
  # Expected: {'messages': [{'role': 'user', 'content': 'Ask question 1 about PromptL.'}], 'config': {}, 'completed': False}
  print(f"Chain completed? {step1_result.chain.completed}") # False
  
  # --- Simulate LLM Response ---
  response1 = "Okay, Question 1: What is the main advantage of PromptL?"
  
  # --- Second step ---
  print("\n--- Step 2 ---")
  # Use the updated chain from the previous result!
  step2_result = step1_result.chain.step(response1)
  pprint(step2_result.model_dump(exclude={'chain'}))
  # Expected: {'messages': [..., {'role': 'assistant', 'content': response1}, {'role': 'user', 'content': 'Ask question 2 about PromptL.'}], 'config': {}, 'completed': False}
  print(f"Chain completed? {step2_result.chain.completed}") # False
  
  # --- Simulate LLM Response ---
  response2 = "Question 2: How does it handle different LLM providers?"
  
  # --- Final step ---
  print("\n--- Final Step ---")
  final_result = step2_result.chain.step(response2)
  pprint(final_result.model_dump(exclude={'chain'}))
  # Expected: {'messages': [..., {'role': 'assistant', 'content': response2}], 'config': {}, 'completed': True}
  print(f"Chain completed? {final_result.chain.completed}") # True