@overmind-lab/trace-sdk 0.0.1

package/README.md

@@ -0,0 +1,124 @@
+# overmind-js
+
+JavaScript/TypeScript SDK for [Overmind](https://overmindlab.ai) — automatic LLM observability powered by OpenTelemetry.
+
+Instrument your OpenAI calls with a single `initTracing()` call. Traces are exported to the Overmind platform with zero changes to your existing AI code.
+
+---
+
+## Installation
+
+```bash
+bun add overmind-js openai
+# or
+npm install overmind-js openai
+```
+
+---
+
+## Quick Start with OpenAI
+
+```ts
+import { OpenAI } from "openai";
+import { OvermindClient } from "overmind-js";
+
+// 1. Create the client
+const overmindClient = new OvermindClient({
+  apiKey: process.env.OVERMIND_API_KEY!,
+  appName: "my fintech app",
+});
+
+// 2. Initialize tracing — must be called before any OpenAI calls
+overmindClient.initTracing({
+  enableBatching: false,
+  enabledProviders: { openai: true },
+  instrumentations: [],
+});
+
+// 3. Use OpenAI as normal — all calls are automatically traced
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hello, how are you?" }],
+});
+```
+
+Traces are sent automatically to `https://api.overmindlab.ai` and will appear in your Overmind dashboard.
+
+---
+
+## Configuration
+
+### `OvermindClient(config)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your Overmind API key. Falls back to `OVERMIND_API_KEY` env var. |
+| `appName` | `string` | No | Name of your service, shown in the dashboard. Defaults to `"overmind-js"`. |
+| `baseUrl` | `string` | No | Override the Overmind ingest endpoint. Defaults to `OVERMIND_TRACES_URL` env var or `https://api.overmindlab.ai`. |
+
+### `initTracing(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `enabledProviders` | `{ openai?: boolean; anthropic?: boolean }` | Yes | Which LLM providers to instrument. |
+| `enableBatching` | `boolean` | Yes | `true` to batch spans before export (recommended for production), `false` to export immediately. |
+| `instrumentations` | `Instrumentation[]` | No | Additional OpenTelemetry instrumentations to register. |
+| `spanProcessors` | `SpanProcessor[]` | No | Additional span processors (e.g. custom exporters). |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OVERMIND_API_KEY` | Your Overmind API key |
+| `OVERMIND_TRACES_URL` | Override the traces ingest base URL |
+| `DEPLOYMENT_ENVIRONMENT` | Tag traces with an environment (e.g. `production`, `staging`). Defaults to `development`. |
+| `OPENAI_API_KEY` | Your OpenAI API key |
+
+---
+
+## What Gets Traced
+
+When `enabledProviders: { openai: true }` is set, the SDK automatically captures:
+
+- Prompts and completions
+- Model name, temperature, top-p, max tokens
+- Token usage
+- Latency per request
+- Errors and exceptions
+
+All data is attached to OpenTelemetry spans and exported to Overmind.
+
+---
+
+## Production Recommendations
+
+Enable batching in production to reduce network overhead:
+
+```ts
+overmindClient.initTracing({
+  enableBatching: true, // buffer spans and flush in batches
+  enabledProviders: { openai: true },
+});
+```
+
+Use `enableBatching: false` during local development to see traces immediately.
+
+---
+
+## Resource Attributes
+
+Every trace is tagged with the following attributes automatically:
+
+| Attribute | Value |
+|---|---|
+| `service.name` | Value of `appName` |
+| `service.version` | SDK version |
+| `deployment.environment` | `DEPLOYMENT_ENVIRONMENT` env var or `"development"` |
+| `overmind.sdk.name` | `overmind-js` |
+| `overmind.sdk.version` | SDK version |

package/biome.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.3/schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on",
+          "options": {
+            "groups": [
+              ["@opentelemetry/**"],
+              ":BLANK_LINE:",
+              [":PACKAGE:", ":PACKAGE_WITH_PROTOCOL:"],
+              ":BLANK_LINE:",
+              [":PATH:"],
+              ":BLANK_LINE:"
+            ]
+          }
+        },
+        "useSortedKeys": {
+          "level": "on",
+          "options": {}
+        },
+        "useSortedProperties": {
+          "level": "on",
+          "options": {}
+        }
+      }
+    },
+    "enabled": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**"]
+  },
+  "formatter": {
+    "attributePosition": "auto",
+    "enabled": true,
+    "formatWithErrors": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "lineWidth": 100,
+      "quoteStyle": "double",
+      "trailingCommas": "es5"
+    }
+  },
+  "json": {
+    "formatter": {
+      "trailingCommas": "none"
+    }
+  },
+  "linter": {
+    "domains": {
+      "project": "recommended",
+      "test": "recommended"
+    },
+    "enabled": true,
+    "rules": {
+      "suspicious": {
+        "noArrayIndexKey": "off",
+        "noUnknownAtRules": "off"
+      }
+    }
+  },
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "dependencies": {
+    "@opentelemetry/auto-instrumentations-node": "^0.70.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.212.0",
+    "@opentelemetry/instrumentation-openai": "^0.10.0",
+    "@opentelemetry/sdk-node": "^0.212.0",
+    "@opentelemetry/sdk-trace-node": "^2.5.1",
+    "@traceloop/instrumentation-openai": "^0.22.5",
+    "openai": "^6.22.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.3"
+  },
+  "name": "@overmind-lab/trace-sdk",
+  "packageManager": "bun@1.3.5",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "biome check --write",
+    "dev": "tsx watch src/index.ts",
+    "format": "biome format --write"
+  },
+  "version": "0.0.1"
+}