@gmickel/gno 1.18.0 → 1.19.0

package/src/sdk/types.ts

@@ -19,6 +19,17 @@ import type { ContextEvidenceErrorCode } from "../core/context-evidence";
 import type { ContextVerifierErrorCode } from "../core/context-verifier";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
+import type {
+  RetrievalTraceDeleteResult,
+  RetrievalTraceDetail,
+  RetrievalTraceExportRequest,
+  RetrievalTraceExportResult,
+  RetrievalTraceLabelRequest,
+  RetrievalTraceLabelResult,
+  RetrievalTraceListRequest,
+  RetrievalTraceListResult,
+  RetrievalTracePurgeResult as RetrievalTraceManagementPurgeResult,
+} from "../core/retrieval-trace-management";
 import type { DocumentSection } from "../core/sections";
 import type { SyncResult } from "../ingestion";
 import type { DownloadPolicy } from "../llm/policy";
@@ -88,6 +99,8 @@ export type GnoContextErrorCode =
 export interface GnoGetOptions {
   from?: number;
   limit?: number;
+  /** Continue an open retrieval trace returned by search/query. */
+  traceId?: string;
 }
 
 export interface GnoMultiGetOptions {
@@ -221,6 +234,21 @@ export interface GnoClient {
     options?: GnoListOptions
   ): Promise<import("../cli/commands/ls").LsResponse>;
   status(): Promise<IndexStatus>;
+  listRetrievalTraces(
+    options?: RetrievalTraceListRequest
+  ): Promise<RetrievalTraceListResult>;
+  getRetrievalTrace(
+    traceId: string,
+    options?: { detailLimit?: number }
+  ): Promise<RetrievalTraceDetail>;
+  labelRetrievalTrace(
+    input: RetrievalTraceLabelRequest
+  ): Promise<RetrievalTraceLabelResult>;
+  exportRetrievalTraces(
+    input: RetrievalTraceExportRequest
+  ): Promise<RetrievalTraceExportResult>;
+  deleteRetrievalTrace(traceId: string): Promise<RetrievalTraceDeleteResult>;
+  purgeRetrievalTraces(): Promise<RetrievalTraceManagementPurgeResult>;
   update(options?: GnoUpdateOptions): Promise<SyncResult>;
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;

package/src/serve/context-capsule.ts

@@ -1,5 +1,6 @@
 /** REST adapters for the shared Context Capsule application boundary. */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GnoContextErrorCode } from "../sdk/types";
 import type { ServerContext } from "./context";
 
@@ -20,6 +21,8 @@ import {
   parseContextVerifySurfaceInput,
 } from "../app/context-surface";
 import { ContextCapsuleContractError } from "../core/context-capsule";
+import { startRetrievalTraceRequest } from "../core/retrieval-trace-request";
+import { withRetrievalTraceHeader } from "./retrieval-trace";
 
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 const MARKDOWN_HEADERS = {
@@ -80,6 +83,7 @@ export const handleContextBuild = async (
   context: ServerContext,
   request: Request
 ): Promise<Response> => {
+  let traceSession: RetrievalTraceSession | null = null;
   try {
     const { input, format } = parseContextBuildSurfaceInput(
       await parseJsonBody(request),
@@ -90,6 +94,42 @@ export const handleContextBuild = async (
       context.indexName,
       context.config.collections.map((collection) => collection.name)
     );
+    const started = await startRetrievalTraceRequest({
+      store: context.store,
+      config: context.config,
+      query: input.query ?? input.goal,
+      goal: input.goal,
+      filters: {
+        limit: input.limit,
+        collection:
+          input.collections?.length === 1 ? input.collections[0] : undefined,
+        collections: [...(input.collections ?? [])].sort(),
+        lang: input.lang,
+        tagsAll: input.tagsAll,
+        tagsAny: input.tagsAny,
+        since: input.since,
+        until: input.until,
+        categories: input.categories,
+        author: input.author,
+        graph: input.graph,
+        candidateLimit: input.candidateLimit,
+        queryModes: input.queryModes,
+        uriPrefix: input.uriPrefix ?? undefined,
+      },
+      pipeline: "context",
+      indexName: context.indexName,
+      modelUris: [
+        context.embedPort?.modelUri,
+        context.rerankPort?.modelUri,
+      ].filter((value): value is string => Boolean(value)),
+    });
+    if (!started.ok) {
+      throw Object.assign(
+        new Error(`Retrieval trace start failed: ${started.error.message}`),
+        { code: "retrieval_failed" }
+      );
+    }
+    traceSession = started.value;
     const capsule = await buildContextCapsule(input, {
       store: context.store,
       config: context.config,
@@ -97,16 +137,35 @@ export const handleContextBuild = async (
       vectorIndex: context.vectorIndex,
       embedPort: context.embedPort,
       rerankPort: context.rerankPort,
+      traceSession: traceSession ?? undefined,
     });
-    return format === "md"
-      ? new Response(formatContextCapsuleMarkdown(capsule), {
-          headers: MARKDOWN_HEADERS,
-        })
-      : new Response(canonicalBuiltContextCapsuleJson(capsule), {
-          headers: JSON_HEADERS,
-        });
+    const finished = await traceSession?.finish(
+      request.signal.aborted ? "cancelled" : "completed"
+    );
+    if (finished && !finished.ok) {
+      throw Object.assign(
+        new Error(
+          `Retrieval trace finalization failed: ${finished.error.message}`
+        ),
+        { code: "retrieval_failed" }
+      );
+    }
+    const response =
+      format === "md"
+        ? new Response(formatContextCapsuleMarkdown(capsule), {
+            headers: MARKDOWN_HEADERS,
+          })
+        : new Response(canonicalBuiltContextCapsuleJson(capsule), {
+            headers: JSON_HEADERS,
+          });
+    return withRetrievalTraceHeader(response, traceSession);
   } catch (error) {
-    return errorResponse(error);
+    if (traceSession) {
+      await traceSession.finish(
+        request.signal.aborted ? "cancelled" : "failed"
+      );
+    }
+    return withRetrievalTraceHeader(errorResponse(error), traceSession);
   }
 };
 

package/src/serve/public/app.tsx

@@ -29,6 +29,7 @@ import DocumentEditor from "./pages/DocumentEditor";
 import DocView from "./pages/DocView";
 import GraphView from "./pages/GraphView";
 import Search from "./pages/Search";
+import TraceHistory from "./pages/TraceHistory";
 
 type Route =
   | "/"
@@ -39,7 +40,8 @@ type Route =
   | "/edit"
   | "/collections"
   | "/graph"
-  | "/connectors";
+  | "/connectors"
+  | "/traces";
 type Navigate = (to: string | number) => void;
 
 interface RoutePageProps {
@@ -57,6 +59,7 @@ const routes: Record<Route, React.ComponentType<RoutePageProps>> = {
   "/connectors": Connectors,
   "/ask": Ask,
   "/graph": GraphView,
+  "/traces": TraceHistory,
 };
 
 interface AppContentProps {
@@ -165,6 +168,14 @@ function AppContent({
               Collections
             </button>
             <span className="text-border/30">—</span>
+            <button
+              className="transition-colors duration-300 hover:text-primary"
+              onClick={() => navigate("/traces")}
+              type="button"
+            >
+              Trace history
+            </button>
+            <span className="text-border/30">—</span>
             <a
               className="transition-colors duration-300 hover:text-primary"
               href="https://github.com/gmickel/gno"