Ometeotl: A Decision Meta-Model in Progress on Ometeotl, an abstract decision meta-model

Current Standings

Sun, 26 Apr 2026 00:00:00 +0000

🜂 Current Activity Standings

Last computed: 2026-04-26 13:06 UTC · Active contributors: 0 · Smoothing factor k: 12 · Total shares: 1000

Cold start mode: fewer than 3 active contributors. Shares allocated proportionally to raw scores.

No active contributors yet. Start your first PR and become an Eagle Warrior!

Out-of-competition — Founder

Contributor	Raw Score
@kakchouch	1048.5

Scoring formula

Raw score S(u) = Σ weight(event) × 2^(−age / 90)
z-score z(u) = (S(u) − μ) / σ
Adjusted f(z) = exp(sinh(clamp(z, -3.0, 4.0)) / k)
Smoothing k = max(3, 12 − n_active)
Shares s(u) = f(z(u)) / Σf(z) × 1000

Active contributor window: 180 days (2× half-life). Founder included in normalization, excluded from share allocation.

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:

DefaultGoalFeasibilityTool

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

Source:

src/ometeotl_core/model/goal_tools.py

Local role: Default implementation of GoalFeasibilityTool based on deterministic condition-key matching.

Big-picture role: Baseline model-level feasibility evaluator used before domain-specific scoring or planners are introduced.

Inheritance:

GoalFeasibilityTool

Method:

evaluate(goal, projected) -> GoalFeasibilityResult

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:

DiagnosticBuilder

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

Source:

src/ometeotl_core/validation/diagnostic.py

Local role: Builds user-facing diagnostics from ValidationResult.

Big-picture role: Implements motivated rejection support and repair-ready issue suggestions.

Outputs:

DiagnosticEntry
DiagnosticReport

game utility.py Overview

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

This module defines concrete utility combinators and strategy ranking helpers.

Primary structures:

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

Goal

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

Source:

src/ometeotl_core/model/goals.py

Local role: First-class objective model object for one actor.

Big-picture role: Teleology representation primitive that remains domain-neutral while supporting final and intermediate objectives.

Inheritance:

ModelObject

Fields:

id: str
actor_id: str
kind: str (final or intermediate)
priority: float
status: str
horizon: dict
target_condition: dict
target_perception_id: Optional[str]
parent_goal_id: Optional[str]
child_goal_ids: list[str]
strategy_ids: list[str]

Methods:

add_child_goal(goal_id) -> None
remove_child_goal(goal_id) -> None
add_strategy(strategy_id) -> None
remove_strategy(strategy_id) -> None
to_dict() -> dict
from_dict(data) -> Goal

See also:

goal_tools.py Overview

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

This module provides model-level feasibility and admissibility helpers for goals.

Primary contracts:

GoalAdmissibilityChecker

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

Source:

src/ometeotl_core/model/goal_tools.py

Local role: Model-level F-13 checker for whether a goal is admissible for one actor under one perception.

Big-picture role: Guardrail for actor-consistent objective evaluation before strategy ranking.

Inheritance:

standard class

Method:

check(goal, actor, perception) -> GoalAdmissibilityResult

Checks include:

goal actor binding consistency
goal linkage in actor relations
blocking constraints from perception context
optional horizon capacity constraints

See also:

GoalAdmissibilityResult

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

Source:

src/ometeotl_core/model/goal_tools.py

Local role: Result container for actor-relative goal admissibility checks.

Fields:

admissible: bool
reason: str
blocking_constraints: list[str]

Methods:

to_dict() -> dict

See also:

GoalAdmissibilityChecker

GoalBuildStep

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

Source:

src/ometeotl_core/model/goals.py

Local role: Recursive declarative node used to build goal hierarchies.

Big-picture role: Input specification for hierarchy builders that construct Goal trees without introducing domain-specific teleology.

Inheritance:

dataclass

Fields:

kind: str (final or intermediate)
actor_id: str
target_condition: dict
horizon: dict
priority: float
status: str
children: list[GoalBuildStep]
metadata: dict

See also:

GoalDecompositionTree

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

Source:

src/ometeotl_core/model/goals.py

Local role: Container for one goal hierarchy rooted at a single goal id.

Big-picture role: Deterministic structure for intermediate-objective decomposition and hierarchy validation.

Inheritance:

dataclass

Fields:

root_goal_id: str
goals: dict[str, Goal]

Methods:

add_goal(goal) -> None
get_goal(goal_id) -> Optional[Goal]
children_of(goal_id) -> list[Goal]
parent_of(goal_id) -> Optional[Goal]
validate_tree() -> None
to_dict() -> dict
from_dict(data) -> GoalDecompositionTree

See also:

GoalFeasibilityResult

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

Source:

src/ometeotl_core/model/goal_tools.py

Local role: Result container for feasibility checks between a goal and a projected state.

Fields:

reachable: bool
confidence: float
matching_keys: list[str]
metadata: dict

Methods:

to_dict() -> dict

See also:

GoalFeasibilityTool

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

Source:

src/ometeotl_core/model/goal_tools.py

Local role: Abstract contract for evaluating whether a projected perception can satisfy a goal.

Big-picture role: Model-level extensibility seam for feasibility logic, independent of any game domain scoring policy.

Inheritance:

abstract base class

Method:

evaluate(goal, projected) -> GoalFeasibilityResult

See also:

goals.py Overview

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

This module defines first-class objective structures for teleology representation.

Primary structures:

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

LexicographicUtility

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

Source:

src/ometeotl_core/game/utility.py

Local role: Vector-valued utility combinator with explicit criterion ordering and direction.

Big-picture role: Game-layer multi-criteria scoring primitive for lexicographic ranking.

Inheritance:

UtilityFunction

Constructor:

LexicographicUtility(framework_id, metric_order, metric_directions=None)

Method:

evaluate(perception, actor, context) -> UtilityFrame

See also:

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

Overview

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

This page explains the internal workings of Ometeotl/ometeotl_core at three depth levels.

For API-level details, use Class Reference.

04/25/26 - major architectural overhaul: Local tests reveal the current architecture is too abstract for any practical implementation. It has been decided to :

to keep the current code in a core module ometeotl_core, which is intended to remain abstract;
to add a primary layer of specialization ometeotl_foundations, including :
- spatial: primary layer of spatial implementation of ometeotl_core;
- networks: primary layer of graph theory implementation of ometeotl_core
- …
to add, lastly, an adapter layer ometeotl_adapters, which implements each specialization layer with a reputable library.

Beginner View

Ometeotl/ometeotl_core is a modeling library where everything starts from a generic object, then becomes more specific.

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

RankedStrategy

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

Source:

src/ometeotl_core/game/utility.py

Local role: Result container for one evaluated strategy and its aggregate utility.

Fields:

strategy: Strategy
utility_frame: UtilityFrame
rank_key: tuple[float, …]
terminal_node_ids: list[str]
terminal_probabilities: dict

See also:

StrategyRanker

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:

StrategyRanker

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

Source:

src/ometeotl_core/game/utility.py

Local role: Ranks strategies by evaluating projected terminal nodes with a utility function.

Big-picture role: Game-layer bridge from projected strategy structures to comparable utility outcomes.

Inheritance:

standard class

Constructor:

StrategyRanker(utility_function)

Methods:

evaluate_strategy(strategy, actor, context=None) -> RankedStrategy
rank_strategies(strategies, actor, context=None) -> list[RankedStrategy]

Important behavior:

validates strategy trees before ranking
aggregates branch probabilities per child node
supports directed acyclic strategies with duplicate terminal paths by accumulating terminal path probabilities per node id
supports scalar and multi-criteria utility outputs

See also:

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

utility.py Overview

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

This module defines abstract utility contracts shared by model and game layers.

Primary structures:

UtilityFrame

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

Source:

src/ometeotl_core/model/utility.py

Local role: Typed wrapper for scalar or vector utility evaluation results.

Big-picture role: Standard utility payload shared by model-level utility contracts and game-level rankers.

Inheritance:

dataclass

Fields:

value: float or list[float]
framework_id: str
criteria_labels: list[str]
metadata: dict

Methods:

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

Properties:

is_multi_criteria
scalar_value

See also:

UtilityFunction

UtilityFunction

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

Source:

src/ometeotl_core/model/utility.py

Local role: Abstract utility interface required by the model layer.

Big-picture role: Domain-neutral contract defining how actor-relative perceived states are scored under an interpretive framework.

Inheritance:

abstract base class

Core contract:

framework_id property
is_multi_criteria property
evaluate(perception, actor, context) -> UtilityFrame

Helper behavior:

deterministic missing-metric resolution policies
standardized UtilityFrame construction helpers

Concrete game-layer implementations:

Validation Policy Profiles

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

Source:

src/ometeotl_core/validation/policy.py

Local role: Maps high-level hardening profiles to per-stage pipeline modes.

Available profiles:

observe_only
enforce_structure
enforce_domain

Entry point:

build_stage_modes(...)

Big-picture role: Progressive hardening control used by AuthorityCommandHandler and build_runtime(...).

ValidationContext

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

Source:

src/ometeotl_core/validation/base.py

Local role: Execution context passed to each validator stage.

Big-picture role: Carries policy mode plus actor/world/metadata payload needed by contextual validators.

Inheritance:

frozen dataclass

Parameters and fields:

stage: str
policy_mode: str
actor_id: str
world_id: str
metadata: JsonMap

ValidationIssue

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

Source:

src/ometeotl_core/validation/base.py

Local role: Atomic validation finding with code, severity, message, and context.

Big-picture role: Standardized issue contract shared by all validation stages and command boundary exports.

Inheritance:

frozen dataclass

Parameters and fields:

code: str
severity: str (error, warning, info)
message: str
object_id: str
path: str
suggestion: str
context: JsonMap

ValidationPipeline

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

Source:

src/ometeotl_core/validation/pipeline.py

Local role: Orchestrates ordered validator execution and result aggregation.

Big-picture role: Single staged entry point for validation policies across validation and core authority boundaries.

Key modes:

strict
lenient
warn_only

Key behavior:

per-stage mode overrides with stage_modes
error downgrading in warn_only
optional strict raising (ValidationException) when configured
metadata for executed validators and effective stage modes

ValidationResult

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

Source:

src/ometeotl_core/validation/base.py

Local role: Aggregated result of one validator stage or full pipeline execution.

Big-picture role: Stable structured contract consumed by diagnostics and authority command decisions.

Inheritance:

dataclass

Parameters and fields:

issues: list[ValidationIssue]
stage: str
policy_mode: str
metadata: JsonMap

Derived helpers:

summary
valid
errors
warnings
infos
merged_with(...)

Validators Overview

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

Sources:

Implemented validator families:

SyntacticValidator: JSON/YAML payload parse validity.
StructuralValidator: object shape, fields, relations, and hierarchy checks.
TemporalValidator: time-window coexistence checks.
SpatialValidator: relevant-space presence checks.
AdmissibilityValidator: goal admissibility under actor-perception constraints.
EpistemicValidator: epistemic status coherence checks.
CompletenessValidator: minimum/recommended/full completeness thresholds.

WeightedSumUtility

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

Source:

src/ometeotl_core/game/utility.py

Local role: Scalar utility combinator that computes weighted linear sums over metrics.

Big-picture role: Default game-layer scalar scoring primitive used by StrategyRanker.

Inheritance:

UtilityFunction

Constructor:

WeightedSumUtility(framework_id, metric_weights)

Method:

evaluate(perception, actor, context) -> UtilityFrame

See also:

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:

World export

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

Source:

src/ometeotl_core/io/exporters.py

Local role: Canonical JSON and YAML serialization of a World instance.

Big-picture role: The IO export layer is a thin orchestration wrapper. It calls World.to_dict() for the canonical payload, normalizes all guarded container subclasses to plain Python dicts and lists via _deep_plain_copy, then formats the result to the requested text format. This keeps serialization ownership in model and format ownership in io.

Public functions

`world_to_mapping(world)`

Returns the canonical plain-dict payload for a world. Uses _deep_plain_copy to strip guarded subclasses before returning, so the result is safe to pass to any serializer.

World import

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

Source:

src/ometeotl_core/io/importers.py

Local role: Validated reconstruction of a World from JSON text, YAML text, or an already-parsed mapping.

Big-picture role: The import pipeline composes the existing SyntacticValidator, StructuralValidator, and ValidationPipeline from ometeotl_core.validation with World.from_dict from ometeotl_core.model. It keeps parse, validate, and reconstruct as separate internal steps so each failure mode is individually diagnosable. Business logic and serialization rules remain in model; validation rules remain in validation; IO only orchestrates.

`WorldImportResult`

Frozen dataclass returned by every import helper.

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: