fabricatio_core.capabilities.usages

Module for defining LLM (Large Language Model) usage capabilities.

This module contains classes and methods to manage interactions with LLMs, including: - Deploying models - Querying responses - Validating outputs - Generating embeddings - Selecting tools and toolboxes

It provides structured functionality for managing language model operations, embedding generation, and tool selection workflows.

Classes

UseLLM

Class that manages LLM (Large Language Model) usage parameters and methods.

UseEmbedding

A class representing the embedding model.

UseReranker

A class for reranking documents using a reranker model.

Module Contents

class fabricatio_core.capabilities.usages.UseLLM(/, **data: Any)[source]

Bases: fabricatio_core.models.generic.LLMScopedConfig, abc.ABC

Class that manages LLM (Large Language Model) usage parameters and methods.

This class provides methods to deploy LLMs, query them for responses, and handle various configurations related to LLM usage such as API keys, endpoints, and rate limits.

async aask(question: List[str], send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → List[str][source]
async aask(question: str, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → str

Asynchronously asks the language model a question and returns the response content.

Parameters:

  • question (str | List[str]) – The question or list of questions to ask the model.

  • send_to – the completion model group to use

  • **kwargs (Unpack[LLMKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The content of the model’s response message. Returns a single string if input is a string,

or a list of strings if input is a list of strings.

Return type:

str | List[str]

async aask_validate[T](question: str, validator: Callable[[str], T | None], default: T = ..., max_validations: pydantic.PositiveInt = 3, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → T[source]
async aask_validate(question: List[str], validator: Callable[[str], T | None], default: T = ..., max_validations: pydantic.PositiveInt = 3, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → List[T]
async aask_validate(question: str, validator: Callable[[str], T | None], default: None = None, max_validations: pydantic.PositiveInt = 3, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → T | None
async aask_validate(question: List[str], validator: Callable[[str], T | None], default: None = None, max_validations: pydantic.PositiveInt = 3, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → List[T | None]
async aask_validate(question: str | List[str], validator: Callable[[str], T | None], default: T | None = None, max_validations: pydantic.PositiveInt = 3, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.LLMKwargs]) → None | T | List[T | None] | List[T]

Asynchronously asks a question and validates the response using a given validator.

Parameters:

  • question (str | List[str]) – The question to ask.

  • validator (Callable[[str], T | None]) – A function to validate the response.

  • default (T | None) – Default value to return if validation fails. Defaults to None.

  • max_validations (PositiveInt) – Maximum number of validation attempts. Defaults to 3.

  • send_to – the completion model group to use

  • **kwargs (Unpack[LLMKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The validated response.

Return type:

Optional[T] | List[T | None] | List[T] | T

async amapping_kv[K: int | str | bool, V: int | float | str | bool](requirement: str, key_type: Type[K], value_type: Type[V], k: pydantic.NonNegativeInt = 0, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[Dict[K, V]]]) → Dict[K, V] | None[source]
async amapping_kv(requirement: List[str], key_type: Type[K], value_type: Type[V], k: pydantic.NonNegativeInt = 0, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[Dict[K, V]]]) → List[Dict[K, V] | None] | None

Asynchronously maps a requirement to a key-value dictionary via LLM.

Supports arbitrary key/value types through key_type and value_type parameters.

Parameters:

  • requirement – A single string or list of strings describing the mapping task.

  • key_type – The type of the keys in the mapping (String or Int).

  • value_type – The type of the values in the mapping (String, Int, or Float).

  • k – The number of key-value pairs to generate, 0 means infinite. Defaults to 0.

  • send_to – the completion model group to use

  • **kwargs – Additional keyword arguments for LLM configuration and validation.

Returns:

Optional[Dict] for single requirement, List[Optional[Dict]] for batch.

async alist_v[T: int | str | bool | float](requirement: str, value_type: Type[T], k: pydantic.NonNegativeInt = 0, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[T]]]) → List[T] | None[source]
async alist_v(requirement: List[str], value_type: Type[T], k: pydantic.NonNegativeInt = 0, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[T]]]) → List[List[T] | None] | None

Asynchronously generates a list of values based on a given requirement.

Parameters:

  • requirement (str | List[str]) – The requirement for the list.

  • value_type (Type[T]) – The type of list elements (str, int, float, bool). Defaults to str.

  • k (NonNegativeInt) – The number of choices to select, 0 means infinite. Defaults to 0.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The validated response as a list of values.

Return type:

List[T] | List[List[T] | None] | None

async apathstr(requirement: str, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ChooseKwargs[str]]) → List[str] | None[source]

Asynchronously generates a list of path strings based on a given requirement.

Parameters:

  • requirement (str) – The requirement for the list of paths.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ChooseKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The validated response as a list of path strings.

Return type:

Optional[List[str]]

async awhich_pathstr(requirement: str, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[str]]]) → str | None[source]

Asynchronously generates a single path string based on a given requirement.

Parameters:

  • requirement (str) – The requirement for the path.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The validated response as a single string.

Return type:

Optional[str]

async ageneric_string(requirement: str, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[str]]) → str | None[source]
async ageneric_string(requirement: List[str], send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[str]]) → List[str | None] | None

Asynchronously generates a generic string based on a given requirement.

Parameters:

  • requirement (str) – The requirement for the string.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[LLMKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The generated string.

Return type:

Optional[str]

async acode_string(requirement: str, code_language: str | None = None, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[str]]) → str | None[source]
async acode_string(requirement: List[str], code_language: str | None = None, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[str]]) → List[str | None]

Asynchronously generates code strings based on given requirements and code language.

Parameters:

  • requirement (str | List[str]) – The requirement(s) for generating code strings.

  • code_language (str) – The programming language for the generated code.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs[str]]) – Additional keyword arguments for the LLM usage.

Returns:

The generated code string(s). Returns a single string if requirement is a string, or a list of strings/None values if requirement is a list.

Return type:

None | str | List[str | None]

async acode_snippets(requirement: str, code_language: str | None = None, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[fabricatio_core.rust.CodeSnippet]]]) → List[fabricatio_core.rust.CodeSnippet] | None[source]
async acode_snippets(requirement: List[str], code_language: str | None = None, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[fabricatio_core.rust.CodeSnippet]]]) → List[List[fabricatio_core.rust.CodeSnippet] | None] | None

Asynchronously generates code snippets based on given requirements and code language.

Parameters:

  • requirement (str | List[str]) – The requirement(s) for generating code snippets.

  • code_language (Optional[str]) – The programming language for the generated code. Defaults to None.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs[List[CodeSnippet]]]) – Additional keyword arguments for the LLM usage.

Returns:

The generated code snippet(s). Returns a list of CodeSnippet objects if requirement is a string, or a list of lists of CodeSnippet objects or None if requirement is a list.

Return type:

None | List[CodeSnippet] | List[List[CodeSnippet] | None]

async achoose[T: fabricatio_core.models.generic.WithBriefing](instruction: str, choices: List[T], k: pydantic.NonNegativeInt = 0, is_included_fn: Callable[[Set[str], T], bool] | None = None, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[T]]]) → List[T] | None[source]

Asynchronously executes a multi-choice decision-making process, generating a prompt based on the instruction and options, and validates the returned selection results.

Parameters:

  • instruction (str) – The user-provided instruction/question description.

  • choices (List[T]) – A list of candidate options, requiring elements to have name and briefing fields.

  • k (NonNegativeInt) – The number of choices to select, 0 means infinite. Defaults to 0.

  • is_included_fn (Optional[Callable[[Set[str],T], bool]] = None) – A function to check whether a choice is included in the query.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The final validated selection result list, with element types matching the input choices.

Return type:

Optional[List[T]]

async aenum_choose[E: (enum.StrEnum, enum.IntEnum)](instruction: str, enum_type: Type[E], k: pydantic.NonNegativeInt = 0, send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[E]]]) → List[E] | None[source]

Asynchronously selects enum members from the given enum type based on the instruction.

Mimics achoose() but operates on StrEnum / IntEnum members instead of WithBriefing objects. Each member’s name is used as the choice identifier. The enum class __doc__ is passed as enum_doc to the template for context.

Parameters:

  • instruction (str) – The user-provided instruction/question description.

  • enum_type (Type[E]) – The enum type to select from.

  • k (NonNegativeInt) – The number of choices to select, 0 means all relevant. Defaults to 0.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs[List[E]]]) – Additional keyword arguments for the LLM usage.

Returns:

The selected enum member(s), or None if validation fails.

Return type:

Optional[List[E]]

async apick[T: fabricatio_core.models.generic.WithBriefing](instruction: str, choices: List[T], send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[List[T]]]) → T[source]

Asynchronously picks a single choice from a list of options using AI validation.

Parameters:

  • instruction (str) – The user-provided instruction/question description.

  • choices (List[T]) – A list of candidate options, requiring elements to have name and briefing fields.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The single selected item from the choices list.

Return type:

T

Raises:

ValueError – If validation fails after maximum attempts or if no valid selection is made.

async ajudge(prompt: str, affirm_case: str = '', deny_case: str = '', send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[bool]]) → bool | None[source]
async ajudge(prompt: List[str], affirm_case: str = '', deny_case: str = '', send_to: str | None = None, **kwargs: Unpack[fabricatio_core.models.kwargs_types.ValidateKwargs[bool]]) → List[bool | None] | None

Asynchronously judges a prompt using AI validation.

Parameters:

  • prompt (str) – The input prompt to be judged.

  • affirm_case (str) – The affirmative case for the AI model. Defaults to an empty string.

  • deny_case (str) – The negative case for the AI model. Defaults to an empty string.

  • send_to (Optional[str]) – The group name of which the requests will be sent.

  • **kwargs (Unpack[ValidateKwargs]) – Additional keyword arguments for the LLM usage.

Returns:

The judgment result (True or False) based on the AI’s response.

Return type:

bool

class fabricatio_core.capabilities.usages.UseEmbedding(/, **data: Any)[source]

Bases: fabricatio_core.models.generic.EmbeddingScopedConfig, abc.ABC

A class representing the embedding model.

This class extends LLMUsage and provides methods to generate embeddings for input text using various models.

async vectorize(input_text: List[str], **kwargs: Unpack[fabricatio_core.models.kwargs_types.EmbeddingKwargs]) → List[List[float]][source]
async vectorize(input_text: str, **kwargs: Unpack[fabricatio_core.models.kwargs_types.EmbeddingKwargs]) → List[float]
async vectorize(input_text: List[str] | str, **kwargs: Unpack[fabricatio_core.models.kwargs_types.EmbeddingKwargs]) → List[List[float]] | List[float]

Asynchronously generates vector embeddings for the given input text.

Parameters:

  • input_text (List[str] | str) – A string or list of strings to generate embeddings for.

  • **kwargs (Unpack[EmbeddingKwargs]) – Additional keyword arguments for the embedding model.

Returns:

The generated embeddings.

Return type:

List[List[float]] | List[float]

class fabricatio_core.capabilities.usages.UseReranker(/, **data: Any)[source]

Bases: fabricatio_core.models.generic.RerankerScopedConfig, abc.ABC

A class for reranking documents using a reranker model.

async arank(query: str, documents: List[str], **kwargs: Unpack[fabricatio_core.models.kwargs_types.RerankerKwargs]) → List[Tuple[int, float]][source]

Reranks a list of documents based on their relevance to the query.

Parameters:

  • query – The query text to rank documents against.

  • documents – A list of document texts to rerank.

  • **kwargs – Additional keyword arguments for the reranker model.

Returns:

A list of (document_index, score) pairs sorted by relevance descending.

Return type:

List[Tuple[int, float]]