tyche.individuals

This module contains classes used to construct ontological knowledge bases of individuals, the probabilistic beliefs about them (concepts), and the probabilistic relationships between them (roles). These belief models can be used as contexts to evaluate aleatoric description logic (ADL) sentences. This module also contains many learning strategies that may be used to update your belief models based upon ADL observations.

exception tyche.individuals.TycheIndividualsException(message)[source]

An exception type that is thrown when errors occur in the construction or use of individuals.

Parameters:

message (str) –

class tyche.individuals.TycheAccessorStore(type_name, accessors)[source]

Bases: Generic[AccessedValueType]

Stores a set of ways to access concepts or roles from a Tyche individual.

Parameters:
contains(symbol)[source]

Returns whether this store contains a reference to the given symbol.

Parameters:

symbol (str) –

Return type:

bool

get_reference(symbol)[source]

Returns the reference to access the given symbol.

Parameters:

symbol (str) –

Return type:

SymbolReference[AccessedValueType]

get(obj, symbol)[source]

Accesses the given symbol from the given object.

Parameters:

  • obj (any) –

  • symbol (str) –

Return type:

AccessedValueType

set(obj, symbol, value)[source]

Modifies the given symbol in the given object.

Parameters:

  • obj (any) –

  • symbol (str) –

  • value (AccessedValueType) –

static get_accessor_stores_map(accessor_type)[source]

Returns a map from Individual subclass types to their accessor stores for the given type of accessors.

Parameters:

accessor_type (type) –

Return type:

dict[type, ‘TycheAccessorStore’]

static get_accessor_ref_map(accessor_type)[source]

Returns a map from Individual subclass types to their accessor stores for the given type of accessors.

Parameters:

accessor_type (type) –

Return type:

dict[type, dict[str, tyche.references.SymbolReference[~AccessedValueType]]]

static get_or_populate_for(obj_type, accessor_type, field_type_hint, type_name)[source]

Gets or populates the set of accessors associated with obj_type, and returns them.

Parameters:

  • obj_type (type) –

  • accessor_type (type) –

  • field_type_hint (type) –

  • type_name (str) –

Return type:

TycheAccessorStore

class tyche.individuals.ConceptFunctionSymbolReference(symbol, fget, fset=None, learning_strat=None)[source]

Bases: FunctionSymbolReference

Represents a reference to a concept, with additional information about the concept attached.

Parameters:

  • symbol (str) –

  • fget (Callable[[any], TycheConceptValue]) –

  • fset (Optional[Callable[[any, TycheConceptValue], None]]) –

  • learning_strat (Optional[ConceptLearningStrategy]) –

class tyche.individuals.RoleFunctionSymbolReference(symbol, fget, fset=None, learning_strat=None)[source]

Bases: FunctionSymbolReference

Represents a reference to a concept, with additional information about the concept attached.

Parameters:

  • symbol (str) –

  • fget (Callable[[any], TycheRoleValue]) –

  • fset (Optional[Callable[[any, TycheRoleValue], None]]) –

  • learning_strat (Optional[RoleLearningStrategy]) –

class tyche.individuals.IndividualPropertyDecorator(type_name, fget, *, symbol=None)[source]

Bases: Generic[AccessedValueType, LearningStrategyType]

A decorator to mark methods as providing the value of a concept or role, and to provide additional metadata or learning functions.

Parameters:

  • type_name (str) –

  • fget (Callable[[Individual], AccessedValueType]) –

  • symbol (Optional[str]) –

learning_func(learning_strat=None)[source]

This can be used as a decorator to register a method-based setter for this symbol.

Parameters:

learning_strat (Optional[LearningStrategyType]) –

Return type:

Callable[[Callable[[Individual, AccessedValueType], None]], Callable[[Individual, AccessedValueType], None]]

class tyche.individuals.TycheConceptDecorator(fn, *, symbol=None)[source]

Bases: IndividualPropertyDecorator[TycheConceptValue, ConceptLearningStrategy]

Marks that a method provides the value of a concept for use in Tyche formulas. The name of the function is used as the name of the concept in formulas.

Parameters:

  • fn (Callable[[], TycheConceptValue]) –

  • symbol (Optional[str]) –

class tyche.individuals.TycheRoleDecorator(fn, *, symbol=None)[source]

Bases: IndividualPropertyDecorator[TycheRoleValue, RoleLearningStrategy]

Marks that a method provides the value of a role for use in Tyche formulas. The name of the function is used as the name of the role in formulas.

Parameters:

  • fn (Callable[[], TycheRoleValue]) –

  • symbol (Optional[str]) –

tyche.individuals.concept(*, symbol=None)[source]

Registers a method as supplying the value of a concept for the evaluation of Tyche expressions.

Parameters:

symbol (Optional[str]) –

Return type:

Callable[[Callable[[Individual], TycheConceptValue]], TycheConceptDecorator]

tyche.individuals.role(*, symbol=None)[source]

Registers a method as supplying the value of a role for the evaluation of Tyche expressions.

Parameters:

symbol (Optional[str]) –

Return type:

Callable[[Callable[[], TycheRoleValue]], TycheRoleDecorator]

class tyche.individuals.LearningStrategy[source]

Applies changes to individuals to update them based upon observations.

init_for_new_usage()[source]

If a learning strategy requires per-reference per-individual state, then this can clone the learning strategy for each new individual and reference. Otherwise, the state of this learning strategy will be shared for every individual and reference that uses it (which is fine for stateless learning strategies).

Return type:

SelfType_LearningStrategy

class tyche.individuals.ConceptLearningStrategy[source]

Bases: LearningStrategy

Applies changes to individuals to update them based upon observations of concepts.

apply(individual, concept_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.RoleLearningStrategy[source]

Bases: LearningStrategy

Applies changes to individuals to update them based upon observations over roles.

apply(individual, role_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.DirectConceptLearningStrategy(learning_rate=1)[source]

Bases: ConceptLearningStrategy

The most basic learning strategy that simply updates concepts to the values they were observed as. A learning rate can be used to limit the changes to the concept’s value, to stop a single true observation marking the concept always true.

Parameters:

learning_rate (float) –

apply(individual, concept_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.StatisticalConceptLearningStrategy(initial_value_weight=1, *, decay_rate=1, decay_rate_for_decay_rate=1)[source]

Bases: ConceptLearningStrategy

This learning strategy accumulates a running mean of observations about a concept, and uses it to learn the value of the concept. An initial value bias can be used to favour the initial value of the concept until enough observations have been made.

If an initial value is not supplied on construction, then the initial value is considered to be the value of the concept when the first observation is made that calls this learning strategy.

Parameters:

  • initial_value_weight (float) –

  • decay_rate (float) –

  • decay_rate_for_decay_rate (float) –

init_for_new_usage()[source]

This is required so that the state of each reference that uses an instance of this learning strategy is kept separate.

Return type:

SelfType_LearningStrategy

apply(individual, concept_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.BayesRuleLearningStrategy(learning_rate=1.0)[source]

Bases: RoleLearningStrategy

TODO

Parameters:

learning_rate (float) –

apply(individual, role_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.StatisticalRoleLearningStrategy(initial_value_weight=1, *, decay_rate=1, decay_rate_for_decay_rate=1)[source]

Bases: RoleLearningStrategy

TODO

Parameters:

  • initial_value_weight (float) –

  • decay_rate (float) –

  • decay_rate_for_decay_rate (float) –

init_for_new_usage()[source]

This is required so that the state of each reference that uses an instance of this learning strategy is kept separate.

Return type:

SelfType_LearningStrategy

apply(individual, role_ref, observation, likelihood, learning_rate)[source]

Modifies the individual to learn the given concept from the given observation of it.

Parameters:
class tyche.individuals.Individual(name=None)[source]

Bases: TycheContext

A helper class for representing individual entities in an aleatoric knowledge base. These roles can be used as contexts to use to evaluate Tyche expressions within.

The concepts and roles about the individual may be stored as instance variables, or as methods that supply their value. * Fields can be marked as concepts by giving them the TycheConcept type hint. * Fields can be marked as roles by giving them the TycheRole type hint. * Methods can be marked as concepts using the @concept decorator. * Methods can be marked as roles using the @role decorator.

Parameters:

name (Optional[str]) –

eval(node)[source]

Evaluates the given concept to a probability of it being true if sampled within this context.

Parameters:

node (CompatibleWithADLNode) –

Return type:

float

eval_role(role)[source]

Evaluates the given role to a distribution of possible other contexts if it were sampled within this context.

Parameters:

role (CompatibleWithRole) –

Return type:

RoleDist

static describe(obj_type)[source]

Returns a string describing the concepts and roles of the given Individual type.

Parameters:

obj_type (Type[Individual]) –

Return type:

str

static get_concept_names(obj_type)[source]

Returns all the concept names of the given Individual type.

Parameters:

obj_type (Type[Individual]) –

Return type:

set[str]

static get_role_names(obj_type)[source]

Returns all the role names of the given Individual type.

Parameters:

obj_type (Type[Individual]) –

Return type:

set[str]

classmethod coerce_concept_value(value)[source]

Coerces concept values to a float value in the range [0, 1], and raises errors if this is not possible.

Parameters:

value (any) –

Return type:

float

get_concept(symbol)[source]

Gets the probability of the atom with the given symbol being true, without modification by the context.

Parameters:

symbol (str) –

Return type:

float

get_concept_reference(symbol)[source]

Gets a mutable reference to the probability of the atom with the given symbol being true. This reference can be used to get and set the value of the atom.

Parameters:

symbol (str) –

Return type:

BakedSymbolReference[float]

classmethod coerce_role_value(value)[source]

Coerces role values to only allow WeightedRoleDistribution. In the future, this should accept other types of role distributions.

Parameters:

value (any) –

Return type:

RoleDist

get_role(symbol)[source]

Gets the role distribution of the role with the given symbol, without modification by the context.

Parameters:

symbol (str) –

Return type:

RoleDist

get_role_reference(symbol)[source]

Gets a mutable reference to the role distribution of the role with the given symbol. This reference can be used to get and set the value of the role.

Parameters:

symbol (str) –

Return type:

SymbolReference[RoleDist]

observe(observation, likelihood=1, learning_rate=1)[source]

Learns the roles and concepts within this individual based upon the observation, and propagate the effects of the observation node to its child nodes.

Parameters:

  • observation (ADLNode) –

  • likelihood (float) –

  • learning_rate (float) –

to_str(*, detail_lvl=1, indent_lvl=0)[source]

A version of str() that allows additional formatting options to be specified. Allows specifying the number of levels of detail to include, and the indentation to use while formatting.

Parameters:

  • detail_lvl (int) –

  • indent_lvl (int) –

class tyche.individuals.IdentityIndividual(id_role_value=None, *, name=None, entries=None, learning_strat=<tyche.individuals.BayesRuleLearningStrategy object>)[source]

Bases: TycheContext

Implicitly represents a role over the set of possible states that an individual could take. Evaluation of concepts and roles with this context will implicitly perform an expectation over the set of possible individuals in the id role.

The None-individual is not supported for identity roles.

Parameters:

  • id_role_value (ExclusiveRoleDist) –

  • name (Optional[str]) –

  • entries (Union[None, list[Union[ForwardRef('TycheContext'), Tuple[ForwardRef('TycheContext'), float]]], dict['TycheContext', float]]) –

  • learning_strat (Optional[RoleLearningStrategy]) –

is_empty()[source]

Returns whether no possible individuals have been added.

Return type:

bool

add(individual, weight=1)[source]

Adds a possible individual with the given weight. The weights represent the relative weight of the individual against the weights of other individuals. If the given individual already exists, this will replace their weight.

If no weight is given, the default weight of 1 will be used.

Parameters:
remove(individual)[source]

Removes the given individual from this identity individual.

Parameters:

individual (TycheContext) –

eval(node)[source]

Evaluates the given concept to a probability of it being true if sampled within this context.

Parameters:

node (ADLNode) –

Return type:

float

eval_role(role)[source]

Evaluates the given role to a distribution of possible other contexts if it were sampled within this context.

Parameters:

role (Role) –

Return type:

RoleDist

get_role(symbol)[source]

Gets the role distribution of the role with the given symbol, without modification by the context.

Parameters:

symbol (str) –

Return type:

RoleDist

get_concept(symbol)[source]

Gets the probability of the atom with the given symbol being true, without modification by the context.

Parameters:

symbol (str) –

Return type:

float

get_concept_reference(symbol)[source]

Gets a mutable reference to the probability of the atom with the given symbol being true. This reference can be used to get and set the value of the atom.

Parameters:

symbol (str) –

Return type:

SymbolReference[float]

get_role_reference(symbol)[source]

Gets a mutable reference to the role distribution of the role with the given symbol. This reference can be used to get and set the value of the role.

Parameters:

symbol (str) –

Return type:

SymbolReference[RoleDist]

observe(observation, likelihood=1, learning_rate=1)[source]

Attempts to update the beliefs of this individual based upon an observation of the given concept.

The optional likelihood parameter provides a degree of certainty about the observation. By default, the observation is assumed to be reliable.

Parameters:

  • observation (ADLNode) –

  • likelihood (float) –

  • learning_rate (float) –

to_str(*, detail_lvl=1, indent_lvl=0)[source]

A version of str() that allows additional formatting options to be specified. Allows specifying the number of levels of detail to include, and the indentation to use while formatting.

Parameters:

  • detail_lvl (int) –

  • indent_lvl (int) –