# How the Guided Tour Builder Generates Learning Sequences in Understand-Anything

> Learn how the Guided Tour Builder in Understand Anything creates learning sequences. It uses LLM prompts, knowledge graph data, and topological sort for effective learning paths.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-13

---

**The guided tour builder creates step-by-step learning sequences by constructing LLM prompts from knowledge graph data, parsing the response into structured tour steps, and falling back to a deterministic topological sort when the LLM fails.**

The Egonex-AI/Understand-Anything repository helps developers explore unfamiliar codebases through automatically generated guided tours. The **guided tour builder** transforms static knowledge graph data into interactive, educational walkthroughs using a hybrid approach that combines LLM intelligence with algorithmic reliability. Understanding this pipeline reveals how the tool balances AI creativity with deterministic fallbacks to ensure consistent onboarding experiences.

## The Three-Stage Tour Generation Pipeline

The tour generation process in [`understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts) operates through three distinct stages: prompt construction, response parsing, and heuristic fallback.

### Stage 1: Prompt Construction with buildTourGenerationPrompt

When a tour is requested, the `buildTourGenerationPrompt` function (lines 7-45) assembles a comprehensive LLM prompt containing structured project metadata. This includes the project name, description, languages, and frameworks drawn from the knowledge graph's *project* section. The prompt also contains a compact list of all nodes with their type, name, file path, and summary, plus up to 50 edges describing dependencies. If the analyzer has detected architectural layers, these are included with their names, descriptions, and node IDs.

The function returns a plain-text prompt that explicitly instructs the LLM to *"Generate a guided tour … Return a JSON object with a `steps` array …"*. This structured approach ensures the LLM receives sufficient context to generate a meaningful learning sequence while maintaining a predictable output format.

### Stage 2: LLM Response Parsing with parseTourGenerationResponse

Raw LLM outputs may arrive as plain JSON or wrapped in markdown code fences. The `parseTourGenerationResponse` function (lines 66-100) handles this variability by extracting the JSON content regardless of formatting. It validates that each step contains the required fields: `order`, `title`, `description`, and `nodeIds`. Malformed entries are discarded during this process, ensuring only valid data reaches the final tour array.

The function returns an array of `TourStep` objects as defined in [`understand-anything-plugin/packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/types.ts). These type-safe objects guarantee that downstream consumers receive consistently structured data for rendering.

### Stage 3: Heuristic Fallback with generateHeuristicTour

If the LLM fails to produce valid tour steps or returns an empty array, the system invokes `generateHeuristicTour` (lines 122-190) as a deterministic fallback. This algorithm separates *concept* nodes from code nodes, then builds an adjacency map from the graph's edges to compute an **in-degree** table for each node. It performs a **Kahn topological sort** to obtain a dependency-ordered list of code nodes, ensuring learners encounter prerequisites before dependent components.

When architectural layers are present, the algorithm groups nodes by layer according to the topological order; otherwise, it batches nodes into groups of three per step. Finally, it appends a "Key Concepts" step for any concept nodes and assigns sequential `order` numbers to all steps. This guarantees a valid learning sequence even when LLM services are unavailable or unresponsive.

## Rendering Tours into Onboarding Guides

Once generated, the `TourStep[]` array is attached to the `KnowledgeGraph.tour` field. Downstream consumers such as the `buildOnboardingGuide` function in [`understand-anything-plugin/src/onboard-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/onboard-builder.ts) (lines 61-89) iterate over this array to render a readable walkthrough. Each step becomes a markdown section showing the files to examine and optional language tips, transforming the structured tour data into a human-readable onboarding document.

## Implementation Example

Here is a complete workflow demonstrating how to generate and attach a tour using the core analyzer functions:

```typescript
import {
  buildTourGenerationPrompt,
  parseTourGenerationResponse,
  generateHeuristicTour,
} from "@understand-anything/core";

// Assume `graph` is the KnowledgeGraph already built by the analyzer.
const prompt = buildTourGenerationPrompt(graph);

// Send `prompt` to the configured LLM (e.g., Claude, GPT‑4) and receive `rawResponse`.
const rawResponse = await llm.complete(prompt);

// Try to parse the LLM output.
let tour = parseTourGenerationResponse(rawResponse);

// If parsing failed, fall back to the heuristic generator.
if (tour.length === 0) {
  tour = generateHeuristicTour(graph);
}

// Attach the tour to the graph for downstream rendering.
graph.tour = tour;

```

This implementation leverages the hybrid approach ensuring that `graph.tour` always contains a valid sequence, whether derived from LLM intelligence or the heuristic topological sort.

## Summary

- The guided tour builder uses a three-stage pipeline: prompt construction, LLM response parsing, and heuristic fallback.
- `buildTourGenerationPrompt` compiles project metadata, nodes, edges, and layers into a structured LLM prompt.
- `parseTourGenerationResponse` extracts and validates JSON from LLM outputs, requiring `order`, `title`, `description`, and `nodeIds` fields.
- `generateHeuristicTour` provides deterministic fallback using Kahn topological sort to dependency-order nodes.
- The system separates concept nodes from code nodes, grouping the latter by layer or in batches of three.
- Final tours attach to `KnowledgeGraph.tour` and render via `buildOnboardingGuide` into markdown onboarding documents.

## Frequently Asked Questions

### What data sources does the guided tour builder use to create learning sequences?

The builder extracts project metadata, node summaries, and dependency edges directly from the knowledge graph. It includes project name, description, languages, frameworks, node file paths, and up to 50 edges describing relationships between components.

### How does the heuristic fallback algorithm order nodes when the LLM fails?

The `generateHeuristicTour` function computes an in-degree table and performs a Kahn topological sort on the dependency graph. This ensures prerequisite files appear before dependent ones, creating a logically sequenced learning path without LLM intervention.

### What validation does the tour parser perform on LLM responses?

The `parseTourGenerationResponse` function checks that each step contains mandatory fields: `order`, `title`, `description`, and `nodeIds`. It also handles markdown code fences and discards malformed entries, returning only valid `TourStep` objects.

### How does the system handle concept nodes differently from code nodes?

During heuristic generation, concept nodes are separated from code nodes and added to a final "Key Concepts" step. Code nodes are ordered topologically and grouped by architectural layer or batched into groups of three, while concept nodes appear as a separate concluding step for theoretical overview.