neatlogs 1.0.2

package/dist/index.d.mts

@@ -0,0 +1,531 @@
+import { Span as Span$1 } from '@opentelemetry/api';
+
+/**
+ * Span kind for categorizing instrumented operations.
+ */
+type SpanKind = 'WORKFLOW' | 'AGENT' | 'CHAIN' | 'TOOL' | 'RETRIEVER' | 'EMBEDDING' | 'MCP_TOOL' | 'GUARDRAIL';
+/**
+ * A mask function that can redact or transform span data before export.
+ * Return null to drop the span entirely.
+ */
+type MaskFunction = (spanData: Record<string, any>) => Record<string, any> | null;
+/**
+ * A prompt message with role and content.
+ */
+interface PromptMessage {
+    role: string;
+    content: string;
+}
+/**
+ * Options for initializing the Neatlogs SDK.
+ */
+interface InitOptions {
+    /** Neatlogs API key. Falls back to NEATLOGS_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the Neatlogs API. Defaults to https://app.neatlogs.com */
+    baseUrl?: string;
+    /** Name of the workflow being traced. Defaults to process.argv[1]. */
+    workflowName?: string;
+    /** Explicit session ID for grouping traces. */
+    sessionId?: string;
+    /** Auto-generate a session ID if none provided. Defaults to false. */
+    autoSession?: boolean;
+    /** User identifier for the session. */
+    userId?: string;
+    /** Tags to attach to all spans. Must be string array. */
+    tags?: string[];
+    /** Custom metadata to attach to all spans. */
+    metadata?: Record<string, any>;
+    /** Enable debug logging. Defaults to false. */
+    debug?: boolean;
+    /** Disable export to Neatlogs backend. Defaults to false. */
+    disableExport?: boolean;
+    /** Libraries to auto-instrument (e.g., ['openai', 'anthropic']). */
+    instrumentations?: string[];
+    /** Global mask function applied to all spans. */
+    mask?: MaskFunction;
+    /** Sampling rate (0.0 to 1.0). Defaults to 1.0. */
+    sampleRate?: number;
+    /** Whether to capture log records. Defaults to true. */
+    captureLogs?: boolean;
+    /** Whether to capture input/output content. Defaults to true. */
+    traceContent?: boolean;
+    /** PII detection settings. */
+    pii?: 'redact' | 'hash' | false;
+    /** SDK version override. */
+    version?: string;
+    /** Backend endpoint URL. Defaults to https://staging-cloud.neatlogs.com/api/data/v4/batch */
+    endpoint?: string;
+    /** Maximum spans per export batch. Defaults to 100. */
+    batchSize?: number;
+    /** Seconds between batch flushes. Defaults to 5. */
+    flushInterval?: number;
+    /** Override team-level PII redaction toggle. true = enable, false = disable. */
+    piiEnabled?: boolean;
+    /** Override which span types have server-side PII redaction applied. */
+    piiSpanTypes?: string[];
+}
+/**
+ * Options for the span() function wrapper.
+ */
+interface SpanOptions {
+    /** The kind of span. Required. */
+    kind: SpanKind;
+    /** Custom name for the span. Defaults to the function name. */
+    name?: string;
+    /** Human-readable description of what this span does. */
+    description?: string;
+    /** Whether to capture function input. Defaults to true. */
+    captureInput?: boolean;
+    /** Whether to capture function output. Defaults to true. */
+    captureOutput?: boolean;
+    /** Per-span mask function. */
+    mask?: MaskFunction;
+    /** Mark this span as internal (not user-facing). */
+    internal?: boolean;
+    /** Agent role (for kind: AGENT). */
+    role?: string;
+    /** Agent goal (for kind: AGENT). */
+    goal?: string;
+    /** Tool name (for kind: TOOL or MCP_TOOL). */
+    toolName?: string;
+    /** Tool parameters schema (for kind: TOOL). */
+    parameters?: Record<string, any>;
+    /** JSON schema describing the tool interface (for kind: MCP_TOOL). */
+    toolJsonSchema?: Record<string, any>;
+    /** Embedding model name (for kind: EMBEDDING). */
+    model?: string;
+    /** Embedding dimension (for kind: EMBEDDING). */
+    dimension?: number;
+}
+/**
+ * Options for the trace() context wrapper.
+ */
+interface TraceOptions {
+    /** Name for the trace span. */
+    name: string;
+    /** Span kind. Defaults to 'CHAIN'. */
+    kind?: SpanKind;
+    /** Input data for this span. Auto-serialized to input.value. */
+    input?: any;
+    /** Prompt template to associate with this trace (string or PromptTemplate instance). */
+    promptTemplate?: string | {
+        template: string | PromptMessage[];
+        variables: string[];
+    };
+    /** Prompt variables used in this trace. */
+    promptVariables?: Record<string, any>;
+    /** User prompt template (string or UserPromptTemplate instance). */
+    userPromptTemplate?: string | {
+        template: string | PromptMessage[];
+        variables: string[];
+    };
+    /** User prompt variables used in this trace. */
+    userPromptVariables?: Record<string, any>;
+    /** Prompt version identifier. */
+    version?: string;
+    /** Per-trace mask function. */
+    mask?: MaskFunction;
+    /** Custom attributes to set on the span. */
+    attributes?: Record<string, any>;
+    /** Allow extra attributes via index signature. */
+    [key: string]: any;
+}
+/**
+ * Cached prompt data from the Neatlogs API.
+ */
+interface CachedPrompt {
+    id: string;
+    name: string;
+    version: number;
+    content: string | null;
+    messages: PromptMessage[] | null;
+    config: Record<string, any>;
+    labels: string[];
+    updatedAt: string;
+    type: 'text' | 'chat';
+}
+
+/**
+ * Context wrapper for manual span creation.
+ *
+ * Provides the `trace()` function — the TypeScript equivalent of the Python
+ * `trace()` context manager. Creates an OTel span, sets prompt template/variable
+ * context, and executes the user callback within the span.
+ *
+ * @example
+ * ```typescript
+ * await trace({ name: 'my-trace' }, async (span) => {
+ *   // user code runs here with the span active
+ * });
+ * ```
+ */
+
+/**
+ * Get a copy of the current session configuration.
+ */
+declare function getSessionConfig(): Record<string, any>;
+/**
+ * Async callback wrapper for manual span creation with prompt tracking.
+ *
+ * Creates an OTel span, optionally sets prompt template/variable context,
+ * and executes the provided callback within the span.
+ *
+ * **Session-Aware Trace Creation:**
+ * - If `session_id` is set in init() AND no active parent span exists,
+ *   this creates a NEW root trace (for multi-turn conversations).
+ * - Otherwise, creates a normal child span within the existing trace.
+ *
+ * @param options - Trace configuration options
+ * @param fn - Callback that receives the active span
+ * @returns The return value of the callback
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await trace({ name: 'my-pipeline' }, async (span) => {
+ *   await step1();
+ *   await step2();
+ * });
+ *
+ * // With prompt template
+ * const template = new PromptTemplate('Hello {{name}}');
+ * await trace({ name: 'prompt', promptTemplate: template }, async (span) => {
+ *   const rendered = template.compile({ name: 'world' });
+ *   // ...
+ * });
+ * ```
+ */
+declare function trace<T>(options: TraceOptions, fn: (span: Span$1) => T | Promise<T>): Promise<T>;
+
+/**
+ * Neatlogs SDK initialisation, flush, and shutdown.
+ *
+ * Port of Python neatlogs/init.py to TypeScript.
+ *
+ * `init()` sets up the OTel TracerProvider, MeterProvider, LoggerProvider,
+ * span processors, exporters, and instrumentation.
+ * `flush()` and `shutdown()` handle graceful cleanup.
+ */
+
+/**
+ * Initialise the Neatlogs SDK.
+ *
+ * Sets up OTel TracerProvider, MeterProvider, LoggerProvider, span processors,
+ * exporters and auto-instrumentation. Returns a Promise because library
+ * instrumentation uses dynamic `import()`.
+ */
+declare function init(options?: InitOptions): Promise<void>;
+/**
+ * Flush all pending spans, metrics, and log records.
+ *
+ * @returns true if all providers flushed successfully
+ */
+declare function flush(): Promise<boolean>;
+/**
+ * Shutdown the SDK and flush all pending spans, metrics, and log records.
+ *
+ * Resets all module-level state so `init()` can be called again.
+ *
+ * @returns true if all providers shut down successfully
+ */
+declare function shutdown(): Promise<boolean>;
+/**
+ * Return true if neatlogs was initialised with `debug: true`.
+ */
+declare function isDebugEnabled(): boolean;
+
+/**
+ * High-level span() function wrapper and Span() class-method decorator.
+ *
+ * Primary public API for instrumenting user code.
+ */
+
+/**
+ * Wrap a function with OpenTelemetry span instrumentation.
+ *
+ * @example
+ * ```typescript
+ * const myWorkflow = span({ kind: 'WORKFLOW' }, async (query: string) => {
+ *   return await process(query);
+ * });
+ * await myWorkflow('What is TypeScript?');
+ * ```
+ */
+declare function span<TArgs extends any[], TReturn>(options: SpanOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn extends Promise<any> ? TReturn : Promise<Awaited<TReturn>>;
+/**
+ * TC39 Stage 3 class-method decorator variant.
+ *
+ * @example
+ * ```typescript
+ * class MyAgent {
+ *   @Span({ kind: 'AGENT', role: 'researcher' })
+ *   async run(query: string) { ... }
+ * }
+ * ```
+ */
+declare function Span(options: SpanOptions): <T extends (...args: any[]) => any>(target: T, context: ClassMethodDecoratorContext) => T;
+
+/**
+ * Capture a timestamped log step within the current trace.
+ *
+ * @param msgTemplate - Message template with {key} placeholders
+ * @param options - Optional key-value pairs for template rendering and attributes
+ *
+ * @example
+ * ```typescript
+ * log('Processing query: {query}', { query: 'What is TypeScript?', level: 'info' });
+ * ```
+ */
+declare function log(msgTemplate: string, options?: Record<string, any>): void;
+
+interface ContextSetter {
+    set(template: string, variables: Record<string, any>): void;
+}
+/**
+ * Base class for prompt templates with `{{variable}}` placeholders.
+ *
+ * Extracts variables, compiles templates, and renders strings.
+ * Subclasses only need to specify the context class and display name.
+ */
+declare abstract class BasePromptTemplate {
+    protected readonly _template: string | PromptMessage[];
+    protected readonly _variables: string[];
+    /**
+     * @param template - Either a string with `{{variable}}` placeholders or
+     *   an array of `PromptMessage` objects whose `content` fields contain placeholders.
+     */
+    constructor(template: string | PromptMessage[]);
+    /** List of unique variable names found in this template. */
+    get variables(): string[];
+    /** The raw template (string or message array). */
+    get template(): string | PromptMessage[];
+    /** The context class to store template/variables for automatic tracing. */
+    protected abstract get _contextSetter(): ContextSetter;
+    /** Display name for toString(). */
+    protected abstract get _displayName(): string;
+    /**
+     * Compile the prompt template with the given variables.
+     *
+     * @param variables - Key/value pairs to substitute for `{{key}}` placeholders.
+     * @returns The rendered string or rendered message array.
+     * @throws {Error} If any required variables are missing.
+     */
+    compile(variables?: Record<string, any>): string | PromptMessage[];
+    /**
+     * Replace `{{key}}` placeholders in a string with the corresponding values.
+     */
+    _renderString(text: string, variables: Record<string, any>): string;
+    toString(): string;
+    private _extractVariables;
+}
+/**
+ * Template for the system/AI instruction prompt with `{{variable}}` placeholders.
+ */
+declare class PromptTemplate extends BasePromptTemplate {
+    protected get _contextSetter(): ContextSetter;
+    protected get _displayName(): string;
+}
+/**
+ * Template for the user/human turn prompt with `{{variable}}` placeholders.
+ *
+ * Identical to {@link PromptTemplate} but stores context in {@link UserPromptContext}.
+ */
+declare class UserPromptTemplate extends BasePromptTemplate {
+    protected get _contextSetter(): ContextSetter;
+    protected get _displayName(): string;
+}
+
+/** Base exception for prompt client failures. */
+declare class PromptClientError extends Error {
+    constructor(message: string);
+}
+/** Raised when the backend returns an API error. */
+declare class PromptApiError extends PromptClientError {
+    constructor(message: string);
+}
+/** Raised when a prompt/label/version is not found. */
+declare class PromptNotFoundError extends PromptClientError {
+    constructor(message: string);
+}
+/**
+ * Compiled prompt handle returned by {@link PromptClient.getPrompt}.
+ */
+declare class PromptHandle {
+    private readonly _prompt;
+    constructor(prompt: CachedPrompt);
+    get id(): string;
+    get name(): string;
+    get version(): number;
+    get content(): string | null;
+    get messages(): PromptMessage[] | null;
+    get config(): Record<string, any>;
+    get labels(): string[];
+    get updatedAt(): string;
+    get type(): string;
+    /**
+     * Compile string content with `{{variable}}` replacement.
+     *
+     * If the prompt has `content`, renders it directly.
+     * If it only has `messages`, renders and joins all message contents.
+     */
+    compile(variables?: Record<string, any>): string;
+    /**
+     * Compile message list with `{{variable}}` replacement.
+     *
+     * If no messages exist, returns a single synthetic system message from content.
+     */
+    compileMessages(variables?: Record<string, any>): PromptMessage[];
+}
+interface PromptClientOptions {
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * Prompt client for Neatlogs managed prompts.
+ *
+ * Fetches prompts on-demand from the backend.
+ * Uses an in-memory cache to avoid redundant HTTP calls.
+ */
+declare class PromptClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly _cache;
+    constructor(options: PromptClientOptions);
+    /**
+     * Get a prompt by name, optionally pinned to a version or label.
+     * Results are cached in memory by cache key.
+     */
+    getPrompt(name: string, options?: {
+        version?: number;
+        label?: string;
+    }): Promise<PromptHandle>;
+    /**
+     * Always fetch from the API (bypasses cache).
+     */
+    fetchPrompt(name: string, options?: {
+        version?: number;
+        label?: string;
+    }): Promise<PromptHandle>;
+    /**
+     * List all prompts.
+     */
+    listPrompts(): Promise<PromptHandle[]>;
+    /**
+     * Create a new prompt.
+     */
+    createPrompt(data: {
+        name: string;
+        content?: string;
+        messages?: PromptMessage[];
+        config?: Record<string, any>;
+        labels?: string[];
+    }): Promise<PromptHandle>;
+    /**
+     * Update an existing prompt.
+     */
+    updatePrompt(name: string, data: {
+        content?: string;
+        messages?: PromptMessage[];
+        config?: Record<string, any>;
+        labels?: string[];
+    }): Promise<PromptHandle>;
+    /**
+     * Delete a prompt by name.
+     */
+    deletePrompt(name: string): Promise<void>;
+    /**
+     * Remove a tag from a prompt.
+     */
+    removeTag(name: string, tag: string): Promise<void>;
+    /**
+     * Save the current prompt content as a new version, optionally with a label.
+     */
+    saveAsVersion(name: string, options?: {
+        label?: string;
+    }): Promise<PromptHandle>;
+    /**
+     * Internal fetch wrapper with auth headers and OTel suppression.
+     */
+    _request(path: string, options?: RequestInit): Promise<any>;
+}
+declare function getPrompt(name: string, options?: {
+    version?: number;
+    label?: string;
+}): Promise<PromptHandle>;
+declare function fetchPrompt(name: string, options?: {
+    version?: number;
+    label?: string;
+}): Promise<PromptHandle>;
+declare function listPrompts(): Promise<PromptHandle[]>;
+declare function createPrompt(data: {
+    name: string;
+    content?: string;
+    messages?: PromptMessage[];
+    config?: Record<string, any>;
+    labels?: string[];
+}): Promise<PromptHandle>;
+declare function updatePrompt(name: string, data: {
+    content?: string;
+    messages?: PromptMessage[];
+    config?: Record<string, any>;
+    labels?: string[];
+}): Promise<PromptHandle>;
+declare function saveAsVersion(name: string, options?: {
+    label?: string;
+}): Promise<PromptHandle>;
+declare function deletePrompt(name: string): Promise<void>;
+declare function removeTag(name: string, tag: string): Promise<void>;
+
+declare function getMastraObservability(): Promise<any>;
+
+/**
+ * LLM template binding for frameworks that manage LLM calls internally (e.g. CrewAI).
+ *
+ * Usage:
+ *   const boundLlm = bindTemplates(llm, systemTpl, userTpl, { content: '...' });
+ *   const agent = new Agent({ llm: boundLlm, ... });
+ *
+ * When the LLM's invoke/call method runs, this wrapper fires first:
+ *   1. Sets prompt template + user prompt template in OTel context
+ *   2. Calls the instrumented class-level invoke (creates the LLM span)
+ *   3. span_processor reads context -> templates land on the LLM span
+ */
+/**
+ * Return a copy of `llm` whose invoke()/call() injects prompt template context
+ * before the instrumented LLM span is created.
+ *
+ * @param llm - Any LangChain-compatible chat model or crewai.LLM
+ * @param systemTpl - PromptTemplate for the agent backstory / system role
+ * @param userTpl - Optional UserPromptTemplate for the task description
+ * @param compiledVars - Variable values to pass to userTpl.compile()
+ * @returns A new LLM instance with template context pre-wired
+ */
+declare function bindTemplates(llm: any, systemTpl: any, userTpl?: any, compiledVars?: Record<string, any>): any;
+
+/**
+ * Registry for CrewAI task template bindings.
+ *
+ * Call registerCrewaiTask(task, userTpl, vars) in your task setup after creating
+ * each Task. The span processor reads and clears the entry when the corresponding
+ * AGENT span ends, stamping the template onto that span.
+ */
+/**
+ * Register a user prompt template for a CrewAI task.
+ *
+ * @param task - A CrewAI Task instance (must have an .id property)
+ * @param userTpl - A neatlogs UserPromptTemplate describing the task prompt
+ * @param vars - Variable values passed to userTpl at task-creation time
+ */
+declare function registerCrewaiTask(task: {
+    id: string | number;
+}, userTpl: {
+    template: string | any;
+}, vars?: Record<string, any>): void;
+
+/**
+ * SDK version. Updated during release process.
+ */
+declare const __version__ = "1.0.0";
+
+export { type CachedPrompt, type InitOptions, type MaskFunction, PromptApiError, PromptClient, PromptClientError, PromptHandle, type PromptMessage, PromptNotFoundError, PromptTemplate, Span, type SpanKind, type SpanOptions, type TraceOptions, UserPromptTemplate, __version__, bindTemplates, createPrompt, deletePrompt, fetchPrompt, flush, getMastraObservability, getPrompt, getSessionConfig, init, isDebugEnabled, listPrompts, log, registerCrewaiTask, removeTag, saveAsVersion, shutdown, span, trace, updatePrompt };