cognition.knowledge.organization

Knowledge organization

Classes

WorldSnapshot

A fixed set of entities and/or relations

LinkedEntity

Entity and the linked world graph

LinkedBinaryRelation

Relation and the linked world graph

WorldGraph

Graph of binary relations (edges) between entities (nodes)

Module Contents

class cognition.knowledge.organization.WorldSnapshot

A fixed set of entities and/or relations

items: frozenset[cognition.knowledge.representation.Fact]

Fixed set of facts

__str__()
Returns:

facts in ascending order

Return type:

str

__len__()
Returns:

number of facts

Return type:

int

__contains__(item)

Checks for set containment, freezing the fact if necessary

Parameters:

item (cognition.knowledge.representation.Fact) – fact of interest

Returns:

True if supplied fact is in this set

Return type:

bool

__eq__(other)
Parameters:

other (object) – some object

Returns:

True if the object is of this type and has the same facts

Return type:

bool

__lt__(other)
Parameters:

other (object) – some object

Returns:

True if the object is of this type and has a strict subset of the facts

Return type:

bool

__le__(other)
Parameters:

other (object) – some object

Returns:

True if the object is of this type and has a subset of the facts

Return type:

bool

__iter__()
Returns:

iterator over the facts

Return type:

collections.abc.Iterator[cognition.knowledge.representation.Fact]

classmethod click(*facts)

Convenience method for producing a snapshot from a supplied source.

Note: each fact is checked for immutability and frozen if it is not already.

Parameters:

facts (cognition.knowledge.representation.Fact) – source of facts

Returns:

resulting snapshot

Return type:

Self

copy(add=(), remove=())

Convenience method for producing a new snapshot from the contents of this snapshot + some added facts - some removed facts.

Note: each fact is checked for immutability and frozen if it is not already.

Parameters:
Returns:

resulting snapshot

Return type:

Self

by[FT](cls_t, check=lambda _: ...)

Access by fact type and an optional check

Parameters:
Returns:

fact(s) matching the filter and gate

Return type:

collections.abc.Iterable[FT]

find_first[FT](cls_t, check=lambda _: ...)

Finds the first typed fact that satisfies the check

Parameters:
Returns:

first found fact

Raises:

ValueError – no fact of the supplied type satisfies the check

Return type:

FT

entity_by_name(entity_name)

Finds the first entity with the supplied name

Parameters:

entity_name (str) – target name

Returns:

entity, or None if unused name

Return type:

cognition.knowledge.representation.Entity | None

filter_relations[RT](cls_t=None, e1=None, e2=None)

Finds all relation(s) that match the supplied criteria

Parameters:
Returns:

any matching relations

Return type:

collections.abc.Iterable[cognition.knowledge.representation.BinaryRelation]

class cognition.knowledge.organization.LinkedEntity[E: cognition.knowledge.representation.Entity]

Entity and the linked world graph

e: E

Entity instance

wg: WorldGraph

Associated graph instance

update()

Adds the entity to the graph (updating any values)

Return type:

None

remove()

Removes the entity (by name) from the graph

Return type:

None

property outgoing: collections.abc.Iterable[LinkedBinaryRelation[Any]]
Returns:

the linked outgoing relations from this entity

Return type:

collections.abc.Iterable[LinkedBinaryRelation[Any]]

class cognition.knowledge.organization.LinkedBinaryRelation[R: cognition.knowledge.representation.BinaryRelation]

Relation and the linked world graph

r: R

Relation instance

wg: WorldGraph

Associated graph instance

update()

Adds the relation to the graph (updating any values)

Return type:

None

remove()

Removes the relation (by entity names + relation type) from the graph

Return type:

None

class cognition.knowledge.organization.WorldGraph

Graph of binary relations (edges) between entities (nodes)

g: networkx.MultiDiGraph[str]

Knowledge graph - publicly exposed, but should be handled in a read-only fashion and conversion data read/writes left to the WorldGraph API

add_entity[E](e)

Using the entity name as id, sets the associated node data within the graph

Parameters:

e (E) – entity with node data

Returns:

object holding the added entity and this graph

Return type:

LinkedEntity[E]

add_relation[R](r)

Using the (entity1 -[key=r.type]-> entity2) as id, sets the associated edge data within the graph

Parameters:

r (R) – relation with edge data

Returns:

object holding the added relation and this graph

Raises:

KeyError – supplied node not in the graph

Return type:

LinkedBinaryRelation[R]

get_entity(entity_name: str) → LinkedEntity[Any]
get_entity(entity_name: str, linked: Literal[True]) → LinkedEntity[Any]
get_entity(entity_name: str, linked: Literal[False]) → cognition.knowledge.representation.Entity

Retrieves an entity given its name

Parameters:

  • entity_name – node to find

  • linked – whether to link result to this graph

Returns:

node data

Raises:

KeyError – supplied entity name not in the graph

property entities: collections.abc.Iterable[cognition.knowledge.representation.Entity]

All graph entities

Returns:

data from all graph nodes

Return type:

collections.abc.Iterable[cognition.knowledge.representation.Entity]

outgoing_relations(start: cognition.knowledge.representation.Entity) → collections.abc.Iterable[LinkedBinaryRelation[Any]]
outgoing_relations(start: cognition.knowledge.representation.Entity, linked: Literal[True]) → collections.abc.Iterable[LinkedBinaryRelation[Any]]
outgoing_relations(start: cognition.knowledge.representation.Entity, linked: Literal[False]) → collections.abc.Iterable[cognition.knowledge.representation.BinaryRelation]
Parameters:

  • start – originating graph entity

  • linked – True to produce linked relations

Returns:

outgoing relations from an entity

produce_relation(entity1, entity2, edge_info)

Produces a relation given the supplied edge data (assumed to be directly from the graph)

Parameters:
Returns:

edge data

Return type:

cognition.knowledge.representation.BinaryRelation

get_relation(entity1_name: str, entity2_name: str, edge_type: str) → LinkedBinaryRelation[Any]
get_relation(entity1_name: str, entity2_name: str, edge_type: str, linked: Literal[True]) → LinkedBinaryRelation[Any]
get_relation(entity1_name: str, entity2_name: str, edge_type: str, linked: Literal[False]) → cognition.knowledge.representation.BinaryRelation

Retrieves a relation give the names of the associated entities and the relation type

Parameters:

  • entity1_name – starting node name

  • entity2_name – ending node name

  • edge_type – edge schema type

  • linked – whether to link result to this graph

Returns:

edge data

Raises:

KeyError – supplied entity name not in the graph

property relations: collections.abc.Iterable[cognition.knowledge.representation.BinaryRelation]

All graph relations

Returns:

data from all graph edges

Return type:

collections.abc.Iterable[cognition.knowledge.representation.BinaryRelation]

property snapshot: WorldSnapshot

Produces a snapshot of this graph

Returns:

static snapshot of all entities and relations

Return type:

WorldSnapshot

classmethod from_snapshot(snap)

Create a graph from (the thawed contents of) a snapshot

Parameters:

snap (WorldSnapshot) – set of entities/relations

Returns:

resulting (thawed) graph

Return type:

Self

remove_node(entity_name)

Removes a graph node

Parameters:

entity_name (str) – node name to remove

Returns:

reference to this graph

Return type:

Self

remove_edge(entity1_name, entity2_name, edge_type)

Remove a graph edge

Parameters:

  • entity1_name (str) – starting node name

  • entity2_name (str) – ending node name

  • edge_type (str) – edge schema type

Returns:

reference to this graph

Return type:

Self