@juspay/neurolink/dist/telemetry/withSpan.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

import { type Span } from "@opentelemetry/api";
import type { GenerationRecord, SpanOptions } from "../types/index.js";
export declare function withSpan<T>(options: SpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;
export declare function withClientSpan<T>(options: Omit<SpanOptions, "kind">, fn: (span: Span) => Promise<T>): Promise<T>;
/**
 * @description Wraps a streaming operation in a span that stays open until the consumer reaches end-of-stream, throws, or closes the iterable, so the span covers the whole stream rather than only its setup.
 * @param options {SpanOptions} - Span name, tracer, kind and initial attributes.
 * @param fn {(span: Span) => Promise<TResult>} - Produces the result; must not depend on the iterable being consumed before returning.
 * @param getIterable {(result: TResult) => AsyncIterable<TChunk>} - Selects the iterable to wrap out of the result.
 * @param setIterable {(result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult} - Returns a new result carrying the wrapped iterable; must clone rather than mutate.
 * @returns {Promise<TResult>} The result with its iterable replaced by the span-lifetime-extending one.
 * @example
 * ```ts
 * return withStreamSpan(
 *   { name: "provider.stream", tracer, attributes: {...} },
 *   async () => this.executeStreamInner(options),
 *   (r) => r.stream,
 *   (r, wrapped) => ({ ...r, stream: wrapped }),
 * );
 * ```
 */
export declare function withStreamSpan<TResult, TChunk>(options: SpanOptions, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult): Promise<TResult>;
/**
 * @description Runs one model request inside a Langfuse generation span, recording the request half before `fn` runs. `fn` records the response half with `observeGeneration`; errors mark the span ERROR.
 * @param request {GenerationRecord} - Provider, model, parameters and input sent.
 * @param fn {(span: Span) => Promise<T>} - Issues the request and returns its result.
 * @returns {Promise<T>} Whatever `fn` resolves to.
 */
export declare function withGeneration<T>(request: GenerationRecord, fn: (span: Span) => Promise<T>): Promise<T>;
/** Convenience CLIENT-kind alias matching `withClientSpan`. */
export declare function withClientStreamSpan<TResult, TChunk>(options: Omit<SpanOptions, "kind">, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult): Promise<TResult>;
/**
 * @description Runs `fn` inside a `step` span, for a single model call that belongs to a step outside the shared loop, such as a forced finalization request.
 * @param stepNumber {number} - One-based step number within the turn.
 * @param fn {() => Promise<T>} - The step's work.
 * @returns {Promise<T>} Whatever `fn` resolves to.
 */
export declare function withStepSpan<T>(stepNumber: number, fn: () => Promise<T>): Promise<T>;
/**
 * @description Groups the observations of each agentic loop step under one `step` span. Call `begin` at the top of a step, run the step's model call and tool dispatch through `run`, and `end` when the loop is over; `begin` closes the previous step.
 */
export declare class StepSpans {
    private current;
    /**
     * @description Closes the previous step and opens `step` under the active span.
     * @param stepNumber {number} - One-based step number within the turn.
     * @returns {void} Nothing.
     */
    begin(stepNumber: number): void;
    /**
     * @description Runs `fn` with the open step as the active span, so the observations it creates become the step's children.
     * @param fn {() => T} - Work belonging to the current step.
     * @returns {T} Whatever `fn` returns.
     */
    run<T>(fn: () => T): T;
    /**
     * @description Closes the open step, if any.
     * @returns {void} Nothing.
     */
    end(): void;
}