@lmnr-ai/lmnr 0.3.0 → 0.3.2

package/.eslintrc.json

@@ -0,0 +1,2 @@
+{
+}

package/README.md

@@ -8,11 +8,85 @@ npm install @lmnr-ai/lmnr
 
 ## Features
 
-- Make Laminar endpoint calls from your JS code
-- Make Laminar endpoint calls that can run your own functions as tools from your NodeJS code
-- `LaminarRemoteDebugger` to execute your own functions while you test your flows in workshop
+- Instrumentation of your JS/TS code
+- Events and semantic events right from the code
+- Make Laminar pipeline calls from your JS code
 
-## Making Laminar endpoint calls
+## Prerequisite
+
+- Laminar project created at https://lmnr.ai
+- Export (or set using .env) a variable `LMNR_PROJECT_API_KEY` with the value from the project settings page
+
+## Code instrumentation 
+
+For manual instrumetation you will need to import the following:
+- `trace` - this is a function to start a trace. It returns a `TraceContext`
+- `TraceContext` - a pointer to the current trace that you can pass around functions as you want.
+- `SpanContext` - a pointer to the current span that you can pass around functions as you want
+- `ObservationContext` – parent class of `TraceContext` and `SpanContext`. Useful, if you don't want to import the separate context types in TS.
+
+Both `TraceContext` and `SpanContext` expose the following interfaces:
+- `span(name: string, props: CreateSpanProps)` - create a child span within the current context. Returns `SpanContext`
+- `update(props)` - update the current trace or span and return it. Returns `TraceContext` or `SpanContext`. Useful when some metadata becomes known later during the program execution
+
+In addition, `SpanContext` allows you to:
+- `event(templateName: string, props: SpanEventProps)` - emit a custom event at any point
+- `evaluateEvent(templateName: string, data: str, props: SpanEvaluateEventProps)` - register a possible event for automatic checking by Laminar.
+- `end(props: UpdateSpanProps)` – update the current span, and terminate it
+
+### Example
+
+```javascript
+// `trace()` is the main entrypoint into the observation of your app
+// `ObservationContext` is a parent class for `SpanContext` and `TraceContext`
+import { trace, ObservationContext } from '@lmnr-ai/lmnr';
+
+import OpenAI from 'openai';
+
+const openai = new OpenAI({apiKey: process.env.OPENAI_API_KEY});
+
+const getRandomCountry = (s: ObservationContext): string => {
+    // create the span without registering the input
+    const span = s.span('getRandomCountry');
+    const countries = ['United States', 'Canada', 'Australia', 'Germany', 'Japan'];
+    const country =  countries[Math.floor(Math.random() * countries.length)];
+    
+    // end the span and register the output
+    span.end({output: country});
+
+    return country;
+}
+
+const foo = (question: string, t: ObservationContext) => {
+    // create the span and register the input
+    const span = t.span('foo', {input: {question}});
+
+    // pass the span context down the function call if you want to trace it
+    const country = getRandomCountry(span);
+    question += country;
+    const result = openai.chat.completions.create({
+        model: 'gpt-4o-mini',
+        messages: [{role: 'system', content: 'You are a helpful assistant.'}, {role: 'user', content: question}],
+    }).then((response) => {
+        const output = response.choices[0].message.content;
+
+        // ask Laminar to check for a pre-defined event.
+        // In this example correctness is pre-defined in the UI as "The data is factually correct"
+        span.evalueateEvent('correctness', output ?? '');
+        // end the span and register the output
+        span.end({output});
+    });
+};
+
+// Start the trace observation at the entry to your program
+const t = trace();
+
+// pass the trace context into the handler
+foo("What is the capital of ", t);
+
+```
+
+## Making Laminar pipeline calls
 
 After you are ready to use your pipeline in your code, deploy it in Laminar by selecting the target version for the pipeline.
 
@@ -21,7 +95,7 @@ Once your pipeline target is set, you can call it from JS in just a few lines.
 Example use:
 
 ```typescript
-import { Laminar, NodeInput } from '@lmnr-ai/lmnr';
+import { Laminar } from '@lmnr-ai/lmnr';
 
 const l = new Laminar('<YOUR_PROJECT_API_KEY>');
 const result = await l.run({

package/dist/index.d.mts

@@ -0,0 +1,136 @@
+type ChatMessage = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+};
+type NodeInput = ChatMessage[] | string;
+type PipelineRunRequest = {
+    inputs: Record<string, NodeInput>;
+    pipeline: string;
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+};
+type PipelineRunResponse = {
+    outputs: Record<string, Record<string, NodeInput>>;
+    runId: string;
+};
+type EvaluateEvent = {
+    name: string;
+    data: string;
+    timestamp?: Date;
+};
+type Event = {
+    id: string;
+    templateName: string;
+    timestamp: Date;
+    spanId: string;
+    value: number | string | null;
+};
+type SpanType = 'DEFAULT' | 'LLM';
+type Span = {
+    version: string;
+    spanType: SpanType;
+    id: string;
+    parentSpanId: string | null;
+    traceId: string;
+    name: string;
+    startTime: Date;
+    endTime: Date | null;
+    attributes: Record<string, any>;
+    input: any | null;
+    output: any | null;
+    metadata: Record<string, any> | null;
+    evaluateEvents: EvaluateEvent[];
+    events: Event[];
+};
+type Trace = {
+    id: string;
+    version: string;
+    success: boolean;
+    startTime: Date | null;
+    endTime: Date | null;
+    userId: string | null;
+    sessionId: string | null;
+    release: string;
+    metadata: Record<string, any> | null;
+};
+
+declare class Collector {
+    private readonly flushInterval;
+    private readonly client;
+    private readonly maxQueueSize;
+    private queue;
+    private flushTimeout;
+    constructor();
+    addTask(task: Span | Trace): void;
+    private flush;
+}
+
+interface CreateSpanProps {
+    input?: any | null;
+    metadata?: Record<string, any> | null;
+    attributes?: Record<string, any>;
+    spanType?: SpanType;
+}
+declare class ObservationContext {
+    protected observation: Span | Trace;
+    parent: ObservationContext | null;
+    children: Record<string, SpanContext>;
+    protected collector: Collector;
+    constructor(observation: Span | Trace, parent: ObservationContext | null);
+    id(): string;
+    span(name: string, { input, metadata, attributes, spanType, }?: CreateSpanProps): SpanContext;
+}
+interface UpdateSpanProps {
+    input?: any | null;
+    output?: any | null;
+    metadata?: Record<string, any> | null;
+    attributes?: Record<string, any>;
+    evaluateEvents?: EvaluateEvent[];
+    override?: boolean;
+}
+interface SpanEventProps {
+    value?: string | number | boolean;
+    timestamp?: Date;
+}
+interface SpanEvaluateEventProps {
+    timestamp?: Date;
+}
+declare class SpanContext extends ObservationContext {
+    private inerSpan;
+    constructor(span: Span, parent: ObservationContext);
+    end({ input, output, metadata, attributes, evaluateEvents, override }?: UpdateSpanProps): SpanContext;
+    update({ input, output, metadata, attributes, evaluateEvents, override }: UpdateSpanProps): SpanContext;
+    event(templateName: string, { value, timestamp, }?: SpanEventProps): SpanContext;
+    evalueateEvent(templateName: string, data: string, { timestamp }?: SpanEvaluateEventProps): SpanContext;
+    private getParent;
+    private innerUpdate;
+}
+interface UpdateTraceProps {
+    success?: boolean;
+    userId?: string | null;
+    sessionId?: string | null;
+    release?: string;
+    metadata?: Record<string, any> | null;
+}
+declare class TraceContext extends ObservationContext {
+    private trace;
+    constructor(trace: Trace, parent: ObservationContext | null);
+    update({ success, userId, sessionId, release, metadata }?: UpdateTraceProps): TraceContext;
+}
+interface TraceProps {
+    userId?: string | null;
+    sessionId?: string | null;
+    release?: string;
+    metadata?: Record<string, any> | null;
+}
+declare const trace: ({ userId, sessionId, release, metadata, }?: TraceProps) => TraceContext;
+
+declare class Laminar {
+    private readonly projectApiKey;
+    private readonly url;
+    private readonly response;
+    constructor(projectApiKey: string);
+    run({ pipeline, inputs, env, metadata, }: PipelineRunRequest): Promise<PipelineRunResponse>;
+}
+
+export { type ChatMessage, type EvaluateEvent, type Event, Laminar, type NodeInput, ObservationContext, type PipelineRunRequest, type PipelineRunResponse, type Span, SpanContext, type Trace, TraceContext, trace };

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+type ChatMessage = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+};
+type NodeInput = ChatMessage[] | string;
+type PipelineRunRequest = {
+    inputs: Record<string, NodeInput>;
+    pipeline: string;
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+};
+type PipelineRunResponse = {
+    outputs: Record<string, Record<string, NodeInput>>;
+    runId: string;
+};
+type EvaluateEvent = {
+    name: string;
+    data: string;
+    timestamp?: Date;
+};
+type Event = {
+    id: string;
+    templateName: string;
+    timestamp: Date;
+    spanId: string;
+    value: number | string | null;
+};
+type SpanType = 'DEFAULT' | 'LLM';
+type Span = {
+    version: string;
+    spanType: SpanType;
+    id: string;
+    parentSpanId: string | null;
+    traceId: string;
+    name: string;
+    startTime: Date;
+    endTime: Date | null;
+    attributes: Record<string, any>;
+    input: any | null;
+    output: any | null;
+    metadata: Record<string, any> | null;
+    evaluateEvents: EvaluateEvent[];
+    events: Event[];
+};
+type Trace = {
+    id: string;
+    version: string;
+    success: boolean;
+    startTime: Date | null;
+    endTime: Date | null;
+    userId: string | null;
+    sessionId: string | null;
+    release: string;
+    metadata: Record<string, any> | null;
+};
+
+declare class Collector {
+    private readonly flushInterval;
+    private readonly client;
+    private readonly maxQueueSize;
+    private queue;
+    private flushTimeout;
+    constructor();
+    addTask(task: Span | Trace): void;
+    private flush;
+}
+
+interface CreateSpanProps {
+    input?: any | null;
+    metadata?: Record<string, any> | null;
+    attributes?: Record<string, any>;
+    spanType?: SpanType;
+}
+declare class ObservationContext {
+    protected observation: Span | Trace;
+    parent: ObservationContext | null;
+    children: Record<string, SpanContext>;
+    protected collector: Collector;
+    constructor(observation: Span | Trace, parent: ObservationContext | null);
+    id(): string;
+    span(name: string, { input, metadata, attributes, spanType, }?: CreateSpanProps): SpanContext;
+}
+interface UpdateSpanProps {
+    input?: any | null;
+    output?: any | null;
+    metadata?: Record<string, any> | null;
+    attributes?: Record<string, any>;
+    evaluateEvents?: EvaluateEvent[];
+    override?: boolean;
+}
+interface SpanEventProps {
+    value?: string | number | boolean;
+    timestamp?: Date;
+}
+interface SpanEvaluateEventProps {
+    timestamp?: Date;
+}
+declare class SpanContext extends ObservationContext {
+    private inerSpan;
+    constructor(span: Span, parent: ObservationContext);
+    end({ input, output, metadata, attributes, evaluateEvents, override }?: UpdateSpanProps): SpanContext;
+    update({ input, output, metadata, attributes, evaluateEvents, override }: UpdateSpanProps): SpanContext;
+    event(templateName: string, { value, timestamp, }?: SpanEventProps): SpanContext;
+    evalueateEvent(templateName: string, data: string, { timestamp }?: SpanEvaluateEventProps): SpanContext;
+    private getParent;
+    private innerUpdate;
+}
+interface UpdateTraceProps {
+    success?: boolean;
+    userId?: string | null;
+    sessionId?: string | null;
+    release?: string;
+    metadata?: Record<string, any> | null;
+}
+declare class TraceContext extends ObservationContext {
+    private trace;
+    constructor(trace: Trace, parent: ObservationContext | null);
+    update({ success, userId, sessionId, release, metadata }?: UpdateTraceProps): TraceContext;
+}
+interface TraceProps {
+    userId?: string | null;
+    sessionId?: string | null;
+    release?: string;
+    metadata?: Record<string, any> | null;
+}
+declare const trace: ({ userId, sessionId, release, metadata, }?: TraceProps) => TraceContext;
+
+declare class Laminar {
+    private readonly projectApiKey;
+    private readonly url;
+    private readonly response;
+    constructor(projectApiKey: string);
+    run({ pipeline, inputs, env, metadata, }: PipelineRunRequest): Promise<PipelineRunResponse>;
+}
+
+export { type ChatMessage, type EvaluateEvent, type Event, Laminar, type NodeInput, ObservationContext, type PipelineRunRequest, type PipelineRunResponse, type Span, SpanContext, type Trace, TraceContext, trace };

package/dist/index.js

@@ -0,0 +1,319 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Laminar: () => Laminar,
+  ObservationContext: () => ObservationContext,
+  SpanContext: () => SpanContext,
+  TraceContext: () => TraceContext,
+  trace: () => trace
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/types.ts
+var DEFAULT_SPAN_TYPE = "DEFAULT";
+
+// src/constants.ts
+var CURRENT_TRACING_VERSION = "0.1.0";
+
+// src/tracing.ts
+var Collector = class {
+  constructor() {
+    this.flushInterval = 2;
+    // seconds
+    this.client = new Client(process.env.LMNR_PROJECT_API_KEY || "");
+    this.maxQueueSize = 1e3;
+    this.queue = [];
+    this.flushTimeout = setTimeout(this.flush.bind(this), this.flushInterval * 1e3);
+  }
+  addTask(task) {
+    this.queue.push(task);
+    if (this.queue.length >= this.maxQueueSize) {
+      this.flush();
+    }
+    if (!this.flushTimeout) {
+      this.flushTimeout = setTimeout(this.flush.bind(this), this.flushInterval * 1e3);
+    }
+  }
+  flush() {
+    if (this.flushTimeout != null) {
+      clearTimeout(this.flushTimeout);
+      this.flushTimeout = null;
+    }
+    if (this.queue.length === 0) {
+      return;
+    }
+    this.client.batchPost(this.queue);
+    this.queue = [];
+  }
+};
+var CollectorSingleton = class {
+  static getInstance() {
+    if (this.instance === null) {
+      this.instance = new Collector();
+    }
+    return this.instance;
+  }
+};
+CollectorSingleton.instance = null;
+var Client = class {
+  constructor(projectApiKey) {
+    this.baseUrl = "https://api.lmnr.ai";
+    this.projectApiKey = projectApiKey;
+  }
+  getHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${this.projectApiKey}`
+    };
+  }
+  batchPost(data) {
+    const body = JSON.stringify({
+      traces: data
+    });
+    const headers = this.getHeaders();
+    const url = `${this.baseUrl}/v1/traces`;
+    fetch(url, {
+      method: "POST",
+      headers,
+      body
+    }).then((response) => {
+      if (!response.ok) {
+        console.error("Failed to send traces. Response: ");
+        response.text().then((text) => console.error(text));
+      }
+    }).catch((error) => {
+      console.error("Failed to send traces. Error: ", error);
+    });
+  }
+};
+
+// src/utils.ts
+var import_uuid = require("uuid");
+var newUUID = () => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  } else {
+    return (0, import_uuid.v4)();
+  }
+};
+
+// src/interface.ts
+var ObservationContext = class {
+  constructor(observation, parent) {
+    this.observation = observation;
+    this.parent = parent;
+    this.children = {};
+    this.collector = CollectorSingleton.getInstance();
+  }
+  id() {
+    return this.observation.id;
+  }
+  span(name, {
+    input,
+    metadata,
+    attributes,
+    spanType
+  } = {}) {
+    const parent = this;
+    const parentSpanId = parent instanceof SpanContext ? parent.observation.id : null;
+    const traceId = parent instanceof TraceContext ? parent.observation.id : parent.observation.traceId;
+    const span = {
+      version: CURRENT_TRACING_VERSION,
+      spanType: spanType != null ? spanType : DEFAULT_SPAN_TYPE,
+      id: newUUID(),
+      parentSpanId,
+      traceId,
+      name,
+      startTime: /* @__PURE__ */ new Date(),
+      endTime: null,
+      attributes: attributes != null ? attributes : {},
+      input: input != null ? input : null,
+      output: null,
+      metadata: metadata != null ? metadata : null,
+      evaluateEvents: [],
+      events: []
+    };
+    const spanContext = new SpanContext(span, this);
+    this.children[span.id] = spanContext;
+    return spanContext;
+  }
+};
+var SpanContext = class extends ObservationContext {
+  constructor(span, parent) {
+    super(span, parent);
+    this.inerSpan = span;
+  }
+  end({
+    input,
+    output,
+    metadata,
+    attributes,
+    evaluateEvents,
+    override
+  } = {}) {
+    if (this.children && Object.keys(this.children).length > 0) {
+      console.warn(`Ending span ${this.observation.id}, but it has children that have not been finalized. Children: ${Object.values(this.children).map((child) => child.inerSpan.name)}`);
+    }
+    delete this.getParent().children[this.inerSpan.id];
+    this.innerUpdate(input, output, metadata, attributes, evaluateEvents, override, true);
+    return this;
+  }
+  update({
+    input,
+    output,
+    metadata,
+    attributes,
+    evaluateEvents,
+    override
+  }) {
+    return this.innerUpdate(input, output, metadata, attributes, evaluateEvents, override, false);
+  }
+  event(templateName, {
+    value,
+    timestamp
+  } = {}) {
+    const event = {
+      id: newUUID(),
+      templateName,
+      timestamp: timestamp != null ? timestamp : /* @__PURE__ */ new Date(),
+      spanId: this.inerSpan.id,
+      value: value != null ? value : null
+    };
+    this.inerSpan.events.push(event);
+    return this;
+  }
+  evalueateEvent(templateName, data, {
+    timestamp
+  } = {}) {
+    const event = {
+      name: templateName,
+      data,
+      timestamp: timestamp != null ? timestamp : /* @__PURE__ */ new Date()
+    };
+    this.inerSpan.evaluateEvents.push(event);
+    return this;
+  }
+  getParent() {
+    return this.parent;
+  }
+  innerUpdate(input, output, metadata, attributes, evaluateEvents, override, finalize) {
+    const newMetadata = override ? metadata : { ...this.observation.metadata, ...metadata != null ? metadata : {} };
+    const newAttributes = override ? attributes : { ...this.inerSpan.attributes, ...attributes != null ? attributes : {} };
+    const newEvaluateEvents = override ? evaluateEvents : [...this.inerSpan.evaluateEvents, ...evaluateEvents != null ? evaluateEvents : []];
+    this.inerSpan.input = input || this.inerSpan.input;
+    this.inerSpan.output = output || this.inerSpan.output;
+    this.inerSpan.metadata = newMetadata != null ? newMetadata : null;
+    this.inerSpan.attributes = newAttributes != null ? newAttributes : {};
+    this.inerSpan.evaluateEvents = newEvaluateEvents != null ? newEvaluateEvents : [];
+    if (finalize) {
+      this.inerSpan.endTime = /* @__PURE__ */ new Date();
+      this.collector.addTask(this.inerSpan);
+    }
+    return this;
+  }
+};
+var TraceContext = class extends ObservationContext {
+  constructor(trace2, parent) {
+    super(trace2, parent);
+    this.trace = trace2;
+    this.collector.addTask(this.trace);
+  }
+  update({
+    success,
+    userId,
+    sessionId,
+    release,
+    metadata
+  } = {}) {
+    const newMetadata = metadata ? { ...this.observation.metadata, ...metadata } : this.observation.metadata;
+    this.trace.success = success != null ? success : this.trace.success;
+    this.trace.userId = userId != null ? userId : this.trace.userId;
+    this.trace.sessionId = sessionId != null ? sessionId : this.trace.sessionId;
+    this.trace.release = release != null ? release : this.trace.release;
+    this.trace.metadata = newMetadata != null ? newMetadata : null;
+    this.collector.addTask(this.trace);
+    return this;
+  }
+};
+var trace = ({
+  userId,
+  sessionId,
+  release,
+  metadata
+} = {}) => {
+  const trace2 = {
+    id: newUUID(),
+    version: CURRENT_TRACING_VERSION,
+    success: true,
+    startTime: /* @__PURE__ */ new Date(),
+    endTime: null,
+    userId: userId != null ? userId : null,
+    sessionId: sessionId != null ? sessionId : newUUID(),
+    release: release != null ? release : "v1",
+    metadata: metadata != null ? metadata : null
+  };
+  return new TraceContext(trace2, null);
+};
+
+// src/index.ts
+var Laminar = class {
+  constructor(projectApiKey) {
+    this.response = null;
+    this.projectApiKey = projectApiKey != null ? projectApiKey : process.env.LMNR_PROJECT_API_KEY;
+    this.url = "https://api.lmnr.ai/v1/pipeline/run";
+  }
+  async run({
+    pipeline,
+    inputs,
+    env = {},
+    metadata = {}
+  }) {
+    if (this.projectApiKey === void 0) {
+      throw new Error(
+        "Please initialize the Laminar object with your project API key or set the LMNR_PROJECT_API_KEY environment variable"
+      );
+    }
+    const response = await fetch(this.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.projectApiKey}`
+      },
+      body: JSON.stringify({
+        inputs,
+        pipeline,
+        env,
+        metadata
+      })
+    });
+    return await response.json();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Laminar,
+  ObservationContext,
+  SpanContext,
+  TraceContext,
+  trace
+});
+//# sourceMappingURL=index.js.map