langwatch 0.2.0 → 0.3.0-prerelease.1

package/.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[*.ts]
+indent_size = 2
+indent_style = space
+
+[*.md]
+trim_trailing_whitespace = true

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 LangWatch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,270 @@
 # LangWatch TypeScript SDK
 
-This SDK is used to integrate LangWatch with TypeScript projects. Check out the [official documentation](https://docs.langwatch.ai/integration/typescript/guide) for more information, or go to [LangWatch main repository](https://github.com/langwatch/langwatch).
+<p align="center">
+  <img src="https://app.langwatch.ai/logo.svg" alt="LangWatch Logo" width="120"/>
+</p>
+
+<p align="center">
+  <b>Observability, Prompt Management, and Evaluation for JS LLM/GenAI Apps</b><br/>
+  <a href="https://langwatch.ai">langwatch.ai</a> &nbsp;|&nbsp; <a href="https://github.com/langwatch/langwatch">GitHub</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/langwatch"><img src="https://img.shields.io/npm/v/langwatch.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square" alt="License"></a>
+</p>
+
+---
+
+LangWatch helps you monitor, debug, and optimize your LLM/GenAI applications. This TypeScript SDK provides:
+
+- **OpenTelemetry-based tracing** for LLM, RAG, tool, and workflow spans
+- **Prompt management** with versioning and variable interpolation
+- **Automated and custom evaluation** of model outputs
+
+---
+
+## Features
+
+- 📊 **Observability**: Trace LLM, RAG, tool, and workflow operations with rich context
+- 📝 **Prompt Management**: Fetch, version, and interpolate prompts with variables
+- 🧪 **Evaluation**: Run and record evaluations, with results linked to traces
+- 🔌 **OpenTelemetry**: Integrates with your existing observability stack
+- 🦾 **TypeScript-first**: Full type safety and modern API design
+
+---
+
+## Installation
+
+```bash
+npm install langwatch
+```
+
+---
+
+## 🚀 Getting Started
+
+Here's the fastest way to get LangWatch working in your app:
+
+```ts
+import { setupLangWatch } from "langwatch/node";
+import { getLangWatchTracer } from "langwatch";
+
+// 1. Initialize LangWatch (Node.js example)
+await setupLangWatch({ apiKey: "YOUR_API_KEY" }); // By default, this will read the LANGWATCH_API_KEY environment variable
+
+// 2. Create a tracer and span
+const tracer = getLangWatchTracer("my-app");
+const span = tracer.startSpan("my-operation");
+span.setInput("User prompt");
+span.setOutput("Model response");
+span.end();
+```
+
+> **Tip:** For use in the browser, use `import { setupLangWatch } from "langwatch/browser"` instead.
+
+---
+
+## Quick Start: Core Features
+
+### 1. Tracing & Observability
+
+- **Get a tracer:**
+  ```ts
+  const tracer = getLangWatchTracer("my-app");
+  ```
+- **Start a span and record input/output:**
+  ```ts
+  const span = tracer.startSpan("call-llm");
+  span.setType("llm");
+  span.setInput("User prompt"); // Main way to record input
+  span.setOutput("Model response"); // Main way to record output
+  span.end();
+  ```
+  > **Note:** `setInput` and `setOutput` are the primary methods to record input/output. Use `setInputString`/`setOutputString` for plain text, or pass any serializable value.
+
+- **Use withActiveSpan for automatic error handling:**
+  ```ts
+  await tracer.withActiveSpan("my-operation", async (span) => {
+    span.setType("llm");
+    span.setInput("User prompt");
+    // ... your code ...
+    span.setOutput("Model response");
+  });
+  ```
+
+- **Record an evaluation directly on a span:**
+  ```ts
+  span.recordEvaluation({ name: "My Eval", passed: true, score: 1.0 });
+  ```
+  > **Note:** This associates evaluation results with a specific span (operation or model call).
+
+- **(Optional) Add GenAI message events:**
+  ```ts
+  span.addGenAISystemMessageEvent({ content: "You are a helpful assistant." });
+  span.addGenAIUserMessageEvent({ content: "Hello!" });
+  span.addGenAIAssistantMessageEvent({ content: "Hi! How can I help you?" });
+  span.addGenAIToolMessageEvent({ content: "Tool result", id: "tool-1" });
+  span.addGenAIChoiceEvent({ finish_reason: "stop", index: 0, message: { content: "Response" } });
+  ```
+  > **Advanced:** The `addGenAI...` methods are optional and mainly for advanced/manual instrumentation. Most users do not need these unless you want fine-grained message event logs.
+
+- **RAG context, metrics, and model information:**
+  ```ts
+  span.setRAGContexts([{ document_id: "doc1", chunk_id: "c1", content: "..." }]);
+  span.setMetrics({ promptTokens: 10, completionTokens: 20, cost: 0.002 });
+  span.setRequestModel("gpt-4");
+  span.setResponseModel("gpt-4");
+  ```
+
+### 2. Prompt Management
+
+- **Fetch and format a prompt:**
+  ```ts
+  import { getPrompt } from "langwatch/prompt";
+  const prompt = await getPrompt("prompt-id");
+  const compiledPrompt = await getPrompt("prompt-id", { user: "Alice" });
+  ```
+- **Fetch a specific prompt version:**
+  ```ts
+  import { getPromptVersion } from "langwatch/prompt";
+  const compiledPrompt = await getPromptVersion("prompt-id", "version-id", {
+    user: "Alice",
+  });
+  ```
+
+  > **Note:** The prompt APIs (`getPrompt`, `getPromptVersion`) automatically create spans and add useful tracing information.
+
+### 3. Evaluation
+
+- **Run an evaluation:**
+  ```ts
+  import { runEvaluation } from "langwatch/evaluation";
+  const result = await runEvaluation({
+    slug: "helpfulness",
+    data: { input: "Hi", output: "Hello!" }
+  });
+  ```
+- **Record a custom evaluation:**
+  ```ts
+  import { recordEvaluation } from "langwatch/evaluation";
+  recordEvaluation({
+    name: "Manual Eval",
+    passed: true,
+    score: 0.9,
+    details: "Looks good!"
+  });
+  ```
+  > **Note:** The evaluation APIs (`runEvaluation`, `recordEvaluation`) also create spans and add tracing/evaluation info automatically.
+
+### 4. LangChain Integration
+
+- **Use with LangChain:**
+  ```ts
+  import { LangWatchCallbackHandler } from "langwatch/observability/instrumentation/langchain";
+
+  const chatModel = new ChatOpenAI({
+    callbacks: [new LangWatchCallbackHandler()],
+  });
+  ```
+
+---
+
+## API Reference
+
+### Setup
+- `setupLangWatch(options?)` → Initialize LangWatch (from `langwatch/node` or `langwatch/browser`)
+
+### Observability
+- `getLangWatchTracer(name, version?)` → `LangWatchTracer`
+- `LangWatchTracer` methods: `.startSpan()`, `.startActiveSpan()`, `.withActiveSpan()`
+- `LangWatchSpan` methods:
+  - `.setType()`, `.setInput()`, `.setOutput()`, `.setInputString()`, `.setOutputString()`
+  - `.recordEvaluation()`, `.setRequestModel()`, `.setResponseModel()`
+  - `.setRAGContexts()`, `.setRAGContext()`, `.setMetrics()`, `.setSelectedPrompt()`
+  - `.addGenAISystemMessageEvent()`, `.addGenAIUserMessageEvent()`, `.addGenAIAssistantMessageEvent()`, `.addGenAIToolMessageEvent()`, `.addGenAIChoiceEvent()`
+
+### Prompt
+- `getPrompt(promptId, variables?)` → fetches and formats a prompt (creates a span automatically)
+- `getPromptVersion(promptId, versionId, variables?)` → fetches specific prompt version
+
+### Evaluation
+- `runEvaluation(details)` → runs an evaluation and returns result (creates a span automatically)
+- `recordEvaluation(details, attributes?)` → records a custom evaluation span (creates a span automatically)
+
+### LangChain Integration
+- `LangWatchCallbackHandler` → LangChain callback handler for automatic instrumentation
+
+### Exporters & Processors
+- `LangWatchExporter` → Custom OpenTelemetry exporter
+- `FilterableBatchSpanProcessor` → Span processor with filtering capabilities
+
+---
+
+## Types
+
+### Core Types
+- `LangWatchSpan` → Extended OpenTelemetry span with LangWatch methods
+- `LangWatchTracer` → Extended OpenTelemetry tracer with LangWatch methods
+- `SpanType` → Union of supported span types (`"llm"`, `"chain"`, `"tool"`, `"agent"`, etc.)
+
+### Evaluation Types
+- `EvaluationDetails` → Configuration for running evaluations
+- `SingleEvaluationResult` → Result from evaluation runs
+- `RecordedEvaluationDetails` → Configuration for recording custom evaluations
+
+### Prompt Types
+- `Prompt` → Prompt object with compilation capabilities
+- `CompiledPrompt` → Compiled prompt with variables interpolated
+- `TemplateVariables` → Variables for prompt compilation
+
+### RAG & Metrics Types
+- `LangWatchSpanRAGContext` → RAG context structure
+- `LangWatchSpanMetrics` → Metrics structure (tokens, cost)
+- `LangWatchSpanGenAI*EventBody` → GenAI message event structures
+
+---
+
+## Advanced
+
+### Custom OpenTelemetry Integration
+```ts
+import { FilterableBatchSpanProcessor, LangWatchExporter } from "langwatch";
+
+const processor = new FilterableBatchSpanProcessor(
+  new LangWatchExporter(apiKey, endpoint),
+  excludeRules
+);
+```
+
+### Span Processing Rules
+```ts
+const excludeRules: SpanProcessingExcludeRule[] = [
+  { attribute: "http.url", value: "/health" },
+  { attribute: "span.type", value: "health" }
+];
+```
+
+### Manual Instrumentation
+```ts
+import { semconv } from "langwatch/observability";
+
+span.setAttributes({
+  [semconv.ATTR_LANGWATCH_THREAD_ID]: threadId,
+});
+```
+
+---
+
+## Community & Support
+
+- [LangWatch Website](https://langwatch.ai)
+- [Documentation](https://docs.langwatch.ai)
+- [GitHub Issues](https://github.com/langwatch/langwatch/issues)
+- [Discord Community](https://discord.gg/langwatch)
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/copy-types.sh

@@ -1,17 +1,28 @@
+#!/bin/bash
+
 set -e
 
-cp ../langwatch/src/server/tracer/types.ts src/server/types/tracer.ts
-ts-to-zod src/server/types/tracer.ts src/server/types/tracer.generated.ts
+cp ../langwatch/src/server/tracer/types.ts src/internal/generated/types/tracer.ts
+ts-to-zod src/internal/generated/types/tracer.ts src/internal/generated/types/tracer.generated.ts
 
-cp ../langwatch/src/server/evaluations/types.ts src/server/types/evaluations.ts
+cp ../langwatch/src/server/evaluations/types.ts src/internal/generated/types/evaluations.ts
 if [[ "$OSTYPE" == "darwin"* ]]; then
-  sed -i '' 's/\.\.\/tracer\/types\.generated/.\/tracer.generated/g' src/server/types/evaluations.ts
+  sed -i '' 's/\.\.\/tracer\/types\.generated/.\/tracer.generated/g' src/internal/generated/types/evaluations.ts
 else
-  sed -i 's/\.\.\/tracer\/types\.generated/.\/tracer.generated/g' src/server/types/evaluations.ts
+  sed -i 's/\.\.\/tracer\/types\.generated/.\/tracer.generated/g' src/internal/generated/types/evaluations.ts
 fi
-ts-to-zod src/server/types/evaluations.ts src/server/types/evaluations.generated.ts
+ts-to-zod src/internal/generated/types/evaluations.ts src/internal/generated/types/evaluations.generated.ts
 
-cd src/server/types/
+cd src/internal/generated/types/
 curl -L "https://raw.githubusercontent.com/langwatch/langevals/main/ts-integration/evaluators.generated.ts?$(date +%s)" -o evaluators.generated.ts
 cd -
-ts-to-zod src/server/types/evaluators.generated.ts src/server/types/evaluators.zod.generated.ts
+ts-to-zod src/internal/generated/types/evaluators.generated.ts src/internal/generated/types/evaluators.zod.generated.ts
+
+# Fix z.record(z.never()) to z.record(z.string(), z.never())
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  sed -i '' 's/z\.record(z\.never())/z.record(z.string(), z.never())/g' src/internal/generated/types/evaluators.zod.generated.ts
+  sed -i '' 's/z\.record(z\.any())/z.record(z.string(), z.any())/g' src/internal/generated/types/tracer.generated.ts
+else
+  sed -i 's/z\.record(z\.never())/z.record(z.string(), z.never())/g' src/internal/generated/types/evaluators.zod.generated.ts
+  sed -i 's/z\.record(z\.any())/z.record(z.string(), z.any())/g' src/internal/generated/types/tracer.generated.ts
+fi

package/examples/langchain/.env.example

@@ -0,0 +1,2 @@
+LANGWATCH_API_KEY=""
+OPENAI_API_KEY=""

package/examples/langchain/README.md

@@ -0,0 +1,42 @@
+# LangChain Example
+
+This directory contains examples of AI apps built with the LangWatch SDK and LangChain.
+
+## Example
+
+### Basic Chatbot (`src/index.ts`)
+
+A simple chatbot that handles basic conversation flow using LangChain:
+
+- **Features:**
+  - Basic conversation loop
+  - User input handling
+  - AI response generation using LangChain
+  - Conversation history management
+  - Error handling
+  - Exit commands (`quit`, `exit`)
+
+- **Usage:**
+  ```bash
+  npm run start
+  ```
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **"Cannot find module 'langwatch/node'"**
+   - Make sure you've built the LangWatch SDK
+   - Check that the package is properly built
+
+2. **OpenAI API errors**
+   - Verify your API key is set correctly
+   - Check your OpenAI account has sufficient credits
+
+3. **TypeScript compilation errors**
+   - Run `npm run start` to check for type errors
+   - Ensure all dependencies are installed
+
+4. **LangChain import errors**
+   - Make sure all LangChain dependencies are installed
+   - Check that the LangChain version is compatible