Class Reference on Ometeotl, an abstract decision meta-model

Action

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/actions.py

Local role: Represents one actor-driven state transition in one world and one space.

Big-picture role: Operational unit tying Actor, World, ResourceEffect, and ActionPrerequisite.

Inheritance:

ModelObject

Parameters and fields:

object_type: str = "action"
actor_id: ObjectId
world_id: ObjectId
space_id: ObjectId
action_type: str
resource_effects: List[ResourceEffect]
prerequisites: List[ActionPrerequisite]
outcome_description: str
state_changes: JsonMap

Methods:

add_resource_effect(...)
add_prerequisite(...)
set_state_change(...)
to_dict(...), from_dict(...)

See also:

Resource

ActionPrerequisite

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/actions.py

Local role: One admissibility condition attached to one Action.

Big-picture role: Models constraints based on resources, capabilities, perception, or space rules linked to Actor.

Inheritance:

dataclass

Parameters and fields:

prerequisite_type: str
field_name: str
required_value: Any
metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)

See also:

ResourceEffect

ActionProjection

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: Serializable result of projecting one Action from one Perception with an explicit resource set.

Big-picture role: Intermediate projection artifact that records explicit assumptions and the projected successor perceived state before later strategy-node construction.

Inheritance:

dataclass

Parameters and fields:

action_id: str
actor_id: str
source_perception_id: str
source_id: str
status: str
resource_ids: list[str]
assumptions: list[ProjectionAssumption]
projected_state: Optional[ProjectedPerceptionState]
metadata: dict

Methods:

to_dict() -> dict
from_dict(data) -> ActionProjection

See also:

Actor

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/actors.py

Local role: Represents an actor entity with roles, composition mode, and domain relations.

Big-picture role: Central decision-capable abstraction consumed by Action and observed through Sensor.

Inheritance:

Parameters and fields:

object_type: str = "actor"
actor attributes: kind, roles, emergent, composition_mode
composition modes: standalone, composite, collective, perceived, projected
component relations are stored in relations["component"]

Methods:

actor properties: kind, roles, emergent, composition_mode, is_composite, is_collective
role methods: add_role, remove_role
component methods: get_components, add_component, remove_component
generated relation methods: add_action/remove_action, add_resource/remove_resource, add_goal/remove_goal, and related pairs
from_dict(...)

Module-level helpers:

AuditEntry

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/generic/authority.py

Local role: Immutable audit row recording one command decision.

Big-picture role: Traceability primitive for authoritative command boundaries enforced by AuthorityCommandHandler.

Inheritance:

frozen dataclass

Parameters and fields:

command_id: str
actor_id: ObjectId
command_type: str
sequence: int
accepted: bool
reason: str
validation_summary: JsonMap
logged_at: str

Methods:

no custom methods

See also:

AuthorityCommandHandler

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/generic/authority.py

Local role: Single server-side mutation path that validates and applies allowlisted commands.

Big-picture role: Authority boundary that locks direct mutation on World, enforces sequencing, handles deduplication, and emits AuditEntry records.

Inheritance:

standard class

Constructor parameters:

world: World
allowed_command_types: Optional[Sequence[str]]
custom_command_handlers: Optional[Mapping[str, CommandHandler]]
object_factories: Optional[Mapping[str, ObjectFactory]]
audit_log_maxlen: int
processed_ids_maxlen: int
sequence_tracker_max_actors: Optional[int]
sequence_history_max_actors: Optional[int]
validation_soft_gate: bool
validation_policy_profile: str (observe_only, enforce_structure, enforce_domain)
validation_stage_mode_overrides: Optional[Mapping[str, str]]
validation_block_on_error: bool
validation_completeness_level: str

Methods:

submit(command: CommandEnvelope) -> CommandResult
close() -> None
audit_log -> list[AuditEntry]
internal validation and handler methods for add_space, add_space_relation, place_object, register_object, unregister_object

Validation behavior:

CommandEnvelope

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/generic/authority.py

Local role: Canonical command payload consumed by AuthorityCommandHandler.

Big-picture role: Transport object that standardizes authoritative world mutation requests targeting World.

Inheritance:

frozen dataclass

Parameters and fields:

command_id: str
actor_id: ObjectId
command_type: str
payload: JsonMap
sequence: int
issued_at: str

Methods:

to_dict() -> JsonMap
from_dict(data) -> CommandEnvelope

See also:

CommandResult

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/generic/authority.py

Local role: Outcome container returned by AuthorityCommandHandler after processing a CommandEnvelope.

Big-picture role: Stable contract for accepted/rejected command execution against World.

Inheritance:

frozen dataclass

Parameters and fields:

accepted: bool
reason: str
applied: Optional[JsonMap]
validation: JsonMap

Methods:

no custom methods

See also:

AuditEntry

CoverageRule

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/sensor.py

Local role: Abstract visibility policy.

Big-picture role: Extensibility seam controlling which spaces, memberships, and relations enter Perception through Sensor.

Inheritance:

abstract base class

Methods:

covers_space(space, actor_id, world) -> bool
covers_membership(membership, actor_id, world) -> bool
covers_relation(relation, actor_id, world) -> bool

See also:

DefaultProjectionTool

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: Minimal concrete ProjectionTool that turns action/perception/resource inputs into explicit assumptions and one projected successor perceived state without executing actions or building strategy nodes.

Big-picture role: First-order strategizing helper: it prepares both the assumption basis and the next perceived state that later strategy-building steps may consume.

Inheritance:

ProjectionTool

Methods:

project_action(action, perception, resources=()) -> ActionProjection
- Builds ProjectionAssumption entries for actor binding, source context, space binding, each ResourceEffect (indexed as effect:{idx}:…), and each ActionPrerequisite (indexed as prerequisite:{idx}:…).
- For consume/transfer effects, verifies that the resource has a PerceivedMembership in effect.source_id (or action.space_id as fallback); sets satisfied=False when the resource is not perceived there.
- Calls _build_projected_perception_state and attaches the result as projected_state.
- Status is "projected" when all required resources are satisfied and the actor matches; "partial" if resources or actor mismatch; "blocked" otherwise.
inherited project_actions(actions, perception, resources=()) -> ProjectionBatch

Resource projection modes:

GenericObject

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/objects.py

Local role: First semantic layer above ModelObject.

Big-picture role: Shared convenience API inherited by Actor, Resource, and Space.

Inheritance:

ModelObject

Parameters and fields:

inherited base fields

Methods:

metadata properties: label, description, tags, profile
metadata mutators: add_tag, remove_tag, set_profile_item
space binding helpers: add_space_membership, remove_space_membership via SpaceObjectGraph

See also:

SpaceObjectMembership

GuardedJsonDict

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/base.py

Local role: Guarded dictionary wrapper used in mutable fields of ModelObject.

Big-picture role: Prevents direct mutations when authority lock is active through World.

Inheritance:

dict[str, Any]

Parameters and fields:

initial: Mapping[str, Any] | None
mutation_guard: MutationGuard

Methods:

set_mutation_guard(...)
guarded mutators: __setitem__, __delitem__, clear, pop, popitem, setdefault, update
__deepcopy__(...)

See also:

GuardedJsonList

GuardedJsonList

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/base.py

Local role: Guarded list wrapper used in mutable fields of ModelObject.

Big-picture role: Extends authority-safe mutation behavior to list operations in objects managed by World.

Inheritance:

list[Any]

Parameters and fields:

initial: List[Any] | None
mutation_guard: MutationGuard

Methods:

set_mutation_guard(...)
guarded mutators: append, extend, insert, pop, remove, reverse, sort, __setitem__, __delitem__, __iadd__
__deepcopy__(...)

See also:

GuardedJsonDict

IdentityNoiseRule

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/sensor.py

Local role: Default NoiseRule that leaves copies unchanged.

Big-picture role: Zero-noise baseline to isolate coverage behavior in Sensor.

Inheritance:

NoiseRule

Methods:

apply_to_space(...)
apply_to_membership(...)
apply_to_relation(...)

See also:

TotalCoverageRule

MinimalModelRegistry

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/registry.py

Local role: Global class-level fallback registry.

Big-picture role: Legacy/simple referential integrity utility, while WorldModelRegistry is preferred for world-scoped isolation.

Inheritance:

standard class with class methods

Parameters and fields:

class field _instances: Dict[ObjectId, [ModelObject](/ometeotl/documentation/class-reference/model/base/model-object/)]

Methods:

register, unregister, exists, get, clear, all_ids

See also:

World

ModelObject

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/base.py

Local role: Universal schema root for core model entities.

Big-picture role: Canonical serialization backbone used by GenericObject, Action, and all domain subclasses.

Inheritance:

dataclass root

Parameters and fields:

id: ObjectId
object_type: str
schema_version: SchemaVersion
attributes: JsonMap
relations: RelationMap
state: JsonMap
context: JsonMap
provenance: JsonMap

Methods:

mutation helpers: set_mutation_guard, add_relation, remove_relation, _manage_relation
map/list helpers: set_attribute, set_state, set_provenance, add_to_attribute_list, remove_from_attribute_list
serialization: to_dict, from_dict, _base_kwargs

See also:

NoiseRule

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/sensor.py

Local role: Abstract distortion policy over sensed copies.

Big-picture role: Extensibility seam that injects uncertainty and bias into Perception built by Sensor.

Inheritance:

abstract base class

Methods:

apply_to_space(space, actor_id) -> Tuple[Space, JsonMap]
apply_to_membership(membership, actor_id) -> Tuple[SpaceObjectMembership, JsonMap]
apply_to_relation(relation, actor_id) -> Tuple[SpaceRelation, JsonMap]

See also:

IdentityNoiseRule

PerceivedComponentLink

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/perception.py

Local role: Epistemic wrapper for one perceived composition edge between a composite actor and one component actor.

Big-picture role: Lets Perception represent actor hierarchy knowledge without mutating the ontological Actor graph.

Inheritance:

dataclass

Parameters and fields:

link_id: str
composite_id: ObjectId
component_id: ObjectId
epistemic_status: str
noise_metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)
__post_init__(...)

Notes:

epistemic_status follows the same validation rules as the other perceived wrappers.
This type is used both for sensed hierarchy knowledge and for projected hierarchy updates in successor perceived states.

See also:

PerceivedMembership

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/perception.py

Local role: Epistemic wrapper around one copied SpaceObjectMembership.

Big-picture role: Actor-specific placement knowledge item inside Perception.

Inheritance:

dataclass

Parameters and fields:

membership: SpaceObjectMembership
epistemic_status: str
noise_metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)
__post_init__(...)

See also:

PerceivedSpace

PerceivedRelation

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/perception.py

Local role: Epistemic wrapper around one copied SpaceRelation.

Big-picture role: Actor-relative space-topology knowledge element in Perception.

Inheritance:

dataclass

Parameters and fields:

relation: SpaceRelation
epistemic_status: str
noise_metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)
__post_init__(...)

See also:

SpaceRelationGraph

PerceivedSpace

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/perception.py

Local role: Epistemic wrapper around one copied Space.

Big-picture role: Captures actor-relative certainty and noise metadata in Perception.

Inheritance:

dataclass

Parameters and fields:

space: Space
epistemic_status: str
noise_metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)
__post_init__(...)

See also:

Sensor

Perception

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/perception.py

Local role: Subject-specific partial world snapshot.

Big-picture role: Formal epistemic layer that separates what the world is from what an actor knows through Sensor.

Inheritance:

dataclass

Parameters and fields:

id: str
actor_id: ObjectId
source_id: ObjectId
schema_version: str
timestamp: Optional[Union[int, float, str]]
perceived_spaces: Dict[SpaceId, PerceivedSpace]
perceived_memberships: List[PerceivedMembership]
perceived_relations: List[PerceivedRelation]
perceived_component_links: List[PerceivedComponentLink]
context: JsonMap
provenance: JsonMap

Methods:

query helpers: get_perceived_space, memberships_for_object, memberships_in_space, relations_for_space, component_links_for_composite, composite_for_component
serialization: to_dict, from_dict

Notes:

A perception can now carry perceived composition edges independently from space memberships and space-to-space relations.
Each perceived component link has its own epistemic status, allowing composition knowledge to remain uncertain, believed, projected, or erroneous without mutating ontological actor relations.

See also:

ProjectedPerceptionChange

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: One explicit change applied while deriving a successor perceived state from an action projection.

Big-picture role: Audit-friendly delta object that makes projected changes visible instead of hiding them inside the final projected perception only.

Inheritance:

dataclass

Parameters and fields:

change_id: str
change_type: str
subject_id: Optional[str]
space_id: Optional[str]
applied: Optional[bool]
metadata: dict

Known change_type values:

state_changes
resource_consume
resource_produce
object_added
object_removed
component_added
component_removed

Methods:

to_dict() -> dict
from_dict(data) -> ProjectedPerceptionChange

Notes:

ProjectedPerceptionState

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: Projected successor perceived state produced by evaluating one Action from one source Perception.

Big-picture role: Bridge object between first-order projection and later strategy construction: it is the state that child strategy nodes consume.

Inheritance:

dataclass

Parameters and fields:

source_perception_id: str
generating_action_id: str
perception: Perception — deep copy of the source perception, marked epistemic_status="projected" on perceived spaces, memberships, relations, and perceived component links
changes: list[ProjectedPerceptionChange] — sorted by change_id on serialization
metadata: dict

Context keys written into perception.context:

ProjectionAssumption

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: One explicit assumption extracted from evaluating an Action under a Perception and a resource set.

Big-picture role: Projection atom used to externalize the assumptions from which later strategy nodes may be built.

Inheritance:

dataclass

Parameters and fields:

assumption_id: str — unique ID within a projection; format "{action_id}:{type}" for actor/context/space bindings, "{action_id}:effect:{idx}:{resource_id}:{effect_type}" for resource effects (positional index prevents collisions for duplicate effects), "{action_id}:prerequisite:{idx}:{prerequisite_type}:{field_name}" for prerequisites
assumption_type: str — one of actor_binding, perception_context, space_binding, resource_effect, prerequisite
description: str
subject_id: Optional[str]
epistemic_status: str — default "projected"
satisfied: Optional[bool] — None means deferred to a later stage
rationale: str
metadata: dict

Methods:

ProjectionBatch

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: Deterministic batch of ActionProjection instances for one actor/perception context.

Big-picture role: Batch transport object for first-order projection over a candidate action set.

Inheritance:

dataclass

Parameters and fields:

actor_id: str
source_perception_id: str
source_id: str
projections: list[ActionProjection]
metadata: dict

Methods:

to_dict() -> dict
from_dict(data) -> ProjectionBatch

See also:

ProjectionTool

ProjectionTool

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/projection.py

Local role: Abstract contract for deriving assumption sets and successor perceived states from Action, Perception, and Resource inputs.

Big-picture role: Extensibility seam for projection logic that stays separate from strategy-node construction while still feeding it with projected successor states.

Inheritance:

abstract base class

Methods:

project_action(action, perception, resources=()) -> ActionProjection
project_actions(actions, perception, resources=()) -> ProjectionBatch

See also:

DefaultProjectionTool

reconstruct_model_object

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/registry.py

Local role: Module-level factory function that reconstructs any ModelObject subclass from its canonical serialized dict.

Big-picture role: Single deserialization entry point used by WorldModelRegistry.from_dict and by AuthorityCommandHandler when replaying serialized state.

Signature:

def reconstruct_model_object(
 raw_object: Mapping[str, Any],
 object_factories: Optional[Mapping[str, ObjectFactory]] = None,
) -> ModelObject

Parameters:

raw_object — canonical serialized dict; must contain an "object_type" key matching one of the registered factory keys (case-insensitive)
object_factories — optional caller-supplied overrides; merged on top of the default factory table so custom types extend rather than replace the defaults

Default factory table (object_type → class):

Resource

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/resources.py

Local role: Represents modeled resources with rivalry and transferability semantics.

Big-picture role: Constraint and capability component used by Action and related to Actor.

Inheritance:

Parameters and fields:

object_type: str = "resource"
resource attributes: kind, resource_mode, rivalry, transferability, divisibility, composite

Methods:

attribute properties with setters for each resource attribute
generated relation methods: add_user/remove_user, add_owner/remove_owner, add_dependency/remove_dependency, and related pairs
from_dict(...)

See also:

ResourceEffect

ResourceEffect

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/actions.py

Local role: Describes one resource effect of one Action.

Big-picture role: Encodes consumption, production, or transfer semantics for Resource.

Inheritance:

dataclass

Parameters and fields:

resource_id: ObjectId
effect_type: str
quantity: float
source_id: Optional[ObjectId]
target_id: Optional[ObjectId]
metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)

See also:

ActionPrerequisite

RuntimeContext

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/generic/runtime.py

Local role: Context manager that bundles one World with optional AuthorityCommandHandler.

Big-picture role: Runtime switch between local mode and server-authoritative mode.

Inheritance:

dataclass

Parameters and fields:

world: World
authority_handler: Optional[AuthorityCommandHandler]

Methods:

enter() -> RuntimeContext
__exit__(...) -> None
authoritative -> bool
close() -> None

Related function:

build_runtime(...) in src/ometeotl_core/generic/runtime.py

Runtime policy options passed through build_runtime(...):

validation_soft_gate
validation_policy_profile (observe_only, enforce_structure, enforce_domain)
validation_stage_mode_overrides
validation_block_on_error
validation_completeness_level

See also:

CommandEnvelope

Sensor

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/sensor.py

Local role: Builds one Perception for one actor from one World.

Big-picture role: Bridge between ontology and epistemic state, composing CoverageRule and NoiseRule policies.

Inheritance:

dataclass

Parameters and fields:

coverage_rules: List[CoverageRule]
noise_rules: List[NoiseRule]
default_epistemic_status: str

Methods:

sense(world, actor_id, timestamp=None) -> Perception
internal passes: _sense_spaces, _sense_memberships, _sense_relations
policy aggregators: _covers_space, _covers_membership, _covers_relation
noise pipeline: _apply_noise_to_space, _apply_noise_to_membership, _apply_noise_to_relation, _apply_noise

See also:

Space

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/spaces.py

Local role: Represents one space of existence.

Big-picture role: Fundamental topological unit used by World, SpaceObjectGraph, SpaceRelationGraph, and PerceivedSpace.

Inheritance:

Parameters and fields:

object_type: str = "space"
space attributes: kind, dimensions, validity, is_abstract

Methods:

space properties: kind, dimensions, validity, is_abstract
dimension and validity methods: set_dimension, set_validity
legacy disabled methods: add_member, remove_member, connect_to
from_dict(...), __deepcopy__(...)

Notes:

is_abstract marks non-canonical spaces such as conceptual, analytical, or strategic grouping spaces.
Abstract spaces support the multi-space model described in the spec and can host abstraction-layer actors without changing the canonical world object model.

See also:

SpaceObjectGraph

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/spaces.py

Local role: Graph holding spaces and object memberships.

Big-picture role: Deterministic topology service used by World and Sensor.

Inheritance:

dataclass

Parameters and fields:

spaces: Dict[ObjectId, Space]
object_memberships: List[SpaceObjectMembership]
_membership_keys: set[...]

Methods:

mutation: add_space, add_object_membership, remove_object_membership
queries: get_space, spaces_where_object_exists, shared_spaces_ids_for_objects, list_objects_in_space
serialization: to_dict, from_dict

See also:

SpaceRelationGraph

SpaceObjectMembership

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/spaces.py

Local role: Canonical object-to-space membership record.

Big-picture role: Placement primitive used by SpaceObjectGraph, World, and perceived by PerceivedMembership.

Inheritance:

dataclass

Parameters and fields:

object_id: ObjectId
space_id: ObjectId
role: str
validity: JsonMap
metadata: JsonMap

Methods:

to_dict(...)
from_dict(...)
__deepcopy__(...)

See also:

Space

SpaceRelation

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/space_relations.py

Local role: Typed edge linking two spaces.

Big-picture role: Space topology primitive used by SpaceRelationGraph and copied into PerceivedRelation.

Inheritance:

frozen dataclass

Parameters and fields:

source_space_id: SpaceId
target_space_id: SpaceId
relation_type: str
metadata: JsonMap

Methods:

canonicalize(...)
to_dict(...)
from_dict(...)
__deepcopy__(...)

See also:

SpaceRelationType

SpaceRelationGraph

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/space_relations.py

Local role: Validated relation graph over spaces.

Big-picture role: Topology query and validation layer used by World and by Sensor through Perception.

Inheritance:

dataclass

Parameters and fields:

relations: List[SpaceRelation]
_relation_keys: set[...]

Methods:

mutation: add_relation, remove_relation
queries: relations_from, relations_to, children_of, parents_of, neighbors_of, intersects_with
serialization: to_dict, from_dict

See also:

SpaceObjectGraph

SpaceRelationType

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/space_relations.py

Local role: Metadata definition for one relation type.

Big-picture role: Rule descriptor consumed by SpaceRelation and SpaceRelationGraph.

Inheritance:

frozen dataclass

Parameters and fields:

name: str
is_symmetric: bool
is_antisymmetric: bool
is_transitive: bool
is_reflexive: bool

Methods:

no custom methods

See also:

Space

Strategy

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/strategies.py

Local role: Declarative strategy tree composed of StrategyNode objects and their StrategyOutcomeBranch links.

Big-picture role: Current strategy-layer root object. It is the first model-level structure that chains action projections through successive perceived states.

Inheritance:

ModelObject

Parameters and fields:

id: str
actor_id: str
goal_id: Optional[str]
root_node_id: str
nodes: list[StrategyNode]
projection_policy: str

Methods:

add_node(node) -> None
get_node(node_id) -> Optional[StrategyNode]
validate_tree() -> None
to_dict() -> dict
from_dict(data) -> Strategy

Important behavior:

validates that root_node_id exists
validates branch ids are unique per node
validates branch child references
validates that child nodes consume the parent node’s projected successor perception when a parent branch links to that child

Builder functions in the same source module:

StrategyBuildStep

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/strategies.py

Local role: Recursive builder specification used to describe a strategy tree before it is materialized into StrategyNode objects.

Big-picture role: Input format for minimal strategy construction APIs, especially build_branching_strategy(...).

Inheritance:

dataclass

Parameters and fields:

action: Action
children: list[StrategyBuildStep]
branch_label: str
branch_probability: Optional[float]
branch_condition: dict
branch_metadata: dict
metadata: dict

Methods:

dataclass validation in __post_init__()

See also:

StrategyNode

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/strategies.py

Local role: Strategy node that binds one action id to one input perception and one projected successor perceived state.

Big-picture role: Primary strategy-chain unit. A node says “apply this action from this perceived state, producing this projected successor perceived state.”

Inheritance:

dataclass

Parameters and fields:

node_id: str
action_id: str
source_perception_id: Optional[str]
projected_state: Optional[ProjectedPerceptionState]
outcome_branches: list[StrategyOutcomeBranch]
metadata: dict

Properties:

successor_perception_id -> Optional[str]

Methods:

to_dict() -> dict
from_dict(data) -> StrategyNode

Important behavior:

StrategyOutcomeBranch

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/strategies.py

Local role: One branch edge leaving a StrategyNode toward an optional child node.

Big-picture role: Strategy tree edge model used to encode labels, probabilities, conditions, and child-node references.

Current note:

The current implementation keeps projected successor state on the node, not on the branch.
A future TODO prefers branch-specific projected outcomes here if one action later supports several distinct projected outcomes.

Inheritance:

dataclass

Parameters and fields:

branch_id: str
label: str
child_node_id: Optional[str]
probability: Optional[float]
condition: dict
metadata: dict

Methods:

TotalCoverageRule

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/sensor.py

Local role: Default CoverageRule that includes everything.

Big-picture role: Transparent sensing baseline, useful as omniscient reference behavior for Sensor.

Inheritance:

CoverageRule

Methods:

covers_space(...) -> bool
covers_membership(...) -> bool
covers_relation(...) -> bool

See also:

IdentityNoiseRule

World

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/world.py

Local role: Root simulation container and orchestration hub.

Big-picture role: Aggregates SpaceObjectGraph, SpaceRelationGraph, and WorldModelRegistry, while enabling authority mode used by AuthorityCommandHandler.

Inheritance:

Parameters and fields:

object_type: str = "world"
is_root_world: bool
space_object_graph: SpaceObjectGraph
space_relation_graph: SpaceRelationGraph
model_registry: WorldModelRegistry

Methods:

authority mode: enable_authority_mode, disable_authority_mode
topology operations: add_space, add_space_relation, place_object, get_space
abstract-space helper: is_space_abstract
registry operations: register_object, unregister_object
serialization: to_dict, from_dict

Notes:

is_space_abstract(space_id) is a convenience query over registered spaces and returns False for unknown space ids.

See also:

WorldModelRegistry

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_core/model/registry.py

Local role: World-scoped in-memory registry of ModelObject instances.

Big-picture role: Identity boundary used by World and by AuthorityCommandHandler.

Inheritance:

standard class

Parameters and fields:

internal _instances dictionary
optional mutation guard callback

Methods:

mutation: register(obj, authority_token=None), unregister(obj_id, authority_token=None), clear(authority_token=None)
lookup: exists(obj_id) -> bool, get(obj_id) -> Optional[ModelObject], all_ids() -> list[ObjectId]
serialization: to_dict() -> JsonMap, from_dict(data) -> WorldModelRegistry
guard wiring: set_mutation_guard(guard)

Notes:

authority_token is forwarded to the mutation guard callback when set. Re-registering the exact same object instance is a no-op. Duplicate IDs from different object instances raise ValueError.

See also: