NeuralTrust TypeScript SDK

The NeuralTrust TypeScript SDK provides a convenient way to interact with the NeuralTrust API for tracing, evaluation sets, knowledge bases, and testsets.

Installation

You can install the NeuralTrust TypeScript SDK using npm or yarn:

npm install neuraltrust
# or
yarn add neuraltrust

Usage

To use the NeuralTrust TypeScript SDK, you need to initialize the client with your API key:

import { NeuralTrust } from 'neuraltrust';

// Initialize the client with your API key
const client = new NeuralTrust({ apiKey: "your_api_key_here" });

// Optionally, you can specify a custom base URL and SDK version
const client = new NeuralTrust({ 
  apiKey: "your_api_key_here",
  baseUrl: "https://custom.api.url",
});

Basic Trace Usage

The SDK supports various types of events that can be sent during tracing. Here are the different event types and their usage:

Traces

The SDK supports various event types:

• MESSAGE
• TOOL
• AGENT
• RETRIEVAL
• GENERATION
• ROUTER
• SYSTEM
• CUSTOM (event)
• FEEDBACK

All event types except MESSAGE require a parent_id.

Creating Traces

The SDK supports both nested and non-nested trace creation:

Nested Approach (Recommended)

import { NeuralTrust, EventType, FeedbackTag, User, Metadata } from 'neuraltrust';

// Initialize client
const client = new NeuralTrust({ apiKey: "your-api-key" });

// Create a root trace and message
const trace = client.trace({
    conversationId: "conversation_12345678",
    sessionId: "session_12345678",
    channelId: "channel_12345678",
    user: { id: "user_12345678", name: "John Doe" },
    metadata: { id: "metadata_12345678", name: "John Doe" },
    custom: { key: "value" }
});
const message = trace.message("User input: Hello!");

// Create nested traces (parentId is handled automatically)
const tool = message.tool("Processing request...");
await tool.end("Request processed");

// Create deeper nested traces
const agent = tool.agent("Agent working...");
await agent.end("Task completed");

// Example of a complete conversation flow
const trace = client.trace({
    conversationId: "conversation_12345678",
    sessionId: "session_12345678",
});
const message = trace.message("What's the weather?");
const router = message.router("What's the weather?");
await router.end("Routing to weather service");
const retrieval = router.retrieval("What's the weather in San Francisco?");
await retrieval.end("Found current weather in San Francisco is sunny and 75°F");
const generation = retrieval.generation("Generating response: The weather is sunny and 75°F");
await generation.end("The weather is sunny and 75°F");
await message.end("The weather is sunny and 75°F");

Non-nested Approach (Using explicit parentId)

// Create a root trace
const trace = client.trace({
    conversationId: "conversation_12345678",
    sessionId: "session_12345678",
    channelId: "channel_12345678",
    user: { id: "user_12345678", name: "John Doe" },
    metadata: { id: "metadata_12345678", name: "John Doe" },
    custom: { key: "value" }
});

// Create a message trace
const message = trace.message("User input: Hello!");
await message.end("Assistant: Hi there!");

// Create child traces with explicit parentId
const toolTrace = trace.tool("Processing request...", { parentId: message.traceId });
await toolTrace.end("Request processed");

// Create another child trace referencing the tool trace
const agentTrace = trace.agent("Agent working...", { parentId: toolTrace.traceId });
await agentTrace.end("Task completed");

// Add feedback with explicit parentId
const feedback = await trace.feedback({
    feedbackTag: FeedbackTag.POSITIVE,
    feedbackText: "Accurate weather report",
    parentId: message.traceId
});

Using the Send Method

The send method provides a more direct way to create traces:

const trace = client.trace({
    conversationId: "conversation_12345678",
    sessionId: "session_12345678",
    channelId: "channel_12345678",
    user: { id: "user_12345678", name: "John Doe" },
    metadata: { id: "metadata_12345678", name: "John Doe" },
    custom: { key: "value" }
});

// Message trace (no parent required)
const message = await trace.send({
    eventType: EventType.MESSAGE,
    input: "Hello",
    output: "Hi there"
});

// Other event types (require parentId)
const tool = await trace.send({
    eventType: EventType.TOOL,
    input: "Processing",
    output: "Done",
    parentId: message.traceId
});

Evaluation Sets

// Run evaluation set
const evalSet = await client.runEvaluationSet({ id: "eval_set_id" });

// Create an evaluation set
const evalSet = await client.createEvaluationSet({
    name: "My Eval Set",
    description: "A test evaluation set"
});

// Get an evaluation set
const evalSet = await client.getEvaluationSet({ id: "eval_set_id" });

// Delete an evaluation set
await client.deleteEvaluationSet({ id: "eval_set_id" });

Knowledge Bases

// Create a knowledge base
const kb = await client.createKnowledgeBase({
    type: "upstash",
    credentials: { apiKey: "your_doc_api_key" }
});

// Get a knowledge base
const kb = await client.getKnowledgeBase({ id: "kb_id" });

// Delete a knowledge base
await client.deleteKnowledgeBase({ id: "kb_id" });

Testsets

// Create a testset
const testset = await client.createTestset({
    name: "My Testset",
    type: "adversarial",
    evaluationSetId: "eval_set_id",
    knowledgeBaseId: "kb_id",
    numQuestions: 10
});

// Get a testset
const testset = await client.getTestset({ id: "testset_id" });

// Delete a testset
await client.deleteTestset({ id: "testset_id" });

Configuration

You can configure the SDK using environment variables:

• NEURALTRUST_API_KEY: Your NeuralTrust API key
• NEURALTRUST_BASE_URL: Custom base URL for the API (optional)

Advanced Usage

Custom Metadata and User Information

import { User, Metadata } from 'neuraltrust';

const user: User = { id: "user123", name: "John Doe" };
const metadata: Metadata = { appVersion: "1.0.0", platform: "web" };

const trace = client.trace({ user, metadata });

Error Handling

The SDK will throw errors for API errors. Make sure to handle these appropriately in your application using try/catch blocks or .catch() for promises.

Contributing

Contributions to the NeuralTrust TypeScript SDK are welcome! Please refer to the contribution guidelines for more information.

License

This SDK is distributed under the MIT License.