@railtownai/railengine

JavaScript/TypeScript SDK for Railtown AI Rail Engine - Retrieval package. This package provides a simple interface for reading and searching data from Rail Engine.

Installation

npm install @railtownai/railengine

Requirements

• Node.js 20+
• TypeScript 5.0+ (optional, but recommended)

Quick Start

Basic Usage

import { RailEngine } from "@railtownai/railengine";

// ENGINE_PAT and ENGINE_ID are read from environment variables automatically

// Initialize client
const client = new RailEngine();

// Get storage document by EventId
const document = await client.getStorageDocumentByEventId({
  eventId: "event-id"
});
console.log(document);

Using Environment Variables

import { RailEngine } from "@railtownai/railengine";

const client = new RailEngine();

// Use client.engineId if you need it
const results = client.searchVectorStore(client.engineId, "VectorStore1", "query");
for await (const result of results) {
  console.log(result);
}

Zod Schema Support

You can provide a Zod schema during client initialization to automatically validate retrieved data:

import { z } from "zod";
import { RailEngine } from "@railtownai/railengine";

const FoodDiaryItemSchema = z.object({
  food_name: z.string(),
  calories: z.number(),
  carbs: z.number(),
  proteins: z.number(),
  fats: z.number()
});

type FoodDiaryItem = z.infer<typeof FoodDiaryItemSchema>;

// Initialize with schema
const client = new RailEngine({
  schema: FoodDiaryItemSchema
});

// Results automatically validated against FoodDiaryItemSchema
const results = client.searchVectorStore({
  vectorStore: "VectorStore1",
  query: "apple"
});
for await (const item of results) {
  // item is FoodDiaryItem
  console.log(item.food_name, item.calories);
}

API Methods

Embeddings API

searchVectorStore

Search a vector store using semantic similarity.

Example:

const results = client.searchVectorStore({
  engineId: "engine-id", // Optional, defaults to process.env.ENGINE_ID
  vectorStore: "VectorStore1",
  query: "apple"
});
for await (const result of results) {
  console.log(result);
}

Storage API

getStorageDocumentByEventId

Get a single storage document by EventId.

Example:

const document = await client.getStorageDocumentByEventId({
  eventId: "event-id",
  engineId: "engine-id" // Optional, defaults to process.env.ENGINE_ID
});
if (document) {
  console.log(document);
}

getStorageDocumentByCustomerKey

Get storage documents by CustomerKey with automatic pagination.

Example:

const documents = client.getStorageDocumentByCustomerKey({
  customerKey: "doc-123",
  engineId: "engine-id", // Optional, defaults to process.env.ENGINE_ID
  pageSize: 50
});

for await (const doc of documents) {
  console.log(doc);
}

queryStorageByJsonPath

Query storage documents using JSONPath.

const documents = client.queryStorageByJsonPath(
  engineId: string,
  jsonPathQuery: string,
  options?: {
    filterFn?: (item: T | Record<string, unknown>) => boolean;
    schema?: z.ZodSchema<unknown>;
  }
): AsyncIterable<T | Record<string, unknown>>

Example:

const documents = await client.queryStorageByJsonPath({
  engineId: "engine-id",
  jsonPathQuery: "$.status:active"
});
for await (const doc of documents) {
  console.log(doc);
}

listStorageDocuments

List storage documents with automatic pagination.

Example:

// List all documents
const documents = await client.listStorageDocuments({
  engineId: "engine-id"
});

// List documents filtered by customerKey
const filtered = await client.listStorageDocuments({
  engineId: "engine-id",
  customerKey: "doc-123"
});

for await (const doc of documents) {
  console.log(doc);
}

Indexing API

searchIndex

Search Railengine Index.

Example:

const results = client.searchIndex("engine-id", { search: "example query" });

for await (const result of results) {
  console.log(result);
}

License

MIT.