### Install Rigging with Extras

Source: https://github.com/dreadnode/rigging/blob/main/docs/install.mdx

Installs Rigging along with optional dependencies for features like vLLM, transformers, and examples. This is useful for development or when needing extended functionality.

```bash
pip install -U rigging[all]
```

```bash
uv pip install -U rigging[all]
```

```bash
poetry add rigging[all]
```

--------------------------------

### Detailed Chat Interaction

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Provides a more detailed example of a chat interaction, including the assistant's response. It highlights the `chat()` method's flexibility in accepting message formats and demonstrates running the pipeline to get the full conversation, including the model's output.

```python
import rigging as rg

generator = rg.get_generator("claude-3-sonnet-20240229")
pipeline = generator.chat( # (1)!
    [
        {"role": "system", "content": "You are a wizard harry."},
        {"role": "user", "content": "Say hello!"},
    ]
)
chat = await pipeline.run()
print(chat.all)
# [
#   Message(role='system', parts=[], content='You are a wizard harry.'),
#   Message(role='user', parts=[], content='Say hello!'),
#   Message(role='assistant', parts=[], content='Hello! How can I help you today?'),
# ]
```

--------------------------------

### Build Rigging from Source

Source: https://github.com/dreadnode/rigging/blob/main/docs/install.mdx

Builds and installs Rigging from its source code repository. This method is typically used by developers or for custom builds. It requires navigating to the project directory and using Poetry for installation.

```bash
cd rigging/
poetry install
```

--------------------------------

### Python: Example Usage of `using` Function

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/chat.mdx

This example demonstrates how to define a custom tool (`get_weather`) and integrate it into a chat pipeline using the `using` function. It shows the typical workflow of getting a generator, initiating a chat, adding the tool, and running the pipeline.

```python
async def get_weather(city: Annotated[str, "The city name to get weather for"]) -> str:
    "Get the weather"
    city = city.replace(" ", "+")
    return requests.get(f"http://wttr.in/{city}?format=2").text.strip()

chat = (
    await rg.get_generator("openai/gpt-4o-mini")
    .chat("What's the weather in london?")
    .using(get_weather)
    .run()
)
```

--------------------------------

### Install Rigging Base Package

Source: https://github.com/dreadnode/rigging/blob/main/docs/install.mdx

Installs the core Rigging package using common Python package managers. Ensure you have the respective package manager (pip, uv, or Poetry) installed.

```bash
pip install -U rigging
```

```bash
uv pip install -U rigging
```

```bash
poetry add rigging
```

--------------------------------

### Generating XML Examples with Rigging

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/data-models.mdx

Shows how to overload the `.xml_example()` method in Rigging models to provide detailed XML structure examples. This is achieved by instantiating the model and using `.to_pretty_xml()`, optionally with custom serializers for formatting.

```Python
import rigging as rg
from typing import Annotated
from pydantic import PlainSerializer

newline_str = Annotated[str, PlainSerializer(lambda x: f'\n{x}\n', return_type=str)]

class SaveMemory(rg.Model):
    key: str = rg.attr()
    content: newline_str

    @classmethod
    def xml_example(cls) -> str:
        return SaveMemory(
            key="my-note",
            content="Lots of custom data\nKeep this for later."
        ).to_pretty_xml()

# print(f"Use the following format:\n{SaveMemory.xml_example()}")
# Expected output:
# Use the following format:
# <save-memory key="my-note">
# Lots of custom data
# Keep this for later.
# </save-memory>
```

--------------------------------

### Starting Self-Hosted vLLM Server

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/generators.mdx

Shows the command-line instructions for starting a vLLM server, which provides an OpenAI-compatible API. This can be done directly using `vllm serve` or via a Docker container, mapping the necessary ports and volumes.

```bash
$ vllm serve --model Qwen/Qwen3-0.6B
```

```bash
$ docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    vllm/vllm-openai \
    --model Qwen/Qwen3-0.6B
```

--------------------------------

### Install Rigging with Pip (Bash)

Source: https://github.com/dreadnode/rigging/blob/main/README.md

Installs the Rigging library using pip, the standard Python package installer. This command fetches the latest stable version from the Python Package Index (PyPI) and makes it available for use in your Python projects.

```bash
pip install rigging
```

--------------------------------

### Python ChatPipeline Chaining Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/workflow.mdx

Demonstrates the functional chaining style for building a `ChatPipeline` in Python. This example shows how to configure a pipeline using methods like `.using()`, `.then()`, `.with_()`, and finally execute it with `.run()` to generate a `Chat` object.

```python
chat = (
    await
    generator.chat(...)
    .using(...)  # tools
    .then(...)   # follow up functions
    .with_(...)  # generation params
    .run()
)
```

--------------------------------

### Generate Multiple Examples with run_many

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Shows how to generate multiple chat instances using `run_many()` and then parse individual `FunFact` objects from each. This is useful for batch processing LLM outputs.

```python
import rigging as rg

# Assuming FunFact is a defined Pydantic model or similar
# class FunFact(rg.Model):
#     fact: str

chats = await rg.get_generator('gpt-3.5-turbo').chat(
    f"Provide a fun fact between {FunFact.xml_example()} tags."
).run_many(3)

for chat in chats:
    print(chat.last.parse(FunFact).fact)
```

--------------------------------

### XML Example for FunFact Model

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Shows the default XML structure generated by the `.xml_example()` class method for a Rigging Model. This output is used in prompts to instruct the LLM on the desired response format.

```xml
<fun-fact></fun-fact>
```

--------------------------------

### Python: bind_many Example Usage

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/prompt.mdx

This example demonstrates how to use the `bind_many` function to bind a prompt named `say_hello` to a specific model (e.g., 'gpt-3.5-turbo'). It then shows how to invoke the bound prompt using the returned `run_many` callable, passing the desired count and arguments.

```python
@rg.prompt
def say_hello(name: str) -> str:
    """Say hello to {{ name }}"""

await say_hello.bind("gpt-3.5-turbo")(5, "the world")
```

--------------------------------

### Define and Parse FunFact Model

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Demonstrates defining a simple data model inheriting from Rigging's Model class and parsing an LLM response into this model. It shows how to use `.xml_example()` to guide the LLM's output format.

```python
import rigging as rg

class FunFact(rg.Model):
    fact: str

chat = await rg.get_generator('gpt-3.5-turbo').chat(
    f"Provide a fun fact between {FunFact.xml_example()} tags."
).run()

fun_fact = chat.last.parse(FunFact)

print(fun_fact.fact)
```

--------------------------------

### Rigging Translator Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/completions.mdx

Demonstrates building a multilingual translator using Rigging's CompletionPipeline. It shows how to define a prompt, configure stop tokens with `.with_()`, and iteratively apply the pipeline to translate text into different languages.

```Python
PROMPT = """
As an expert translator, you accept english text and translate it to $language.

# Format

Input: [english text]
Output: [translated text]
---

Input: $input
Output: """

translator = (
    rg.get_generator('gpt-3.5-turbo')
    .complete(PROMPT)
    .with_(stop=["---", "Input:", "\n\n"])
)

text = "Could you please tell me where the nearest train station is?"

for language in ["spanish", "french", "german"]:
    completion = await translator.apply(
        language=language,
        input=text
    ).run()
    print(f"[{language}]: {completion.generated}")

# [spanish]: ¿Podría decirme por favor dónde está la estación de tren más cercana?
# [french]:  Pouvez-vous me dire où se trouve la gare la plus proche, s'il vous plaît ?
# [german]:  Könnten Sie mir bitte sagen, wo sich der nächste Bahnhof befindet?
```

--------------------------------

### Use @rg.prompt for Inline Set Parsing

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Demonstrates using the `@rg.prompt` decorator to define a function that returns a list of models directly. This streamlines the process of getting multiple structured outputs from an LLM.

```python
import rigging as rg

class FunFact(rg.Model):
    fact: str

@rg.prompt(generator_id="gpt-3.5-turbo")
def get_fun_facts(count: int = 3) -> list[FunFact]:
    """Provide fun facts."""

fun_facts = await get_fun_facts()
```

--------------------------------

### Async Migration: Using rg.await_ and asyncio.run

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/migrations.mdx

Provides examples for adapting to the exclusively asynchronous interface of rigging. It shows how to use the `rg.await_` helper function for synchronous contexts and the standard `asyncio.run` for running async main functions.

```python
import rigging as rg

def main():
    generator = rg.get_generator(...)
    pipeline = generator.chat(...)

    chat = rg.await_(pipeline.run())

if __name__ == "__main__":
    main()
```

```python
import asyncio
import rigging as rg

async def main():
    generator = rg.get_generator(...)
    pipeline = generatore.chat(...)

    chat = await pipeline.run()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Python rigging.prompt Decorator Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/prompt.mdx

Demonstrates how to use the `@rigging.prompt` decorator to define a prompt-generating function. It shows the structure for defining a data class for the output and calling the decorated function.

```python
from dataclasses import dataclass
import rigging as rg

@dataclass
class ExplainedJoke:
    chat: rg.Chat
    setup: str
    punchline: str
    explanation: str

@rg.prompt(generator_id="gpt-3.5-turbo")
async def write_joke(topic: str) -> ExplainedJoke:
    """Write a joke."""
    ...

# Example of calling the decorated function:
# await write_joke("programming")
```

--------------------------------

### Use @rg.prompt for Multiple Generations

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Refactors the previous example to use the `@rg.prompt` decorator for generating multiple `FunFact` objects. This simplifies prompt definition and execution for structured outputs.

```python
import rigging as rg

class FunFact(rg.Model):
    fact: str

@rg.prompt(generator_id="gpt-3.5-turbo")
def get_fun_fact() -> FunFact:
    """Provide a fun fact."""

fun_facts = await get_fun_fact.run_many(3)
```

--------------------------------

### Define Rigging Model for List Outputs

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/prompt-functions.mdx

Shows how to generate a list of `rigging.Model` objects. This example defines a `User` model and a prompt that generates a specified count of these user objects, detailing the structure for each list item.

```python
import rigging as rg

class User(rg.Model):
    name: str
    email: str
    age: int

@rg.prompt
def generate_users(count: int = 3) -> list[User]:
    """Generate fake test users."""

print(generate_users.template)

# Generate fake test users.
#
# {{ count }}
#
# Produce the following output for each item:
#
# <user>
#   <name/>
#   <email/>
#   <age/>
# </user>
```

--------------------------------

### Example Usage of @rg.prompt Decorator

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/prompt.mdx

Demonstrates how to use the @rg.prompt decorator to convert a Python function into a prompt. It shows defining output data structures using dataclasses and calling the generated prompt with an input topic.

```python
from dataclasses import dataclass
import rigging as rg

@dataclass
class ExplainedJoke:
    chat: rg.Chat
    setup: str
    punchline: str
    explanation: str

@rg.prompt(generator_id="gpt-3.5-turbo")
async def write_joke(topic: str) -> ExplainedJoke:
    """Write a joke."""
    ... # Hollow function implementation

# Example of calling the prompt
# await write_joke("programming")
```

--------------------------------

### Run Many Generations with ChatPipeline

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/iterating-and-batching.mdx

Demonstrates scaling out generation N times using `ChatPipeline.run_many()`. This example shows how to process chat messages, apply transformations using `.map()`, and execute multiple generation runs concurrently. It requires the `rigging` library.

```python
import rigging as rg

async def check_animal(chats: list[rg.Chat]) -> list[rg.Chat]:
    return [
        await chat.continue_(f"Why did you pick that animal?").meta(questioned=True).run()
        if any(a in chat.last.content.lower() for a in ["cat", "dog", "cow", "mouse"])
        else chat
        for chat in chats
    ]

chats = (
    await
    rg.get_generator("gpt-3.5-turbo")
    .chat("Tell me a joke about an animal.")
    .map(check_animal)
    .run_many(3)
)

for i, chat in enumerate(chats):
    questioned = chat.metadata.get("questioned", False)
    print(f"--- Chat {i+1} (?: {questioned}) ---")
    print(chat.conversation)
    print()
```

--------------------------------

### Build Rigging from Source (Bash)

Source: https://github.com/dreadnode/rigging/blob/main/README.md

Installs Rigging from local source code using Poetry, a dependency management and packaging tool for Python. This method is useful for development, testing unreleased features, or when contributing to the Rigging project.

```bash
cd rigging/
poetry install
```

--------------------------------

### Apply Ctx Annotations to Prompt Inputs/Outputs

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/prompt-functions.mdx

Demonstrates how to use `Ctx` annotations on prompt inputs and outputs to override XML tags, provide examples, and add prefix text. It also shows how to omit output processing by returning a `Chat` object.

```python
import rigging as rg

@rg.prompt
def summarize(text: str) -> rg.Chat:
    """Summarize this text."""

print(summarize.template)

# Summarize this text.
#
# {{ text }}
```

--------------------------------

### Basic Chat Generation

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Illustrates initiating a basic chat conversation with a language model using Rigging. It shows how to obtain a generator instance using `rg.get_generator`, create a chat pipeline with system and user messages, run the pipeline, and print the conversation history.

```python
import rigging as rg

generator = rg.get_generator("claude-3-sonnet-20240229")
pipeline = generator.chat(
    [
        {"role": "system", "content": "You are a wizard harry."},
        {"role": "user", "content": "Say hello!"},
    ]
)
chat = await pipeline.run()
print(chat.all)
# [
#   Message(role='system', parts=[], content='You are a wizard harry.'),
#   Message(role='user', parts=[], content='Say hello!'),
# ]
```

--------------------------------

### Rigging: Dynamic Slice Position Adjustment in Python

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/message-slicing.mdx

This Python example demonstrates how slices in the Rigging library automatically adjust their positions when the content of a message changes. It illustrates adding slices to a message, then removing parts of the message, and shows how the remaining slices correctly update their start and stop positions.

```python
import rigging as rg

message = rg.Message("assistant", "I think the answer is maybe 42.")

# Add slices for different parts
uncertainty = message.mark_slice("I think")
hedge = message.mark_slice("maybe ")
answer = message.mark_slice("42")

# Remove uncertain parts
message.remove_slices(uncertainty, hedge)  # (1)!

# Content updates automatically
print(message.content)  # "the answer is 42."
print(len(message.slices))  # 1 (only the answer slice remains)
```

--------------------------------

### Generate Example XML Representation

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/model.mdx

Returns an example XML representation of a given model class. Models can override this to provide more complex examples. By default, it generates a basic XML scaffold.

```APIDOC
xml_example:
  Returns an example XML representation of the given class.
  Models should typically override this method to provide a more complex example.
  By default, this method returns a hollow XML scaffold one layer deep.
  Returns:
    str: A string containing the XML representation of the class.
```

```python
@classmethod
def xml_example(cls) -> str:
    """
    Returns an example XML representation of the given class.

    Models should typically override this method to provide a more complex example.

    By default, this method returns a hollow XML scaffold one layer deep.

    Returns:
        A string containing the XML representation of the class.
    """
    if cls.is_simple():
        return cls.xml_tags()

    schema = cls.model_json_schema()
    properties = schema["properties"]
    structure = {cls.__xml_tag__: dict.fromkeys(properties)}
    xml_string = xmltodict.unparse(
        structure,
        pretty=True,
        full_document=False,
        indent="  ",
        short_empty_elements=True,
    )
    return t.cast("str", xml_string)  # Bad type hints in xmltodict
```

--------------------------------

### Generator Identifiers Examples

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/generators.mdx

Provides examples of valid generator identifier strings used in Rigging. These strings define the provider, model, and optional generation parameters for LLMs.

```text
gpt-4.1
openai/o3-mini
gemini/gemini-2.5-pro
claude-4-sonnet-latest
vllm_hosted/meta-llama/Llama-3.1-8B-Instruct
ollama/qwen3

openai/gpt-4,api_key=sk-1234
anthropic/claude-3-7-haiku-latest,stop=output:;---,seed=1337
together_ai/meta-llama/Llama-3-70b-chat-hf
openai/google/gemma-7b,api_base=https://integrate.api.nvidia.com/v1
```

--------------------------------

### Basic Chat Pipeline Execution

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Demonstrates how to initialize a generator, create a chat pipeline with system and user messages, and execute it to obtain a Chat object containing the conversation history and model response. This process involves staging messages into a pipeline before triggering generation with `.run()`.

```python
import rigging as rg

generator = rg.get_generator("claude-3-sonnet-20240229")
pipeline = generator.chat(
    [
        {"role": "system", "content": "You are a wizard harry."},
        {"role": "user", "content": "Say hello!"},
    ]
)
chat = await pipeline.run()
print(chat.all)
```

--------------------------------

### Rigging Tool Error Handling Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/tools.mdx

A Python example demonstrating the use of the `catch=True` parameter in the `@rg.tool` decorator. This ensures that any exception raised within the `potentially_failing_tool` function is caught and returned as a tool result to the model.

```python
@rg.tool(catch=True) # Catch any exception
def potentially_failing_tool(input: str) -> str:
    if input == "fail":
        raise ValueError("Intentional failure")
    return "Success"
```

--------------------------------

### Python: Define and use prompts with rigging library

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

This snippet demonstrates how to define custom prompts using the Dreadnode Rigging library. It shows how to specify a generator, define input types using Annotated, and create a prompt function that can be used as a tool. It also illustrates combining prompts to create more complex agent behaviors.

```python
import rigging as rg
from typing import Annotated

Joke = Annotated[str, rg.Ctx("joke")]

@rg.prompt(generator_id="gpt-4o-mini")
async def generate_jokes(count: int) -> list[Joke]:
    """Write {{count}} short hilarious jokes."""


@rg.prompt(generator_id="gpt-4o", tools=[generate_jokes])
async def write_joke() -> Joke:
    """
    Generate some jokes, then choose the best.
    You must return just a single joke.
    """

joke = await write_joke()
```

--------------------------------

### Llama 3 Tool Definition Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/tokenization.mdx

Provides an example of defining a tool using the Rigging library's decorator syntax. This snippet showcases how to create a Python function that can be registered as a tool, including type hints for parameters and return values.

```python
import rigging as rg

@rg.tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))

```

--------------------------------

### MessageSlice __len__ Method

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/message.mdx

Implements the __len__ method for the MessageSlice class, returning the length of the slice based on its start and stop indices.

```python
def __len__(self) -> int:
    """Returns the length of the slice."""
    return self.stop - self.start
```

--------------------------------

### CompletionPipeline Class and Methods

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/completion.mdx

Documentation for the CompletionPipeline class and its primary methods: fork, meta, and restart. This section groups related functionalities for comprehensive understanding.

```APIDOC
CompletionPipeline:
  __init__(generator: Generator, text: str, *, params: GenerateParams | None = None, watch_callbacks: list[WatchCompletionCallback] | None = None)
    Initializes a CompletionPipeline.
    Parameters:
      generator: The generator object responsible for generating the completion.
      text: The text to be completed.
      params: The parameters for generating the completion.
      watch_callbacks: Callbacks to watch the completion process.
    Attributes:
      metadata: Additional metadata associated with the completion.
      errors_to_fail_on: Exceptions to catch during generation.
      on_failed: How to handle failures in the pipeline.
      until_callbacks: Callbacks triggered until a condition is met.
      until_types: Types of models to trigger until callbacks.
      then_callbacks: Callbacks executed after completion.
      map_callbacks: Callbacks to map completion results.
      watch_callbacks: Callbacks to monitor completion progress.

fork(text: str, *, include_all: bool = False) -> CompletionPipeline
  Forks the completion by creating calling [rigging.completion.Completion.restart][] and appends the specified text.
  Parameters:
    text: The text to append.
    include_all: Whether to include all generations or just the last one.
  Returns:
    A new instance of the pipeline with the specified messages added.

meta(**kwargs: Any) -> Completion
  Updates the metadata of the completion with the provided key-value pairs.
  Parameters:
    **kwargs: Key-value pairs representing the metadata to be updated.
  Returns:
    The updated completion object.

restart(*, generator: Generator | None = None, include_all: bool = False) -> CompletionPipeline
  Attempt to convert back to a CompletionPipeline for further generation.
  Parameters:
    generator: The generator to use for the restarted completion. If None, the original generator is used.
    include_all: Whether to include the generation before the next round.
  Returns:
    The restarted completion.
  Raises:
    ValueError: If the completion was not created with a CompletionPipeline and no generator is provided.
```

--------------------------------

### Ctx Class Definition

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/prompt.mdx

The Ctx class is used in type annotations to provide additional context for prompt construction, allowing for custom tags, prefixes, or examples.

```APIDOC
Ctx:
  __init__(tag: str | None = None, prefix: str | None = None, example: str | Model | None = None)
    tag: Optional string tag for context.
    prefix: Optional string prefix for context.
    example: Optional example string or Model for context.

  Example Usage:
    tag_override = Annotated[str, Ctx(tag="custom_tag", ...)]
```

--------------------------------

### Transform Chaining Example

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/generators.mdx

Demonstrates how to chain multiple transforms sequentially, where the output of one transform becomes the input for the next, enabling complex data processing pipelines.

```yaml
transforms:
    - type: "jsonpath"
      pattern: "$.data"  # Extract data object
    - type: "jinja"
      pattern: "{{ result | tojson }}"  # Convert to string
    - type: "regex"
      pattern: "message: (.*)"  # Extract specific field
```

--------------------------------

### Fetch and Use Robopages Tools

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/tools.mdx

Demonstrates fetching tool definitions from a Robopages server and integrating them into a Rigging pipeline. This allows language models to utilize external tools by unpacking them using the `.using()` method.

```python
ROBOPAGES_URL = "http://localhost:8080" # Example URL

try:
    # Fetch tools from the server
    robopages_tools = rg.robopages(ROBOPAGES_URL)

    # Use the fetched tools in a pipeline
    chat = (
        await rg.get_generator("openai/gpt-4o-mini")
        .chat("Use the available Robopages tool to do X.") # Adjust prompt based on available tools
        .using(*robopages_tools) # Unpack the list of tools
        .run()
    )
    print(chat.conversation)

except Exception as e:
    print(f"Failed to connect to Robopages or use tools: {e}")
    # Handle connection errors or cases where no tools are found
```

--------------------------------

### Custom Transform: Message Preprocessing

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/transforms.mdx

Demonstrates creating a custom transform function to preprocess messages before they are sent to the model. This example injects dynamic context into user messages.

```python
import rigging as rg

# Placeholder for fetching dynamic context
def get_current_context() -> str:
    return "User is asking about weather."

# Custom transform function
async def add_context_transform(
    messages: list[rg.Message],
    params: rg.GenerateParams
) -> tuple[list[rg.Message], rg.GenerateParams, None]:
    # Add context to user messages
    for message in messages:
        if message.role == "user":  # Target only user messages
            context = get_current_context()  # Fetch dynamic context
            message.content = f"Context: {context}\n\n{message.content}"  # Prepend context

    return messages, params, None  # Return modified messages and params

# Apply the custom transform during generation
chat = (
    await rg.get_generator("gpt-4")
    .chat("Help me with this task")
    .transform(add_context_transform) # Apply the custom transform
    .run()
)
```

--------------------------------

### Connect to Self-Hosted OpenAI-Compatible Servers

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/generators.mdx

Demonstrates connecting to self-hosted OpenAI-compatible LLM servers using the `rigging` library. It requires specifying the `openai/` prefix and the `api_base` URL. An API key is necessary, and alternatives like `hosted_vllm` or `llamafile` are suggested for direct integration.

```python
import rigging as rg

gen = rg.get_generator("openai/<model>,api_base=http://<server>/v1"

chat = await gen.chat("Hello").run()
print(chat.conversation)
```

```python
gen = rg.get_generator(
  "openai/<model>,api_base=http://localhost:8000/v1,api_key=sk-none"
)
```

--------------------------------

### Stop Exception and Usage

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/error.mdx

The Stop exception is used to signal a deliberate stopping condition within a pipeline. It includes an example demonstrating its use in an asynchronous file reading function.

```python
import rigging as rg

async def read_file(path: str) -> str:
    """Read the contents of a file."""

    if no_more_files(path):
        raise rg.Stop("There are no more files to read.")

    ...

chat = await pipeline.using(read_file).run()
```

```python
class Stop(Exception):
    def __init__(self, message: str):
        super().__init__(message)
        self.message = message
        """The message associated with the stop."""
```

--------------------------------

### Define and Call Prompt Function

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Demonstrates how to define a prompt as an asynchronous Python function using the `@rg.prompt` decorator. The function specifies the generator ID and includes type hints for parameters and return values. It then shows how to call this function and print the result.

```python
import rigging as rg

@rg.prompt(generator_id="gpt-4")
async def get_authors(count: int = 3) -> list[str]:
    """Provide famous authors."""

print(await get_authors())

# ['William Shakespeare', 'J.K. Rowling', 'Jane Austen']
```

--------------------------------

### Basic Slice Access

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/message-slicing.mdx

Demonstrates how to access the start, stop, and content properties of a message slice. This is useful for retrieving information about marked text segments within a message.

```python
print(f"Answer at: {message.slices[0].start}-{message.slices[0].stop}")  # (2)!
print(f"Content: {message.slices[0].content}")  # "42"
```

--------------------------------

### Get Transform by Identifier (API)

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/transform.mdx

Retrieves a pre-defined transform function using its unique string identifier. This function is crucial for accessing specific transformation logic within the library.

```APIDOC
get_transform(identifier: str) -> Transform

Get a well-known transform by its identifier.

Parameters:
  identifier (str): The identifier of the transform to retrieve.

Returns:
  Transform: The corresponding transform callable.

Example:
  # Assuming 'json' is a registered identifier
  json_transformer = get_transform('json')
```

```python
def get_transform(identifier: str) -> Transform:
    """
    Get a well-known transform by its identifier.

    Args:
        identifier: The identifier of the transform to retrieve.

    Returns:
        The corresponding transform callable.
    """
    match identifier:
        case "json":
            return tools_to_json_transform
        case "json-in-xml":
            return tools_to_json_in_xml_transform
        case "json-with-tag":
            return tools_to_json_with_tag_transform
        case _:
            raise ValueError(f"Unknown transform identifier: {identifier}")
```

--------------------------------

### Batch Generation with Parameters using Python

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/iterating-and-batching.mdx

Demonstrates how to use the `run_batch` method to generate responses by varying a set of generation parameters while keeping the input message constant. This is useful for exploring different model behaviors. It requires the `rigging` library and an LLM provider like `litellm`.

```python
import rigging as rg

pipeline = rg.get_generator("gpt-3.5-turbo").chat()

chats = await pipeline.run_batch(
    ["Tell me a short fact about an japanese city."],
    [rg.GenerateParams(temperature=t) for t in [0.6, 0.9, 1.2, 1.5, 1.8]]
)

for i, chat in enumerate(chats):
    print(f"--- Chat {i+1} ---")
    print(chat.generator_id)
    print()
    print(chat.conversation)
    print()

```

```text
---
--- Chat 1 ---
litellm!gpt-3.5-turbo,temperature=0.6

[assistant]: Tokyo, the capital city of Japan, is the most populous
metropolitan area in the world, with over 37 million residents.

--- Chat 2 ---
litellm!gpt-3.5-turbo,temperature=0.9

[assistant]: Tokyo is the largest metropolitan area in the world,
with a population of over 37 million people.

--- Chat 3 ---
litellm!gpt-3.5-turbo,temperature=1.2

[assistant]: Kyoto, a city in Japan known for its historic temples
and gardens, was once the capital of Japan for over 1,000 years from
794 until the capital was moved to Tokyo in 1869.

--- Chat 4 ---
litellm!gpt-3.5-turbo,temperature=1.5

[assistant]: Nagoya, Japan is known for being one of the leading
manufacturing and industrial regions in the country, with a strong
automotive presence including major factories for Toyota, Honda, and Mitsubishi.

--- Chat 5 ---
litellm!gpt-3.5-turbo,temperature=1.8

[assistant]: Sendai is the largest city in the Tohoku region of
Japan and is known for its incredible natural scenery, such as the
nearby Sendai Bay and Zuihoden mausoleum.

```

--------------------------------

### apply Method

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/completion.mdx

Applies keyword arguments to the text using string template substitution. This produces a clone of the CompletionPipeline, leaving the original unchanged. Returns a new instance of CompletionPipeline with the applied arguments.

```python
def apply(self, **kwargs: str) -> "CompletionPipeline":
    """
    Applies keyword arguments to the text using string template substitution.

    Note:
        This produces a clone of the CompletionPipeline, leaving the original unchanged.

    Args:
        **kwargs: Keyword arguments to be applied to the text.

    Returns:
        A new instance of CompletionPipeline with the applied arguments.
    """
    new = self.clone()
    template = string.Template(self.text)
    new.text = template.safe_substitute(**kwargs)
    return new
```

--------------------------------

### Get Identifier API

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/generator.mdx

Converts a generator instance back into a rigging identifier string. It reconstructs the provider, model, and any relevant parameters, excluding unsupported fields like 'extra'.

```APIDOC
get_identifier

Converts the generator instance back into a rigging identifier string.

Warning:
    The `extra` parameter field is not currently supported in identifiers.

Signature:
get_identifier(
    generator: Generator,
    params: GenerateParams | None = None,
) -> str

Parameters:
  generator (`Generator`): The generator object.
  params (`GenerateParams | None`, optional): The generation parameters. Defaults to None.

Returns:
  `str`: The identifier string for the generator.

Example Usage:
# Assuming 'my_generator' is an instance of a Generator subclass
# identifier = get_identifier(my_generator)

# Related Methods:
# register_generator: Used to register generator classes.
# Generator.model_dump: Used internally to serialize generator state.
```

--------------------------------

### Registering and Getting Custom Generators

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/generators.mdx

Demonstrates how to register a custom generator class with a provider ID and then retrieve it using `get_generator`, specifying model and custom fields in the identifier string.

```python
import rigging as rg

# Assuming 'Custom' class is defined elsewhere
# rg.register_generator('custom', Custom)

# custom = rg.get_generator('custom!foo,custom_field=True')
```

--------------------------------

### Managing Chat Conversations

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Illustrates how to manage conversational flow using `fork` and `continue_` methods. `ChatPipeline.fork` creates new pipelines from a specific state, allowing parallel branches. `Chat.continue_` extends a completed conversation by adding new messages and running the pipeline again, facilitating sequential interaction.

```python
import rigging as rg

pipeline = (
    rg.get_generator("gpt-4o-mini")
    .chat("Hello, how are you?")
)

# We can fork before generation has occurred
specific = await pipeline.fork("Be specific please.").run()
poetic = await pipeline.fork("Be as poetic as possible").with_(temperature=1.5).run() # (1)!

print(specific.conversation)

# [user]: Hello, how are you?
# [user]: Be specific please.
# [assistant]: I'm just a computer program, so I don't have feelings ...

print(poetic.conversation)

# [user]: Hello, how are you?
# [user]: Be as poetic as possible
# [assistant]: In the gentle embrace of sun-drenched morn, I find myself a ...

# We can also continue after generation
next_pipeline_chat = poetic.continue_("That's good, tell me a joke") # (2)!
update = await next_pipeline_chat.run()

print(update.conversation)
```

--------------------------------

### Integrate Tools in Chat Pipeline

Source: https://github.com/dreadnode/rigging/blob/main/docs/intro.mdx

Shows how to make Python functions available as tools within a Rigging chat pipeline. The LLM can then call these tools during conversation, and their results are integrated into the output.

```python
import rigging as rg

def add_numbers(x: float, y: float) -> float:
    return x + y

chat = (
    await
    rg.get_generator("gpt-4o-mini")
    .chat("What is 1337 + 42?")
    .using(add_numbers)
    .run()
)

print(chat.conversation)

# Expected output snippet:
# [user]: What is 1337 + 42?
#
# [assistant]:
#  |- add_numbers({"x":1337,"y":42})
#
# [tool]: 1379
#
```

--------------------------------

### MessageSlice __str__ Method

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/message.mdx

Implements the __str__ method for the MessageSlice class, providing a string representation of the slice's properties, including type, start, stop, and a preview of its content.

```python
def __str__(self) -> str:
    """Returns a string representation of the slice."""
    content_preview = self.content if self._message else "[detached]"
    return f"<MessageSlice type='{self.type}' start={self.start} stop={self.stop} obj={self.obj.__class__.__name__ if self.obj else None} content='{shorten_string(content_preview, 50)}'>"
```

--------------------------------

### rigging.prompt.prompt Decorator API

Source: https://github.com/dreadnode/rigging/blob/main/docs/api/prompt.mdx

Provides the API documentation for the @rg.prompt decorator. It details the decorator's parameters for configuring prompt generation, including pipelines, generators, tools, and system prompts, along with its return type.

```APIDOC
rg.prompt(
    func: Callable[P, Coroutine[Any, Any, R]] | Callable[P, R] | None = None, 
    /, 
    *, 
    pipeline: ChatPipeline | None = None, 
    generator: Generator | None = None, 
    generator_id: str | None = None, 
    tools: list[Tool[..., Any] | Callable[..., Any]] | None = None, 
    system_prompt: str | None = None,
) -> Callable[[Callable[P, Coroutine[Any, Any, R]] | Callable[P, R]], Prompt[P, R]] | Prompt[P, R]

Description:
    Convert a hollow function into a Prompt, which can be called directly or passed a
    chat pipeline to execute the function and parse the outputs.

    Note:
        A docstring is not required, but this can be used to provide guidance to the model, or
        even handle any number of input transformations. Any input parameter which is not
        handled inside the docstring will be automatically added and formatted internally.

    Note:
        Output parameters can be basic types, dataclasses, rigging models, lists, or tuples.
        Internal inspection will attempt to ensure your output types are valid, but there is
        no guarantee of complete coverage/safety. It's recommended to check
        [rigging.prompt.Prompt.template][] to inspect the generated jinja2 template.

    Note:
        If you annotate the return value of the function as a [rigging.chat.Chat][] object,
        then no output parsing will take place and you can parse objects out manually.

        You can also use Chat in any number of type annotation inside tuples or dataclasses.
        All instances will be filled with the final chat object transparently.

    Note:
        All input parameters and output types can be annotated with the [rigging.prompt.Ctx][] annotation
        to provide additional context for the prompt. This can be used to override the xml tag, provide
        a prefix string, or example content which will be placed inside output xml tags.

Parameters:
    func: The function to convert into a prompt.
    pipeline: An optional pipeline to use for the prompt.
    generator: An optional generator to use for the prompt.
    generator_id: An optional generator id to use for the prompt.
    tools: An optional list of tools to make available during generation (can be other prompts).
    system_prompt: An optional system prompt fragment to inject into the messages before generation.

Returns:
    A prompt instance or a function that can be used to create a prompt.
```

--------------------------------

### Contextual Output Formatting with Ctx

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/prompt-functions.mdx

Demonstrates using `Annotated` and `rg.Ctx` to provide richer context and formatting instructions for prompt outputs.

```python
from typing import Annotated
import rigging as rg

Summary = Annotated[str, rg.Ctx(tag="summary", example="[2-3 sentences]")]

@rg.prompt
def summarize(text: Annotated[str, rg.Ctx(tag="long-text")]) -> Summary:
    """Summarize this text."""

print(summarize.template)

# Expected output:
# Summarize this text.
# 
# {{ long_text }}
# 
# Produce the following output:
# 
# <summary>[2-3 sentences]</summary>

```

--------------------------------

### Get Tokenizer Instance

Source: https://github.com/dreadnode/rigging/blob/main/docs/topics/tokenization.mdx

Shows how to retrieve a tokenizer instance using an identifier string, similar to how generators are obtained. It supports Hugging Face models and custom tokenizers, with an optional provider prefix.

```python
import rigging as rg

# Hugging Face models (most common)
qwen = rg.get_tokenizer("Qwen/Qwen2-7B-Instruct")

print(f"{qwen!r})

# TransformersTokenizer(model='Qwen/Qwen2-7B-Instruct', apply_chat_template_kwargs={}, encode_kwargs={}, decode_kwargs={})

```