@rubytech/create-maxy-code 0.1.132 → 0.1.140

package/payload/platform/lib/graph-search/src/query-expansion.ts

@@ -0,0 +1,129 @@
+/**
+ * Multi-query expansion via Haiku (Task 308).
+ *
+ * Generates 3-5 paraphrases of the user query so the hybrid pipeline runs
+ * each paraphrase against vector + BM25 in parallel and unions the
+ * candidate sets before fusion. Recovers recall on terse queries where the
+ * embedding's nearest-neighbour is unstable.
+ *
+ * The expansion runs through `@rubytech/oauth-llm` against Claude Haiku —
+ * the same OAuth-bearer path the admin classifiers use; no new SDK
+ * dependency and no Anthropic-API-key path. Cache is in-process, keyed by
+ * (accountId, normalisedQuery, retrievalClass), with a 1-hour TTL.
+ *
+ * Graceful degrade: if the LLM call fails, returns just the original
+ * query. The caller's hybrid pipeline still runs — just on one query
+ * instead of N — so missing paraphrases are a recall regression, not a
+ * fault.
+ */
+
+import { callOauthLlm } from "../../oauth-llm/dist/index.js";
+
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const HAIKU_MODEL = "claude-haiku-4-5";
+const MAX_PARAPHRASES = 5;
+
+interface CacheEntry {
+  expansions: string[];
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export function clearExpansionCache(): void {
+  cache.clear();
+}
+
+export interface ExpandQueryParams {
+  query: string;
+  retrievalClass?: string;
+  accountId?: string;
+  /**
+   * Override the cache or skip it entirely (useful in tests). When
+   * `false`, the cache is read but never written; when `true` (default),
+   * both reads and writes are active.
+   */
+  useCache?: boolean;
+}
+
+/**
+ * Return `[query, ...paraphrases]` (original always first). On LLM
+ * failure returns `[query]` only and writes a single stderr line so the
+ * operator can see expansion is degrading without breaking search.
+ */
+export async function expandQuery(
+  params: ExpandQueryParams,
+): Promise<string[]> {
+  const { query, retrievalClass = "general", accountId = "", useCache = true } = params;
+  const normalised = query.trim().toLowerCase();
+  const cacheKey = `${accountId}::${retrievalClass}::${normalised}`;
+
+  if (useCache) {
+    const hit = cache.get(cacheKey);
+    if (hit && hit.expiresAt > Date.now()) {
+      return [query, ...hit.expansions];
+    }
+  }
+
+  const systemPrompt = [
+    "You generate paraphrases of a user query for hybrid graph search.",
+    "Return 3-5 alternative phrasings that preserve the user's intent but vary the surface form (synonyms, word order, entity-vs-attribute framing).",
+    "Do not change the entity names. Do not invent constraints the user did not state.",
+    "Output ONLY a JSON object via the provided tool; never free text.",
+  ].join("\n");
+
+  const classHint = retrievalClass === "general"
+    ? ""
+    : `The retrieval class is '${retrievalClass}' — tailor paraphrases accordingly.`;
+  const userMessage = [
+    `Original query: ${query}`,
+    classHint,
+  ].filter((s) => s.length > 0).join("\n");
+
+  const result = await callOauthLlm({
+    model: HAIKU_MODEL,
+    system: systemPrompt,
+    userMessage,
+    maxTokens: 512,
+    timeoutMs: 15_000,
+    tools: [
+      {
+        name: "emit_paraphrases",
+        description: "Emit 3-5 paraphrases of the user query.",
+        input_schema: {
+          type: "object",
+          properties: {
+            paraphrases: {
+              type: "array",
+              items: { type: "string" },
+              minItems: 3,
+              maxItems: MAX_PARAPHRASES,
+            },
+          },
+          required: ["paraphrases"],
+        },
+      },
+    ],
+    toolChoiceName: "emit_paraphrases",
+  });
+
+  if (result.kind !== "ok-tool") {
+    process.stderr.write(
+      `[graph-search:expansion-failed] cause=${result.kind === "fallback" ? result.cause : "unexpected"} query=${query.slice(0, 60).replace(/\s+/g, " ")}\n`,
+    );
+    return [query];
+  }
+
+  const raw = (result.input as { paraphrases?: unknown }).paraphrases;
+  if (!Array.isArray(raw)) return [query];
+  const expansions = raw
+    .filter((p): p is string => typeof p === "string" && p.trim().length > 0)
+    .map((p) => p.trim())
+    .slice(0, MAX_PARAPHRASES);
+
+  if (useCache) {
+    cache.set(cacheKey, { expansions, expiresAt: Date.now() + CACHE_TTL_MS });
+  }
+
+  return [query, ...expansions];
+}

package/payload/platform/lib/graph-search/src/route.ts

@@ -0,0 +1,70 @@
+/**
+ * Retrieval-class routing (Task 308).
+ *
+ * Consumes the `retrievalClass` field produced by Task 304's
+ * gateway-classifier (landed) and returns a per-class index plan: which
+ * labels to filter to, which fusion weights to favour, and whether to
+ * skip the lookup entirely.
+ *
+ * No new Haiku call here — this module is a pure deterministic mapping
+ * over the gateway's existing classification.
+ */
+
+export type RetrievalClass =
+  | "entity"
+  | "temporal"
+  | "event"
+  | "general"
+  | "none";
+
+export interface IndexPlan {
+  /** When true, the caller short-circuits and returns no results. */
+  skip: boolean;
+  /** Restrict vector + BM25 to these labels. Undefined means no filter. */
+  labelFilter?: string[];
+  /** Weight on the vector half of the (weighted-sum) fusion. */
+  vectorWeight: number;
+  /** Weight on the BM25 half of the (weighted-sum) fusion. */
+  bm25Weight: number;
+}
+
+/**
+ * Return the index plan for a retrieval class. Unknown values fall back
+ * to `general` rather than throwing — the routing is a soft hint and the
+ * caller's old behaviour is the safe default.
+ */
+export function pickIndexMix(retrievalClass: string | undefined): IndexPlan {
+  switch (retrievalClass) {
+    case "entity":
+      return {
+        skip: false,
+        labelFilter: ["Person", "Company", "Concept"],
+        vectorWeight: 0.85,
+        bm25Weight: 0.15,
+      };
+    case "temporal":
+      return {
+        skip: false,
+        labelFilter: ["Event"],
+        vectorWeight: 0.2,
+        bm25Weight: 0.8,
+      };
+    case "event":
+      return {
+        skip: false,
+        labelFilter: ["Event"],
+        vectorWeight: 0,
+        bm25Weight: 1,
+      };
+    case "none":
+      return { skip: true, vectorWeight: 0, bm25Weight: 0 };
+    case "general":
+    default:
+      if (retrievalClass && retrievalClass !== "general") {
+        process.stderr.write(
+          `[graph-search:unknown-class] rc=${retrievalClass} fallback=general\n`,
+        );
+      }
+      return { skip: false, vectorWeight: 0.7, bm25Weight: 0.3 };
+  }
+}

package/payload/platform/lib/graph-search/src/rrf-fusion.ts

@@ -0,0 +1,62 @@
+/**
+ * Reciprocal Rank Fusion (Task 308).
+ *
+ * Replaces the weighted-sum fusion (`0.7 * vector + 0.3 * bm25_norm`) when
+ * the `MAXY_GS_RRF` flag is on. RRF is robust to score-distribution drift
+ * between the vector and BM25 indexes — it sums `1 / (k + rank_i)` for each
+ * node across the ranked lists it appears in. Higher rank (lower index) →
+ * larger contribution; the constant `k` (default 60, per the gbrain
+ * default) smooths the long tail.
+ *
+ * The weighted-sum baseline stays as the fallback so flag flips are
+ * reversible without code edits.
+ */
+
+export interface FusionCandidate {
+  nodeId: string;
+}
+
+/**
+ * Fuse multiple ranked lists by Reciprocal Rank Fusion.
+ *
+ * Each input list is treated as already sorted (best first). For each
+ * candidate, score = sum over lists of `1 / (k + rank)`. Returns the union
+ * sorted by descending RRF score.
+ *
+ * Ties on RRF score are broken by the candidate's earliest appearance
+ * across the input lists (first-seen wins), which is deterministic given
+ * a deterministic input order.
+ */
+export function fuseRrf<T extends FusionCandidate>(
+  rankedLists: T[][],
+  k = 60,
+): Array<T & { rrfScore: number }> {
+  const scores = new Map<string, number>();
+  const representatives = new Map<string, T>();
+  const firstSeen = new Map<string, number>();
+  let order = 0;
+
+  for (const list of rankedLists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const candidate = list[rank];
+      const contribution = 1 / (k + rank);
+      const prior = scores.get(candidate.nodeId) ?? 0;
+      scores.set(candidate.nodeId, prior + contribution);
+      if (!representatives.has(candidate.nodeId)) {
+        representatives.set(candidate.nodeId, candidate);
+        firstSeen.set(candidate.nodeId, order++);
+      }
+    }
+  }
+
+  const out: Array<T & { rrfScore: number }> = [];
+  for (const [nodeId, rrfScore] of scores) {
+    const rep = representatives.get(nodeId)!;
+    out.push({ ...rep, rrfScore });
+  }
+  out.sort((a, b) => {
+    if (b.rrfScore !== a.rrfScore) return b.rrfScore - a.rrfScore;
+    return (firstSeen.get(a.nodeId)! - firstSeen.get(b.nodeId)!);
+  });
+  return out;
+}

package/payload/platform/lib/obsidian-parser/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * obsidian-parser — pure functions for parsing an Obsidian vault on disk.
+ *
+ * No DB access, no MCP, no I/O side effects other than fs reads. Composed by
+ * the `obsidian-vault-import` MCP tool in the memory plugin.
+ *
+ * Doctrine: every regex is linear-time (no catastrophic backtracking), every
+ * function is deterministic. The agent never calls this code; the server does.
+ */
+export interface ParsedPage {
+    /** Path relative to the vault root, with forward slashes. The MERGE natural key. */
+    obsidianPath: string;
+    /** Filename without `.md` — the default wikilink target form. */
+    title: string;
+    /** Aliases declared in frontmatter (`aliases:` array). */
+    aliases: string[];
+    /** Tag tokens (without `#`), unioned from frontmatter `tags:` and inline `#tag` body matches. */
+    tags: string[];
+    /** Body text (frontmatter stripped). Stored verbatim. */
+    body: string;
+    /** SHA-256 of the on-disk file bytes — idempotency key. */
+    contentHash: string;
+    /** Detected daily-note date (YYYY-MM-DD) or null. */
+    noteDate: string | null;
+    /** Wikilinks emitted by this page. */
+    wikilinks: WikilinkOccurrence[];
+    /** Embedded attachments declared via `![[file.png]]` or `![alt](file.png)`. */
+    attachments: AttachmentOccurrence[];
+    /** Last-modified timestamp from fs stat — used for modified-since filtering. */
+    mtimeMs: number;
+}
+export interface WikilinkOccurrence {
+    /** The exact text inside `[[…]]` before any alias `|`. May contain `#anchor`. */
+    rawTarget: string;
+    /** Target after stripping `#anchor`. */
+    target: string;
+    /** Anchor portion (after `#`) or null. */
+    anchor: string | null;
+    /** Alias text after `|`, or null when absent. The display text. */
+    alias: string | null;
+}
+export interface AttachmentOccurrence {
+    /** Path as written in the markdown. May be relative to the page or to the vault root. */
+    rawPath: string;
+    /** Resolved path relative to vault root, normalised. May not exist on disk yet. */
+    resolvedPath: string;
+    /** Display alt text (from `![alt](path)` form) or null for embed-syntax `![[file]]`. */
+    alt: string | null;
+}
+export interface VaultWalkOptions {
+    /** Filter: only pages whose path starts with one of these folder prefixes. */
+    folderPrefixes?: string[];
+    /** Filter: only pages whose tags intersect with this set. */
+    tagFilter?: string[];
+    /** Filter: only pages modified at or after this epoch-ms. */
+    modifiedSinceMs?: number;
+}
+/**
+ * Walk the vault directory and return one ParsedPage per `.md` file that
+ * survives the optional filter set.
+ *
+ * Path-traversal defence: paths containing `..` segments are rejected at
+ * entry. The `vaultRoot` passed in is assumed to have already been verified
+ * by the caller as living under the account's archive directory.
+ */
+export declare function walkVault(vaultRoot: string, opts?: VaultWalkOptions): Promise<ParsedPage[]>;
+export declare function parsePage(obsidianPath: string, bytes: Buffer, mtimeMs: number): ParsedPage;
+interface ParsedFrontmatter {
+    raw: string;
+    /** Map of top-level key → raw value string. Arrays are returned as the
+     *  block following the key (caller parses per-key). */
+    fields: Map<string, string>;
+}
+export declare function splitFrontmatter(text: string): {
+    frontmatter: ParsedFrontmatter;
+    body: string;
+};
+export declare function normalizeTag(tag: string): string;
+export declare function detectDailyNote(obsidianPath: string, fm: ParsedFrontmatter): string | null;
+export interface VaultIndex {
+    /** Lowercased title (without `.md`) → set of `obsidianPath` candidates. */
+    byTitle: Map<string, string[]>;
+    /** Lowercased alias → set of `obsidianPath` candidates. */
+    byAlias: Map<string, string[]>;
+}
+export declare function buildVaultIndex(pages: ParsedPage[]): VaultIndex;
+/**
+ * Look up a wikilink target inside the vault, returning candidate page paths.
+ *
+ * The target is matched against (a) page titles and (b) declared aliases.
+ * Path-form targets (`Folder/Page`) match directly. Returns an empty array
+ * when no intra-vault candidate exists — the caller falls through to entity
+ * resolution.
+ */
+export declare function resolveWikilinkInVault(target: string, index: VaultIndex, knownPaths: Set<string>): string[];
+export declare function makeImportId(): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/obsidian-parser/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sCAAsC;IACtC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,+EAA+E;IAC/E,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,UAAU,EAAE,CAAC,CA6EvB;AAoBD,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,UAAU,CA6BZ;AAMD,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ;2DACuD;IACvD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAID,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAoDlD;AAiKD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMhD;AAmBD,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,iBAAiB,GACpB,MAAM,GAAG,IAAI,CAyBf;AAMD,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,2DAA2D;IAC3D,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAChC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,CAU/D;AAWD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GACtB,MAAM,EAAE,CAmBV;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAErC"}