Promplate

https://docs.py.promplate.dev
Admin
Promplate is a templating framework and agent orchestrator that enhances prompt engineering...
Tokens:53,179
Snippets:380
Trust Score:6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Promplate with OpenAI support

Source: https://docs.py.promplate.dev/quick-start

Installs the Promplate library with optional support for OpenAI models using pip. This is the first step to integrating LLMs.

```bash
pip install promplate[openai]
```

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

### Initialize OpenAI TextComplete LLM client

Source: https://docs.py.promplate.dev/quick-start

Initializes a TextComplete client for OpenAI's instruct models. This is an alternative to ChatComplete for models that process plain text prompts.

```python
from promplate.llm.openai import TextComplete
complete = TextComplete(api_key="...").bind(model="gpt-3.5-turbo-instruct")
```

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

### Create and render a simple template

Source: https://docs.py.promplate.dev/quick-start

Creates a `Template` object with dynamic content using `{{ }}` placeholders and renders it by providing local variables. This is useful for generating prompts with variable data.

```python
import time
from promplate import Template
greet = Template("Greet me. It is {{ time.asctime() }} now.")
greet.render(locals())
```

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

### Stream LLM responses with ChatGenerate

Source: https://docs.py.promplate.dev/quick-start

Demonstrates how to stream responses from an OpenAI chat model using `ChatGenerate`. This allows for processing generated tokens as they arrive, providing a more interactive experience.

```python
from promplate.llm.openai import ChatGenerate
generate = ChatGenerate(api_key="...").bind(model="gpt-3.5-turbo-0125")
for i in generate("Explain why 1 + 1 = 2"):
    print(i, end="", flush=True)
```

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

### Make a simple LLM call with ChatComplete

Source: https://docs.py.promplate.dev/quick-start

Demonstrates a basic call to the ChatComplete client to get a response from an OpenAI model. The model parameter specifies which model to use.

```python
complete("hi", model="gpt-3.5-turbo-0125")
```

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

### Initialize and render a Node with local variables

Source: https://docs.py.promplate.dev/quick-start

Demonstrates how to initialize a 'Node' object with a template string and local variables. The 'Node.render()' method then processes the template, embedding the current time. This is useful for creating dynamic prompts.

```python
>>> from promplate import Node
>>> greet = Node("Greet me. It is {{ time.asctime() }} now.", locals())
>>> greet.render()
'Greet me. It is Sun Oct 1 04:16:04 2023 now.'
```

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

### Initialize OpenAI ChatComplete LLM client

Source: https://docs.py.promplate.dev/quick-start

Initializes a ChatComplete client for OpenAI's chat models. Requires an API key. This client can be used to send prompts and receive completions.

```python
from promplate.llm.openai import ChatComplete
complete = ChatComplete(api_key="...")
```

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

### Use FREE proxy for OpenAI API calls

Source: https://docs.py.promplate.dev/quick-start

Initializes the ChatComplete client using a free proxy service as the base URL, useful when an API key is unavailable. The API key can be left empty when using the proxy.

```python
from promplate.llm.openai import ChatComplete
complete = ChatComplete(base_url="https://promplate.dev", api_key="").bind(model="gpt-3.5-turbo-0125")
```

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

### Install Promplate

Source: https://docs.py.promplate.dev/index

The command to install the Promplate library using pip. This is the first step to using Promplate in your Python environment.

```shell
pip install promplate 

```

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

### Pass parameters to LLM calls

Source: https://docs.py.promplate.dev/quick-start

Shows how to pass additional parameters like `temperature` and `max_tokens` during an LLM call to control the generation process. These parameters influence the output's creativity and length.

```python
complete("1 + 1 = ", temperature=0, max_tokens=1)
```

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

### Basic Prompt Chaining with Promplate (Python)

Source: https://docs.py.promplate.dev/index

Demonstrates how to create and chain two Jinja2 templates ('reply.j2' and 'translate.j2') using Promplate's Node system. It shows setting run configurations, binding an LLM completion model, and invoking the chain to get a result.

```python
from promplate.llm.openai import ChatComplete 
from promplate import Node

reply = Node.read("reply.j2")
translate = Node.read("translate.j2")

translate.run_config["temperature"] = 0

chain = reply + translate 

complete = ChatComplete().bind(model="gpt-3.5-turbo")
context = {"lang": "chinese"}

# To get the result:
# chain.invoke(context, complete).result

```

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

### Get Base Prompt Builder (Python)

Source: https://docs.py.promplate.dev/references/prompt

Creates a base CodeBuilder instance for constructing prompts. It initializes with either synchronous or asynchronous render methods and sets up internal variables for parts and appending.

```python
def get_base_builder(sync=True, indent_str="\t"):
    return (
        CodeBuilder(indent_str=indent_str)
        .add_line("def render():" if sync else "async def render():")
        .indent()
        .add_line("__parts__ = []")
        .add_line("__append__ = __parts__.append")
    )
```

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

### Registering a callback using a decorator

Source: https://docs.py.promplate.dev/quick-start

Illustrates how to register a callback function to be executed after a node finishes processing using the '@end_process' decorator. This callback, 'log_greet_result', logs the node's result and a context variable, showcasing how to add custom logic to the processing pipeline.

```python
>>> @greet.end_process
... def log_greet_result(context):
...     print(context.result)
...     print(context["target_language"])
... 
>>> chain.invoke({"target_language": "zh_CN"}, complete).result
Good morning!
zh_CN
'早上好！'
```

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

### Get User Agent String (Python)

Source: https://docs.py.promplate.dev/references/prompt

Constructs a user agent string including the Promplate version, Python version, and versions of additional specified packages. It utilizes caching to avoid redundant computations.

```Python
from sys import version as py_version

@cache_once
def get_user_agent(self, *additional_packages: tuple[str, str]):
    return " ".join(
        (
            f"Promplate/{version('promplate')} ({self.__name__ if isinstance(self, type) else self.__class__.__name__})",
            *(f"{name}/{v}" for name, v in additional_packages),
            f"HTTPX/{version('httpx') or '-'}",
            f"Python/{py_version.split()[0]}",
        )
    )
```

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

### Chain Nodes and invoke with context

Source: https://docs.py.promplate.dev/quick-start

Shows how to combine two 'Node' objects using the addition operator to create a processing pipeline. The '.invoke()' method executes the chained nodes, passing context and retrieving the final result, demonstrating a simple 'greeting in another language' scenario.

```python
>>> translate = Node('translate \'\'\'{{ __result__ }}\'\'\' into {{ target_language }}')
>>> chain = greet + translate # this represents the pipeline of "greeting in another language"
>>> chain.invoke({"target_language": "zh_CN"}, complete).result
'早上好！'
```

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

### Render template with explicit context

Source: https://docs.py.promplate.dev/quick-start

Renders a template by explicitly providing the context dictionary, which can include modules like `time`. This offers more control over the data available for rendering compared to `locals()`.

```python
import time
from promplate import Template
greet = Template("Greet me. It is {{ time.asctime() }} now.", {"time": time})
greet.render()
```

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

### Message Start Token Parsing (Python)

Source: https://docs.py.promplate.dev/references/prompt

Compiles a regular expression to identify and parse the start of a message token, which can include user, system, or assistant roles along with an optional identifier. This is useful for structured message processing.

```Python
from re import compile

is_message_start = compile('<\|\s?(user|system|assistant)\s?(\w{1,64})?\s?\|>')
```

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

### Fetch Template from URL (Python)

Source: https://docs.py.promplate.dev/references/prompt

The `fetch` classmethod in the `Loader` class retrieves template content from a given URL. It handles constructing the full URL and making an HTTP GET request. The response content is used to instantiate the class, and the template name is derived from the URL's stem.

```python
@classmethod
def fetch(cls, url: str, **kwargs):
    from .utils import _get_client

    response = _get_client().get(cls._join_url(url), **cls._patch_kwargs(kwargs))
    obj = cls(response.raise_for_status().text)
    obj.name = Path(url).stem
    return obj
```

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

### Config class for OpenAI API configuration (Python)

Source: https://docs.py.promplate.dev/references/llm

The 'Config' class, inheriting from 'Configurable', specifically handles OpenAI API configurations. It initializes with essential parameters like 'model' and optional parameters such as 'temperature', 'top_p', 'stop', 'max_tokens', 'api_key', and 'api_base'. It also includes placeholder methods for attribute setting and getting.

```python
class Config(Configurable):
    def __init__(
        self,
        model: str,
        temperature: float | int | None = None,
        top_p: float | int | None = None,
        stop: str | list[str] | None = None,
        max_tokens: int | None = None,
        api_key: str | None = None,
        api_base: str | None = None,
        **other_config,
    ):
        self.model = model
        self.temperature = temperature
        self.top_p = top_p
        self.stop = stop
        self.max_tokens = max_tokens
        self.api_key = api_key
        self.api_base = api_base

        for key, val in other_config.items():
            setattr(self, key, val)

    def __setattr__(self, *_): ...

    def __getattr__(self, _): ...

```

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

### Get Package Version with Caching in Python

Source: https://docs.py.promplate.dev/references/prompt

Retrieves the version of a specified package using `importlib.metadata.version`. It caches the result and returns None if the package is not found. Requires the `importlib.metadata` module.

```python
@cache
def version(package: str):
    from importlib.metadata import PackageNotFoundError, version

    try:
        return version(package)
    except PackageNotFoundError:
        return None
```

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

### Initialize OpenAI Client (__init__)

Source: https://docs.py.promplate.dev/references/llm

Initializes the synchronous OpenAI client with provided configuration. It accepts arbitrary keyword arguments for configuration. This is a base constructor for client-related classes.

```python
@same_params_as(Client)
def __init__(self, **config): ...
```

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

### Initialize Async OpenAI Client Configuration (__init__)

Source: https://docs.py.promplate.dev/references/llm

Initializes the asynchronous client configuration. It inherits from the base Config class and uses `@same_params_as` to ensure compatibility with the AsyncClient. Accepts arbitrary keyword arguments for configuration.

```python
class AsyncClientConfig(Config):
    @same_params_as(AsyncClient)
    def __init__(self, **config): ...
```

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

### OpenAI v0 __init__ Method

Source: https://docs.py.promplate.dev/references/llm

Initializes the OpenAI v0 configuration with model, temperature, top_p, stop, max_tokens, api_key, api_base, and other optional configurations. It sets instance attributes based on the provided parameters.

```python
def __init__(
    self,
    model: str,
    temperature: float | int | None = None,
    top_p: float | int | None = None,
    stop: str | list[str] | None = None,
    max_tokens: int | None = None,
    api_key: str | None = None,
    api_base: str | None = None,
    **other_config,
):
    self.model = model
    self.temperature = temperature
    self.top_p = top_p
    self.stop = stop
    self.max_tokens = max_tokens
    self.api_key = api_key
    self.api_base = api_base

    for key, val in other_config.items():
        setattr(self, key, val)
```

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

### Bind model to ChatComplete client

Source: https://docs.py.promplate.dev/quick-start

Binds a specific model to the ChatComplete client, so the model parameter doesn't need to be provided on every call. Simplifies repeated calls to the same model.

```python
complete = ChatComplete(api_key="...").bind(model="gpt-3.5-turbo-0125")
```

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

### Node Initialization

Source: https://docs.py.promplate.dev/references/chain

Initializes a Node instance with a template, optional partial context, LLM, and additional configuration. It ensures the template is a Template object and sets up internal attributes.

```python
def __init__(
    self,
    template: Template | str,
    partial_context: Context | None = None,
    llm: LLM | None = None,
    **config,
):
    self.template = Template(template) if isinstance(template, str) else template
    self._context = partial_context
    self.callbacks: list[BaseCallback | type[BaseCallback]] = []
    self.llm = llm
    self.run_config = config
```

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

### OpenAI v1 Client: Config __init__ Method

Source: https://docs.py.promplate.dev/references/llm

Initializes the Config object for the OpenAI v1 client, calling the superclass constructor and setting up an internal dictionary for run-specific configurations.

```python
def __init__(self, **config):
    super().__init__(**config)
    self._run_config = {}
```

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

### OpenAI v1 Client: ClientConfig Class

Source: https://docs.py.promplate.dev/references/llm

Defines the 'ClientConfig' class, which inherits from 'Config'. It uses 'same_params_as' to ensure its constructor signature matches the 'Client' class, simplifying configuration for direct client instantiation.

```python
class ClientConfig(Config):
    @same_params_as(Client)
    def __init__(self, **config): ...
```

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

### Get Compiled Script

Source: https://docs.py.promplate.dev/references/prompt

Retrieves the compiled Python script of the template. Useful for debugging or inspecting the generated code.

```APIDOC
## get_script get_script(sync=True, indent_str='    ')

### Description
Compiles the template string into a Python script and returns it as a string. This is useful for inspecting the generated Python code.

### Method
get_script

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sync** (bool) - Optional. Determines if the script generation should be based on synchronous compilation. Defaults to True.
- **indent_str** (str) - Optional. The string to use for indentation in the generated script. Defaults to '    '.

#### Request Body
None

### Request Example
None

### Response
- **str** - The compiled Python script as a string.

#### Success Response (200)
- **script_string** (str) - The string representation of the compiled Python script.

#### Response Example
None
```

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

### Get Builtin Namespace in Python

Source: https://docs.py.promplate.dev/references/prompt

Retrieves the built-in namespace, handling cases where `__builtins__` might be a module or a dictionary. It returns the `__dict__` if `__builtins__` is a module.

```python
@cache_once
def get_builtins() -> dict[str, Any]:
    return __builtins__ if isinstance(__builtins__, dict) else __builtins__.__dict__
```

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

### promplate.prompt.builder

Source: https://docs.py.promplate.dev/references/prompt

Utilities for building code strings with proper indentation.

```APIDOC
## promplate.prompt.builder API

### Description
This module provides the `CodeBuilder` class for constructing code snippets with managed indentation levels and string formatting.

### Classes
#### `CodeBuilder`
A class for building code strings with indentation management.

Attributes:
- `code` (str) - The current code string being built.
- `indent_level` (int) - The current indentation level.
- `indent_str` (str) - The string used for each indentation level (e.g., '    ').

Methods:
- `__init__(indent_str: str = '    ')`
- `__str__()` - Returns the current code string.
- `add_line(line: str)` - Adds a line of code with the current indentation.
- `add_section(section_name: str, lines: list[str])` - Adds a named section with indented lines.
- `indent()` - Increases the indentation level.
- `dedent()` - Decreases the indentation level.
- `get_render_function()` - Returns a function that renders the current code.
```

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

### Initialize PromptTemplate in Python

Source: https://docs.py.promplate.dev/references/prompt

Initializes a PromptTemplate object with a given text and an optional context. The context is stored internally and can be used during rendering.

```python
def __init__(self, text: str, /, context: Context | None = None):
    super().__init__(text)
    self.context = {} if context is None else context
```

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

### Get Package Version (Python)

Source: https://docs.py.promplate.dev/references/prompt

Fetches the version of a specified Python package using importlib.metadata. It returns None if the package is not found. This function is cached for efficiency.

```Python
from importlib.metadata import PackageNotFoundError, version
from functools import cache

@cache
def version(package: str):
    try:
        return version(package)
    except PackageNotFoundError:
        return None
```

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

### Creating Chat Prompts (Python - shorthand)

Source: https://docs.py.promplate.dev/index

Presents a shorthand syntax for creating chat messages using `U`, `A`, and `S` (aliases for `user`, `assistant`, `system`). This provides a more concise way to build chat message lists, including named users.

```python
from promplate.prompt.chat import U, A, S

# Simple messages using shorthand
U > "hello"
A > "hi"

# Messages with names and system prompts using shorthand
[S > "...", U @ "example_user" > "hi"]

```

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

### Cache Function Result Once in Python

Source: https://docs.py.promplate.dev/references/prompt

A decorator that caches the result of a function call. The function is executed only once, and subsequent calls return the cached result. This is useful for expensive computations or setup.

```python
def cache_once(func: Callable[P, T]) -> Callable[P, T]:
    result = None

    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
        nonlocal result
        if result is None:
            result = func(*args, **kwargs)
        return result

    return wrapper
```

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

### promplate.prompt.template

Source: https://docs.py.promplate.dev/references/prompt

Core templating engine for defining and rendering dynamic content.

```APIDOC
## promplate.prompt.template API

### Description
This module contains the core `TemplateCore` and `Template` classes for parsing, compiling, and rendering templates. It also includes utilities for tokenization, context management, and loading templates.

### Classes
#### `TemplateCore`
The fundamental class for template processing.

- `text` (str) - The raw template string.
- `error_handling` (str) - Specifies how errors during rendering should be handled.

Methods:
- `__init__(text: str, error_handling: str = 'strict')`
- `compile()`
- `render(context: dict | None = None, **kwargs)`
- `arender(context: dict | None = None, **kwargs)`
- `get_script()`

#### `Template`
A user-facing wrapper around `TemplateCore` for simpler usage.

- `context` (Context) - The context object for rendering.

Methods:
- `__init__(template: str, context: Context | None = None)`
- `render(context: dict | None = None, **kwargs)`
- `arender(context: dict | None = None, **kwargs)`

#### `Context`
Represents the context available during template rendering.

#### `Loader`
Abstract base class for template loaders.

Methods:
- `read(template_name: str)`
- `aread(template_name: str)`
- `fetch(template_name: str)`
- `afetch(template_name: str)`

#### `SafeChainMapContext`
A context implementation that safely chains mappings.

#### `Component`
Base class for template components.

Methods:
- `render(context: dict | None = None, **kwargs)`
- `arender(context: dict | None = None, **kwargs)`

#### `AutoNaming`
Helper class for automatically generating names.

### Functions
#### `split_template_tokens`
Splits a template string into tokens.

#### `var_name_checker`
Checks the validity of a variable name.

#### `is_message_start`
Checks if a string marks the beginning of a chat message.

#### `P`
Placeholder for template variables.

#### `T`
Placeholder for template sections.

#### `is_not_valid`
Checks if a template is invalid.

#### `ensure_valid`
Ensures a template is valid.

#### `cache_once`
A decorator for caching function results once.

#### `get_builtins`
Retrieves built-in template functions and variables.

#### `version`
Returns the Promplate version.

#### `get_user_agent`
Gets the user agent string.

#### `add_linecache`
Adds a line to the line cache.

#### `save_tempfile`
Saves content to a temporary file.
```

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

### Get Compiled Python Script

Source: https://docs.py.promplate.dev/references/prompt

Retrieves the compiled Python script for the template. This method first ensures the template is compiled using the `compile` method and then returns the script as a string, optionally with custom indentation.

```python
def get_script(self, sync=True, indent_str="    "):
    """compile template string into python script"""
    self.compile(sync, indent_str)
    return str(self._builder)
```

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

### Templite Initialization

Source: https://docs.py.promplate.dev/references/prompt

Constructs a Templite instance with the provided text content.

```APIDOC
## __init__ __init__(text: str)

### Description
Construct a Templite with the given `text`.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (str) - The template string to be used for constructing the Templite.

### Request Example
None

### Response
None

#### Success Response (200)
None

#### Response Example
None
```

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

### CodeBuilder: Get Render Function

Source: https://docs.py.promplate.dev/references/prompt

Executes the generated Python source code and returns the 'render' function defined within it. It asserts that the indentation level is zero before execution, ensuring the code is not improperly nested.

```python
def get_render_function(self) -> FunctionType:
    """Execute the code, and return a dict of globals it defines."""
    assert self.indent_level == 0
    python_source = str(self)
    global_namespace = {}
    exec(python_source, global_namespace)
    return global_namespace["render"]
```

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

### Creating Chat Prompts (Python - verbose)

Source: https://docs.py.promplate.dev/index

Shows how to construct chat message lists using the `user`, `assistant`, and `system` objects from `promplate.prompt.chat`. This allows for programmatic creation of messages with roles and content, including user-specific names.

```python
from promplate.prompt.chat import user, assistant, system

# Simple messages
user > "hello"
assistant > "hi"

# Messages with names and system prompts
[system > "...", user @ "example_user" > "hi"]

```

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

### Fetching Templates from HTTP URLs (Python)

Source: https://docs.py.promplate.dev/index

Demonstrates fetching templates from remote HTTP URLs using `Template.fetch` (synchronous) and `Template.afetch` (asynchronous). Similar to file reading, the template name is based on the filename.

```python
from promplate import Template

foo = Template.fetch("https://your-domain.com/path/to/some-template.j2")  // synchronous
bar = await Template.afetch("https://your-domain.com/path/to/some-prompt.md")  // asynchronous

print(foo)
print(bar)

```

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

### TemplateCore Initialization and Compilation (Python)

Source: https://docs.py.promplate.dev/references/prompt

Initializes the TemplateCore with template text and compiles it into Python code. The compilation process involves iterating through tokens, handling different types (literal, eval, exec, special), and building the renderable code.

```python
from promplate.prompt.template import TemplateCore

# Example usage:

# Create a TemplateCore instance
template_text = "Hello, {{ name }}!\nYour age is {{ age }}."
templater = TemplateCore(template_text)

# Compile the template
# sync=True means synchronous rendering, indent_str specifies the indentation character
compiled_code = templater.compile(sync=True, indent_str="\t")

# The compiled_code is not directly returned by compile(), but the internal
# _render_code property holds the compiled function. To execute it, you would
# typically use a render method (not shown in this snippet).

# To see the generated code (for demonstration purposes):
# print(templater._builder.get_code())

# Example of a more complex template with control flow:
template_text_complex = "{% for item in items %}- {{ item }}\n{% endfor %}"
templater_complex = TemplateCore(template_text_complex)
# compiled_code_complex = templater_complex.compile()
# print(templater_complex._builder.get_code())

```

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

### On Enter Node

Source: https://docs.py.promplate.dev/references/chain

Callback function executed upon entering a node in the chain. Returns the updated context and config.

```APIDOC
## `on_enter` Callback

### Description
Callback function executed upon entering a node in the chain. Returns the updated context and config.

### Method
on_enter

### Endpoint
N/A (Method within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **node** (Interruptible) - The node being entered.
- **context** (Context | None) - The current context.
- **config** (Context) - The current configuration.

### Request Example
```json
{
  "node": null, 
  "context": {},
  "config": {}
}
```

### Response
#### Success Response (200)
- **context** (Context | None) - The potentially updated context.
- **config** (Context) - The potentially updated configuration.

#### Response Example
```json
{
  "context": {},
  "config": {}
}
```
```

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

### Asynchronously Fetch Template from URL (Python)

Source: https://docs.py.promplate.dev/references/prompt

The `afetch` classmethod in the `Loader` class asynchronously fetches template content from a URL. It uses an asynchronous HTTP client to make the request. The method returns an instance of the Loader class, named after the URL's stem, after successfully fetching and parsing the content.

```python
@classmethod
async def afetch(cls, url: str, **kwargs):
    from .utils import _get_aclient

    response = await _get_aclient().get(cls._join_url(url), **cls._patch_kwargs(kwargs))
    obj = cls(response.raise_for_status().text)
    obj.name = Path(url).stem
    return obj
```

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

### Callback Initialization

Source: https://docs.py.promplate.dev/references/chain

Initializes a callback handler with optional pre-processing, mid-processing, end-processing, on_enter, and on_leave functions.

```APIDOC
## `__init__` Callback

### Description
Initializes a callback handler with optional pre-processing, mid-processing, end-processing, on_enter, and on_leave functions.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pre_process** (Process | AsyncProcess | None) - Optional - A function to process the context before the main chain.
- **mid_process** (Process | AsyncProcess | None) - Optional - A function to process the context during the main chain.
- **end_process** (Process | AsyncProcess | None) - Optional - A function to process the context after the main chain.
- **on_enter** (Callable[[Interruptible, Context | None, Context], tuple[Context | None, Context]] | None) - Optional - A callback function executed upon entering a node.
- **on_leave** (Callable[[Interruptible, ChainContext, Context], tuple[ChainContext, Context]] | None) - Optional - A callback function executed upon leaving a node.

### Request Example
```json
{
  "pre_process": null,
  "mid_process": null,
  "end_process": null,
  "on_enter": null,
  "on_leave": null
}
```

### Response
#### Success Response (200)
None (Constructor)

#### Response Example
None
```

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

### Node Class Initialization and Rendering

Source: https://docs.py.promplate.dev/references/chain

The Node class serves as a fundamental building block for chains, handling template rendering and execution logic. Its constructor initializes the template, partial context, LLM, and configuration. It includes methods for synchronous and asynchronous rendering, invocation, and streaming.

```python
class Node(Loader, Interruptible):
    def __init__(
        self, 
        template: Template | str,
        partial_context: Context | None = None,
        llm: LLM | None = None,
        **config,
    ):
        self.template = Template(template) if isinstance(template, str) else template
        self._context = partial_context
        self.callbacks: list[BaseCallback | type[BaseCallback]] = []
        self.llm = llm
        self.run_config = config
```

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

### Initialize Callback Chain with Processes and Callbacks

Source: https://docs.py.promplate.dev/references/chain

Initializes a callback handler for a chain, accepting optional pre-processing, mid-processing, and end-processing steps, along with on_enter and on_leave callbacks.

```python
def __init__(
    self,
    *,
    pre_process: "Process | AsyncProcess | None" = None,
    mid_process: "Process | AsyncProcess | None" = None,
    end_process: "Process | AsyncProcess | None" = None,
    on_enter: Callable[["Interruptible", Context | None, Context], tuple[Context | None, Context]] | None = None,
    on_leave: Callable[["Interruptible", "ChainContext", Context], tuple["ChainContext", Context]] | None = None,
):
    self._pre_process = pre_process
    self._mid_process = mid_process
    self._end_process = end_process
    self._on_enter = on_enter
    self._on_leave = on_leave

```

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

### Asynchronously Render PromptTemplate in Python

Source: https://docs.py.promplate.dev/references/prompt

Asynchronously renders the prompt template with the provided context. Similar to `render`, it uses SafeChainMapContext for context management.

```python
async def arender(self, context: Context | None = None):
    if context is None:
        context = SafeChainMapContext({}, self.context)
    else:
        context = SafeChainMapContext({}, context, self.context)

    return await super().arender(context)
```

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

### Template Class - __init__ Method

Source: https://docs.py.promplate.dev/references

Initializes a `Template` object. It takes a template string and an optional context. The template string can contain placeholders for dynamic content.

```python
__init__(self, template: str, context: Context | None = None)
```

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

### Render PromptTemplate in Python

Source: https://docs.py.promplate.dev/references/prompt

Renders the prompt template with the provided context. If no context is given, it uses the internal context. It ensures a SafeChainMapContext is used for rendering.

```python
def render(self, context: Context | None = None):
    if context is None:
        context = SafeChainMapContext({}, self.context)
    else:
        context = SafeChainMapContext({}, context, self.context)

    return super().render(context)
```

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

### OpenAI v1 Client: Config bind Method

Source: https://docs.py.promplate.dev/references/llm

The bind method creates a copy of the current configuration object and merges new run-specific configurations into it. This allows for temporary adjustments to client behavior without modifying the original configuration.

```python
def bind(self, **run_config):
    obj = copy(self)
    obj._run_config = self._run_config | run_config
    return obj
```

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

### Generate User Agent String in Python

Source: https://docs.py.promplate.dev/references/prompt

Constructs a user agent string including Promplate version, package name, optional additional packages, httpx version, and Python version. It utilizes cached version lookups.

```python
@cache_once
def get_user_agent(self, *additional_packages: tuple[str, str]):
    from sys import version as py_version

    return " ".join(
        (
            f"Promplate/{version('promplate')} ({self.__name__ if isinstance(self, type) else self.__class__.__name__})",
            *(f"{name}/{v}" for name, v in additional_packages),
            f"HTTPX/{version('httpx') or '-'}",
            f"Python/{py_version.split()[0]}",
        )
    )
```

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

### Handle Entry into a Chain Node

Source: https://docs.py.promplate.dev/references/chain

Handles actions to be performed upon entering a node in the chain. It executes the on_enter callback if provided, otherwise returns the original context and config.

```python
def on_enter(self, node, context, config):
    if self._on_enter is not None:
        return self._on_enter(node, context, config)
    return context, config

```

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

### Callback Class - __init__ Method

Source: https://docs.py.promplate.dev/references

Initializes a `Callback` object, allowing customization of pre-process, mid-process, end-process, on_enter, and on_leave hooks. Accepts callable functions or asynchronous functions for these hooks.

```python
__init__(*, pre_process: Process | AsyncProcess | None = None, mid_process: Process | AsyncProcess | None = None, end_process: Process | AsyncProcess | None = None, on_enter: Callable[[Interruptible, Context | None, Context], tuple[Context | None, Context]] | None = None, on_leave: Callable[[Interruptible, ChainContext, Context], tuple[ChainContext, Context]] | None = None)
```

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

### get_base_builder Function

Source: https://docs.py.promplate.dev/references/prompt

Initializes and returns a CodeBuilder instance for constructing prompts, with options for synchronous or asynchronous rendering and custom indentation.

```APIDOC
## get_base_builder

### Description
Initializes a `CodeBuilder` instance for constructing prompts. It allows for specifying whether the rendering should be synchronous or asynchronous, and defines the string used for indentation.

### Method
`get_base_builder(sync: bool = True, indent_str: str = '\t')`

### Parameters
#### Keyword Arguments
- **sync** (bool) - Optional - If True, generates a synchronous `render` function; otherwise, generates an asynchronous `render` function. Defaults to True.
- **indent_str** (str) - Optional - The string to use for indentation within the generated code. Defaults to a tab character (`\t`).

### Returns
- `CodeBuilder` - An instance of `CodeBuilder` pre-configured with initial lines for a render function.

### Usage Example
```python
# For synchronous rendering
builder_sync = get_base_builder(sync=True, indent_str='    ')

# For asynchronous rendering
builder_async = get_base_builder(sync=False, indent_str='\t')
```
```

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

### Chain Class - __init__ Method

Source: https://docs.py.promplate.dev/references

Initializes a `Chain` object with a sequence of nodes and an optional partial context. The chain orchestrates the execution of these nodes.

```python
__init__(*nodes: AbstractNode, partial_context: Context | None = None)
```

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

### Node Class - __init__ Method

Source: https://docs.py.promplate.dev/references

Initializes a `Node` object, which represents a single step in a chain. It requires a template and can optionally be configured with callbacks, an LLM, and run-specific configurations.

```python
__init__(self, template: Template, callbacks: list[BaseCallback] | None = None, llm: LLM | None = None, run_config: dict[str, Any] | None = None)
```

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

### Synchronous Text Generation with Streaming (__call__)

Source: https://docs.py.promplate.dev/references/llm

Generates text synchronously using the OpenAI client with streaming enabled. It takes a text prompt and configuration, sends it to the completions endpoint, and yields generated text chunks as they arrive. It includes error handling for potential issues during streaming.

```python
class TextGenerate(ClientConfig):
    def __call__(self, text: str, /, **config):
        config = self._run_config | config | {"prompt": text}
        stream = self._client.completions.create(**config, stream=True)
        for event in stream:
            with suppress(AttributeError, IndexError):
                yield event.choices[0].text
```

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

### AsyncTextOpenAI API

Source: https://docs.py.promplate.dev/references/llm

Offers asynchronous text completion and generation through OpenAI's API. It allows for non-blocking text-based AI interactions.

```APIDOC
## POST /v1/completions (AsyncTextOpenAI)

### Description
Offers asynchronous text completion and generation through OpenAI's API. It allows for non-blocking text-based AI interactions.

### Method
POST

### Endpoint
/v1/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **prompt** (str) - Required - The prompt to generate text from.
- **config** (dict) - Optional - Additional configuration for the completion.

### Request Example
```json
{
  "prompt": "The quick brown fox...",
  "max_tokens": 30
}
```

### Response
#### Success Response (200)
- **completion** (str) - The asynchronously generated text completion.

#### Response Example
```json
{
  "completion": " jumps over the lazy dog."
}
```
```

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

### Callback Management

Source: https://docs.py.promplate.dev/references/chain

Details on how to use and implement callbacks within the Promplate chain. This includes base callback functionality and custom callback implementations.

```APIDOC
## Callback Management

This section describes the callback system in Promplate chains, allowing for custom logic to be executed at different stages of the chain's lifecycle.

### `promplate.chain.callback.BaseCallback`

**Description**: Abstract base class for defining callback behavior.

**Methods**:
- `pre_process()`: Hook executed before processing a node.
- `mid_process()`: Hook executed during the middle of node processing.
- `end_process()`: Hook executed after a node has finished processing.
- `on_enter()`: Hook executed when entering a node's execution context.
- `on_leave()`: Hook executed when leaving a node's execution context.

### `promplate.chain.callback.Callback`

**Description**: A concrete implementation of a callback that can be used or subclassed.

**Methods**:
- `__init__()`: Initializes the callback.
- `pre_process()`: Custom logic before node processing.
- `mid_process()`: Custom logic during node processing.
- `end_process()`: Custom logic after node processing.
- `on_enter()`: Custom logic upon entering a node.
- `on_leave()`: Custom logic upon leaving a node.

### `promplate.chain.callback.ensure_callbacks`

**Description**: Utility function to ensure a list of callbacks is properly formatted or initialized.
```

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

### CodeBuilder: Initialize CodeBuilder

Source: https://docs.py.promplate.dev/references/prompt

Initializes a CodeBuilder instance to construct source code. It takes an optional indent_level and indent_str to control indentation. The instance stores code lines and indentation settings.

```python
class CodeBuilder:
    """Build source code conveniently."""

    def __init__(self, indent_level=0, indent_str="\t"):
        self.code = []
        self.indent_level = indent_level
        self.indent_str = indent_str
```

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

### OpenAI v1 TextComplete Synchronous Completion

Source: https://docs.py.promplate.dev/references/llm

The `TextComplete` class in `promplate.llm.openai.v1` provides synchronous text completion using the OpenAI API. It takes a string prompt and optional configuration, returning the generated text as a single string. This is suitable for use cases where streaming is not required.

```python
class TextComplete(ClientConfig):
    def __call__(self, text: str, /, **config):
        config = self._run_config | config | {"prompt": text}
        result = self._client.completions.create(**config, stream=False)
        return result.choices[0].text

```

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

### Pre-process Input with Node (Python)

Source: https://docs.py.promplate.dev/references/chain

Processes the input using a specified process before the main execution. This method takes a Process or AsyncProcess and adds it using the internal add_pre_processes method, returning the processed input.

```python
def pre_process(self, process: Process | AsyncProcess):
    self.add_pre_processes(process)
    return process
```

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

### Utility Functions

Source: https://docs.py.promplate.dev/references/chain

Helper functions for Promplate chains, including type hinting, string manipulation, and asynchronous accumulation.

```APIDOC
## Utility Functions

This section lists utility functions provided within the `promplate.chain.utils` module for common operations.

### `promplate.chain.utils.T`

**Description**: Likely a type alias or generic type hint for template-related types.

### `promplate.chain.utils.appender`

**Description**: A utility function for appending elements, potentially to strings or lists within the chain context.

### `promplate.chain.utils.is_positional_parameter`

**Description**: Checks if a given parameter is a positional parameter.

### `promplate.chain.utils.count_position_parameters`

**Description**: Counts the number of positional parameters in a function or callable.

### `promplate.chain.utils.resolve`

**Description**: Resolves a value, possibly looking it up in a context or applying transformations.

### `promplate.chain.utils.async_accumulate`

**Description**: Asynchronously accumulates results from multiple asynchronous operations.

### `promplate.chain.utils.accumulate_any`

**Description**: Accumulates results from various sources, potentially handling different types or asynchronous operations.
```

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

### OpenAI v1 Client: Config Class

Source: https://docs.py.promplate.dev/references/llm

Configuration class for the OpenAI v1 client, inheriting from 'Configurable'. It initializes with provided configuration, manages run-specific configurations, and provides access to OpenAI client instances.

```python
class Config(Configurable):
    def __init__(self, **config):
        super().__init__(**config)
        self._run_config = {}

    def bind(self, **run_config):
        obj = copy(self)
        obj._run_config = self._run_config | run_config
        return obj

    @cached_property
    def _user_agent(self):
        from openai.version import VERSION

        return get_user_agent(self, ("OpenAI", VERSION))

    @property
    def _config(self):
        ua_header = {"User-Agent": self._user_agent}
        config = dict(super()._config)
        config["default_headers"] = config.get("default_headers", {}) | ua_header
        return MappingProxyType(config)

    @cached_property
    def _client(self):
        if "http_client" in self._config:
            return Client(**self._config)
        else:
            return Client(**self._config, http_client=_get_client())

    @cached_property
    def _aclient(self):
        if "http_client" in self._config:
            return AsyncClient(**self._config)
        else:
            return AsyncClient(**self._config, http_client=_get_aclient())
```

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

### Asynchronous Text Generation with Streaming (__call__)

Source: https://docs.py.promplate.dev/references/llm

Generates text asynchronously using the OpenAI client with streaming enabled. It takes a text prompt and configuration, sends it to the completions endpoint asynchronously, and yields generated text chunks as they arrive. It utilizes async for loops and includes error handling.

```python
class AsyncTextGenerate(AsyncClientConfig):
    async def __call__(self, text: str, /, **config):
        config = self._run_config | config | {"prompt": text}
        stream = await self._aclient.completions.create(**config, stream=True)
        async for event in stream:
            with suppress(AttributeError, IndexError):
                yield event.choices[0].text
```

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

### Node Class - render Method

Source: https://docs.py.promplate.dev/references

Synchronously renders the template associated with the node, using the provided context and configuration. Returns the rendered output.

```python
render(context: Context, **kwargs: Any) -> str
```

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

### Asynchronous Text Completion (__call__)

Source: https://docs.py.promplate.dev/references/llm

Performs asynchronous text completion using the OpenAI client. It takes a text prompt and configuration, sends it to the completions endpoint asynchronously, and returns the generated text. Streaming is disabled.

```python
class AsyncTextComplete(AsyncClientConfig):
    async def __call__(self, text: str, /, **config):
        config = self._run_config | config | {"prompt": text}
        result = await self._aclient.completions.create(**config, stream=False)
        return result.choices[0].text
```

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

### OpenAI v0 AsyncTextComplete __call__ Method

Source: https://docs.py.promplate.dev/references/llm

Asynchronously completes the given text using the OpenAI API. It merges internal configuration with provided parameters and calls the Completion.acreate method. Returns the first choice's text content.

```python
async def __call__(self, text: str, /, **config):
    config = self._config | config | {"stream": False, "prompt": text}
    result: Any = await Completion.acreate(**config)
    return result["choices"][0]["text"]
```

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

### ChainContext __init__ method

Source: https://docs.py.promplate.dev/references/chain

Initializes the ChainContext, optionally taking a least-recently-used mapping or other mappings to seed the context. It ensures proper initialization of the underlying context management system.

```python
from typing import MutableMapping, Mapping

def __init__(self, least: MutableMapping | None = None, *maps: Mapping):
    super().__init__({} if least is None else least, *maps)  # type: ignore

```

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

### Synchronous Text Completion (__call__)

Source: https://docs.py.promplate.dev/references/llm

Performs synchronous text completion using the OpenAI client. It takes a text prompt and configuration, sends it to the completions endpoint, and returns the generated text. It ensures streaming is disabled for a single response.

```python
class TextComplete(ClientConfig):
    def __call__(self, text: str, /, **config):
        config = self._run_config | config | {"prompt": text}
        result = self._client.completions.create(**config, stream=False)
        return result.choices[0].text
```

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

### promplate.llm.base.Complete Protocol

Source: https://docs.py.promplate.dev/references/llm

Defines the interface for synchronous text completion. Any class implementing this protocol must provide a `__call__` method that accepts a prompt and configuration, returning a single string.

```APIDOC
## promplate.llm.base.Complete

### Description
Defines the interface for synchronous text completion. Any class implementing this protocol must provide a `__call__` method that accepts a prompt and configuration, returning a single string.

### Protocol
`class Complete(Protocol)`

### Methods
#### `__call__`
```
__call__(prompt, /, **config) -> str
```
Performs synchronous text completion for the given prompt and configuration.
```

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

### Configurable __init__ Method in Python

Source: https://docs.py.promplate.dev/references/llm

The initializer for the Configurable class. It iterates through keyword arguments and sets them as instance attributes.

```python
def __init__(self, **config):
    for key, val in config.items():
        setattr(self, key, val)

```

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

### Initialize Templite Instance

Source: https://docs.py.promplate.dev/references/prompt

Constructs a Templite instance with the provided text. It initializes the instance attributes, including the text content to be processed.

```python
def __init__(self, text: str):
    """Construct a Templite with the given `text`. """

    self.text = text
```

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

### Mid-process Input with Node (Python)

Source: https://docs.py.promplate.dev/references/chain

Applies a mid-processing step to the input. It takes a Process or AsyncProcess and adds it via the internal add_mid_processes method, returning the modified input.

```python
def mid_process(self, process: Process | AsyncProcess):
    self.add_mid_processes(process)
    return process
```

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

### Promplate LLM Base: __init__ Method

Source: https://docs.py.promplate.dev/references/llm

Initializes the base LLM object with configuration parameters. It iterates through provided key-value pairs in the config dictionary and sets them as attributes of the object.

```python
def __init__(self, **config):
    for key, val in config.items():
        setattr(self, key, val)
```
Tokens:
Raw