@quelvio/langchain 0.1.0

package/dist/index.js

@@ -0,0 +1,564 @@
+import { z } from 'zod';
+import { Document } from '@langchain/core/documents';
+import { BaseRetriever } from '@langchain/core/retrievers';
+import { StructuredTool } from '@langchain/core/tools';
+
+// src/exceptions.ts
+var QuelvioError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuelvioAuthError = class extends QuelvioError {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioAuthError";
+  }
+};
+var QuelvioBadRequestError = class extends QuelvioError {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioBadRequestError";
+  }
+};
+var QuelvioNotFoundError = class extends QuelvioError {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioNotFoundError";
+  }
+};
+var QuelvioRateLimitError = class extends QuelvioError {
+  /** Value of the `Retry-After` header if present; otherwise `null`. */
+  retryAfterSeconds;
+  constructor(message, retryAfterSeconds = null) {
+    super(message);
+    this.name = "QuelvioRateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var QuelvioServerError = class extends QuelvioError {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "QuelvioServerError";
+    this.statusCode = statusCode;
+  }
+};
+var QuelvioTimeoutError = class extends QuelvioError {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioTimeoutError";
+  }
+};
+var QuelvioNetworkError = class extends QuelvioError {
+  constructor(message) {
+    super(message);
+    this.name = "QuelvioNetworkError";
+  }
+};
+var QueryModeSchema = z.enum(["fast", "standard", "deep"]);
+var QueryRequestSchema = z.object({
+  query: z.string(),
+  limit: z.number().int().min(1).max(50).default(5),
+  mode: QueryModeSchema.default("standard"),
+  domain_filter: z.string().nullable().optional()
+});
+var ChunkResultSchema = z.object({
+  chunk_id: z.string(),
+  content_piece_id: z.string(),
+  title: z.string(),
+  excerpt: z.string(),
+  score: z.number(),
+  rank: z.number().int(),
+  authority_score: z.number().nullable().optional(),
+  taxonomy_domain: z.string().nullable().optional(),
+  source_url: z.string().nullable().optional(),
+  creator_id: z.string().nullable().optional(),
+  author_name: z.string().nullable().optional(),
+  author_email: z.string().nullable().optional(),
+  department: z.string().nullable().optional()
+}).passthrough();
+var QueryResponseSchema = z.object({
+  query: z.string(),
+  query_id: z.string(),
+  results: z.array(ChunkResultSchema).default([]),
+  result_count: z.number().int().default(0),
+  coverage: z.string().nullable().optional(),
+  risk_flag: z.record(z.boolean()).default({}),
+  retrieval_mode: z.string().nullable().optional(),
+  synthesis: z.string().nullable().optional(),
+  synthesis_model: z.string().nullable().optional(),
+  latency_ms: z.number().int().nullable().optional(),
+  tokens_consumed: z.number().int().nullable().optional()
+}).passthrough();
+var DomainCoverageSchema = z.object({
+  taxonomy_domain: z.string(),
+  document_count: z.number().int().default(0),
+  chunk_count: z.number().int().default(0),
+  expert_count: z.number().int().default(0),
+  coverage_level: z.string().nullable().optional()
+}).passthrough();
+var DomainsListResponseSchema = z.object({
+  domains: z.array(DomainCoverageSchema).default([]),
+  total: z.number().int().default(0)
+}).passthrough();
+var SourceChunkSchema = z.object({
+  chunk_id: z.string(),
+  content_piece_id: z.string(),
+  title: z.string(),
+  excerpt: z.string(),
+  source_url: z.string().nullable().optional(),
+  source_type: z.string().nullable().optional(),
+  lifecycle_state: z.string().nullable().optional(),
+  embedded_at: z.string().nullable().optional(),
+  last_source_updated_at: z.string().nullable().optional(),
+  authority_score: z.number().nullable().optional(),
+  taxonomy_domain: z.string().nullable().optional(),
+  author_name: z.string().nullable().optional(),
+  author_email: z.string().nullable().optional()
+}).passthrough();
+var SourceDetailResponseSchema = z.object({
+  query_id: z.string(),
+  tenant_id: z.string().nullable().optional(),
+  chunks: z.array(SourceChunkSchema).default([]),
+  chunk_count: z.number().int().default(0)
+}).passthrough();
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.quelvio.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_BACKOFF_MS = 1e3;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
+var VALID_MODES = /* @__PURE__ */ new Set(["fast", "standard", "deep"]);
+function resolveApiKey(explicit) {
+  if (explicit) return explicit;
+  const fromEnv = process.env.QUELVIO_API_KEY;
+  if (fromEnv) return fromEnv;
+  throw new QuelvioAuthError(
+    "No Quelvio API key was provided. Pass `apiKey` to the constructor or set the QUELVIO_API_KEY environment variable. Generate a Personal Access Token at https://enterprise.quelvio.com/account."
+  );
+}
+function resolveBaseUrl(explicit) {
+  const candidate = explicit ?? process.env.QUELVIO_API_BASE ?? DEFAULT_BASE_URL;
+  return candidate.replace(/\/+$/, "");
+}
+function buildUserAgent() {
+  return `@quelvio/langchain/${VERSION} node/${process.version} ${process.platform}-${process.arch}`;
+}
+function normalizeMode(mode) {
+  if (mode === void 0 || mode === null) return "standard";
+  const lowered = String(mode).trim().toLowerCase();
+  if (!VALID_MODES.has(lowered)) {
+    throw new QuelvioBadRequestError(
+      `Invalid mode ${JSON.stringify(mode)}. Expected one of: fast, standard, deep.`
+    );
+  }
+  return lowered;
+}
+function boundLimit(value) {
+  if (value === void 0 || value === null) return 5;
+  if (value < 1) return 1;
+  if (value > 50) return 50;
+  return Math.floor(value);
+}
+function buildQueryBody(opts) {
+  const body = {
+    query: opts.query,
+    limit: boundLimit(opts.limit),
+    mode: normalizeMode(opts.mode)
+  };
+  if (opts.domainFilter !== void 0 && opts.domainFilter !== null) {
+    body.domain_filter = opts.domainFilter;
+  }
+  return body;
+}
+function backoffMs(attempt, rand) {
+  const base = BASE_BACKOFF_MS * 2 ** attempt;
+  const jitter = 1 + (rand * 0.4 - 0.2);
+  return Math.round(base * jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : null;
+}
+async function extractDetail(response) {
+  try {
+    const clone = response.clone();
+    const payload = await clone.json();
+    if (payload && typeof payload === "object") {
+      const obj = payload;
+      const detail = obj.detail ?? obj.message;
+      if (typeof detail === "string") return detail;
+    }
+  } catch {
+    try {
+      const text = (await response.clone().text()).trim();
+      return text ? text.slice(0, 500) : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+async function mapError(response) {
+  const detail = await extractDetail(response);
+  const status = response.status;
+  const reason = response.statusText || "";
+  if (status === 400) {
+    return new QuelvioBadRequestError(detail ?? `Bad request: ${reason}`);
+  }
+  if (status === 401 || status === 403) {
+    return new QuelvioAuthError(
+      "Quelvio authentication failed. Your token may be invalid, expired, or revoked. Generate a new Personal Access Token at https://enterprise.quelvio.com/account."
+    );
+  }
+  if (status === 404) {
+    return new QuelvioNotFoundError(detail ?? `Not found: ${reason}`);
+  }
+  if (status === 429) {
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    const suffix = retryAfter !== null ? ` (retry after ${retryAfter}s)` : "";
+    return new QuelvioRateLimitError(`Quelvio rate limit exceeded.${suffix}`, retryAfter);
+  }
+  if (status >= 500 && status < 600) {
+    return new QuelvioServerError(`Quelvio server error: ${status} ${reason}`, status);
+  }
+  return new QuelvioError(`Unexpected response: ${status} ${reason}`);
+}
+var QuelvioClient = class {
+  baseUrl;
+  timeoutMs;
+  maxRetries;
+  // Held in a closure so it is invisible to `toString`, `JSON.stringify`,
+  // and any introspection. There is no field on the instance.
+  #buildHeaders;
+  #fetch;
+  #source;
+  #apiKey;
+  constructor(options = {}) {
+    this.#apiKey = resolveApiKey(options.apiKey);
+    this.baseUrl = resolveBaseUrl(options.baseUrl);
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#source = options.source ?? "langchain-js-client";
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiKey = this.#apiKey;
+    const source = this.#source;
+    this.#buildHeaders = () => {
+      const h = new Headers();
+      h.set("Authorization", `Bearer ${apiKey}`);
+      h.set("Accept", "application/json");
+      h.set("Content-Type", "application/json");
+      h.set("User-Agent", buildUserAgent());
+      h.set("X-Quelvio-Source", "langchain-js");
+      h.set("X-Quelvio-Command", source);
+      return h;
+    };
+  }
+  /**
+   * Don't surface the bearer token from string coercion or JSON
+   * serialization. We deliberately list non-sensitive fields only.
+   */
+  toString() {
+    return `QuelvioClient(baseUrl=${this.baseUrl}, timeoutMs=${this.timeoutMs}, maxRetries=${this.maxRetries})`;
+  }
+  toJSON() {
+    return {
+      baseUrl: this.baseUrl,
+      timeoutMs: this.timeoutMs,
+      maxRetries: this.maxRetries
+    };
+  }
+  /** Internal accessor used by sibling classes that share the same client. */
+  _exposeApiKeyForSibling() {
+    return this.#apiKey;
+  }
+  /** Internal accessor — returns the configured `fetch` for sibling reuse. */
+  _exposeFetchForSibling() {
+    return this.#fetch;
+  }
+  /** Send a one-shot query and return the parsed response. */
+  async query(opts) {
+    if (!opts.query || !opts.query.trim()) {
+      throw new TypeError("query must be a non-empty string");
+    }
+    const body = buildQueryBody(opts);
+    const raw = await this.#request({ method: "POST", path: "/v1/enterprise/query", body });
+    return QueryResponseSchema.parse(raw);
+  }
+  async listDomains(opts = {}) {
+    const params = opts.coverage ? { coverage: opts.coverage } : void 0;
+    const raw = await this.#request({ method: "GET", path: "/v1/enterprise/domains", params });
+    return DomainsListResponseSchema.parse(raw);
+  }
+  async getSourceDetail(queryId) {
+    if (!queryId) {
+      throw new TypeError("queryId must be a non-empty string");
+    }
+    const raw = await this.#request({
+      method: "GET",
+      path: `/v1/enterprise/sources/${encodeURIComponent(queryId)}`
+    });
+    return SourceDetailResponseSchema.parse(raw);
+  }
+  async #request(opts) {
+    const url = this.#buildUrl(opts.path, opts.params);
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let response;
+      try {
+        response = await this.#fetch(url, {
+          method: opts.method,
+          headers: this.#buildHeaders(),
+          body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+          signal: controller.signal
+        });
+      } catch (err) {
+        lastError = err;
+        clearTimeout(timer);
+        const isAbort = err instanceof Error && err.name === "AbortError" || typeof err === "object" && err !== null && err.name === "AbortError";
+        if (isAbort) {
+          if (attempt < this.maxRetries) {
+            await sleep(backoffMs(attempt, Math.random()));
+            continue;
+          }
+          throw new QuelvioTimeoutError(
+            `Request to ${opts.path} timed out after ${this.timeoutMs}ms`
+          );
+        }
+        if (attempt < this.maxRetries) {
+          await sleep(backoffMs(attempt, Math.random()));
+          continue;
+        }
+        const name = err instanceof Error ? err.constructor.name : typeof err;
+        throw new QuelvioNetworkError(`Network error contacting Quelvio: ${name}`);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (response.ok) {
+        if (response.status === 204) return null;
+        const text = await response.text();
+        if (!text) return null;
+        return JSON.parse(text);
+      }
+      if (RETRYABLE_STATUSES.has(response.status) && attempt < this.maxRetries) {
+        await sleep(backoffMs(attempt, Math.random()));
+        continue;
+      }
+      throw await mapError(response);
+    }
+    throw new QuelvioError(
+      `Request failed after ${this.maxRetries + 1} attempts${lastError instanceof Error ? `: ${lastError.message}` : ""}`
+    );
+  }
+  #buildUrl(path, params) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    if (!params) return `${this.baseUrl}${normalized}`;
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0) search.set(k, v);
+    }
+    const qs = search.toString();
+    return qs ? `${this.baseUrl}${normalized}?${qs}` : `${this.baseUrl}${normalized}`;
+  }
+};
+function chunkToDocument(chunk) {
+  const metadata = {
+    chunk_id: chunk.chunk_id,
+    content_piece_id: chunk.content_piece_id,
+    title: chunk.title,
+    score: chunk.score,
+    rank: chunk.rank
+  };
+  if (chunk.authority_score !== void 0 && chunk.authority_score !== null) {
+    metadata.authority_score = chunk.authority_score;
+  }
+  if (chunk.taxonomy_domain) metadata.taxonomy_domain = chunk.taxonomy_domain;
+  if (chunk.source_url) {
+    metadata.source_url = chunk.source_url;
+    metadata.source = chunk.source_url;
+  }
+  if (chunk.author_name) metadata.author_name = chunk.author_name;
+  if (chunk.author_email) metadata.author_email = chunk.author_email;
+  if (chunk.department) metadata.department = chunk.department;
+  return new Document({ pageContent: chunk.excerpt, metadata });
+}
+function responseToDocuments(response) {
+  const docs = response.results.map(chunkToDocument);
+  if (docs.length > 0) {
+    docs[0].metadata.query_id = response.query_id;
+  }
+  return docs;
+}
+var QuelvioRetriever = class extends BaseRetriever {
+  static lc_name() {
+    return "QuelvioRetriever";
+  }
+  lc_namespace = ["quelvio", "retrievers"];
+  limit;
+  mode;
+  domainFilter;
+  #client;
+  constructor(options = {}) {
+    super(options);
+    this.limit = options.limit ?? 5;
+    this.mode = options.mode ?? "standard";
+    this.domainFilter = options.domainFilter ?? null;
+    if (options.client) {
+      this.#client = options.client;
+    } else {
+      const clientOpts = { source: "langchain-js-retriever" };
+      if (options.apiKey !== void 0) clientOpts.apiKey = options.apiKey;
+      if (options.baseUrl !== void 0) clientOpts.baseUrl = options.baseUrl;
+      if (options.timeoutMs !== void 0) clientOpts.timeoutMs = options.timeoutMs;
+      if (options.maxRetries !== void 0) clientOpts.maxRetries = options.maxRetries;
+      if (options.fetch !== void 0) clientOpts.fetch = options.fetch;
+      this.#client = new QuelvioClient(clientOpts);
+    }
+  }
+  toString() {
+    return `QuelvioRetriever(limit=${this.limit}, mode=${this.mode}, domainFilter=${this.domainFilter ?? "null"})`;
+  }
+  async _getRelevantDocuments(query, _runManager) {
+    if (!query || !query.trim()) {
+      throw new TypeError("query must be a non-empty string");
+    }
+    const response = await this.#client.query({
+      query,
+      limit: this.limit,
+      mode: this.mode,
+      domainFilter: this.domainFilter
+    });
+    return responseToDocuments(response);
+  }
+};
+
+// src/synthesis.ts
+function fromResponse(response) {
+  return {
+    answer: response.synthesis ?? null,
+    sources: [...response.results],
+    queryId: response.query_id
+  };
+}
+async function synthesizeAnswer(question, options = {}) {
+  if (!question || !question.trim()) {
+    throw new TypeError("question must be a non-empty string");
+  }
+  let client = options.client;
+  if (!client) {
+    const clientOpts = { source: "langchain-js-synthesis" };
+    if (options.apiKey !== void 0) clientOpts.apiKey = options.apiKey;
+    if (options.baseUrl !== void 0) clientOpts.baseUrl = options.baseUrl;
+    if (options.timeoutMs !== void 0) clientOpts.timeoutMs = options.timeoutMs;
+    if (options.maxRetries !== void 0) clientOpts.maxRetries = options.maxRetries;
+    if (options.fetch !== void 0) clientOpts.fetch = options.fetch;
+    client = new QuelvioClient(clientOpts);
+  }
+  const response = await client.query({
+    query: question,
+    limit: options.maxSources ?? 5,
+    mode: options.mode ?? "standard",
+    domainFilter: options.domainFilter ?? null
+  });
+  return fromResponse(response);
+}
+var asynthesizeAnswer = synthesizeAnswer;
+var DEFAULT_DESCRIPTION = "Search the organization's connected knowledge brain (Google Drive, SharePoint, Confluence, Slack, Notion, and other internal sources) for an authoritative, cited answer. Use this whenever the user asks about internal company information \u2014 policies, processes, decisions, people, products, projects, or anything else that lives in the company's systems rather than on the public internet. The answer is scoped to the running user's individual access permissions, so results never include documents they cannot already see. Returns a synthesized answer plus a list of cited sources (titles + URLs).";
+var QuelvioToolInputSchema = z.object({
+  question: z.string().min(1).describe(
+    "The natural-language question to ask the company's knowledge brain. Phrase it as the user would ask it \u2014 do not pre-process or keyword-extract."
+  ),
+  mode: z.enum(["fast", "standard", "deep"]).optional().describe(
+    "Synthesis depth: 'fast' for low-latency retrieval-only, 'standard' (default) for retrieval + synthesis, 'deep' for multi-pass reasoning over a wider window."
+  ),
+  max_sources: z.number().int().min(1).max(50).optional().describe("Maximum number of source chunks to retrieve (1 to 50, default 5)."),
+  domain: z.string().optional().describe(
+    "Optional taxonomy domain to restrict retrieval to (e.g. 'engineering', 'legal', 'people-ops')."
+  )
+});
+function formatResponse(response) {
+  const lines = [];
+  if (response.synthesis) {
+    lines.push(response.synthesis.trim());
+    lines.push("");
+  }
+  if (response.results.length > 0) {
+    lines.push("Sources:");
+    response.results.forEach((chunk, idx) => {
+      const label = chunk.title || chunk.chunk_id;
+      if (chunk.source_url) {
+        lines.push(`  [${idx + 1}] ${label} \u2014 ${chunk.source_url}`);
+      } else {
+        lines.push(`  [${idx + 1}] ${label}`);
+      }
+    });
+  }
+  if (lines.length === 0) {
+    return "No matching content was found in the company's knowledge brain.";
+  }
+  return lines.join("\n").trimEnd();
+}
+var QuelvioTool = class extends StructuredTool {
+  static lc_name() {
+    return "QuelvioTool";
+  }
+  get lc_namespace() {
+    return ["quelvio", "tools"];
+  }
+  name = "quelvio_query";
+  description = DEFAULT_DESCRIPTION;
+  schema = QuelvioToolInputSchema;
+  defaultMode;
+  defaultMaxSources;
+  #client;
+  constructor(options = {}) {
+    super();
+    if (options.name) this.name = options.name;
+    if (options.description) this.description = options.description;
+    this.defaultMode = options.defaultMode ?? "standard";
+    this.defaultMaxSources = options.defaultMaxSources ?? 5;
+    if (options.client) {
+      this.#client = options.client;
+    } else {
+      const clientOpts = { source: "langchain-js-tool" };
+      if (options.apiKey !== void 0) clientOpts.apiKey = options.apiKey;
+      if (options.baseUrl !== void 0) clientOpts.baseUrl = options.baseUrl;
+      if (options.timeoutMs !== void 0) clientOpts.timeoutMs = options.timeoutMs;
+      if (options.maxRetries !== void 0) clientOpts.maxRetries = options.maxRetries;
+      if (options.fetch !== void 0) clientOpts.fetch = options.fetch;
+      this.#client = new QuelvioClient(clientOpts);
+    }
+  }
+  toString() {
+    return `QuelvioTool(name=${this.name}, defaultMode=${this.defaultMode}, defaultMaxSources=${this.defaultMaxSources})`;
+  }
+  async _call(input, _runManager) {
+    if (!input.question || !input.question.trim()) {
+      throw new TypeError("question must be a non-empty string");
+    }
+    const response = await this.#client.query({
+      query: input.question,
+      limit: input.max_sources ?? this.defaultMaxSources,
+      mode: input.mode ?? this.defaultMode,
+      domainFilter: input.domain ?? null
+    });
+    return formatResponse(response);
+  }
+};
+
+export { ChunkResultSchema, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DomainCoverageSchema, DomainsListResponseSchema, QuelvioAuthError, QuelvioBadRequestError, QuelvioClient, QuelvioError, QuelvioNetworkError, QuelvioNotFoundError, QuelvioRateLimitError, QuelvioRetriever, QuelvioServerError, QuelvioTimeoutError, QuelvioTool, QuelvioToolInputSchema, QueryModeSchema, QueryRequestSchema, QueryResponseSchema, SourceChunkSchema, SourceDetailResponseSchema, VERSION, asynthesizeAnswer, boundLimit, buildQueryBody, normalizeMode, synthesizeAnswer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map