# How Guided Tours Are Ordered and Learning Sequence Determined in Egonex

> Discover how Egonex orders guided tours using LLM or deterministic heuristics to define a clear learning sequence based on file grouping and dependency flow.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-21

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/__tests__/tour-generator.test.ts) validates these behaviors:

```typescript
// 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.