cognition.language.description

Describing data types

Classes

EgColor

Example choice of colors

EgBlock

A block

EgSurface

A surface for blocks

EgOnTop

Represents spatial relations between blocks

FactDescriber

Describes a category of BaseModel instances.

Functions

enum_name_doc(enum_type)

An enumeration's name and doc string

enum_item_doc(enum_item)

An enumeration item's value and doc string

enum_description(enum_type)

Description of an enumerated type

basemodel_name_doc(schema_type)

A base model's name and description

basemodel_field_doc(field_name, field_info)

A base model field's name, type, and description

basemodel_dep_types(start_schema, deep)

Accounts for a base model's dependent types

basemodel_description(schema_types, deep)

Description of basemodel type(s)

describe_facts(instances, task_desc, llm[, ...])

One-off description of a supplied set of facts

Module Contents

cognition.language.description.enum_name_doc(enum_type)

An enumeration’s name and doc string

Parameters:

enum_type (type[enum.Enum]) – type to describe

Returns:

“{name}[ ({doc})]”

Return type:

str

cognition.language.description.enum_item_doc(enum_item)

An enumeration item’s value and doc string

Parameters:

enum_item (enum.Enum) – item to describe

Returns:

“{value}[ ({doc})]”

Return type:

str

cognition.language.description.enum_description(enum_type)

Description of an enumerated type and its members

Parameters:

enum_type (type[enum.Enum]) – type to describe

Returns:

type description

Return type:

str

cognition.language.description.basemodel_name_doc(schema_type)

A base model’s name and description

Parameters:

schema_type (type[pydantic.BaseModel]) – type to describe

Returns:

“{name}[ ({desc})]”

Return type:

str

cognition.language.description.basemodel_field_doc(field_name, field_info)

A base model field’s name, type, and description

Parameters:

  • field_name (str) – field name

  • field_info (pydantic.fields.FieldInfo) – field annotation information

Returns:

“{name} ({type}[; {desc}])”

Return type:

str

cognition.language.description.basemodel_dep_types(start_schema, deep)

Accounts for a base model’s dependent types

Parameters:

  • start_schema (type[pydantic.BaseModel] | collections.abc.Iterable[type[pydantic.BaseModel]]) – source type(s)

  • deep (bool) – if True, recursively includes base model fields

Returns:

enum.Enum and pydantic.BaseModel types needed to understand the schema (including itself)

Return type:

collections.abc.Iterable[type]

cognition.language.description.basemodel_description(schema_types, deep)

Description of basemodel type(s) and their members

Parameters:

  • schema_types (type[pydantic.BaseModel] | collections.abc.Iterable[type[pydantic.BaseModel]]) – type(s) to describe

  • deep (bool) – if True, recursively includes fields’ types

Returns:

description

Return type:

str

class cognition.language.description.EgColor(*args)

Bases: cognition.util.enumeration.AutoDocEnum

Example choice of colors

Parameters:

args (Any)

RED = 'the color red'
GREEN = 'the color green'
BLUE = 'the color blue'
class cognition.language.description.EgBlock

Bases: cognition.knowledge.representation.Entity

A block

name: str
color: EgColor
class cognition.language.description.EgSurface

Bases: cognition.knowledge.representation.Entity

A surface for blocks

name: str
class cognition.language.description.EgOnTop

Bases: cognition.knowledge.representation.BinaryRelation

Represents spatial relations between blocks

entity1: EgBlock
entity2: EgBlock | EgSurface
class cognition.language.description.FactDescriber[T: pydantic.BaseModel](schema_type, task_desc)

Describes a category of BaseModel instances.

Parameters:

  • schema_type (type[T]) – type for this describer

  • task_desc (str | None) – textual description of the task

prompt(instance, others, *extra)

Produces the prompt for a supplied instance

Parameters:

  • instance (T) – instance to describe

  • others (collections.abc.Iterable[T]) – other facts for consideration

  • extra (str) – dynamic extra context to supply

Returns:

resulting describer llm prompt

Return type:

str

__call__(instance, others, llm, *extra, timeout_secs=10)

Describes the instance based upon a timeout budget.

Parameters:

  • instance (T) – instance to describe

  • others (collections.abc.Iterable[T]) – other facts for consideration

  • llm (pydantic_ai.models.Model) – textual model to utilize

  • extra (str) – dynamic extra context to supply

  • timeout_secs (int) – time given per LLM call

Returns:

description

Return type:

str

classmethod describe(instance, task_desc, others, llm, *extra, timeout_secs=10)

One-off instantiation and calling of a describer

Parameters:

  • instance (T) – instance to describe

  • task_desc (str | None) – textual description of the task

  • others (collections.abc.Iterable[T]) – other facts for consideration

  • llm (pydantic_ai.models.Model) – textual model to utilize

  • extra (str) – dynamic extra context to supply

  • timeout_secs (int)

Parm timeout_secs:

time given per LLM call

Returns:

description

Return type:

str

cognition.language.description.describe_facts(instances, task_desc, llm, timeout_secs=10, debug=False)

One-off description of a supplied set of facts

Parameters:

  • instance – instance(s) to describe

  • task_desc (str | None) – textual description of the task

  • llm (pydantic_ai.models.Model) – textual model to utilize

  • timeout_secs (int) – time given per LLM call

  • debug (bool) – returns the prompt instead of the description

  • instances (collections.abc.Iterable[pydantic.BaseModel])

Returns:

description (or prompt it debug)

Return type:

str