0
# LlamaIndex.TS
1

2
LlamaIndex.TS is a comprehensive TypeScript/JavaScript data framework that enables developers to integrate large language models (LLMs) with their own data. It provides a lightweight, easy-to-use set of tools for building LLM applications that can process and query custom data sources, supporting multiple JavaScript runtimes including Node.js, Deno, Bun, and edge environments.
3

4
## Package Information
5

6
- **Package Name**: llamaindex
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install llamaindex`
10
- **Minimum Node.js**: 18.0.0
11
- **Runtime Support**: Node.js, Deno, Bun, Vercel Edge Runtime, Cloudflare Workers
12

13
## Core Imports
14

15
```typescript
16
import { Settings, VectorStoreIndex, Document } from "llamaindex";
17
```
18

19
For submodule imports:
20
```typescript
21
import { ReACTAgent } from "llamaindex/agent";
22
import { RetrieverQueryEngine } from "llamaindex/engines";
23
import { SimpleVectorStore } from "llamaindex/vector-store";
24
```
25

26
For CommonJS:
27
```javascript
28
const { Settings, VectorStoreIndex, Document } = require("llamaindex");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { Settings, VectorStoreIndex, Document } from "llamaindex";
35

36
// Configure global settings
37
Settings.llm = "your-llm-instance";
38
Settings.embedModel = "your-embedding-model";
39

40
// Create documents and build index
41
const documents = [
42
  new Document({ text: "This is a document about AI.", id_: "doc1" }),
43
  new Document({ text: "LlamaIndex helps build LLM apps.", id_: "doc2" }),
44
];
45

46
// Build vector index
47
const index = await VectorStoreIndex.fromDocuments(documents);
48

49
// Query the index
50
const queryEngine = index.asQueryEngine();
51
const response = await queryEngine.query("Tell me about AI");
52
console.log(response.toString());
53
```
54

55
## Architecture
56

57
LlamaIndex.TS is built around several key architectural components:
58

59
- **Settings System**: Global configuration for LLMs, embeddings, and processing parameters
60
- **Document Processing**: Node parsers and text splitters for data ingestion
61
- **Indexing System**: Vector stores, keyword indices, and summary indices for data organization
62
- **Query Engines**: Retrieval and synthesis systems for answering questions
63
- **Agent Framework**: ReAct agents for complex reasoning and tool usage
64
- **Memory System**: Chat memory, vector memory, and context management
65
- **Storage Backend**: Document stores, index stores, and vector stores for persistence
66

67
## Capabilities
68

69
### Settings and Configuration
70

71
Global configuration system for managing LLMs, embedding models, and processing parameters across the framework.
72

73
```typescript { .api }
74
interface GlobalSettings extends Config {
75
  llm: LLM;
76
  embedModel: BaseEmbedding;
77
  nodeParser: NodeParser;
78
  promptHelper: PromptHelper;
79
  callbackManager: CallbackManager;
80
  chunkSize: number | undefined;
81
  chunkOverlap: number | undefined;
82
  prompt: PromptConfig;
83
  debug: boolean;
84
  
85
  withLLM<Result>(llm: LLM, fn: () => Result): Result;
86
  withEmbedModel<Result>(embedModel: BaseEmbedding, fn: () => Result): Result;
87
  withNodeParser<Result>(nodeParser: NodeParser, fn: () => Result): Result;
88
  withPromptHelper<Result>(promptHelper: PromptHelper, fn: () => Result): Result;
89
  withCallbackManager<Result>(callbackManager: CallbackManager, fn: () => Result): Result;
90
  withChunkSize<Result>(chunkSize: number, fn: () => Result): Result;
91
  withChunkOverlap<Result>(chunkOverlap: number, fn: () => Result): Result;
92
  withPrompt<Result>(prompt: PromptConfig, fn: () => Result): Result;
93
}
94

95
const Settings: GlobalSettings;
96
```
97

98
[Settings and Configuration](./settings.md)
99

100
### Document Processing and Node Parsing
101

102
Text processing and document chunking functionality for preparing data for indexing and retrieval.
103

104
```typescript { .api }
105
class SentenceSplitter implements NodeParser {
106
  constructor(options?: { chunkSize?: number; chunkOverlap?: number });
107
  getNodesFromDocuments(documents: Document[]): TextNode[];
108
}
109

110
class Document {
111
  constructor(init: { text: string; id_?: string; metadata?: Record<string, any> });
112
  text: string;
113
  id_: string;
114
  metadata: Record<string, any>;
115
}
116
```
117

118
[Document Processing](./document-processing.md)
119

120
### Vector Indexing and Storage
121

122
Core indexing functionality for creating searchable representations of documents using vector embeddings.
123

124
```typescript { .api }
125
class VectorStoreIndex {
126
  static fromDocuments(documents: Document[]): Promise<VectorStoreIndex>;
127
  asQueryEngine(): QueryEngine;
128
  asRetriever(): BaseRetriever;
129
  insert(document: Document): Promise<void>;
130
}
131

132
interface BaseVectorStore {
133
  add(nodes: BaseNode[]): Promise<string[]>;
134
  query(query: VectorStoreQuery): Promise<VectorStoreQueryResult>;
135
}
136
```
137

138
[Vector Indexing](./vector-indexing.md)
139

140
### Query Engines
141

142
Query processing and response synthesis for retrieving and generating answers from indexed data.
143

144
```typescript { .api }
145
interface BaseQueryEngine {
146
  query(query: string): Promise<EngineResponse>;
147
}
148

149
class RetrieverQueryEngine implements BaseQueryEngine {
150
  constructor(retriever: BaseRetriever, responseSynthesizer?: ResponseSynthesizer);
151
  query(query: string): Promise<EngineResponse>;
152
}
153
```
154

155
[Query Engines](./query-engines.md)
156

157
### Chat Engines
158

159
Conversational interfaces that maintain context and enable back-and-forth interactions with your data.
160

161
```typescript { .api }
162
interface BaseChatEngine {
163
  chat(message: string): Promise<EngineResponse>;
164
  reset(): void;
165
}
166

167
class ContextChatEngine implements BaseChatEngine {
168
  constructor(options: { retriever: BaseRetriever; memory?: BaseMemory });
169
  chat(message: string): Promise<EngineResponse>;
170
}
171
```
172

173
[Chat Engines](./chat-engines.md)
174

175
### Agent Framework
176

177
ReAct agents and task execution system for complex reasoning and multi-step operations with tool usage.
178

179
```typescript { .api }
180
class ReActAgent {
181
  constructor(params: ReACTAgentParams);
182
  chat(message: string): Promise<AgentChatResponse>;
183
  createTask(input: string): Task;
184
}
185

186
interface AgentParamsBase {
187
  tools: BaseTool[];
188
  llm: LLM;
189
  memory?: BaseMemory;
190
}
191
```
192

193
[Agent Framework](./agents.md)
194

195
### LLM Integration
196

197
Comprehensive integration with large language models including OpenAI, Anthropic, and other providers.
198

199
```typescript { .api }
200
interface LLM {
201
  chat(messages: ChatMessage[]): Promise<ChatResponse>;
202
  complete(prompt: string): Promise<CompletionResponse>;
203
  metadata: LLMMetadata;
204
}
205

206
interface ChatMessage {
207
  role: MessageType;
208
  content: MessageContent;
209
}
210

211
type MessageContent = string | MessageContentDetail[];
212
```
213

214
[LLM Integration](./llm-integration.md)
215

216
### Embeddings
217

218
Text embedding generation and similarity operations for semantic search and retrieval.
219

220
```typescript { .api }
221
interface BaseEmbedding {
222
  getTextEmbedding(text: string): Promise<number[]>;
223
  getQueryEmbedding(query: string): Promise<number[]>;
224
}
225

226
function similarity(embedding1: number[], embedding2: number[]): number;
227
function getTopKEmbeddings(
228
  queryEmbedding: number[],
229
  embeddings: number[][],
230
  k: number
231
): number[];
232
```
233

234
[Embeddings](./embeddings.md)
235

236
### Storage System
237

238
Persistent storage backends for documents, indices, and vector data across different storage systems.
239

240
```typescript { .api }
241
interface BaseDocumentStore {
242
  addDocuments(documents: Document[]): Promise<void>;
243
  getDocument(docId: string): Promise<Document | undefined>;
244
  getAllDocuments(): Promise<Document[]>;
245
}
246

247
class StorageContext {
248
  static fromDefaults(options?: {
249
    docStore?: BaseDocumentStore;
250
    indexStore?: BaseIndexStore;
251
    vectorStore?: BaseVectorStore;
252
  }): StorageContext;
253
}
254
```
255

256
[Storage System](./storage.md)
257

258
### Tools and Utilities
259

260
Tool integration system for extending agent capabilities with external functions and APIs.
261

262
```typescript { .api }
263
interface BaseTool {
264
  metadata: ToolMetadata;
265
  call(input: string): Promise<ToolOutput>;
266
}
267

268
class QueryEngineTool implements BaseTool {
269
  constructor(queryEngine: BaseQueryEngine, metadata: ToolMetadata);
270
  call(input: string): Promise<ToolOutput>;
271
}
272
```
273

274
[Tools and Utilities](./tools.md)
275

276
### Response Synthesis
277

278
Response generation and synthesis strategies for combining retrieved information into coherent answers.
279

280
```typescript { .api }
281
interface BaseSynthesizer {
282
  synthesize(query: string, nodes: BaseNode[]): Promise<EngineResponse>;
283
}
284

285
type ResponseMode = "refine" | "compact" | "tree_summarize" | "simple_summarize";
286

287
function createResponseSynthesizer(mode: ResponseMode): BaseSynthesizer;
288
```
289

290
[Response Synthesis](./response-synthesis.md)
291

292
### Ingestion Pipelines
293

294
Advanced document ingestion system with support for transformation pipelines, duplicate detection, and batch processing.
295

296
```typescript { .api }
297
class IngestionPipeline {
298
  constructor(options: {
299
    transformations?: TransformComponent[];
300
    readers?: Record<string, BaseReader>;
301
    vectorStore?: BaseVectorStore;
302
    cache?: IngestionCache;
303
    docStore?: BaseDocumentStore;
304
    duplicatesStrategy?: DuplicatesStrategy;
305
  });
306
  
307
  async run(
308
    documents?: Document[],
309
    inputDir?: string,
310
    cacheCollection?: string
311
  ): Promise<BaseNode[]>;
312
  
313
  loadDataFromDirectory(inputDir: string, inputFiles?: string[]): Promise<Document[]>;
314
  
315
  // Properties
316
  transformations: TransformComponent[];
317
  readers: Record<string, BaseReader>;
318
  vectorStore?: BaseVectorStore;
319
  cache?: IngestionCache;
320
  docStore?: BaseDocumentStore;
321
  duplicatesStrategy: DuplicatesStrategy;
322
}
323

324
enum DuplicatesStrategy {
325
  DUPLICATES_ONLY = "duplicates_only",
326
  UPSERTS = "upserts", 
327
  UPSERTS_AND_DELETE = "upserts_and_delete",
328
}
329

330
interface TransformComponent {
331
  transform(nodes: BaseNode[], options?: Record<string, any>): Promise<BaseNode[]>;
332
}
333
```
334

335
[Ingestion Pipelines](./ingestion.md)
336

337
### Evaluation Framework
338

339
Comprehensive evaluation system for assessing LLM application performance with built-in metrics and custom evaluators.
340

341
```typescript { .api }
342
interface BaseEvaluator {
343
  evaluate(query: string, response: string, contexts?: string[]): Promise<EvaluationResult>;
344
}
345

346
interface EvaluationResult {
347
  query: string;
348
  response: string;
349
  score: number;
350
  feedback: string;
351
  passingGrade?: boolean;
352
  metadata?: Record<string, any>;
353
}
354

355
class FaithfulnessEvaluator implements BaseEvaluator {
356
  constructor(options?: { llm?: LLM });
357
  evaluate(query: string, response: string, contexts: string[]): Promise<EvaluationResult>;
358
}
359

360
class RelevancyEvaluator implements BaseEvaluator {
361
  constructor(options?: { llm?: LLM });
362
  evaluate(query: string, response: string, contexts?: string[]): Promise<EvaluationResult>;
363
}
364

365
class CorrectnessEvaluator implements BaseEvaluator {
366
  constructor(options?: { llm?: LLM });
367
  evaluate(query: string, response: string, contexts?: string[], referenceAnswer?: string): Promise<EvaluationResult>;
368
}
369
```
370

371
[Evaluation Framework](./evaluation.md)
372

373
## Types
374

375
### Core Schema Types
376

377
```typescript { .api }
378
abstract class BaseNode<T extends Metadata = Metadata> {
379
  id_: string;
380
  embedding?: number[];
381
  metadata: T;
382
  excludedEmbedMetadataKeys: string[];
383
  excludedLlmMetadataKeys: string[];
384
  relationships: Partial<Record<NodeRelationship, RelatedNodeType<T>>>;
385
  hash: string;
386
  
387
  abstract get type(): ObjectType;
388
  abstract getContent(metadataMode?: MetadataMode): string;
389
  abstract getMetadataStr(metadataMode?: MetadataMode): string;
390
  abstract setContent(value: string): void;
391
}
392

393
class TextNode extends BaseNode {
394
  constructor(init?: {
395
    text?: string;
396
    id_?: string;
397
    metadata?: Record<string, any>;
398
    embedding?: number[];
399
    excludedEmbedMetadataKeys?: string[];
400
    excludedLlmMetadataKeys?: string[];
401
    relationships?: Partial<Record<NodeRelationship, RelatedNodeType>>;
402
  });
403
  
404
  text: string;
405
  startCharIdx?: number;
406
  endCharIdx?: number;
407
  textTemplate: string;
408
  metadataTemplate: string;
409
  metadataSeparator: string;
410
}
411

412
class ImageNode extends BaseNode {
413
  constructor(init?: {
414
    image?: string;
415
    text?: string;
416
    mimetype?: string;
417
    imageUrl?: string;
418
    imagePath?: string;
419
    id_?: string;
420
    metadata?: Record<string, any>;
421
  });
422
  
423
  image?: string;
424
  imageUrl?: string;
425
  imagePath?: string;
426
  imageMimetype?: string;
427
}
428

429
class Document extends TextNode {
430
  constructor(init: {
431
    text: string;
432
    id_?: string;
433
    metadata?: Record<string, any>;
434
    excludedLlmMetadataKeys?: string[];
435
    excludedEmbedMetadataKeys?: string[];
436
    relationships?: Partial<Record<NodeRelationship, RelatedNodeType>>;
437
    mimetype?: string;
438
    textTemplate?: string;
439
  });
440
  
441
  docId?: string;
442
  mimetype?: string;
443
}
444

445
class EngineResponse {
446
  response: string;
447
  sourceNodes?: NodeWithScore[];
448
  metadata?: Record<string, any>;
449
  
450
  toString(): string;
451
  print(): void;
452
}
453

454
interface NodeWithScore {
455
  node: BaseNode;
456
  score?: number;
457
}
458

459
enum NodeRelationship {
460
  SOURCE = "SOURCE",
461
  PREVIOUS = "PREVIOUS", 
462
  NEXT = "NEXT",
463
  PARENT = "PARENT",
464
  CHILD = "CHILD",
465
}
466

467
enum ObjectType {
468
  TEXT = "TEXT",
469
  IMAGE = "IMAGE",
470
  INDEX = "INDEX", 
471
  DOCUMENT = "DOCUMENT",
472
  IMAGE_DOCUMENT = "IMAGE_DOCUMENT",
473
}
474

475
enum MetadataMode {
476
  ALL = "ALL",
477
  EMBED = "EMBED",
478
  LLM = "LLM", 
479
  NONE = "NONE",
480
}
481

482
type Metadata = Record<string, any>;
483

484
interface RelatedNodeInfo<T extends Metadata = Metadata> {
485
  nodeId: string;
486
  nodeType?: ObjectType;
487
  metadata: T;
488
  hash?: string;
489
}
490

491
type RelatedNodeType<T extends Metadata = Metadata> = 
492
  | RelatedNodeInfo<T> 
493
  | RelatedNodeInfo<T>[];
494
```
495

496
### Configuration Types
497

498
```typescript { .api }
499
interface Config {
500
  prompt: PromptConfig;
501
  promptHelper: PromptHelper | null;
502
  embedModel: BaseEmbedding | null;
503
  nodeParser: NodeParser | null;
504
  callbackManager: CallbackManager | null;
505
  chunkSize: number | undefined;
506
  chunkOverlap: number | undefined;
507
}
508

509
interface PromptConfig {
510
  llm?: string;
511
  lang?: string;
512
}
513
```
514

515
### Structured Output Types
516

517
```typescript { .api }
518
interface StructuredOutput<T> {
519
  rawOutput: string;
520
  parsedOutput: T;
521
}
522

523
type UUID = `${string}-${string}-${string}-${string}-${string}`;
524

525
type ToolMetadataOnlyDescription = Pick<ToolMetadata, "description">;
526
```
527

528
## Constants
529

530
```typescript { .api }
531
const DEFAULT_CHUNK_SIZE: 1024;
532
const DEFAULT_CHUNK_OVERLAP: 200;
533
const DEFAULT_CHUNK_OVERLAP_RATIO: 0.1;
534
const DEFAULT_CONTEXT_WINDOW: 3900;
535
const DEFAULT_NUM_OUTPUTS: 256;
536
const DEFAULT_SIMILARITY_TOP_K: 2;
537
const DEFAULT_PADDING: 5;
538
const DEFAULT_BASE_URL: string;
539
const DEFAULT_COLLECTION: string;
540
const DEFAULT_DOC_STORE_PERSIST_FILENAME: "docstore.json";
541
const DEFAULT_GRAPH_STORE_PERSIST_FILENAME: "graph_store.json";
542
const DEFAULT_INDEX_STORE_PERSIST_FILENAME: "index_store.json";
543
const DEFAULT_NAMESPACE: "default";
544
const DEFAULT_PERSIST_DIR: "./storage";
545
const DEFAULT_PROJECT_NAME: string;
546
const DEFAULT_VECTOR_STORE_PERSIST_FILENAME: "vector_store.json";
547
```
548

549
## Event System
550

551
```typescript { .api }
552
interface LlamaIndexEventMaps {
553
  "llm-start": LLMStartEvent;
554
  "llm-end": LLMEndEvent;
555
  "llm-stream": LLMStreamEvent;
556
  "llm-tool-call": LLMToolCallEvent;
557
  "llm-tool-result": LLMToolResultEvent;
558
}
559

560
interface LLMStartEvent {
561
  id: string;
562
  timestamp: Date;
563
  payload: {
564
    messages: ChatMessage[];
565
    additionalKwargs?: Record<string, any>;
566
  };
567
}
568

569
interface LLMEndEvent {
570
  id: string;
571
  timestamp: Date;
572
  payload: {
573
    response: ChatResponse | CompletionResponse;
574
  };
575
}
576

577
interface LLMStreamEvent {
578
  id: string;
579
  timestamp: Date;
580
  payload: {
581
    chunk: string;
582
    snapshot: string;
583
  };
584
}
585

586
interface LLMToolCallEvent {
587
  id: string;
588
  timestamp: Date;
589
  payload: {
590
    toolCall: ToolCall;
591
  };
592
}
593

594
interface LLMToolResultEvent {
595
  id: string;
596
  timestamp: Date;
597
  payload: {
598
    toolResult: ToolOutput;
599
  };
600
}
601

602
type JSONValue = string | number | boolean | null | { [key: string]: JSONValue } | JSONValue[];
603
type JSONObject = { [key: string]: JSONValue };
604
type JSONArray = JSONValue[];
605
```