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

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 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. 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 (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:

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.

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