# How the Bundle Synthesizer Generates Documentation from Extracted Source Concepts

> Learn how the bundle synthesizer generates documentation from source concepts using a generative model and deterministic fallback logic. Explore its capabilities.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/index.md) front matter. This creates a navigable hierarchy where every directory contains a machine-generated description derived from its contents.

## Implementation Example

```python
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:

```python
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/bundle/index.py) — Orchestrates directory traversal and persists generated descriptions to [`index.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/index.md) files via `regenerate_indexes`.
- [`okf/src/reference_agent/bundle/document.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/bundle/document.py) — Parses individual markdown documents for the index builder.
- [`okf/src/reference_agent/tools/bundle_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/bundle/index.py) writes synthesized descriptions into each directory's [`index.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/index.md) file within the YAML front matter, creating the hierarchical documentation structure that defines the OKF bundle's navigation and metadata.