@kagan-sh/opensearch 0.1.0

package/dist/orchestrator.js

@@ -0,0 +1,152 @@
+import { searchCode } from "./sources/code";
+import { searchSessions } from "./sources/session";
+import { searchWeb } from "./sources/web";
+function clampUnit(value) {
+    return Math.max(0, Math.min(1, value));
+}
+export function normalize(raw) {
+    return {
+        id: raw.id,
+        type: raw.type,
+        title: raw.title,
+        snippet: raw.snippet,
+        url: raw.url,
+        relevance: clampUnit(raw.relevance),
+        timestamp: raw.timestamp,
+    };
+}
+function resultMeta(input) {
+    return {
+        query: input.query,
+        duration: Date.now() - input.start,
+        sources_requested: input.requested.length,
+        sources_queried: input.queried.length,
+        sources_yielded: input.yielded,
+        sources_unavailable: input.unavailable,
+        source_errors: input.sourceErrors,
+    };
+}
+function createResult(input) {
+    return {
+        status: input.status,
+        answer: input.answer,
+        confidence: input.confidence,
+        evidence: input.evidence,
+        sources: input.sources,
+        followups: input.followups,
+        meta: input.meta,
+    };
+}
+export async function runSourceSearches(input) {
+    const outcomes = await Promise.all(input.sources.map((source) => {
+        if (source === "session") {
+            return searchSessions(input.client, input.directory, input.query, input.depth);
+        }
+        if (source === "web") {
+            return searchWeb(input.query, input.config.sources.web.key, input.depth);
+        }
+        return searchCode(input.query, input.depth);
+    }));
+    return {
+        raw: outcomes.flatMap((outcome) => outcome.results),
+        sourceErrors: outcomes.flatMap((outcome) => outcome.error ? [outcome.error] : []),
+    };
+}
+export function noSourcesResult(input) {
+    return createResult({
+        status: "no_sources",
+        answer: "No sources available",
+        confidence: "none",
+        evidence: [],
+        sources: [],
+        followups: [
+            "Enable at least one search source in opensearch config",
+            "Set OPENSEARCH_WEB_KEY or EXA_API_KEY to enable web search",
+        ],
+        meta: resultMeta({
+            query: input.query,
+            start: input.start,
+            requested: input.requested,
+            queried: [],
+            yielded: 0,
+            unavailable: input.unavailable,
+            sourceErrors: [],
+        }),
+    });
+}
+export function noResultsResult(input) {
+    const followups = [
+        `Use broader terms for: ${input.query}`,
+        `Search only web for: ${input.query}`,
+    ];
+    if (input.sourceErrors.length > 0) {
+        followups.unshift("Inspect meta.source_errors for failed search sources");
+    }
+    return createResult({
+        status: "no_results",
+        answer: "No results found",
+        confidence: "none",
+        evidence: [],
+        sources: [],
+        followups,
+        meta: resultMeta({
+            query: input.query,
+            start: input.start,
+            requested: input.requested,
+            queried: input.queried,
+            yielded: 0,
+            unavailable: input.unavailable,
+            sourceErrors: input.sourceErrors,
+        }),
+    });
+}
+export function rawResultsResult(input) {
+    const answer = input.status === "raw"
+        ? "Raw results (synthesis disabled)"
+        : "Unable to synthesize structured answer. Returning raw evidence.";
+    const followups = input.status === "raw"
+        ? [
+            `Enable synthesis for: ${input.query}`,
+            `Filter to one source for: ${input.query}`,
+        ]
+        : [
+            `Refine: ${input.query}`,
+            `Find contradictory sources for: ${input.query}`,
+        ];
+    return createResult({
+        status: input.status,
+        answer,
+        confidence: "none",
+        evidence: [],
+        sources: input.raw.map(normalize),
+        followups,
+        meta: resultMeta({
+            query: input.query,
+            start: input.start,
+            requested: input.requested,
+            queried: input.queried,
+            yielded: input.raw.length,
+            unavailable: input.unavailable,
+            sourceErrors: input.sourceErrors,
+        }),
+    });
+}
+export function synthesizedResult(input) {
+    return createResult({
+        status: "ok",
+        answer: input.synthesis.answer,
+        confidence: input.synthesis.confidence,
+        evidence: input.synthesis.evidence,
+        sources: input.raw.map(normalize),
+        followups: input.synthesis.followups,
+        meta: resultMeta({
+            query: input.query,
+            start: input.start,
+            requested: input.requested,
+            queried: input.queried,
+            yielded: input.raw.length,
+            unavailable: input.unavailable,
+            sourceErrors: input.sourceErrors,
+        }),
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,419 @@
+import { z } from "zod";
+export declare const SOURCE_IDS: readonly ["session", "web", "code"];
+export declare const DEPTHS: readonly ["quick", "thorough"];
+export declare const RESULT_STATUSES: readonly ["ok", "raw", "raw_fallback", "no_sources", "no_results"];
+export declare const SourceIdSchema: z.ZodEnum<["session", "web", "code"]>;
+export declare const DepthSchema: z.ZodEnum<["quick", "thorough"]>;
+export declare const ResultStatusSchema: z.ZodEnum<["ok", "raw", "raw_fallback", "no_sources", "no_results"]>;
+export declare const SourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["session", "web", "code"]>;
+    url: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    snippet: z.ZodString;
+    relevance: z.ZodNumber;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    type: "session" | "web" | "code";
+    title: string;
+    snippet: string;
+    relevance: number;
+    url?: string | undefined;
+    timestamp?: number | undefined;
+}, {
+    id: string;
+    type: "session" | "web" | "code";
+    title: string;
+    snippet: string;
+    relevance: number;
+    url?: string | undefined;
+    timestamp?: number | undefined;
+}>;
+export declare const SourceErrorSchema: z.ZodObject<{
+    source: z.ZodEnum<["session", "web", "code"]>;
+    code: z.ZodEnum<["unavailable", "request_failed", "invalid_response"]>;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: "unavailable" | "request_failed" | "invalid_response";
+    message: string;
+    source: "session" | "web" | "code";
+}, {
+    code: "unavailable" | "request_failed" | "invalid_response";
+    message: string;
+    source: "session" | "web" | "code";
+}>;
+export declare const EvidenceSchema: z.ZodObject<{
+    claim: z.ZodString;
+    sources: z.ZodArray<z.ZodString, "many">;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+}, "strict", z.ZodTypeAny, {
+    claim: string;
+    sources: string[];
+    confidence: "high" | "medium" | "low";
+}, {
+    claim: string;
+    sources: string[];
+    confidence: "high" | "medium" | "low";
+}>;
+export declare const ResultSchema: z.ZodObject<{
+    status: z.ZodEnum<["ok", "raw", "raw_fallback", "no_sources", "no_results"]>;
+    answer: z.ZodString;
+    confidence: z.ZodEnum<["high", "medium", "low", "none"]>;
+    evidence: z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        sources: z.ZodArray<z.ZodString, "many">;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+    }, "strict", z.ZodTypeAny, {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }, {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }>, "many">;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["session", "web", "code"]>;
+        url: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        snippet: z.ZodString;
+        relevance: z.ZodNumber;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }, {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }>, "many">;
+    followups: z.ZodArray<z.ZodString, "many">;
+    meta: z.ZodObject<{
+        query: z.ZodString;
+        duration: z.ZodNumber;
+        sources_requested: z.ZodNumber;
+        sources_queried: z.ZodNumber;
+        sources_yielded: z.ZodNumber;
+        sources_unavailable: z.ZodArray<z.ZodEnum<["session", "web", "code"]>, "many">;
+        source_errors: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<["session", "web", "code"]>;
+            code: z.ZodEnum<["unavailable", "request_failed", "invalid_response"]>;
+            message: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }, {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    }, {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    status: "ok" | "raw" | "raw_fallback" | "no_sources" | "no_results";
+    sources: {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }[];
+    confidence: "high" | "medium" | "low" | "none";
+    answer: string;
+    evidence: {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }[];
+    followups: string[];
+    meta: {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    };
+}, {
+    status: "ok" | "raw" | "raw_fallback" | "no_sources" | "no_results";
+    sources: {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }[];
+    confidence: "high" | "medium" | "low" | "none";
+    answer: string;
+    evidence: {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }[];
+    followups: string[];
+    meta: {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    };
+}>;
+export declare const SynthesisSchema: z.ZodObject<Omit<{
+    status: z.ZodEnum<["ok", "raw", "raw_fallback", "no_sources", "no_results"]>;
+    answer: z.ZodString;
+    confidence: z.ZodEnum<["high", "medium", "low", "none"]>;
+    evidence: z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        sources: z.ZodArray<z.ZodString, "many">;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+    }, "strict", z.ZodTypeAny, {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }, {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }>, "many">;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["session", "web", "code"]>;
+        url: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        snippet: z.ZodString;
+        relevance: z.ZodNumber;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }, {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }>, "many">;
+    followups: z.ZodArray<z.ZodString, "many">;
+    meta: z.ZodObject<{
+        query: z.ZodString;
+        duration: z.ZodNumber;
+        sources_requested: z.ZodNumber;
+        sources_queried: z.ZodNumber;
+        sources_yielded: z.ZodNumber;
+        sources_unavailable: z.ZodArray<z.ZodEnum<["session", "web", "code"]>, "many">;
+        source_errors: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<["session", "web", "code"]>;
+            code: z.ZodEnum<["unavailable", "request_failed", "invalid_response"]>;
+            message: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }, {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    }, {
+        query: string;
+        duration: number;
+        sources_requested: number;
+        sources_queried: number;
+        sources_yielded: number;
+        sources_unavailable: ("session" | "web" | "code")[];
+        source_errors: {
+            code: "unavailable" | "request_failed" | "invalid_response";
+            message: string;
+            source: "session" | "web" | "code";
+        }[];
+    }>;
+}, "status" | "sources" | "meta">, "strict", z.ZodTypeAny, {
+    confidence: "high" | "medium" | "low" | "none";
+    answer: string;
+    evidence: {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }[];
+    followups: string[];
+}, {
+    confidence: "high" | "medium" | "low" | "none";
+    answer: string;
+    evidence: {
+        claim: string;
+        sources: string[];
+        confidence: "high" | "medium" | "low";
+    }[];
+    followups: string[];
+}>;
+export declare const RawResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["session", "web", "code"]>;
+    title: z.ZodString;
+    snippet: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    relevance: z.ZodNumber;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    type: "session" | "web" | "code";
+    title: string;
+    snippet: string;
+    relevance: number;
+    url?: string | undefined;
+    timestamp?: number | undefined;
+}, {
+    id: string;
+    type: "session" | "web" | "code";
+    title: string;
+    snippet: string;
+    relevance: number;
+    url?: string | undefined;
+    timestamp?: number | undefined;
+}>;
+export declare const ConfigSchema: z.ZodObject<{
+    sources: z.ZodObject<{
+        session: z.ZodBoolean;
+        web: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            key: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            enabled: boolean;
+            key?: string | undefined;
+        }, {
+            enabled: boolean;
+            key?: string | undefined;
+        }>;
+        code: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        session: boolean;
+        web: {
+            enabled: boolean;
+            key?: string | undefined;
+        };
+        code: boolean;
+    }, {
+        session: boolean;
+        web: {
+            enabled: boolean;
+            key?: string | undefined;
+        };
+        code: boolean;
+    }>;
+    depth: z.ZodEnum<["quick", "thorough"]>;
+    synth: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    sources: {
+        session: boolean;
+        web: {
+            enabled: boolean;
+            key?: string | undefined;
+        };
+        code: boolean;
+    };
+    depth: "quick" | "thorough";
+    synth: boolean;
+}, {
+    sources: {
+        session: boolean;
+        web: {
+            enabled: boolean;
+            key?: string | undefined;
+        };
+        code: boolean;
+    };
+    depth: "quick" | "thorough";
+    synth: boolean;
+}>;
+export type SourceId = z.infer<typeof SourceIdSchema>;
+export type Depth = z.infer<typeof DepthSchema>;
+export type ResultStatus = z.infer<typeof ResultStatusSchema>;
+export type Source = z.infer<typeof SourceSchema>;
+export type SourceError = z.infer<typeof SourceErrorSchema>;
+export type Evidence = z.infer<typeof EvidenceSchema>;
+export type Result = z.infer<typeof ResultSchema>;
+export type Synthesis = z.infer<typeof SynthesisSchema>;
+export type RawResult = z.infer<typeof RawResultSchema>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function resultJsonSchema(): import("zod-to-json-schema").JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+    } | undefined;
+};
+export declare function synthesisJsonSchema(): import("zod-to-json-schema").JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+    } | undefined;
+};

package/dist/schema.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+export const SOURCE_IDS = ["session", "web", "code"];
+export const DEPTHS = ["quick", "thorough"];
+export const RESULT_STATUSES = [
+    "ok",
+    "raw",
+    "raw_fallback",
+    "no_sources",
+    "no_results",
+];
+export const SourceIdSchema = z.enum(SOURCE_IDS);
+export const DepthSchema = z.enum(DEPTHS);
+export const ResultStatusSchema = z.enum(RESULT_STATUSES);
+export const SourceSchema = z
+    .object({
+    id: z.string(),
+    type: SourceIdSchema,
+    url: z.string().optional(),
+    title: z.string(),
+    snippet: z.string(),
+    relevance: z.number().min(0).max(1),
+    timestamp: z.number().optional(),
+})
+    .strict();
+export const SourceErrorSchema = z
+    .object({
+    source: SourceIdSchema,
+    code: z.enum(["unavailable", "request_failed", "invalid_response"]),
+    message: z.string(),
+})
+    .strict();
+export const EvidenceSchema = z
+    .object({
+    claim: z.string(),
+    sources: z.array(z.string()),
+    confidence: z.enum(["high", "medium", "low"]),
+})
+    .strict();
+export const ResultSchema = z
+    .object({
+    status: ResultStatusSchema,
+    answer: z.string(),
+    confidence: z.enum(["high", "medium", "low", "none"]),
+    evidence: z.array(EvidenceSchema),
+    sources: z.array(SourceSchema),
+    followups: z.array(z.string()),
+    meta: z
+        .object({
+        query: z.string(),
+        duration: z.number(),
+        sources_requested: z.number(),
+        sources_queried: z.number(),
+        sources_yielded: z.number(),
+        sources_unavailable: z.array(SourceIdSchema),
+        source_errors: z.array(SourceErrorSchema),
+    })
+        .strict(),
+})
+    .strict();
+export const SynthesisSchema = ResultSchema.omit({
+    status: true,
+    sources: true,
+    meta: true,
+});
+export const RawResultSchema = z
+    .object({
+    id: z.string(),
+    type: SourceIdSchema,
+    title: z.string(),
+    snippet: z.string(),
+    url: z.string().optional(),
+    relevance: z.number(),
+    timestamp: z.number().optional(),
+})
+    .strict();
+export const ConfigSchema = z
+    .object({
+    sources: z
+        .object({
+        session: z.boolean(),
+        web: z
+            .object({
+            enabled: z.boolean(),
+            key: z.string().optional(),
+        })
+            .strict(),
+        code: z.boolean(),
+    })
+        .strict(),
+    depth: DepthSchema,
+    synth: z.boolean(),
+})
+    .strict();
+export function resultJsonSchema() {
+    return zodToJsonSchema(ResultSchema, "OpensearchResult");
+}
+export function synthesisJsonSchema() {
+    return zodToJsonSchema(SynthesisSchema, "OpensearchSynthesis");
+}

package/dist/sources/code.d.ts

@@ -0,0 +1,3 @@
+import type { Depth } from "../schema";
+import { type SourceSearchOutcome } from "./shared";
+export declare function searchCode(query: string, depth: Depth): Promise<SourceSearchOutcome>;