Handbook

Structured output composition (LCDL)

Generic structured data → markdown composition lives in forge_lcdl.output. Domain shapes and layouts are registered by consumers (KA, Cockpit, etc.) at process startup — not shipped inside LCDL core.

Updated

Public API

from forge_lcdl.output import (
    compose,
    register_block_type,
    register_layout,
    register_shape_validator,
    registered_shapes,
    registered_block_types,
)
Function Purpose
compose(shape_id, data, *, consumer=None) Walk a registered layout, bind fields from data, return markdown
register_layout(shape_id, spec, *, consumer=None) Register a LayoutSpec (ordered block descriptors)
register_block_type(type_id, renderer) Register a block renderer (BlockSpec, data, ComposeContext → str)
register_shape_validator(shape_id, fn) Optional pre-compose payload check

Raises UnknownShapeError / UnknownBlockTypeError when a shape or block type is missing.

Built-in block types (LCDL core)

heading, paragraph, bullet_list, markdown_table, section_if, bind_field

Block renderers are pure (no I/O, no consumer imports).

Consumer pack pattern

Consumers ship an install_*_output_pack() that registers layouts, optional custom block types, and validators:

def install_ka_output_pack() -> None:
    register_block_type("ka.inventory_glance", render_inventory_glance)
    register_layout("presentation.comparison@1", COMPARISON_LAYOUT, consumer="ka")
    register_shape_validator("presentation.comparison@1", validate_comparison_payload)

Call once before the first compose() (KA: lcdl_bridge.make_run_lcdl).

Layout spec

Layouts are lists of block descriptors:

{"type": "heading", "static": {"level": 2, "text": "Executive summary"}}
{"type": "bind_field", "bind": "executive_summary"}
{"type": "ka.comparison_table", "bind": "comparison_table"}

Use when on a block to skip sections when bound data is empty.

Test fixture shape

LCDL tests register structured.document@1 in fixtures only — no consumer domain in core tests.

  • Task packs — parallel extension model for governed LLM tasks
  • Knowledge index — evidence retrieval vs presentation compose