Generation on Ometeotl, an abstract decision meta-model

ContextualBuilder / per-kind builders

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

Source:

src/ometeotl_core/generation/context_builder.py

Local role: Typed class-based abstraction wrapping the function-based builders in builders.py. Provides a stable override point for kind-specific generation behavior.

Big-picture role: Enables callers to compose or replace per-kind generation logic without touching the pipeline. Satisfies the pluggable builder requirement of the generation architecture (F-16).

Inheritance (ContextualBuilder):

ABC, Generic[TGenerated]

Parameters and fields:

kind: str — class-level attribute; must be declared on each concrete subclass

Methods (ContextualBuilder):

ensure_kind(context) — raises ValueError if context.kind does not match self.kind
build(context) -> TGenerated — abstract; must be implemented by subclasses

Concrete builders:

ContextualGenerationPipeline / GenerationResult

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

Source:

src/ometeotl_core/generation/pipeline.py

Local role: Orchestrates the full generation workflow: rule application → builder dispatch → optional registration → optional validation → structured result.

Big-picture role: Top-level entry point for the generation architecture (F-16 to F-22). Accepts a GenerationContext, applies the configured GenerationRuleSet, delegates to the appropriate builder, and returns a GenerationResult carrying the generated object, applied rule names, validation outcome, and repair suggestions.

Parameters and fields (ContextualGenerationPipeline):

rules: GenerationRuleSet — rule set applied before building; defaults to combined_generation_rules()
validation_pipeline: ValidationPipeline | None — optional validation pipeline; only runs when context.validate=True

Methods (ContextualGenerationPipeline):

Generation examples

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

Source:

src/ometeotl_core/generation/examples.py

Local role: Self-contained runnable demo scenarios for the contextual generation pipeline. Each function is independent and illustrates one generation pattern end to end.

Big-picture role: Executable documentation for the generation architecture (F-16 to F-22). Run python -m ometeotl_core.generation.examples to see all four scenarios.

Module-level helpers:

demo_simple_world() — generates a world with 2 spaces and 1 placed actor; demonstrates nested contexts and GenerationPlacement
demo_multi_actor_world() — generates a world with 3 actors and temporal/spatial constraint propagation; demonstrates deduplication and combined_generation_rules
demo_perception_generation() — generates a Perception object for an actor observing a known space; demonstrates metadata-driven perception and registry-selected rule sets
demo_goal_generation() — generates a Goal with admissibility constraints; demonstrates confidence clamping, capability propagation, and priority validation
run_all() — runs all four scenarios in sequence; called when the module is executed directly

Notes:

GenerationContext / GenerationPlacement

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

Source:

src/ometeotl_core/generation/context.py

Local role: Declarative input dataclass threaded through every generation function and builder. Carries identity, attributes, nested child contexts, placement instructions, and optional constraint overrides.

Big-picture role: Central data-transfer object of the generation pipeline (F-16 to F-22). Consumed by ContextualBuilder, the rule engine, and ContextualGenerationPipeline.

Parameters and fields (GenerationContext):

kind: str — target entity kind: "world", "actor", "goal", "strategy", "perception", "space", "resource", "action"
id: str — stable identity of the generated object
label: str — promoted into attributes["label"] by the promote_label rule
attributes: dict — arbitrary key/value pairs forwarded to the model object
relations: dict[str, list[str]] — named relation groups; duplicates deduplicated by normalize_relations
state: dict, context: dict, provenance: dict — forwarded verbatim to the model object
spaces, actors, resources, goals, strategies, actions: list[GenerationContext] — nested child contexts for world generation
placements: list[GenerationPlacement] — explicit object-to-space placement instructions
metadata: dict — read by constraint propagation rules; also forwarded into merged_context()
rules: dict — rule override hints (reserved)
constraints: dict — constraint declarations consumed by the rule engine
operation: str — "create" (default), "partial_update", "corrective_update"
registration_policy: str — "none" (default), "if_available", "require"
validate: bool — if True, pipeline runs validation after generation
validation_mode: str — "lenient" (default) or "strict"
stage_modes: dict[str, str] — per-stage validation mode overrides

Methods:

GenerationRule / GenerationRuleSet / RuleRegistry

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

Source:

src/ometeotl_core/generation/rule_engine.py

Local role: Pluggable, ordered transformation layer that refines a GenerationContext before it is handed to builders. All rules are deterministic: same input → same output, no side effects.

Big-picture role: Implements the rule engine and constraint propagation requirements of F-17 and F-18. Consumed by ContextualGenerationPipeline. The RuleRegistry enables pluggable policy selection without modifying pipeline code.

Parameters and fields (GenerationRule, frozen dataclass):

name: str — unique human-readable identifier
predicate: Callable[[GenerationContext], bool] — guard; rule runs only when this returns True
apply: Callable[[GenerationContext], GenerationContext] — pure transformation returning a new context

Methods (GenerationRule):

LLMGenerationAdapter / LLMRefinementResult

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

Source:

src/ometeotl_core/generation/llm_integration.py

Local role: Provider-agnostic bridge that converts a GenerationContext into a prompt, calls an external text generator, parses the response, and returns a refined GenerationContext.

Big-picture role: Optional pre-refinement step in the hybrid generation workflow (F-20). Keeps LLM usage opt-in and auditable — the pipeline does not call the adapter automatically.

Parameters and fields (LLMGenerationAdapter):

text_generator: Callable[[str], str] — any callable that takes a prompt and returns a text response
response_parser: Callable[[str], Mapping[str, Any]] | None — optional custom parser; defaults to json.loads-based mapping extraction

Methods (LLMGenerationAdapter):