eta.schema

Classes and methods for representing and modifying different types of schemas.

A schema is, in general, a collection of sections. Each section is a sequence of eventualities (natural language expressions or ULF/ELF formulas with associated episode symbols) under a section label, e.g., types or preconditions.

A schema is denoted by a specific predicate string (e.g., dog.n or eat.v), and also has a unique header, which is a formula characterizing the schema episode potentially containing participant variables, e.g., ((^me eat.v ?x) ** ?e1).

Classes

`DialSchema`	A schema representing a prototypical episode.
`EpiSchema`	A schema representing a prototypical episode.
`ObjSchema`	A schema representing a prototypical object.
`Schema`	An abstract schema class.
`SchemaLibrary`	A library of all generic episode, dialogue, and object schemas.

class Schema(predicate='', participants=[], vars=[], bindings={}, header=[], contents=[])[source]

Bases: object

An abstract schema class.

id

A unique ID for this schema.

Type:: str

predicate

The main predicate of the schema (e.g., dog.n or eat.v).

Type:: str

participants

All participant roles of a schema, i.e., variables and constants present as arguments in the header.

Type:: list[s-expr]

vars

All variables scoped within a schema.

Type:: list[str]

bindings

A mapping from variables to bound values.

Type:: dict

header

The ELF formula for the header of the schema.

Type:: ELF

contents

The ELF formula for the contents of the schema.

Type:: ELF

sections

A dict mapping each section label (e.g., types) to a list of eventualities created from the schema contents.

Type:: dict[str, list[Eventuality]]

embedding

A vector embedding of this schema.

Type:: list[float]

read_param_dict(schema_contents)[source]: Read an S-expression containing schema contents (for a given predicate) into a dict of schema parameters.

to_probability_dict(eventualities, swap_duals=False)[source]

Given a list of certainty or necessity eventualities, create a probability dict with entries of form {<ep>:<prob>}.

If swap_duals is True, swap episode constants in the resulting probability dict with the dual var (e.g., ?e1 for !e1).

subst_mappings(mappings)[source]: Given a list of variable replacement mappings, apply the mappings to each part of the schema.

duplicate_variables()[source]

Duplicate all variables across a schema, mapping the original variables to the duplicated ones.

Note that this needs to be done in two steps to avoid mapping conflicts.

instantiate(args)[source]

Instantiate a specific instance of a schema given a list of argument values for each variable in the header.

This creates a deep copy of the schema, with duplicate variables to ensure that no collisions occur if the events in the schema are added to a plan.

Parameters:: args (list[s-expr]) – A list of expressions to bind to each respective header variable.
Return type:: Schema

bind(var, val)[source]: Bind the given variable symbol to the given value.

unbind(var)[source]: Unbind the given variable symbol.

bind_args(args)[source]

Bind variables in the schema header with a list of respective argument values.

Generally, we assume that args should correspond to the variables in the participants list of the schema, but we allow for the possibility of ^me and ^you as implicit arguments if fewer arguments than variables are given - in which case, they’re added to the arguments list in that order.

On the other hand, if more arguments than variables are given, we assume that ^me and ^you might be provided as redundant arguments, and remove those from the front of the list if present. Otherwise, we remove superfluous arguments starting from the end of the list.

Parameters:: args (list[s-expr]) – A list of expressions to bind to each respective header variable.

embed(embedder)[source]: Embed the schema based on the natural language representation of its contents, given an embedder object.

retrieve(embedder, query, n=5, header=True)[source]

Retrieve some number of facts from the schema according to similarity with a query string, given an embedder object.

Parameters:

embedder (Embedder) – An Embedder object.
query (str) – A query string to use to compute similarity.
n (int, default=5) – The number of facts to retrieve.
header (bool, default=True) – Whether to prefix the retrieved facts with the schema header.

Returns:

The retrieved schema facts as S-expressions.

Return type:

list[s-expr]

get_participants(no_bind=False)[source]

Get the schema participants.

Parameters:: no_bind (bool, default=False) – Do not make variable substitutions.
Return type:: list[s-expr]

get_contents(no_bind=False)[source]

Get the schema contents as an S-expression.

Parameters:: no_bind (bool, default=False) – Do not make variable substitutions.
Return type:: s-expr

get_section(sec)[source]

Get the eventualities within a given schema section or list of sections.

Parameters:: sec (str or list[str]) – A section label or list of section labels, or the keyword :all to return all sections.
Return type:: list[Eventuality]

get_section_eps(sec, no_bind=False)[source]

Get all episode symbols within a schema section or list of sections.

Parameters:

sec (str or list[str]) – A section label or list of section labels, or the keyword :all to return all sections.
no_bind (bool, default=False) – Do not make variable substitutions.

Return type:

list[str]

get_section_wffs(sec, no_bind=False)[source]

Get all wffs within a schema section or list of sections.

Parameters:

sec (str or list[str]) – A section label or list of section labels, or the keyword :all to return all sections.
no_bind (bool, default=False) – Do not make variable substitutions.

Return type:

list[s-expr]

format(no_bind=False)[source]: Format the contents of this schema as an S-expression string.

class EpiSchema(predicate='', participants=[], vars=[], bindings={}, header=[], contents=[], types=[], rigid_conds=[], static_conds=[], preconds=[], postconds=[], goals=[], episodes=[], episode_relations=[], necessities=[], certainties=[])[source]

Bases: Schema

A schema representing a prototypical episode.

Sections

types : the nominal types of each participant/variable.
rigid-conds : non-fluent conditions relevant to episode.
static-conds : fluent conditions that are not expected to change during episode.
preconds : fluent conditions that are expected to hold at the beginning of episode.
postconds : fluent conditions that are expected to hold at end of episode.
goals : goals of participants in schema (e.g., (^me want.v (that ...))).
episodes : the expected/intended sub-episodes of the schema episode.
episode-relations : the temporal/causal relations between episodes of schema.
necessities : probabilities associated with schema formulas.
certainties : probabilities associated with schema episodes.

read_param_dict(schema_contents)[source]: Read an S-expression containing schema contents (for a given predicate) into a dict of schema parameters.

class DialSchema(predicate='', participants=[], vars=[], bindings={}, header=[], contents=[], types=[], rigid_conds=[], static_conds=[], preconds=[], postconds=[], goals=[], episodes=[], episode_relations=[], obligations=[], necessities=[], certainties=[])[source]

Bases: EpiSchema

A schema representing a prototypical episode.

Sections

types : the nominal types of each participant/variable.
rigid-conds : non-fluent conditions relevant to episode.
static-conds : fluent conditions that are not expected to change during episode.
preconds : fluent conditions that are expected to hold at the beginning of episode.
postconds : fluent conditions that are expected to hold at end of episode.
goals : goals of participants in schema (e.g., (^me want.v (that …))).
episodes : the expected/intended sub-episodes of the schema episode.
episode-relations : the temporal/causal relations between episodes of schema.
obligations : the dialogue obligations associated with episodes within the schema.
necessities : probabilities associated with schema formulas.
certainties : probabilities associated with schema episodes.

read_param_dict(schema_contents)[source]: Read an S-expression containing schema contents (for a given predicate) into a dict of schema parameters.

get_obligations_of_ep(ep)[source]

Return all obligations attached to a given episode symbol.

Parameters:: ep (str) – An episode symbol.
Return type:: list[Eventuality]

Notes

TODO: it may be better to create a generalized accessor function for other types of schema annotations/episode relations.

class ObjSchema(predicate='', participants=[], vars=[], bindings={}, header=[], contents=[], types=[], rigid_conds=[], skeletal_prototype='', purposes=[], necessities=[])[source]

Bases: Schema

A schema representing a prototypical object.

Sections

types : the nominal types of each participant/variable.
rigid-conds : non-fluent conditions relevant to object.
skeletal-prototype : 3D mesh decomposition of object (.obj filenames).
purposes : telic purpose associated with object.
necessities : probabilities associated with schema formulas.

read_param_dict(schema_contents)[source]: Read an S-expression containing schema contents (for a given predicate) into a dict of schema parameters.

class SchemaLibrary(embedder=None)[source]

Bases: object

A library of all generic episode, dialogue, and object schemas.

Parameters:: embedder (Embedder, optional) – If provided, an embedder to embed all schemas that are added.

dial

A dict mapping dialogue schema predicates to dialogue schemas.

Type:: dict[str, DialSchema]

epi

A dict mapping episode schema predicates to episode schemas.

Type:: dict[str, EpiSchema]

obj

A dict mapping object schema predicates to object schemas.

Type:: dict[str, ObjSchema]

embedder

Type:: Embedder

add(schema)[source]: Add a schema object to the library.

create(predicate, contents)[source]: Create a schema object from the given predicate and contents (an S-expression) and add it to the library.

get_schemas(type)[source]

Get all schemas of a particular type or list of types.

Parameters:: type (str or list[str]) – A schema type (dial, epi, or obj), or a list of types.
Return type:: list[Schema]

is_schema(predicate, type=None)[source]

Check whether a given predicate exists in the schema library.

Parameters:

predicate (str) – The predicate to check.
type (str, optional) – If a type is given, only check that type of schema.

Return type:

bool

retrieve(type, query=None, m=1)[source]

Retrieve some number of schemas of a particular type (or list of types).

Parameters:

type (str or list[str]) – A schema type (dial, epi, or obj), or a list of types.
query (str, optional) – A query string to use to compute similarity. If not given, or if no embedder is defined, an arbitrary schema is retrieved.
m (int, default=1) – The number of schemas to retrieve.

Returns:

The retrieved schemas.

Return type:

list[Schema]

retrieve_knowledge(type, query=None, m=1, n=5, header=True)[source]

Retrieve some number of facts from some number of retrieved schemas of a particular type (or list of types).

Parameters:

type (str or list[str]) – A schema type (dial, epi, or obj), or a list of types.
query (str, optional) – A query string to use to compute similarity. If not given, or if no embedder is defined, an arbitrary schema is retrieved.
m (int, default=1) – The number of schemas to retrieve.
n (int, default=5) – The number of facts to retrieve from each retrieved schema.
header (bool, default=True) – Whether to prefix the retrieved facts with the schema header.

Returns:

The facts retrieved from each retrieved schema, as S-expressions.

Return type:

list[s-expr]

from_lisp_file(fname)[source]

Read a set of schemas from a LISP file, storing them in the library.

Parameters:: fname (str) – The LISP file to read.

from_lisp_dirs(dirs)[source]

Recursively read schemas from all LISP files in a given directory or list of directories.

Parameters:: dirs (str or list[str]) – Either a directory name or a list of directory names to read.