Gaia Lang Compiler API

Status: Generated from current Python docstrings and type hints.

Package compilation entrypoints used to lower Gaia Lang packages into compiled artifacts.

gaia.engine.lang.compiler

Compiler entry points for Gaia Lang packages.

CompiledPackage dataclass

CompiledPackage(graph: LocalCanonicalGraph, knowledge_ids_by_object: dict[int, str], strategies_by_object: dict[int, Strategy], action_label_map: dict[str, str] = dict(), target_action_labels_by_id: dict[str, str] = dict(), formalization_manifest: dict[str, Any] = (lambda: {'version': 1, 'dependencies': [], 'materializations': []})(), review: ReviewManifest | None = None)

Compiled Gaia package plus runtime-object to IR-ID mappings.

to_json

to_json() -> dict[str, Any]

Serialize the compiled graph as Gaia IR JSON.

Source code in gaia/engine/lang/compiler/compile.py

def to_json(self) -> dict[str, Any]:
    """Serialize the compiled graph as Gaia IR JSON."""
    return self.graph.model_dump(mode="json", exclude_none=True, serialize_as_any=True)

compile_package

compile_package(pkg: CollectedPackage, *, references: dict[str, Any] | None = None) -> dict[str, Any]

Compile collected declarations into LocalCanonicalGraph JSON.

Source code in gaia/engine/lang/compiler/compile.py

def compile_package(
    pkg: CollectedPackage,
    *,
    references: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Compile collected declarations into LocalCanonicalGraph JSON."""
    return compile_package_artifact(pkg, references=references).to_json()

compile_package_artifact

compile_package_artifact(pkg: CollectedPackage, *, references: dict[str, Any] | None = None) -> CompiledPackage

Compile collected declarations into Gaia IR plus runtime mappings.

First, predicate / equation lowering registers any CDF-derived predicate prior records. Then the package's :class:ResolutionPolicy resolves all per-claim metadata['prior_records'] populated by register_prior(), predicate lowering, or the claim(prior=...) shortcut. The winning value is written to metadata['prior'] so downstream BP / render / brief consumers see a single resolved prior.

Source code in gaia/engine/lang/compiler/compile.py

def compile_package_artifact(
    pkg: CollectedPackage,
    *,
    references: dict[str, Any] | None = None,
) -> CompiledPackage:
    """Compile collected declarations into Gaia IR plus runtime mappings.

    First, predicate / equation lowering registers any CDF-derived predicate
    prior records. Then the package's :class:`ResolutionPolicy` resolves all
    per-claim ``metadata['prior_records']`` populated by ``register_prior()``,
    predicate lowering, or the ``claim(prior=...)`` shortcut. The winning value
    is written to ``metadata['prior']`` so downstream BP / render / brief
    consumers see a single resolved prior.
    """
    if references is None:
        references = {}

    from gaia.engine.lang.compiler.distribution_diagnostics import emit_distribution_warnings
    from gaia.engine.lang.compiler.predicate_lowering import lower_predicate_priors

    discover_and_register_extensions()

    lower_predicate_priors(pkg)
    _resolve_pkg_priors_with_package_policy(pkg)
    emit_distribution_warnings(pkg)

    knowledge_collection = _KnowledgeCollector(pkg).collect()
    knowledge_map = _assign_knowledge_ids(pkg, knowledge_collection.nodes)
    ir_knowledges = _build_ir_knowledges(pkg, knowledge_collection.nodes, knowledge_map)
    ir_operators, operator_target_ids_by_object = _compile_top_level_operators(
        pkg,
        knowledge_map,
        knowledge_collection.formal_operators,
    )

    generated_knowledges: list[IrKnowledge] = []
    strategy_compiler = _StrategyCompiler(pkg, knowledge_map, generated_knowledges)
    ir_strategies, strategy_target_ids_by_object = _compile_package_strategies(
        pkg,
        strategy_compiler,
    )

    action_compiler = _ActionCompiler(
        pkg=pkg,
        knowledge_map=knowledge_map,
        ir_knowledges=ir_knowledges,
        ir_strategies=ir_strategies,
        generated_knowledges=generated_knowledges,
    )
    action_compiler.compile_non_compose_actions()

    formula_generated = _lower_formula_claims(
        pkg, knowledge_collection.nodes, knowledge_map, ir_knowledges
    )
    action_labels_by_object = _build_action_labels_by_object(pkg)
    extension_lowered = lower_registered_actions(
        ActionLoweringContext(
            knowledge_nodes=knowledge_collection.nodes,
            actions=tuple(getattr(pkg, "actions", ())),
            namespace=pkg.namespace,
            package_name=pkg.name,
            knowledge_map=knowledge_map,
            action_labels_by_object=action_labels_by_object,
            existing_operators=[
                *ir_operators,
                *action_compiler.action_operators,
                *formula_generated.operators,
            ],
        )
    )
    _apply_formula_knowledge_updates(
        ir_knowledges,
        metadata_updates=extension_lowered.metadata_updates,
        parameter_updates={},
    )
    _merge_action_label_targets(
        action_compiler.action_label_map,
        action_compiler.target_action_labels_by_id,
        extension_lowered.action_label_map,
        extension_lowered.target_action_labels_by_id,
    )
    action_compiler.action_target_ids_by_object.update(
        extension_lowered.action_target_ids_by_object
    )

    ir_composes = action_compiler.compile_compose_actions(
        strategy_target_ids_by_object=strategy_target_ids_by_object,
        operator_target_ids_by_object=operator_target_ids_by_object,
    )
    action_compiler.compile_materializations()
    extension_lowered_knowledges_updated = _ReferenceScanner(
        pkg=pkg,
        references=references,
        knowledge_nodes=knowledge_collection.nodes,
        knowledge_map=knowledge_map,
        action_label_map=action_compiler.action_label_map,
        action_labels_by_object=action_labels_by_object,
        ir_knowledges=ir_knowledges,
        generated_knowledges=generated_knowledges,
        formula_generated_knowledges=formula_generated.knowledges,
        extension_lowered_knowledges=extension_lowered.knowledges,
        ir_strategies=ir_strategies,
        formula_generated_strategies=formula_generated.strategies,
        extension_strategies=extension_lowered.strategies,
        ir_operators=ir_operators,
        action_operators=action_compiler.action_operators,
        formula_generated_operators=formula_generated.operators,
        extension_operators=extension_lowered.operators,
        ir_composes=ir_composes,
    ).scan()

    graph = _build_graph(
        pkg,
        ir_knowledges=ir_knowledges,
        generated_knowledges=generated_knowledges,
        formula_generated=formula_generated,
        extension_lowered=extension_lowered,
        extension_lowered_knowledges_updated=extension_lowered_knowledges_updated,
        ir_operators=ir_operators,
        action_operators=action_compiler.action_operators,
        action_formula_graphs=action_compiler.formula_graphs,
        ir_strategies=ir_strategies,
        ir_composes=ir_composes,
    )
    compiled = CompiledPackage(
        graph=graph,
        knowledge_ids_by_object=dict(knowledge_map),
        strategies_by_object=dict(strategy_compiler.compiled_strategies),
        action_label_map=action_compiler.action_label_map,
        target_action_labels_by_id=action_compiler.target_action_labels_by_id,
        formalization_manifest={
            "version": 1,
            "dependencies": action_compiler.formalization_dependencies,
            "materializations": action_compiler.formalization_materializations,
        },
    )
    from gaia.engine.lang.review.manifest import generate_review_manifest

    compiled.review = generate_review_manifest(compiled)
    return compiled