How Guided Tours Are Ordered and Learning Sequence Determined in Egonex

Guided tours in Egonex are ordered either by an LLM-generated sequence that follows dependency flow and logical file grouping, or by a deterministic heuristic using topological sorting and entry-point detection, with both approaches assigning a sequential order field to create a linear learning progression.

The Egonex Understand Anything platform generates guided tours as structured learning paths through a project's knowledge graph. The ordering of these tours and the resulting learning sequence depend on whether the system leverages a language model or employs graph-based heuristics. This article examines the dual-path architecture implemented in the Egonex-AI/Understand-Anything repository, detailing how TourStep objects are sequenced to optimize codebase comprehension.

Two Methods for Ordering Guided Tours

The tour generation system in tour-generator.ts employs two distinct strategies for determining the order of guided steps.

LLM-Generated Tour Sequences

When a language model is available, the buildTourGenerationPrompt function constructs a detailed prompt instructing the model to generate a step-by-step guided tour. According to the source code in understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts, the prompt explicitly directs the LLM to:

• Start with entry-point or high-level overview files
• Follow the natural dependency flow
• Group related files together
• End with supporting utilities or concepts

The model must return a JSON object containing a steps array where each step includes an order field beginning at 1. This ordering reflects the model's semantic interpretation of the project structure based on the provided knowledge graph.

Heuristic-Based Tour Generation

If no LLM is configured or as a fallback mechanism, the generateHeuristicTour function creates a deterministic sequence based purely on graph topology. Implemented in understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts, this algorithm:

1. Identifies entry points (nodes with zero incoming edges) and places them first
2. Applies Kahn's algorithm for topological sorting to preserve dependency direction
3. Groups nodes by layer when layer data exists, maintaining topological order within each group
4. Batches remaining code nodes (typically three per step) when no layers are defined
5. Collects concept nodes (type concept) into a final "Key Concepts" step

After assembly, the system assigns sequential order numbers (1, 2, 3...) to create the final linear progression.

How the Learning Sequence Is Determined

The learning sequence emerges from specific topological and semantic rules encoded in the generation logic.

Entry Points and Dependency Flow

In the heuristic approach, the algorithm prioritizes nodes with no incoming edges as starting points. This ensures learners encounter standalone files or high-level modules before diving into dependent implementations. The topological sort guarantees that prerequisite code is always visited before the files that depend on it.

Layer-Aware Grouping

When the knowledge graph includes layer metadata, the heuristic respects these architectural boundaries while maintaining dependency order. Nodes within the same layer are grouped together in a single step, allowing learners to understand horizontal slices of the architecture before moving deeper.

Concept Node Handling

Unlike code nodes that follow the dependency graph, concept nodes are deliberately deferred to the final step. This separation ensures that learners first understand the concrete implementation and file relationships before encountering abstract architectural concepts.

Implementing Tour Generation

The following code examples demonstrate how to interact with the tour generation system.

Building the LLM Prompt

import { buildTourGenerationPrompt } from "./tour-generator.js";

const prompt = buildTourGenerationPrompt(myKnowledgeGraph);
console.log(prompt);   // Sent to the LLM; response must contain a JSON "steps" array

Parsing the LLM Response

import { parseTourGenerationResponse } from "./tour-generator.js";

const llmResponse = `...`; // LLM output
const steps = parseTourGenerationResponse(llmResponse);
steps.forEach(s => console.log(`${s.order}: ${s.title}`));

Generating a Deterministic Heuristic Tour

import { generateHeuristicTour } from "./tour-generator.js";

const heuristicTour = generateHeuristicTour(myKnowledgeGraph);
heuristicTour.forEach(step => {
  console.log(`Step ${step.order}: ${step.title}`);
  console.log(`  Nodes: ${step.nodeIds.join(", ")}`);
});

Verifying Ordering in Tests

The test suite in understand-anything-plugin/packages/core/src/__tests__/tour-generator.test.ts validates these behaviors:

// From tour-generator.test.ts
it("starts with entry‑point nodes", () => {
  const tour = generateHeuristicTour(sampleGraph);
  expect(tour[0].nodeIds).toContain("file:src/index.ts");
});

Summary

• Guided tours in Egonex are ordered through either LLM-generated sequences or heuristic-based topological sorting.
• The buildTourGenerationPrompt function instructs language models to follow dependency flow and logical grouping when generating steps.
• The generateHeuristicTour function uses Kahn's algorithm to produce a deterministic, dependency-preserving sequence starting from entry points.
• Concept nodes are isolated in a final step, ensuring concrete code understanding precedes abstract concepts.
• The final output always includes a sequential order field starting at 1, ensuring a linear progression through the TourStep array.

Frequently Asked Questions

What file contains the core tour generation logic?

The primary implementation resides in understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts. This file contains the buildTourGenerationPrompt, generateHeuristicTour, and parseTourGenerationResponse functions that determine how guided tours are ordered.

How does the heuristic algorithm determine the starting point of a tour?

The heuristic identifies entry points as nodes with zero incoming edges in the knowledge graph. These nodes represent files or modules with no dependencies, making them logical starting positions for newcomers. The algorithm places these entry points in the first steps before proceeding with the topological sort.

Can the LLM override the heuristic ordering?

The system uses an either/or approach rather than an override mechanism. If an LLM is available and the buildTourGenerationPrompt path is executed, the LLM's semantic interpretation determines the order. If not, the system falls back to generateHeuristicTour. The UI component in understand-anything-plugin/src/onboard-builder.ts displays whichever sequence is generated.

How are concept nodes handled differently from code nodes?

While code nodes follow the dependency graph and topological sort, concept nodes (type concept) are collected separately and appended as a final "Key Concepts" step. This ensures learners encounter concrete implementation files before abstract architectural concepts, regardless of whether the LLM or heuristic method is used.

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