Artanis TypeScript SDK

Artanis SDK for AI application observability - understand failures, build evaluation sets, and act on user feedback.

Installation

npm install @artanis-ai/sdk
# or
yarn add @artanis-ai/sdk
# or
pnpm add @artanis-ai/sdk

Quick Start

import { Artanis } from "@artanis-ai/sdk";

// Initialize client
const artanis = new Artanis({ apiKey: "sk_..." });

// Create a trace
const trace = artanis.trace("answer-question");
trace.input({ question: "What is AI?", model: "gpt-4" });
trace.output("AI stands for Artificial Intelligence");

// Record feedback
artanis.feedback(trace.id, "positive");

Configuration

API Key

Provide your API key either explicitly or via environment variable:

// Explicit
const artanis = new Artanis({ apiKey: "sk_..." });

// Environment variable
process.env.ARTANIS_API_KEY = "sk_...";
const artanis = new Artanis();

Options

const artanis = new Artanis({
  apiKey: "sk_...", // Required (or ARTANIS_API_KEY env var)
  baseUrl: "https://app.artanis.ai", // Optional: custom API endpoint
  enabled: true, // Optional: enable/disable tracing
  debug: false, // Optional: enable debug logging
  onError: (error) => console.log(error), // Optional: error callback
});

Environment Variables

| Variable | Default | Description | | ------------------ | ------------------------ | ---------------------- | | ARTANIS_API_KEY | Required | Your API key | | ARTANIS_BASE_URL | https://app.artanis.ai | API endpoint | | ARTANIS_ENABLED | true | Enable/disable tracing | | ARTANIS_DEBUG | false | Enable debug logging |

Usage

Basic Tracing

const trace = artanis.trace("operation-name");
trace.input({ question: "...", context: "..." });
// ... perform operation ...
trace.output(result);

With Metadata

const trace = artanis.trace("answer-question", {
  user_id: "user-123",
  session_id: "session-456",
});

Capturing State for Replay

const trace = artanis.trace("rag-query");

// Capture document state
trace.state("documents", [{ id: "doc1", score: 0.95 }]);

// Capture configuration
trace.state("config", { model: "gpt-4", temperature: 0.7 });

// Record inputs and output
trace.input({ query: "...", prompt: "..." });
trace.output(response);

Error Handling

const trace = artanis.trace("risky-operation");
trace.input({ data: inputData });

try {
  const result = process(inputData);
  trace.output(result);
} catch (e) {
  trace.error(String(e));
  throw e;
}

Method Chaining

artanis
  .trace("operation")
  .input({ question: "What is AI?" })
  .state("config", { model: "gpt-4" })
  .output("AI stands for Artificial Intelligence");

Feedback

// Binary feedback
artanis.feedback(trace.id, "positive");
artanis.feedback(trace.id, "negative");

// Numeric rating (0.0-1.0)
artanis.feedback(trace.id, 0.85);

// With comment
artanis.feedback(trace.id, "negative", "The answer was incorrect");

// With correction
artanis.feedback(trace.id, "negative", undefined, {
  answer: "The correct answer is...",
});

Complete Example: RAG Pipeline

import { Artanis } from "@artanis-ai/sdk";

const artanis = new Artanis();

async function answerQuestion(question: string, userId: string) {
  // Create trace with metadata
  const trace = artanis.trace("rag-answer", {
    user_id: userId,
  });

  // Capture document corpus state
  const corpus = await loadDocuments();
  trace.state(
    "corpus",
    corpus.map((doc) => doc.id),
  );

  // Retrieve relevant chunks
  const chunks = await retriever.search(question);
  trace.state(
    "chunks",
    chunks.map((c) => ({
      id: c.id,
      score: c.score,
    })),
  );

  // Generate response
  const prompt = buildPrompt(question, chunks);
  trace.input({
    question,
    prompt,
    model: "gpt-4",
  });

  const response = await llm.generate(prompt);
  trace.output(response);

  return { answer: response, traceId: trace.id };
}

// Later, collect feedback
const { answer, traceId } = await answerQuestion("What is AI?", "user-123");
console.log(answer);

// User provides feedback
artanis.feedback(traceId, "positive");

Next.js Example

API Route

// app/api/ask/route.ts
import { Artanis } from "@artanis-ai/sdk";
import { NextResponse } from "next/server";

const artanis = new Artanis();

export async function POST(request: Request) {
  const { question, userId } = await request.json();

  const trace = artanis.trace("ask-question", { user_id: userId });
  trace.input({ question });

  const answer = await processQuestion(question);
  trace.output(answer);

  return NextResponse.json({
    answer,
    traceId: trace.id,
  });
}

Client Component

'use client';

import { useState } from 'react';

export default function ChatInterface() {
  const [messages, setMessages] = useState<Array<{
    text: string;
    traceId: string;
  }>>([]);

  async function askQuestion(question: string) {
    const response = await fetch('/api/ask', {
      method: 'POST',
      body: JSON.stringify({ question, userId: 'user-123' })
    });

    const { answer, traceId } = await response.json();
    setMessages(prev => [...prev, { text: answer, traceId }]);
  }

  async function submitFeedback(traceId: string, isPositive: boolean) {
    await fetch('/api/feedback', {
      method: 'POST',
      body: JSON.stringify({
        traceId,
        rating: isPositive ? 'positive' : 'negative'
      })
    });
  }

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>
          <p>{msg.text}</p>
          <button onClick={() => submitFeedback(msg.traceId, true)}>👍</button>
          <button onClick={() => submitFeedback(msg.traceId, false)}>👎</button>
        </div>
      ))}
    </div>
  );
}

Testing

Disable tracing in tests:

// Option 1: Environment variable
process.env.ARTANIS_ENABLED = "false";

// Option 2: Explicit configuration
const artanis = new Artanis({ enabled: false });

Performance

• P50 overhead: < 0.05ms per operation
• P99 overhead: < 0.5ms per operation
• All network operations are non-blocking (fire-and-forget)
• No retries or queueing to prevent memory leaks

Error Handling Philosophy

The SDK never throws exceptions. All errors are handled silently to ensure observability never breaks production:

• Invalid API key → traces dropped, error logged (if debug)
• Network failure → traces dropped silently
• Payload too large → trace dropped, error logged

Use the onError callback to monitor SDK errors:

const artanis = new Artanis({
  onError: (error) => logger.warn("Artanis error:", error),
});

Development

Setup

cd typescript
npm install

Build

npm run build

Run Tests

npm test
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage

Type Checking

npm run typecheck

Linting

npm run lint

Support

• Documentation: https://docs.artanis.ai
• GitHub: https://github.com/artanis-ai/sdk
• Email: [email protected]

License

MIT License - see LICENSE file for details.