npm package: @neuraltrust/neuraltrust
Description: SDK for NeuralTrust API
Latest version: 0.7.86

# 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:

```sh
npm install neuraltrust
# or
yarn add neuraltrust
```

## Usage

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

```typescript
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)
```typescript
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)
```typescript
// 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:

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

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

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

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

```typescript
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](LICENSE).