@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.3

package/dist/telemetry/assistant/telemetry-assistant.service.d.ts

@@ -0,0 +1,216 @@
+import type { TelemetrySettings as SystemTelemetryValue } from '@marinoscar/platform-contract/telemetry';
+import { type TelemetryAssistantAnswerEvent, type TelemetryAssistantEmit, type TelemetryAssistantReport, type TelemetryAssistantRequest, type TelemetryAssistantStepEvent } from '../dto/telemetry-assistant.dto';
+import { GreptimeClient } from '../greptime/greptime.client';
+import { TelemetryHttpError } from '../query/telemetry-query.errors';
+import { TelemetryQueryService } from '../query/telemetry-query.service';
+import { TelemetrySchemaService } from '../query/telemetry-schema.service';
+import { type TelemetryAiError as AiError, type TelemetryAiInputMessage as AiInputItem, type TelemetryAiPort, type TelemetryAiToolLoopResult as AiToolLoopResult, type TelemetryAiToolStep as AiToolStep, type TelemetryAppInfo, type TelemetryAuditSink, type TelemetrySettingsStore } from '../ports';
+import { TelemetrySettingsService } from '../telemetry-settings.service';
+import { type VerdictThresholds } from '../dashboard/telemetry-dashboard.verdict';
+import { type AssistantSectionQuery } from './telemetry-assistant.sql';
+/**
+ * The audit `action` for one conversation turn.
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_ASSISTANT_AUDIT_ACTION = "telemetry:assistant";
+/** Hard ceiling on rows handed to the model, whatever the setting says. */
+export declare const TELEMETRY_ASSISTANT_ROWS_HARD_CAP = 100;
+/** A string cell longer than this is cut (with `…`) before the model sees it. */
+export declare const CELL_MAX_CHARS = 500;
+/**
+ * A tool output is kept under this, so the tool loop's own 32 000-character
+ * cut (which would break the JSON) never applies.
+ */
+export declare const TOOL_OUTPUT_MAX_CHARS = 24000;
+/** A step event's `thought` is at most this long. */
+export declare const THOUGHT_MAX_CHARS = 1000;
+/** Report bounds. */
+export declare const REPORT_MAX_FINDINGS = 10;
+export declare const REPORT_MAX_RECOMMENDATIONS = 10;
+export declare const REPORT_MAX_QUERIES = 5;
+/**
+ * The system prompt, with the turn's step budget spelled out.
+ *
+ * @stability experimental
+ */
+export declare function buildTelemetryAssistantInstructions(maxSteps: number): string;
+/** The instructions at the default step budget (`DEFAULT_SYSTEM_SETTINGS`). */
+export declare const TELEMETRY_ASSISTANT_INSTRUCTIONS: string;
+interface RunQueryOutput {
+    columns: {
+        name: string;
+        type: string;
+    }[];
+    rowCount: number;
+    truncated: boolean;
+    rows: unknown[][];
+    note?: string;
+}
+/** One server-built statement's result as the model sees it. */
+export interface SectionOutput {
+    columns: string[];
+    rowCount: number;
+    truncated: boolean;
+    rows: unknown[][];
+    note?: string;
+}
+interface TurnState {
+    toolCalls: number;
+    /** Round-trips whose tool calls have run (`onStep` count). */
+    completedRounds: number;
+    /** The last `run_query` SQL that succeeded — the fallback answer when steps run out. */
+    lastGoodSql: string | null;
+    /** The most recent non-empty text the model wrote alongside its tool calls. */
+    lastText: string | null;
+    /** A telemetry failure that ended the turn. */
+    fatal: TelemetryHttpError | null;
+}
+export interface TelemetryAssistantStreamOptions {
+    /** Aborted when the client disconnects: stops the provider call and the in-flight query. */
+    signal?: AbortSignal;
+    emit: TelemetryAssistantEmit;
+}
+export declare class TelemetryAssistantService {
+    private readonly ai;
+    private readonly greptime;
+    private readonly settings;
+    private readonly queries;
+    private readonly schema;
+    private readonly auditSink;
+    private readonly systemSettings;
+    private readonly appInfo;
+    private readonly thresholds;
+    private readonly logger;
+    constructor(ai: TelemetryAiPort, greptime: GreptimeClient, settings: TelemetrySettingsService, queries: TelemetryQueryService, schema: TelemetrySchemaService, auditSink: TelemetryAuditSink, systemSettings: TelemetrySettingsStore, appInfo: TelemetryAppInfo, thresholds?: VerdictThresholds);
+    /**
+     * The policy, or a `TelemetryHttpError` saying why the assistant cannot run:
+     * store not configured (503), telemetry disabled (409), assistant disabled
+     * (409), no provider/model chosen (409). The global AI kill switch is the
+     * route's `TelemetryAiEnabledGuard`.
+     */
+    assertReady(): Promise<SystemTelemetryValue & {
+        assistant: {
+            provider: string;
+            modelId: string;
+        };
+    }>;
+    /**
+     * One conversation turn. Throws (a `TelemetryHttpError`) ONLY for the
+     * preconditions, before `emit` is ever called — so an SSE controller can
+     * answer those as ordinary JSON errors. After that it never throws: every
+     * failure is an `error` event, and the last event is always `done`.
+     */
+    stream(userId: string, input: TelemetryAssistantRequest, opts: TelemetryAssistantStreamOptions): Promise<void>;
+    private buildTools;
+    /** The column sets of the traces and logs tables (null when a table is absent), and the metric tables. */
+    private columnSets;
+    /**
+     * The one path every server-built statement takes: `TelemetryQueryService.run`
+     * (`source: 'assistant'` — guard, row cap, timeout, audit), at most
+     * `SECTION_CONCURRENCY` at a time, none started after the tool's deadline.
+     * A failed statement is `unavailable` on its own; a fatal telemetry failure
+     * stops the pool, and `settle()` then ends the turn through `recover`.
+     */
+    private statementPool;
+    /** `runSectionsIn` on a pool of its own, settled. */
+    private runSections;
+    /** Server-built section statements, shaped for the model, in plan order. */
+    private runSectionsIn;
+    /** `health_overview`'s saturation section: the dashboard's verdict probes over the window. */
+    private saturation;
+    /** `get_app_context`: every piece on its own, so one failure never loses the rest. */
+    private appContext;
+    /**
+     * Platform features as BOOLEANS, from an explicit allowlist of settings —
+     * never the settings serialised wholesale.
+     */
+    private platformFeatures;
+    private audit;
+}
+/**
+ * The deploy document's NON-SENSITIVE facts only: what was deployed and
+ * when. Never the domain, host facts, proxy, paths or anything else.
+ */
+export declare function pickDeployInfo(result: {
+    status: string;
+    document: {
+        app: {
+            version: string | null;
+            commitSha: string | null;
+        };
+        installedAt: string | null;
+        updatedAt: string | null;
+        lastCommand: string | null;
+        run: {
+            outcome: string | null;
+        } | null;
+    } | null;
+}): Record<string, unknown>;
+/** Adds the step-budget field for the round `currentRound` of `maxSteps`. */
+export declare function withBudget<T extends object>(output: T, currentRound: number, maxSteps: number): T & {
+    budget?: string;
+    stepsLeft?: number;
+};
+/** Prior turns (bounded) and the new question, as model input. */
+export declare function buildInput(input: TelemetryAssistantRequest): AiInputItem[];
+/** Cuts a string to `max` characters, marking the cut. */
+export declare function truncateText(value: string, max: number): string;
+/** A cell as the model may see it: strings (and serialised JSON values) at most `CELL_MAX_CHARS`. */
+export declare function boundCell(value: unknown): unknown;
+/** A `run_query` result as the model sees it. See the header for the three bounds. */
+export declare function shapeQueryOutput(result: {
+    columns: {
+        name: string;
+        type: string;
+    }[];
+    rows: unknown[][];
+    rowCount: number;
+    truncated: boolean;
+}, opts: {
+    shareResults: boolean;
+    rowsToModel: number;
+}): RunQueryOutput;
+/**
+ * A server-built statement's result as the model sees it. With row sharing
+ * off, only the plan's `shareable` columns keep their values — and only when
+ * the value is a number, boolean or timestamp; every other cell is null.
+ */
+export declare function shapeSection(result: {
+    columns: {
+        name: string;
+    }[];
+    rows: unknown[][];
+    rowCount: number;
+    truncated: boolean;
+}, plan: Pick<AssistantSectionQuery, 'shareable' | 'maxRows'>, opts: {
+    shareResults: boolean;
+    rowsToModel: number;
+}): SectionOutput;
+/**
+ * Keeps a multi-section output under `TOOL_OUTPUT_MAX_CHARS` by dropping
+ * rows from the end of the largest section, one at a time, with a note on
+ * each section that lost rows.
+ */
+export declare function fitSections<T extends object>(output: T, sections: unknown[]): T;
+/**
+ * One `step` event per tool call of a round-trip (unknown tool names are
+ * skipped). The round's interim text — what the model said alongside its
+ * calls — rides on the FIRST event as `thought`.
+ */
+export declare function toStepEvents(step: AiToolStep, nextIndex: () => number): TelemetryAssistantStepEvent[];
+/** The model's final text as a report, or null when it is not one (nor a legacy `{ sql, explanation }`). */
+export declare function parseReport(text: string): TelemetryAssistantReport | null;
+/**
+ * Re-checks every report query with the explorer's guard; a refused one is
+ * withdrawn (findings pointing at it lose their `queryIndex`) with a note.
+ */
+export declare function guardReport(report: TelemetryAssistantReport): TelemetryAssistantReport;
+/** Back-compat: the final text as `{ sql, explanation }` (via the report), or null. */
+export declare function parseFinalAnswer(text: string): TelemetryAssistantAnswerEvent | null;
+/** The `answer` event for a finished loop. */
+export declare function finalAnswer(result: Pick<AiToolLoopResult, 'final' | 'stopReason' | 'steps'>, state: Pick<TurnState, 'lastGoodSql'> & Partial<Pick<TurnState, 'lastText'>>): TelemetryAssistantAnswerEvent;
+/** A user-facing message for an `AiError` that ended the turn. */
+export declare function describeAiError(err: AiError, provider: string, model: string): string;
+export {};
+//# sourceMappingURL=telemetry-assistant.service.d.ts.map

package/dist/telemetry/assistant/telemetry-assistant.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-assistant.service.d.ts","sourceRoot":"","sources":["../../../src/telemetry/assistant/telemetry-assistant.service.ts"],"names":[],"mappings":"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"}