Oximy Typescript SDK

Zero-overhead observability for LLM applications.

This library provides a lightweight wrapper for LLM client libraries that captures telemetry and enforces policies without blocking your application.

Full documentation is available at docs.oximy.com.

Installation

npm install oximy

Quick Start

import { Oximy } from 'oximy';
import OpenAI from 'openai';

const oximy = new Oximy({
  apiKey: process.env.OXIMY_API_KEY,
  projectId: process.env.OXIMY_PROJECT_ID,
});

const openai = oximy.wrap(new OpenAI());

// Use exactly as before - telemetry is automatic
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});

Configuration

const oximy = new Oximy({
  // Required
  apiKey: 'ox_xxxxxxxx',
  projectId: 'proj_xxxxxxxx',

  // Optional
  environment: 'production',
  service: 'chat-api',
  version: '1.2.3',
  metadata: { team: 'platform' },
  timeout: 100,
  debug: false,

  // Policy violation callback
  onPolicyViolation: (violation) => {
    console.log(violation.ruleName, violation.action);
  },
});

Per-Request Context

const response = await openai.chat.completions.create(
  {
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }],
  },
  {
    oximy: {
      userId: 'user_123',
      sessionId: 'sess_456',
      traceId: 'trace_789',
      tags: ['support', 'billing'],
      metadata: { ticketId: 'TICKET-123' },
    },
  }
);

Provider Support

Works with any OpenAI-compatible client.

OpenAI

const openai = oximy.wrap(new OpenAI());

Anthropic

const anthropic = oximy.wrap(
  new OpenAI({
    apiKey: process.env.ANTHROPIC_API_KEY,
    baseURL: 'https://api.anthropic.com/v1',
  })
);

OpenRouter

const openrouter = oximy.wrap(
  new OpenAI({
    apiKey: process.env.OPENROUTER_API_KEY,
    baseURL: 'https://openrouter.ai/api/v1',
  })
);

Azure OpenAI

const azure = oximy.wrap(
  new OpenAI({
    apiKey: process.env.AZURE_OPENAI_KEY,
    baseURL: 'https://your-resource.openai.azure.com/v1',
  })
);

Groq

const groq = oximy.wrap(
  new OpenAI({
    apiKey: process.env.GROQ_API_KEY,
    baseURL: 'https://api.groq.com/openai/v1',
  })
);

Streaming

Streaming is fully supported. Telemetry is sent after the stream completes.

const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Captured Data

| Category | Data | |----------|------| | Request | Model, messages, tools, parameters | | Response | Content, finish reason, tool calls | | Usage | Input tokens, output tokens, cached tokens | | Cost | Estimated cost (USD) | | Timing | Duration, time-to-first-token | | Errors | Type, message, status code | | Context | User ID, session ID, trace ID, tags |

Policy Enforcement

Policies are configured in the Oximy dashboard and enforced automatically. No code changes required.

Modes:

• Shadow - Log violations without blocking
• Quarantine - Log and alert, allow through
• Enforce - Block or redact violations

Local Rules (evaluated in SDK, < 5ms):

• Regex patterns (API keys, secrets)
• Deny/allow lists (models, keywords, MCP servers, tool calls)
• Contains matching (SQL injection patterns)
• Token limits
• Rate limits (per user/session/global)
• Cost limits (per user/session/global)

SLM Rules (evaluated via API, 50-200ms):

• AI-powered PII detection with pseudoanonymization
• Prompt injection detection
• Custom content classification

Fail-Open Design

The SDK never blocks your application:

• 100ms telemetry timeout
• Silent failure on network errors
• Zero runtime dependencies
• Falls back to enabled if config fetch fails

TypeScript

Full TypeScript support with exported types:

import type {
  OximyConfig,
  RequestContext,
  OximyEvent,
  PolicyViolation,
} from 'oximy';

Requirements

• Node.js 18+
• TypeScript 4.9+ (if using TypeScript)

Support

• Documentation: docs.oximy.com
• Email: [email protected]