How the Bundle Synthesizer Generates Documentation from Extracted Source Concepts

The bundle synthesizer converts extracted source concept titles and descriptions into concise, human-readable directory summaries using a generative model, with deterministic fallback logic when the LLM fails.

The GoogleCloudPlatform/knowledge-catalog repository implements an Open Knowledge Format (OKF) system that transforms raw source code metadata into structured documentation bundles. At the core of this pipeline, the bundle synthesizer generates documentation by processing lists of extracted concepts into single-sentence descriptions that populate directory indexes.

The synthesize_description Entry Point

Located in okf/src/reference_agent/bundle/synthesizer.py, the synthesize_description function serves as the primary interface for documentation generation. It accepts three parameters:

• rel_path — The directory's path relative to the bundle root.
• children — A list of (title, description) tuples for each child document or subdirectory.
• model — The identifier of the generative model (e.g., Gemini) to invoke.

The children parameter carries the extracted source concepts, where each tuple contains the document title and an optional description. When descriptions are missing, the corresponding string is empty.

Prompt Construction and LLM Instructions

The synthesizer builds a structured prompt using the constant _PROMPT_TEMPLATE. This template injects two key variables:

1. {rel_path} — The relative directory path.
2. {contents} — A markdown-style list where each child appears as - Title: Description (or simply - Title when no description exists).

According to the source code, the prompt explicitly instructs the model to "summarize a directory ... in ONE sentence (max ~25 words)" and mandates that the output consist solely of that sentence ending with a single period. This constraint ensures consistency across automatically generated documentation.

Calling the Generative Model

Within the synthesizer's try block, the code imports google.genai and instantiates genai.Client(). It then calls client.models.generate_content with the specified model name and the prepared prompt string.

The function extracts generated text from the response object's .text attribute, strips surrounding whitespace, and returns the first line. If the model returns empty content or raises an exception, execution shifts to the fallback handler.

Fallback Logic for Failed Generations

When the LLM fails, the _fallback(children) function generates a deterministic description. It counts the total entries and joins their titles with commas, formatting the result as:

"Contains {count} entries: Title A, Title B, Title C."

If the children list is empty, the fallback returns an empty string, ensuring the bundle generation pipeline continues uninterrupted even when source concepts are sparse or the generative service is unavailable.

Integration with Bundle Indexing

The generated descriptions persist through regenerate_indexes in okf/src/reference_agent/bundle/index.py. This function traverses the bundle structure, collects child documents for each directory, invokes synthesize_description to generate appropriate summaries, and writes the results into each directory's index.md front matter. This creates a navigable hierarchy where every directory contains a machine-generated description derived from its contents.

Implementation Example

from reference_agent.bundle.synthesizer import synthesize_description

# Example extracted concepts for a directory "data/analytics"

children = [
    ("UserEvents", "Tracks each user interaction."),
    ("PageViews", "Aggregated view counts per page."),
    ("Sessions", ""),  # No description available

]

description = synthesize_description(
    rel_path="data/analytics",
    children=children,
    model="gemini-flash-latest",
)

print(description)

# → "Contains analytics data about user events, page views, and sessions."

When the LLM is unavailable or the directory contains no children:

description = synthesize_description(
    rel_path="empty/dir",
    children=[],
    model="gemini-flash-latest",
)

# Returns an empty string because there are no children.

Key Files in the Documentation Pipeline

• okf/src/reference_agent/bundle/synthesizer.py — Builds prompts, executes LLM calls, and implements title-based fallback descriptions.
• okf/src/reference_agent/bundle/index.py — Orchestrates directory traversal and persists generated descriptions to index.md files via regenerate_indexes.
• okf/src/reference_agent/bundle/document.py — Parses individual markdown documents for the index builder.
• okf/src/reference_agent/tools/bundle_tools.py — High-level orchestration of bundle creation and index regeneration workflows.

Summary

• The bundle synthesizer in okf/src/reference_agent/bundle/synthesizer.py transforms extracted source concepts into directory descriptions using the synthesize_description function.
• It formats input data using _PROMPT_TEMPLATE to request one-sentence summaries under 25 words from a specified generative model.
• The implementation utilizes google.genai.Client and client.models.generate_content to produce human-readable text.
• A _fallback mechanism ensures deterministic output by concatenating titles when LLM generation fails or returns empty content.
• Final descriptions integrate into OKF bundles through regenerate_indexes in okf/src/reference_agent/bundle/index.py, powering the automated documentation structure.

Frequently Asked Questions

What input format does the bundle synthesizer require?

The synthesize_description function expects a rel_path string and a children list containing tuples of (title, description). The description element can be an empty string when no additional context is available for a particular source concept.

How does the synthesizer handle LLM service failures?

When the generative model returns no text or raises an exception, the synthesizer invokes _fallback(children) to create a deterministic description that reports the total entry count and lists titles separated by commas, ensuring the bundle generation pipeline remains robust.

Which generative models work with the bundle synthesizer?

According to the source code in synthesizer.py, any model supported by the google.genai library can be specified via the model parameter, including variants like gemini-flash-latest or other compatible Gemini model identifiers available through the Google GenAI API.

Where do the generated descriptions appear in the final output?

The regenerate_indexes function in okf/src/reference_agent/bundle/index.py writes synthesized descriptions into each directory's index.md file within the YAML front matter, creating the hierarchical documentation structure that defines the OKF bundle's navigation and metadata.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}