基础数据类#

一个基类，为数据与LLMs的交互提供了一种简便的方式。

函数

`check_adal_dataclass`(data_class)	检查提供的类是否为AdalFlow框架的有效数据类。
`required_field`()	一个工厂函数，用于在数据类中创建一个必填字段。

类

`DataClass`()	与LLMs交互的所有数据类型的基础数据类。
`DataClassFormatType`(value[, names, module, ...])	DataClass 模式的格式类型。
`DynamicDataClassFactory`()

常量

ExcludeType#: List[str] 的别名 | Dict[str, List[str]] | None

IncludeType#: List[str] 的别名 | Dict[str, List[str]] | None

class DataClass[source]#

基础类：object

与LLMs交互的所有数据类型的基础数据类。

请仅在排除字典中排除可选字段。

旨在简化我们应用程序中数据的处理、序列化和描述，特别是针对LLM提示。我们明确处理这一点，而不是依赖第三方库如pydantic或marshmallow，以获得更好的透明度，并在序列化时保持字段的顺序。

如何创建你自己的数据类？

子类化 DataClass 并使用 field 装饰器定义字段。
使用 medata 参数和 desc 键来描述字段。
保持字段的顺序，以便您希望它们如何被序列化并描述给LLMs。
具有默认值的字段被视为可选。没有默认值的字段和具有 default_factory=required_field 的字段被视为必填。

如何使用它？

描述：

我们定义了DataClassFormatType来将DataClass描述格式分类为LLM提示中的输入或输出。

用于描述类（数据结构）：

Signature 比 schema 更节省 token，因为 schema 始终是一个 json 字符串，当你希望 LLMs 输出 yaml 时，如果你用 json 描述数据结构，可能会产生误导。

DataClassFormatType.SCHEMA: 一种更标准的方式来描述Json字符串中的数据结构，to_schema() 作为字符串和 to_schema() 作为字典。
DataClassFormatType.SIGNATURE_JSON: 模拟一个json对象，字段名作为键，描述作为值，to_json_signature() 作为字符串。
DataClassFormatType.SIGNATURE_YAML: 模拟一个yaml对象，字段名作为键，描述作为值，to_yaml_signature() 作为字符串。

(2) 用于描述类实例：这对于在LLM提示中进行少量示例很有帮助。 - DataClassFormatType.EXAMPLE_JSON: 实例的json表示，to_json() 作为字符串。 - DataClassFormatType.EXAMPLE_YAML: 实例的yaml表示，to_yaml() 作为字符串。

总的来说，我们有一个统一的类方法 format_str() 来根据操作类型和类/实例上下文生成格式化输出。

note::

避免使用 Optional[Type] 作为字段的类型，因为 dataclass 已经通过默认值区分了可选和必填字段。
如果需要自定义，可以创建子类并覆盖任何方法以满足您的需求。

加载数据：

from_dict() 用于从字典创建数据类实例。

请参考DataClass获取更详细的说明。

示例：

# Define a dataclass
from adalflow.core import DataClass
from dataclasses import dataclass, field

@dataclass
class MyOutputs(DataClass):
    age: int = field(metadata={"desc": "The age of the person", "prefix": "Age:"})
    name: str = field(metadata={"desc": "The name of the person", "prefix": "Name:"})

# Create json signature
print(MyOutputs.to_json_signature())
# Output:
# {
#     "age": "The age of the person",
#     "name": "The name of the person"
# }
# Create yaml signature
print(MyOutputs.to_yaml_signature())
# Output:
# age: The age of the person
# name: The name of the person

# Create a dataclass instance
my_instance = MyOutputs(age=25, name="John Doe")
# Create json example
print(my_instance.to_json_example())
# Output:
# {
#     "age": 25,
#     "name": "John Doe"
# }
# Create yaml signature
print(my_instance.to_yaml_example())
# Output:
# age: 25
# name: John Doe

classmethod get_task_desc() → str[source]#

获取数据类的任务描述。

Returns:: 数据类的任务描述。
Return type:: 字符串

classmethod set_task_desc(task_desc: str) → None[source]#

为数据类设置任务描述。

Parameters:: task_desc (str) – 要设置的任务描述。

classmethod get_input_fields()[source]#: 返回所有输入字段的列表。

classmethod set_input_fields(input_fields: List[str])[source]#

Set the input fields for the dataclass.: 在创建模式或实例时，它将遵循输入字段和输出字段的顺序

Parameters:: input_fields (List[str]) – 要设置的输入字段。

classmethod get_output_fields()[source]#: 返回所有输出字段的列表。

classmethod set_output_fields(output_fields: List[str])[source]#

Set the output fields for the dataclass.: 在创建模式或实例时，它将遵循输入字段和输出字段的顺序

Parameters:: output_fields (List[str]) – 要设置的输出字段。

to_dict(*, exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → Dict[str, Any][source]#

将数据类对象转换为字典。

支持嵌套的数据类、列表和字典。允许为每个数据类对象排除键。

使用案例： - 决定将哪些信息包含在序列化为JSON或YAML中，以便用于LLM提示。 - 从序列化输出中排除敏感信息。 - 将数据类实例序列化为字典以保存状态。

Parameters:: exclude (可选[Dict[str, List[str]]], 可选) – 一个字典，用于排除每个数据类对象的字段。默认为 None。

示例：

from dataclasses import dataclass
from typing import List

@dataclass
class TrecData:
    question: str
    label: int

@dataclass
class TrecDataList(DataClass):

    data: List[TrecData]
    name: str

trec_data = TrecData(question="What is the capital of France?", label=0)
trec_data_list = TrecDataList(data=[trec_data], name="trec_data_list")

trec_data_list.to_dict(exclude={"TrecData": ["label"], "TrecDataList": ["name"]})

# Output:
# {'data': [{'question': 'What is the capital of France?'}]}

classmethod from_dict(data: Dict[str, Any]) → DataClass[source]#

从字典创建一个数据类实例。

支持嵌套的数据类、列表和字典。

来自to_dict()方法的示例。

..code-block:: python

data_dict = trec_data_list.to_dict() restored_data = TreDataList.from_dict(data_dict)

assert str(restored_data.__dict__) == str(trec_data_list.__dict__)

如果缺少任何必填字段，将会引发错误。不要使用排除了必填字段的字典。

使用案例： - 将LLM预测的json/yaml输出转换为数据类实例。 - 从用于状态保存的序列化输出中恢复数据类实例。

classmethod from_json(json_str: str) → DataClass[source]#

从JSON字符串创建一个数据类实例。

Parameters:: json_str (str) – 要转换为数据类实例的JSON字符串。

示例：

json_str = '{"question": "What is the capital of France?", "label": 0}'
trec_data = TrecData.from_json(json_str)

to_json_obj(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → Any[source]#

将数据类实例转换为JSON对象。

to_dict() 与使用 sort_keys=False 一起确保字段的顺序得以保持。这对于 llm 提示可能很重要。

参数:

exclude (Optional[Dict[str, List[str]]], optional): 一个字典，用于排除每个数据类对象的字段。默认为 None。

to_json(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

将数据类实例转换为JSON字符串。

to_dict() 与使用 sort_keys=False 一起确保字段的顺序得以保持。这对于 llm 提示可能很重要。

参数:

exclude (Optional[Dict[str, List[str]]], optional): 一个字典，用于排除每个数据类对象的字段。默认为 None。

classmethod from_yaml(yaml_str: str) → DataClass[source]#

从YAML字符串创建一个数据类实例。

Args:
yaml_str (str): 要转换为数据类实例的YAML字符串。

示例：
yaml_str = 'question: What is the capital of France?

label: 0’: trec_data = TrecData.from_yaml(yaml_str)

to_yaml_obj(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → Any[source]#

将数据类实例转换为YAML对象。

to_dict() 结合使用 sort_keys=False 以确保字段的顺序得以保持。

参数:

exclude (Optional[Dict[str, List[str]]], optional): 一个字典，用于排除每个数据类对象的字段。默认为 None。

to_yaml(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

将数据类实例转换为YAML字符串。

to_dict() 结合使用 sort_keys=False 以确保字段的顺序得以保持。

参数:

exclude (Optional[Dict[str, List[str]]], optional): 一个字典，用于排除每个数据类对象的字段。默认为 None。

dict_to_yaml(data: Dict[str, Any]) → str[source]#

将字典转换为YAML字符串。

Parameters:: data (Dict[str, Any]) – 要转换为YAML字符串的字典。
Returns:: 字典的YAML字符串表示。
Return type:: 字符串

classmethod to_schema(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → Dict[str, Dict[str, Any]][source]#: 生成一个比签名更详细的Json模式。

classmethod to_schema_str(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#: 生成一个比签名更详细的Json模式。

classmethod to_yaml_signature(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

从元数据中的描述生成类的YAML签名。

主要用于LLM提示，以描述输出数据格式。

classmethod to_json_signature(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

为类从元数据中的描述生成一个JSON `签名`(json字符串)。

主要用于LLM提示，以描述输出数据格式。

示例：

>>> @dataclass
>>> class MyOutputs(DataClass):
>>>    age: int = field(metadata={"desc": "The age of the person", "prefix": "Age:"})
>>>    name: str = field(metadata={"desc": "The name of the person", "prefix": "Name:"})

>>> print(MyOutputs.to_json_signature())
>>> # Output is a JSON string:
>>> # '{
>>> #    "age": "The age of the person (int) (required)",
>>> #    "name": "The name of the person (str) (required)"
>>> #}'

classmethod to_dict_class(exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → Dict[str, Any][source]#

更多用于内部使用的类方法进行序列化。

将数据类转换为字典，可选择排除指定字段。用于在序列化中保存类的状态，不建议在LLM提示中使用。

classmethod format_class_str(format_type: DataClassFormatType, exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

根据操作类型和类/实例上下文生成格式化输出。

Parameters:: format_type (DataClassFormatType) – 指定格式和类型（模式、签名、示例）。
Returns:: 表示格式化输出的字符串。
Return type:: 字符串

示例：

# Define a dataclass
from adalflow.core import DataClass

format_example_str(format_type: DataClassFormatType, exclude: List[str] | Dict[str, List[str]] | None = None, include: List[str] | Dict[str, List[str]] | None = None) → str[source]#

根据操作类型和类/实例上下文生成格式化输出。

Parameters:: format_type (DataClassFormatType) – 指定格式和类型（模式、签名、示例）。
Returns:: 表示格式化输出的字符串。
Return type:: 字符串

class DataClassFormatType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

基础：Enum

DataClass 模式的格式类型。

SCHEMA = 'schema'#

SIGNATURE_YAML = 'signature_yaml'#

SIGNATURE_JSON = 'signature_json'#

EXAMPLE_YAML = 'example_yaml'#

EXAMPLE_JSON = 'example_json'#

required_field() → Callable[[], Any][source]#

一个工厂函数，用于在数据类中创建一个必填字段。返回的可调用对象在调用时会引发TypeError，表示未提供必填字段。

Parameters:: name (可选[str], 可选) – 所需字段的名称。默认为 None
Returns:: 一个可调用对象，当被调用时会引发TypeError，表示缺少必填字段。
Return type:: Callable[[], Any]

示例：

from dataclasses import dataclass
from adalflow.core.base_data_class import required_field, DataClass

@dataclass
class Person(DataClass):
    name: str = field(default=None)
    age: int = field(default_factory=required_field())# allow required field after optional field

check_adal_dataclass(data_class: Type) → None[source]#

检查提供的类是否是AdalFlow框架的有效数据类。

Parameters:: data_class (类型) – 要检查的类。

class DynamicDataClassFactory[source]#

基础类：object

static from_dict(data: ~typing.Dict[str, ~typing.Any], base_class: ~typing.Type = <class 'core.base_data_class.DataClass'>, class_name: str = 'DynamicDataClass') → DataClass[source]#

从字典创建一个数据类的实例。字典应具有以下结构： {

“字段名称”: 字段值, …

}

Parameters:

data (dict) – 包含字段名称和值的字典。
base_class (type) – 要继承的基类（默认：BaseDataClass）。
class_name (str) – 生成的dataclass的名称（默认：DynamicDataClass）。

Returns:

生成的dataclass的一个实例。

Return type:

基础数据类