@glassflow-ai/rius 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,156 @@
+import { Tracer, Span } from '@opentelemetry/api';
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+
+/** Redacts content attribute values at export. Receives the key when it accepts one. */
+type Mask = (value: unknown, context?: {
+    key: string;
+}) => unknown;
+interface RiusOptions {
+    endpoint?: string;
+    apiKey?: string;
+    serviceName?: string;
+    disabled?: boolean;
+    sampleRate?: number;
+    captureContent?: boolean;
+    mask?: Mask;
+}
+
+interface InitOptions extends RiusOptions {
+    /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
+    spanExporter?: SpanExporter;
+}
+declare class RiusClient {
+    private readonly provider;
+    private readonly health?;
+    /** Resolves with the names of the auto-instrumentations that attached. */
+    readonly ready: Promise<string[]>;
+    private constructor();
+    /** Drains the queue. Resolves false if the most recent export failed. */
+    flush(): Promise<boolean>;
+    /**
+     * Drains and tears down the provider, then releases the global registration
+     * so a later init() can reconfigure the SDK.
+     */
+    shutdown(): Promise<void>;
+}
+declare function init(options?: InitOptions): RiusClient;
+/** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
+declare function getTracer(): Tracer;
+
+declare enum SpanKind {
+    AGENT = "AGENT",
+    LLM = "LLM",
+    TOOL = "TOOL",
+    RETRIEVER = "RETRIEVER",
+    EMBEDDING = "EMBEDDING",
+    CHAIN = "CHAIN"
+}
+
+interface SpanOptions {
+    kind?: SpanKind;
+    input?: unknown;
+}
+/** A handle over a span. Chainable setters; `end()` is idempotent. */
+declare class Observation {
+    readonly span: Span;
+    protected ended: boolean;
+    constructor(span: Span);
+    setInput(value: unknown): this;
+    setOutput(value: unknown): this;
+    setAttribute(key: string, value: unknown): this;
+    /**
+     * Record an error on the span and set ERROR status. This is exactly what the
+     * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
+     * `start*` path does not have to reach through `.span` to match it.
+     *
+     * Accepts `unknown` because that is what a `catch` binding is; a non-Error
+     * throwable is wrapped so `recordException` still gets a real Error.
+     */
+    recordException(error: unknown): this;
+    end(): void;
+    /** Lets callers write `using obs = startSpan(...)`. Sugar over end(). */
+    [Symbol.dispose](): void;
+}
+/**
+ * Create a span and return a handle. You MUST call end() (or use `using`).
+ * The span is parented to whatever is current but does NOT become current.
+ */
+declare function startSpan(name: string, options?: SpanOptions): Observation;
+/** The body of a scoped span. */
+type SpanBody<T> = (observation: Observation) => Promise<T> | T;
+/**
+ * Run `fn` with a new span active, so spans created inside it nest under this
+ * one across async boundaries. Auto-ends, records exceptions, rethrows.
+ *
+ * `options` is optional, so the common case is `startAsCurrentSpan(name, fn)`
+ * rather than `startAsCurrentSpan(name, {}, fn)`. The callback stays last.
+ */
+declare function startAsCurrentSpan<T>(name: string, fn: SpanBody<T>): Promise<T>;
+declare function startAsCurrentSpan<T>(name: string, options: SpanOptions, fn: SpanBody<T>): Promise<T>;
+
+interface GenerationOptions {
+    model?: string;
+    provider?: string;
+    input?: unknown;
+    /**
+     * Request parameters, each recorded as `gen_ai.request.<key>` — for example
+     * `{ temperature: 0.2, max_tokens: 512 }`. Keys are passed through verbatim,
+     * so use the provider's own parameter names.
+     */
+    modelParameters?: Record<string, unknown>;
+}
+/** An LLM call. Content uses gen_ai message keys, never input.value. */
+declare class Generation extends Observation {
+    private firstTokenRecorded;
+    setInput(value: unknown): this;
+    setOutput(value: unknown): this;
+    setModel(model: string): this;
+    setUsage(usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+    }): this;
+    /**
+     * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
+     * `"length"`, `"tool_calls"`. The convention is a list; a single reason is
+     * wrapped so callers do not have to.
+     */
+    setFinishReasons(reasons: string | string[]): this;
+    /**
+     * The TTFT anchor: event time minus span start. Idempotent: only the
+     * first call records the event, so a streaming loop can call this
+     * unconditionally on every chunk without inflating the span. A no-op
+     * after the span has ended.
+     */
+    recordFirstToken(): this;
+}
+/** Create a generation span and return a handle. You MUST call end(). */
+declare function startGeneration(name: string, options?: GenerationOptions): Generation;
+/** The body of a scoped generation. */
+type GenerationBody<T> = (generation: Generation) => Promise<T> | T;
+/**
+ * Run `fn` with a generation span active. Auto-ends, records exceptions.
+ *
+ * `options` is optional, so `startAsCurrentGeneration(name, fn)` works without
+ * an empty object. The callback stays last.
+ */
+declare function startAsCurrentGeneration<T>(name: string, fn: GenerationBody<T>): Promise<T>;
+declare function startAsCurrentGeneration<T>(name: string, options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
+
+interface ObserveOptions {
+    name?: string;
+    kind?: SpanKind;
+    captureInput?: boolean;
+    captureOutput?: boolean;
+}
+/**
+ * Wrap a function so each call becomes a span. Returns a function with the
+ * same signature, so call sites and types are unchanged.
+ *
+ * A wrapper rather than a decorator on purpose: TypeScript decorators apply
+ * only to class members, and most agent code is plain functions.
+ */
+declare function observe<F extends (...args: never[]) => unknown>(fn: F, options?: ObserveOptions): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+
+declare const VERSION = "0.1.0";
+
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { Tracer, Span } from '@opentelemetry/api';
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+
+/** Redacts content attribute values at export. Receives the key when it accepts one. */
+type Mask = (value: unknown, context?: {
+    key: string;
+}) => unknown;
+interface RiusOptions {
+    endpoint?: string;
+    apiKey?: string;
+    serviceName?: string;
+    disabled?: boolean;
+    sampleRate?: number;
+    captureContent?: boolean;
+    mask?: Mask;
+}
+
+interface InitOptions extends RiusOptions {
+    /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
+    spanExporter?: SpanExporter;
+}
+declare class RiusClient {
+    private readonly provider;
+    private readonly health?;
+    /** Resolves with the names of the auto-instrumentations that attached. */
+    readonly ready: Promise<string[]>;
+    private constructor();
+    /** Drains the queue. Resolves false if the most recent export failed. */
+    flush(): Promise<boolean>;
+    /**
+     * Drains and tears down the provider, then releases the global registration
+     * so a later init() can reconfigure the SDK.
+     */
+    shutdown(): Promise<void>;
+}
+declare function init(options?: InitOptions): RiusClient;
+/** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
+declare function getTracer(): Tracer;
+
+declare enum SpanKind {
+    AGENT = "AGENT",
+    LLM = "LLM",
+    TOOL = "TOOL",
+    RETRIEVER = "RETRIEVER",
+    EMBEDDING = "EMBEDDING",
+    CHAIN = "CHAIN"
+}
+
+interface SpanOptions {
+    kind?: SpanKind;
+    input?: unknown;
+}
+/** A handle over a span. Chainable setters; `end()` is idempotent. */
+declare class Observation {
+    readonly span: Span;
+    protected ended: boolean;
+    constructor(span: Span);
+    setInput(value: unknown): this;
+    setOutput(value: unknown): this;
+    setAttribute(key: string, value: unknown): this;
+    /**
+     * Record an error on the span and set ERROR status. This is exactly what the
+     * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
+     * `start*` path does not have to reach through `.span` to match it.
+     *
+     * Accepts `unknown` because that is what a `catch` binding is; a non-Error
+     * throwable is wrapped so `recordException` still gets a real Error.
+     */
+    recordException(error: unknown): this;
+    end(): void;
+    /** Lets callers write `using obs = startSpan(...)`. Sugar over end(). */
+    [Symbol.dispose](): void;
+}
+/**
+ * Create a span and return a handle. You MUST call end() (or use `using`).
+ * The span is parented to whatever is current but does NOT become current.
+ */
+declare function startSpan(name: string, options?: SpanOptions): Observation;
+/** The body of a scoped span. */
+type SpanBody<T> = (observation: Observation) => Promise<T> | T;
+/**
+ * Run `fn` with a new span active, so spans created inside it nest under this
+ * one across async boundaries. Auto-ends, records exceptions, rethrows.
+ *
+ * `options` is optional, so the common case is `startAsCurrentSpan(name, fn)`
+ * rather than `startAsCurrentSpan(name, {}, fn)`. The callback stays last.
+ */
+declare function startAsCurrentSpan<T>(name: string, fn: SpanBody<T>): Promise<T>;
+declare function startAsCurrentSpan<T>(name: string, options: SpanOptions, fn: SpanBody<T>): Promise<T>;
+
+interface GenerationOptions {
+    model?: string;
+    provider?: string;
+    input?: unknown;
+    /**
+     * Request parameters, each recorded as `gen_ai.request.<key>` — for example
+     * `{ temperature: 0.2, max_tokens: 512 }`. Keys are passed through verbatim,
+     * so use the provider's own parameter names.
+     */
+    modelParameters?: Record<string, unknown>;
+}
+/** An LLM call. Content uses gen_ai message keys, never input.value. */
+declare class Generation extends Observation {
+    private firstTokenRecorded;
+    setInput(value: unknown): this;
+    setOutput(value: unknown): this;
+    setModel(model: string): this;
+    setUsage(usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+    }): this;
+    /**
+     * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
+     * `"length"`, `"tool_calls"`. The convention is a list; a single reason is
+     * wrapped so callers do not have to.
+     */
+    setFinishReasons(reasons: string | string[]): this;
+    /**
+     * The TTFT anchor: event time minus span start. Idempotent: only the
+     * first call records the event, so a streaming loop can call this
+     * unconditionally on every chunk without inflating the span. A no-op
+     * after the span has ended.
+     */
+    recordFirstToken(): this;
+}
+/** Create a generation span and return a handle. You MUST call end(). */
+declare function startGeneration(name: string, options?: GenerationOptions): Generation;
+/** The body of a scoped generation. */
+type GenerationBody<T> = (generation: Generation) => Promise<T> | T;
+/**
+ * Run `fn` with a generation span active. Auto-ends, records exceptions.
+ *
+ * `options` is optional, so `startAsCurrentGeneration(name, fn)` works without
+ * an empty object. The callback stays last.
+ */
+declare function startAsCurrentGeneration<T>(name: string, fn: GenerationBody<T>): Promise<T>;
+declare function startAsCurrentGeneration<T>(name: string, options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
+
+interface ObserveOptions {
+    name?: string;
+    kind?: SpanKind;
+    captureInput?: boolean;
+    captureOutput?: boolean;
+}
+/**
+ * Wrap a function so each call becomes a span. Returns a function with the
+ * same signature, so call sites and types are unchanged.
+ *
+ * A wrapper rather than a decorator on purpose: TypeScript decorators apply
+ * only to class members, and most agent code is plain functions.
+ */
+declare function observe<F extends (...args: never[]) => unknown>(fn: F, options?: ObserveOptions): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+
+declare const VERSION = "0.1.0";
+
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan };