Version 0.7.0

New Features

The main new features are the following and are detailed bellow:

• new retry attribute to any block,
• new index field to introduce a loop index in repeat blocks
• new syntax for types with suport for JSON Schema,
• extract the signature of a function f with f.signature,
• loop and sequences with independent contexts,
• support for granite-io processors created in Python.

The retry field

Any block can now have a retry field indicating how many times a block should be executed if it encounters a runtime error. For example, a model call can be retried 5 times as follows:

model: replicate/ibm-granite/granite-3.3-8b-instruct
input: How to program "Hello World!"?
retry: 5

The loop index field

A common pattern in PDL programs is to introduce a variable to index the loop iterations. For example, a loop that turns a list of strings into a list of object with a field name and id would be written as follows:

defs:
  id: -1
for:
  name: [ "Alice", "Nicolas", "Rosa", "Remi" ]
repeat:
  defs:
    id: ${ id + 1}
  data:
    name: ${name}
    id: ${id}
join:
  as: array

With the new index field that introduced a variable name as loop index, this code can now be simplified as follows:

for:
  name: [ "Alice", "Nicolas", "Rosa", "Remi" ]
index: id
repeat:
  data:
    name: ${name}
    id: ${id}
join:
  as: array

New type syntax

We extended the type syntax to be able to write directly some JSON Schema as block specification. To do so, the type must contain the type or enum field. For example, we can write a model block that checks that the output starts with the letter "A" as follows:

model: ollama/granite3.3:2b
input: Generate a word that starts with the letter "A". Just output the single word.
spec:
  type: string
  pattern: "^[Aa]"

To make the syntax more uniform, we are using the JSON Schema syntax for the base type. So for example, we are using number instead of float for floating point numbers. We discuss the breaking changes below.

Extract function signature

In order to make the use of PDL functions as tools by LLMs easier, we provide the ability to extract the signature of a function f by executing f.signature. Here is an example:

defs:
  calc:
    description: Calculator function
    function:
      expr:
        type: string
        description: Arithmetic expression to calculate
    return:
      lang: python
      code: result = ${ expr }
text: ${ calc.signature }

The output is:

{"type": "function", "name": "calc", "description": "Calculator function", "parameters": {"type": "object", "properties": {"expr": {"type": "string", "description": "Arithmetic expression to calculate"}}, "required": ["expr"], "additionalProperties": false}}

An example of tool use is given in search.pdl.

Independent contexts

Blocks containing lists of blocks (text, array, object, and lastOf) as well as loops can now be annotated with context: independent. It means that each sub-block is executed in an independent copy of the context. Therefore, if we execute the following program, both model calls are executed with the same input containing the message Hello:

lastOf:
- Hello
- context: independent
  array:
  - model: ollama/granite3.2:2b
  - model: ollama/granite3.3:2b

Support for granite-io processors objects

In addition to the ability to call granite-io processors using the lookup mechanism using backend and processors names, it is possible now to use granite-io processors or backends created in Python. Here is an example:

defs:
  io_proc:
    lang: python
    code: |
      from granite_io import make_backend, make_io_processor
      model_name = "granite3.2:2b"
      backend = make_backend("openai", { "model_name": model_name })
      result = make_io_processor(model_name, backend=backend)
processor: ${ io_proc }
input: Write an Hello World program in Python.

Breaking Changes

This version of PDL is coming with a large number of breaking changes:

• types syntax,
• granite-io syntax,
• rename max_iterations into maxIterations,
• trace format.

Types syntax

As mentioned above, to be consistent with JSON Schema, we renamed the basic types as follows:

• str -> string
• bool -> boolean
• int -> integer
• float -> number
• obj -> object
• list -> array

Moreover, since we can use JSON schema, we removed the old way to put constraints on types. So for example, the following type:

spec: { int: { minimum: 0 } }

must be rewritten:

spec: { type: integer, minimum: 0 }

Finally, the type null now corresponds to a value of any type. For example, the identity function can be written as follows:

function:
  x:
return: ${ x }

Granite-io processors

The structure of the granite-io block changed. Now, the processor field is required and the definition of io-processor is given has sub-fields of this field. So a block that was defined as follows:

processor: 
model: "granite3.2:2b"
backend: openai
input: Hello

is now defined like this:

processor: 
    type: Granite 3.2
    model: "granite3.2:2b"
    backend: openai
input: Hello

Loop iteration bound

The syntax to bound the number of iterations of a loop changed. It is now maxIteration. Here is an example

index: i
repeat: ${ i }
maxIterations: 3

Trace format

The format of the traces generated with the --trace (-t) option has changed. Some internal fields like defsite have changed to pdl__defsite. It means that traces generated with old version of the interpreter are not compatible with the new version of the UI.

What's Changed

• Fix rag example by fully qualifying import by @esnible in #930
• Change to sys.path for python code block by @vazirim in #931
• granite-io hallucination demo example and notebook by @vazirim in #932
• Add contrib. prompt library by @claudiosv in #927
• Fixed the bug where pdl.version was not set by @vite-falcon in #882
• Use granite-io async interface by @mandel in #936
• chore: bump ui dependences by @starpit in #939
• independent implementation by @vazirim in #934
• feat: add a parse_dict function to pdl_parser by @mandel in #943
• feat: specify PDL types in the AST by @mandel in #942
• PDL Optimizer by @claudiosv in #941
• Add a new retry feature to block by @hirokuni-kitahara in #824
• feat: extend PDL types with json schema types by @mandel in #947
• feat: add a signature field to closures containing the function signature by @mandel in #948
• feat: add index field to repeat blocks to name loop index by @mandel in #950
• Fix for extra fields in messages sent to LLMs by @vazirim in #952
• dependent/independent context implementation by @vazirim in #945
• docs: add example of f.signature by @mandel in #955
• fix: remove defsite from messages in model inputs by @mandel in #956
• Introducing Run Examples check in PRs by @jgchn in #908
• Capturing new results for Run Examples by @jgchn in #957
• fix: ensure that model inputs are always contexts by @mandel in #958
• feat: change type syntax by @mandel in #951
• feat: rename max_iterations into maxIterations by @mandel in #961
• fix: unable to set OPENAI_API_BASE for litellm by @starpit in #962
• docs: AST documentation by @mandel in #963
• refactor: rename internal field returns into return_ by @mandel in #964
• feat: export write_trace in pdl.pdl by @mandel in #966
• chore: remove dependency on termcolor types by @mandel in #967
• fix: trace generation with context by @mandel in #968
• chore(deps): Update termcolor requirement from ~=2.0 to >=2,<4 by @mandel in #971
• refactor: make the use of dependent and independent context explicit by @mandel in #972
• feat: all to pass directly backend or processor objects to granite-io blocks by @mandel in #973
• fix: typing of pdl_context in notebook extension and ast by @mandel in #974
• refactor: change granite-io block syntax by @mandel in #975
• Add a new model to ollama action requirement and update config file by @jgchn in #959
• feat: add support for deprecated type syntax by @mandel in #977
• fix: import should yield the result in streaming mode by @mandel in #979
• refactor: rename message field defsite into pdl__defsite by @mandel in #965
• refactor: AST and UI cleanup by @mandel in #984
• tests: disable non-deterministic granite-io tests by @mandel in #983
• fix: handling of processor type in granite-io by @mandel in #986
• fix: improve dumping and UI for functions by @mandel in #988
• docs: link the tutorial to the code by @mandel in #987

New Contributors

• @hirokuni-kitahara made their first contribution in #824

Full Changelog: v0.6.1...v0.7.0