@ggui-ai/negotiator 0.1.0-rc.1

package/src/normalize-schema.ts

@@ -0,0 +1,193 @@
+/**
+ * Deterministic repair of the invalid JSON Schema `type` spellings an
+ * LLM occasionally emits in a synthesized contract. Runs inside
+ * `buildContract` (before the `dataContractSchema` validation gate) so
+ * the dominant synth-decline class — a `type` value outside the seven
+ * JSON Schema primitives — is structurally eliminated rather than left
+ * to a repair retry.
+ *
+ * Pure, recursive, total: a schema that is already valid passes
+ * through unchanged — every mapping fires only on a value NOT in the
+ * valid set. Recursion descends only into sub-schema positions, so
+ * data-value positions (`default`, `const`, `enum`, `examples`) are
+ * left verbatim — a `default` of `{type: "list"}` is user data, not a
+ * schema, and must not be rewritten.
+ */
+
+/** The seven JSON Schema primitive type names. */
+const VALID_TYPES = new Set([
+  'string',
+  'number',
+  'integer',
+  'boolean',
+  'array',
+  'object',
+  'null',
+]);
+
+/** Unambiguous non-canonical type spellings → canonical primitive. */
+const TYPE_ALIASES: Record<string, string> = {
+  list: 'array',
+  tuple: 'array',
+  sequence: 'array',
+  dict: 'object',
+  map: 'object',
+  record: 'object',
+  hash: 'object',
+  str: 'string',
+  text: 'string',
+  char: 'string',
+  int: 'integer',
+  long: 'integer',
+  short: 'integer',
+  float: 'number',
+  double: 'number',
+  decimal: 'number',
+  num: 'number',
+  numeric: 'number',
+  bool: 'boolean',
+};
+
+/** Type words that mean "no constraint" — the `type` key is dropped. */
+const DROP_TYPES = new Set(['any', 'unknown', 'mixed', 'void']);
+
+/** Object keys whose value is itself a single schema. */
+const SCHEMA_VALUED_KEYS = new Set([
+  'items',
+  'additionalProperties',
+  'not',
+  'contains',
+  'propertyNames',
+]);
+
+/** Object keys whose value is a map of name → schema. */
+const SCHEMA_MAP_KEYS = new Set([
+  'properties',
+  'patternProperties',
+  '$defs',
+  'definitions',
+]);
+
+/** Object keys whose value is an array of schemas. */
+const SCHEMA_ARRAY_KEYS = new Set([
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'prefixItems',
+]);
+
+/**
+ * Infer the base type of an `enum`-constrained field from its value
+ * list. Mixed / empty / non-array → `string` (the safe default, and
+ * the overwhelmingly common enum shape).
+ */
+function inferEnumBaseType(enumSibling: unknown): string {
+  if (!Array.isArray(enumSibling) || enumSibling.length === 0) {
+    return 'string';
+  }
+  if (enumSibling.every((v) => typeof v === 'string')) return 'string';
+  if (enumSibling.every((v) => typeof v === 'number')) return 'number';
+  if (enumSibling.every((v) => typeof v === 'boolean')) return 'boolean';
+  return 'string';
+}
+
+/**
+ * Map one `type` value to a canonical primitive, or `undefined` when
+ * the `type` key should be dropped entirely (an absent `type` is valid
+ * JSON Schema — it simply imposes no constraint).
+ *
+ * `enumSibling` is the schema's `enum` array, used to pick the base
+ * type when the LLM wrote the (invalid) `type: "enum"`.
+ */
+function normalizeTypeValue(
+  value: unknown,
+  enumSibling: unknown,
+): string | undefined {
+  if (typeof value === 'string') {
+    const lower = value.toLowerCase();
+    if (VALID_TYPES.has(lower)) return lower;
+    if (lower === 'enum') return inferEnumBaseType(enumSibling);
+    if (DROP_TYPES.has(lower)) return undefined;
+    const alias = TYPE_ALIASES[lower];
+    if (alias !== undefined) return alias;
+    // Unrecognized garbage — drop the constraint rather than guess.
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    // Union type (`["string", "null"]`). The protocol contract schema
+    // accepts only a single string; recover the first valid non-null
+    // member, dropping the nullable arm.
+    for (const member of value) {
+      if (typeof member === 'string') {
+        const norm = normalizeTypeValue(member, enumSibling);
+        if (norm !== undefined && norm !== 'null') return norm;
+      }
+    }
+    return 'string';
+  }
+  // `type` was a number / object / boolean — meaningless; drop it.
+  return undefined;
+}
+
+/** Normalize a map of name → schema (e.g. `properties`). */
+function normalizeSchemaMap(value: unknown): unknown {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [name, sub] of Object.entries(value as Record<string, unknown>)) {
+    out[name] = coerceToSchema(sub);
+  }
+  return out;
+}
+
+/**
+ * Coerce a value found in a schema-expecting position into a schema
+ * object. An LLM sometimes writes the shorthand `items: "number"`
+ * where JSON Schema requires `items: {type: "number"}` — expand it
+ * (`"number"` → `{type: "number"}`, an unrecognized string → `{}`,
+ * the unconstrained schema). A boolean (`additionalProperties: false`)
+ * is a valid schema-position value and passes through; anything else
+ * recurses through {@link normalizeSchema}.
+ */
+function coerceToSchema(value: unknown): unknown {
+  if (typeof value === 'string') {
+    const t = normalizeTypeValue(value, undefined);
+    return t === undefined ? {} : { type: t };
+  }
+  return normalizeSchema(value);
+}
+
+/**
+ * Recursively normalize a JSON Schema, repairing invalid `type`
+ * values. Non-object input (booleans, primitives) passes through —
+ * `additionalProperties: false` and the like are valid as-is.
+ */
+export function normalizeSchema(schema: unknown): unknown {
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+    return schema;
+  }
+  const obj = schema as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === 'type') {
+      const fixed = normalizeTypeValue(value, obj['enum']);
+      if (fixed !== undefined) out[key] = fixed;
+      continue;
+    }
+    if (SCHEMA_VALUED_KEYS.has(key)) {
+      out[key] = coerceToSchema(value);
+    } else if (SCHEMA_MAP_KEYS.has(key)) {
+      out[key] = normalizeSchemaMap(value);
+    } else if (SCHEMA_ARRAY_KEYS.has(key)) {
+      out[key] = Array.isArray(value)
+        ? value.map((s) => coerceToSchema(s))
+        : value;
+    } else {
+      // Data-value position (`default`, `const`, `enum`, `examples`,
+      // `required`, `description`, …) — leave verbatim.
+      out[key] = value;
+    }
+  }
+  return out;
+}

package/src/pure.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure helpers — zero I/O, zero AWS dependencies.
+ *
+ *   - `inferInteractionMode(text)` — keyword-priority mapper from free
+ *     text (category / pattern / prompt) to a categorical interaction
+ *     label. Used for telemetry / RAG hinting only; NOT part of the
+ *     `DataContract` wire surface. Deterministic; default `'display'`.
+ *   - `inferJsonSchemaType(tsType)` — TypeScript-style type-string
+ *     mapper to the JSON Schema type union. Deterministic.
+ */
+
+/**
+ * Categorical interaction-mode label used by `inferInteractionMode` for
+ * telemetry / RAG hinting. NOT a `DataContract` field — the four typed
+ * specs (propsSpec / actionSpec / contextSpec / streamSpec) describe
+ * the wire surface exhaustively, so interaction mode is a derived
+ * heuristic, never part of the contract.
+ */
+export type InteractionMode = 'display' | 'collect' | 'converse' | 'broadcast' | 'flow';
+
+/**
+ * Infer interaction mode from any text (category, pattern, or prompt).
+ * Consolidated keyword matcher — all call sites use the same function.
+ *
+ * Used by rag-search and external benchmark runners for routing /
+ * telemetry. Deterministic; no I/O. Matches the first rule in priority
+ * order, defaulting to 'display'.
+ */
+export function inferInteractionMode(text: string): InteractionMode {
+  const t = text.toLowerCase();
+  if (t.includes('form') || t.includes('survey') || t.includes('input') || t.includes('collect') || t.includes('sign up') || t.includes('contact')) return 'collect';
+  if (t.includes('chat') || t.includes('conversation') || t.includes('messaging') || t.includes('talk')) return 'converse';
+  if (t.includes('dashboard') || t.includes('monitor') || t.includes('live') || t.includes('feed') || t.includes('real-time')) return 'broadcast';
+  if (t.includes('wizard') || t.includes('onboarding') || t.includes('checkout') || t.includes('stepper') || t.includes('multi-step') || t.includes('flow') || t.includes('step')) return 'flow';
+  return 'display';
+}
+
+/** Map TypeScript-style type strings to JSON Schema types. */
+export function inferJsonSchemaType(tsType: string): 'string' | 'number' | 'boolean' | 'array' | 'object' {
+  const t = tsType.toLowerCase();
+  if (t.includes('string')) return 'string';
+  if (t.includes('number') || t.includes('int') || t.includes('float')) return 'number';
+  if (t.includes('boolean') || t.includes('bool')) return 'boolean';
+  if (t.includes('array') || t.includes('[]')) return 'array';
+  return 'object';
+}

package/src/rag-search.ts

@@ -0,0 +1,274 @@
+/**
+ * RAG Search — embedding-similarity blueprint retrieval over the
+ * public `@ggui-ai/mcp-server-core` storage seam.
+ *
+ * Given agent `prompt` + a tenant `scope` (typically appId, or the
+ * literal `"shared"` for the global catalog), this helper:
+ *
+ *   1. Embeds the prompt via {@link EmbeddingProvider.embed}.
+ *   2. Queries the {@link VectorStore} for the top-K nearest neighbors
+ *      (server-side cosine, scope-partitioned — no cross-tenant leak).
+ *   3. Filters by minimum score, biases private (per-app registered
+ *      UIs) over shared (generated pool) at the same score band, and
+ *      projects each hit into a {@link NegotiatorOption}.
+ *
+ * Two pipeline paths emerge from the confidence band:
+ *   - **High confidence** (`score >= HIGH_CONFIDENCE_THRESHOLD`): the
+ *     hit is marked `exact`. Upstream callers (V3 `negotiate()`) can
+ *     short-circuit the decision LLM entirely.
+ *   - **Medium confidence** (`score >= RETRIEVAL_MIN_SCORE` and below
+ *     the exact threshold): marked `partial`. Upstream passes these to
+ *     the decision LLM as candidates.
+ *
+ * ### Public-seam contract
+ *
+ * This function reads only the public `VectorStore` surface (scalar
+ * metadata). Consumers that still hold the rich `EmbeddingStorage`
+ * shape bridge via
+ * `@ggui-cloud/aws-adapters.embeddingStorageToVectorStore`, which
+ * encodes array-valued fields (`props`, `callbacks`, `sourceTools`)
+ * as JSON strings inside `metadata`. Any `VectorStore` implementation
+ * that stores fresh writes through `writeRagVector` (see
+ * `mcp-servers/ggui-protocol/src/adapters/vector-store.ts`) uses the
+ * same encoding — so existing caches, fresh writes, and community
+ * `VectorStore` backends all collide on the same retrieval key.
+ *
+ * ### Scope
+ *
+ * No AWS bindings, no LLM dependency. Pure composition over the two
+ * public seams. The one-LLM-call `makeDecision()` step is separate.
+ */
+
+import type {
+  EmbeddingProvider,
+  VectorSearchResult,
+  VectorStore,
+} from '@ggui-ai/mcp-server-core';
+import type { DataContract, JsonValue } from '@ggui-ai/protocol';
+import { inferJsonSchemaType } from './pure.js';
+import type { NegotiatorOption } from './types.js';
+
+/** RAG search result with per-stage timing. */
+export interface RagSearchResult {
+  options: NegotiatorOption[];
+  embeddingLatencyMs: number;
+  searchLatencyMs: number;
+}
+
+/** Dependencies — both public seams from `@ggui-ai/mcp-server-core`. */
+export interface RagSearchDeps {
+  embedding: EmbeddingProvider;
+  vectors: VectorStore;
+}
+
+export interface RagSearchInput {
+  /** Natural-language query text. Embedded as-is. */
+  prompt: string;
+  /**
+   * Scope / tenant partition. Typically `appId` for per-app indexes
+   * or the literal `"shared"` for the global catalog. Passed straight
+   * through to `VectorStore.query`; the scope is the tenant boundary,
+   * so a query never crosses into another tenant's index.
+   */
+  scope: string;
+  /** Override the k-NN cut-off (default 10). */
+  maxCandidates?: number;
+}
+
+/** Minimum cosine similarity to be considered a retrieval candidate. */
+const RETRIEVAL_MIN_SCORE = 0.15;
+
+/** Cosine similarity above this → exact match (skip LLM). */
+const HIGH_CONFIDENCE_THRESHOLD = 0.45;
+
+/** Default top-K for the k-NN query. */
+const DEFAULT_MAX_CANDIDATES = 10;
+
+/**
+ * Search the vector index for blueprints matching `prompt` within
+ * `scope`. See the module docstring for the confidence-band pipeline
+ * and encoding contract.
+ */
+export async function ragSearch(
+  deps: RagSearchDeps,
+  input: RagSearchInput,
+): Promise<RagSearchResult> {
+  const topK = input.maxCandidates ?? DEFAULT_MAX_CANDIDATES;
+
+  // Stage 1: embed the query text
+  const embedStart = Date.now();
+  const queryEmbedding = await deps.embedding.embed(input.prompt);
+  const embeddingLatencyMs = Date.now() - embedStart;
+
+  // Stage 2: nearest-neighbor query
+  const searchStart = Date.now();
+  const results = await deps.vectors.query(input.scope, queryEmbedding, topK);
+  const searchLatencyMs = Date.now() - searchStart;
+
+  // Filter + sort: private (registered UIs) always beats shared (generated)
+  // at the same score level; then descending score.
+  const candidates = results
+    .filter((r) => r.score >= RETRIEVAL_MIN_SCORE)
+    .sort((a, b) => {
+      const aPrivate = readPoolSource(a.metadata) === 'private' ? 1 : 0;
+      const bPrivate = readPoolSource(b.metadata) === 'private' ? 1 : 0;
+      if (aPrivate !== bPrivate) return bPrivate - aPrivate;
+      return b.score - a.score;
+    });
+
+  if (candidates.length === 0) {
+    return { options: [], embeddingLatencyMs, searchLatencyMs };
+  }
+
+  const seenContracts = new Set<string>();
+  const options: NegotiatorOption[] = [];
+
+  for (const match of candidates) {
+    const option = buildOption(match);
+    if (!option) continue;
+    if (seenContracts.has(option.contractKey)) continue;
+    seenContracts.add(option.contractKey);
+    options.push(option.value);
+  }
+
+  return { options, embeddingLatencyMs, searchLatencyMs };
+}
+
+/**
+ * Project a public {@link VectorSearchResult} hit into a
+ * {@link NegotiatorOption}, together with the dedup key used to
+ * collapse hits that describe the same semantic contract.
+ */
+function buildOption(
+  match: VectorSearchResult,
+): { value: NegotiatorOption; contractKey: string } | undefined {
+  const isExact = match.score >= HIGH_CONFIDENCE_THRESHOLD;
+  const verdict = isExact ? 'exact' : 'partial';
+
+  const blueprintHash = match.key;
+  // Registered (private) blueprints already carry a `p_` prefix in
+  // their hash; generated pool entries do not — prefix them as `c_`
+  // to match the legacy option ID format that downstream consumers
+  // (decision prompt, cache layer) have been reading since V2.
+  const blueprintId = blueprintHash.startsWith('p_')
+    ? blueprintHash
+    : `c_${blueprintHash}`;
+
+  const prompt = readString(match.metadata.prompt, '');
+  const intent = readString(match.metadata.intent, '');
+  const category = readString(match.metadata.category, '');
+  const contractHash = readString(match.metadata.contractHash, '');
+  const poolSource = readPoolSource(match.metadata);
+  const featured = Boolean(match.metadata.featured);
+  const props = readProps(match.metadata.props);
+
+  const contract = buildContract({ prompt, intent, category, props });
+
+  // Dedup: prefer matching on semantic intent; fall back to prop
+  // signature so two blueprints with identical intents but different
+  // prop shapes don't collapse together.
+  const contractKey =
+    intent !== ''
+      ? intent
+      : JSON.stringify(Object.keys(contract.propsSpec?.properties ?? {}).sort());
+
+  const option: NegotiatorOption = {
+    id: `rag_${blueprintId.slice(-8)}`,
+    type: 'blueprint',
+    blueprintId,
+    pattern: category,
+    description: `${prompt} (similarity: ${Math.round(match.score * 100)}%, ${verdict})`,
+    pros: [
+      isExact
+        ? 'Exact blueprint match — instant render'
+        : 'Semantically matched to your request',
+      ...(featured ? ['Featured blueprint — curated quality'] : []),
+    ],
+    cons: [
+      ...(isExact ? [] : ['Partial match — may need adjustments']),
+      ...(!isExact ? ['Fixed layout — limited customization'] : []),
+    ],
+    renderTime: 'instant',
+    contract,
+    ...(contractHash !== '' ? { contractHash } : {}),
+    ...(poolSource !== undefined ? { poolSource } : {}),
+  };
+
+  return { value: option, contractKey };
+}
+
+/** Prop schema shape as encoded by `embeddingStorageToVectorStore`. */
+interface PropSpec {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  example?: unknown;
+}
+
+function buildContract(args: {
+  prompt: string;
+  intent: string;
+  category: string;
+  props: PropSpec[];
+}): DataContract {
+  // `intent` is not a contract field. The `prompt` and `intent` fields
+  // stay on the args because callers still use them for RAG keys +
+  // dedup; the returned contract carries structural shape only.
+  const { props } = args;
+  return {
+    propsSpec: {
+      properties: Object.fromEntries(
+        props.map((p) => [
+          p.name,
+          {
+            description: p.description,
+            schema: { type: inferJsonSchemaType(p.type) },
+            required: p.required,
+            ...(p.example !== undefined
+              ? { example: p.example as JsonValue }
+              : {}),
+          },
+        ]),
+      ),
+    },
+  };
+}
+
+function readString(
+  value: string | number | boolean | null | undefined,
+  fallback: string,
+): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function readPoolSource(
+  metadata: Record<string, string | number | boolean | null>,
+): 'shared' | 'private' | undefined {
+  const v = metadata.poolSource;
+  return v === 'shared' || v === 'private' ? v : undefined;
+}
+
+function readProps(
+  value: string | number | boolean | null | undefined,
+): PropSpec[] {
+  if (typeof value !== 'string' || value.length === 0) return [];
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(isPropSpec);
+  } catch {
+    return [];
+  }
+}
+
+function isPropSpec(value: unknown): value is PropSpec {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.name === 'string' &&
+    typeof v.type === 'string' &&
+    typeof v.required === 'boolean' &&
+    typeof v.description === 'string'
+  );
+}