neograph-dev-rendering

Neograph Rendering Dispatch

Provides the complete rendering architecture: how Pydantic models become text for LLMs, the dispatch hierarchy, inline vs template-ref prompt distinction, and the BAML default rendering behavior.

The Two Prompt Systems

Neograph has two fundamentally different prompt resolution paths. Mixing them up is the #1 source of rendering bugs.

Inline Prompts (${var} syntax)

Detected by: contains a space OR contains ${. Resolved by: _substitute_vars() in _llm.py.

Node("proc", prompt="Summarize: ${seed.text}", ...)

• Neograph resolves ${var} and ${var.field} internally
• Consumer's prompt_compiler is NEVER called
• Input data must be raw (not BAML-rendered) for dotted access
• _render_input in _dispatch.py skips rendering for inline prompts

Template-Ref Prompts (bare name)

Detected by: no space AND no ${. Resolved by: consumer's prompt_compiler callback.

Node("proc", prompt="rw/summarize", ...)

• Neograph passes the name + rendered input_data to prompt_compiler
• Input data is BAML-rendered before reaching the prompt_compiler
• Consumer does template.format(**data) or equivalent
• Placeholder format is {var} (Python str.format), NOT ${var}

Rendering Dispatch Hierarchy

For each Pydantic value flowing into a prompt:

1. render_for_prompt() method wins if defined on the model (always checked, regardless of renderer config)
2. Explicit renderer (XmlRenderer / DelimitedRenderer / JsonRenderer) if configured via node.renderer or configure_llm(renderer=...)
3. BAML default via describe_value() — the fallback when no renderer is configured. Symmetric with tool-result rendering.
4. Primitives pass through unchanged (str, int, etc.)

RenderedInput dataclass

renderers.py:32. The single object that bundles all rendering artifacts:

• raw -- original Pydantic models for inline ${var} dotted access
• rendered -- BAML strings for template-ref prompts
• flattened -- extra fields from render_for_prompt() BaseModel returns (template-ref only)
• available_keys_inline -- keys valid for inline prompts (raw dict keys only)
• available_keys_template -- keys valid for template-ref prompts (raw + flattened + extras)
• for_template_ref property -- merges rendered + flattened