Ctrl+K

JSON

JSON#

Many LLMs and LLM providers support guided generation of JSON. Langworks provides various utilities to help generate and process JSON. They may be accessed through the langworks.util.json module.

langworks.util.json.cast_json_as_cls(json: dict[str, Any], cls: DataclassType | TypedDictType, on_redundancies: Literal['ignore', 'warn', 'raise'] = 'warn', on_missing: Literal['ignore', 'warn', 'raise'] = 'raise')#

Convert a JSON-like dictionary to an instance of the given :py:deco:`dataclasses.dataclass` or typing.TypedDict subclass, adhering to type hints included in this class, converting any properties and fields to the appropriate types (including nested dataclasses or TypedDict subclasses).

Parameters#

json

JSON-like dictionary to convert.

cls

Dataclass or TypedDict subclass to convert to.

on_redundancies

How to handle any potential redundancies included in the passed JSON object, either emitting a warning (warn), raising an error (raise), or ignoring the redundancy (ignore).

on_missing

How to handle missing data in the passed JSON object, either emitting a warning (warn), raising an error (raise), or ignoring the missing key (ignore).

langworks.util.json.json_schema_from_cls(schema: DataclassType | TypedDictType, indent: str = 2, use_refs: bool = False) → str#

Generates from a :py:deco:`dataclasses.dataclass` or typing.TypedDict subclass a string-based JSON schema compliant with the standard governed by The JSON Schema Organization. If a dictionary is desired, use json_dict_schema_from_cls() instead.

Parameters#

schema

The dataclass or TypedDict subclass from which to generate the schema. Attributes may have any of the following types:

  • Boolean

  • Numeric (int, float, or complex)

  • String

  • Literal

  • Regular expressions (re.Pattern[...])

  • None (type[None])

  • List

  • TypedDict subclass

When wrapped by annotation types like Required or NotRequired, these requirements are also included in the schema generated.

indent

The number of whitespaces to use per level when formatting the scheme.

use_refs

Flag that controls whether or not nested TypedDict objects are included directly or through references, the latter allowing for recursive definitions.

langworks.util.json.json_dict_schema_from_cls(schema: DataclassType | TypedDictType, use_refs: bool = False) → dict#

Generates from a :py:deco:`dataclasses.dataclass` or typing.TypedDict subclass a JSON schema compliant with the standard governed by The JSON Schema Organization, represented as a Python dictionary. If a string-based representation is desired, use json_schema_from_cls() instead.

Parameters#

schema

The dataclass or TypedDict subclass from which to generate the schema. Attributes may have any of the following types:

  • Boolean

  • Numeric (int, float, or complex)

  • String

  • Literal

  • Regular expressions (re.Pattern[...])

  • None (type[None])

  • List

  • TypedDict subclass

When wrapped by annotation types like Required or NotRequired, these requirements are also included in the schema generated.

use_refs

Flag that controls whether or not nested TypedDict objects are included directly or through references, the latter allowing for recursive definitions.

langworks.util.json.json_shorthand_schema_from_cls(schema: DataclassType | TypedDictType, indent: str = 2) → str#

Generates a shorthand JSON schema from a :py:deco:`dataclasses.dataclass` or typing.TypedDict subclass

Note

Shorthand JSON schemas are not compliant with JSON Schema as defined by the The JSON Schema Organization. Shorthand JSON schemas only serve to succinctly instruct LLMs when requesting these LLMs to output JSON. If you wish to generate compliant schema, look at json_schema_from_cls().

Parameters#

schema

The TypedDict subclass from which to generate the schema. Attributes may have any of the following types:

  • Boolean

  • Numeric (int, float, complex)

  • String

  • Literal

  • Regular expressions (re.Pattern[...])

  • None (passed as type[None])

  • List

  • TypedDict subclass

Optionally, attributes may also be annotated using typing.Annotated. When these annotations include an typing_extensions.Doc object, their contents will be treated as docstrings to include in the schema alongside the attributes. These docstrings may be further enhanced through the use of typing.NotRequired annotations. For example:

class Item(TypedDict):
    value : Annotated[str, Doc("A wrapped value")]
    index : NotRequired[int]

json_shorthand_schema_from_dict(Item) == """{
  "value": "string", // A wrapped value
  "index": "number" // (optional) 
}"""
indent

The number of whitespaces to use per level when formatting the scheme.

Contents