@nuxtagentic/prompt 0.0.0-stage → 0.1.1

package/runtime/server/utils/jev-dispatch.ts

@@ -0,0 +1,156 @@
+import { createError } from 'h3'
+import { choice, type EntryType, type Questions } from '@typesafe-ai/sdk'
+import type { AgentToolCall, AgentToolName, ToolSpec } from '../../shared/agent-tools'
+import type { ModelView } from '@nuxtagentic/data/runtime/shared/model-views'
+import type { PromptConfig } from '../../shared/prompt-config'
+import { compileModelQuery, type ModelQueryPlan } from './model-query'
+import { prepareCandidates } from './prompt-candidates'
+import { prepareToolArguments } from './jev-tool-plan'
+import { createAnswerReader, summarizeDecisions, NO_CHOICE } from './jev-answers'
+import type { JevInference } from './jev-inference'
+
+interface DispatcherConfig {
+  tools: Record<AgentToolName, ToolSpec>
+  views: readonly ModelView[]
+  query: PromptConfig
+}
+interface PromptContext {
+  model?: string
+  resource?: string
+}
+const ROUTE = '__tool__'
+const escapeRegex = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+export function createDispatcher({ tools, views, query }: DispatcherConfig) {
+  const models = views.map((view) => ({
+    ...compileModelQuery(view, query),
+    route: `model:${view.id}`,
+    mention: new RegExp(
+      `\\b(?:${[view.id, view.model, ...view.aliases].map(escapeRegex).join('|')})\\b`,
+      'i',
+    ),
+  }))
+  const modelRoutes = new Map(models.map((model) => [model.route, model]))
+  const modelIds = new Map(models.map((model) => [model.view.id, model]))
+  const toolEntries = Object.entries(tools).filter(([name]) => name !== 'query_models') as [
+    AgentToolName,
+    ToolSpec,
+  ][]
+  const routeQuestion = choice(
+    'What is the request asking the app to do? Recognize SQL, shorthand, collection names, synonyms and obvious spelling mistakes. Choose a model only for a read-only request about that table.',
+    {
+      ...Object.fromEntries(toolEntries.map(([name, tool]) => [name, tool.description])),
+      ...Object.fromEntries(
+        models.map((model) => [
+          model.route,
+          {
+            action: tools.query_models?.description ?? 'Search this collection',
+            collection: model.view.label,
+            aliases: [...model.view.aliases],
+          },
+        ]),
+      ),
+      [NO_CHOICE]:
+        'A greeting, a question about the app, or anything outside available capabilities',
+    },
+  )
+
+  return async function dispatchPrompt(
+    prompt: string,
+    infer: JevInference,
+    input: PromptContext = {},
+  ): Promise<AgentToolCall> {
+    const context = prepareCandidates(prompt, query)
+    const model = input.model ?? query.model
+    const state = (schemas: Record<string, EntryType>): EntryType => ({
+      request: prompt,
+      interpretationRules: query.instructions,
+      referenceDate: context.now.toISOString(),
+      models: schemas,
+    })
+    if (input.resource) {
+      const target = modelIds.get(input.resource)
+      if (!target) {
+        throw createError({ statusCode: 422, statusMessage: 'Choose an enabled model to search.' })
+      }
+      const plan = target.prepare(context)
+      return plan.decode(
+        await infer(
+          { model, state: state({ [target.view.id]: plan.schema }), questions: plan.questions },
+          `model:${target.view.id}`,
+        ),
+      )
+    }
+
+    const toolPlans = new Map(
+      toolEntries.map(([name, spec]) => [name, prepareToolArguments(name, spec, context.spans)]),
+    )
+    let questions: Questions = { [ROUTE]: routeQuestion }
+    for (const plan of toolPlans.values()) {
+      Object.assign(questions, plan.questions)
+    }
+    const inline = new Map<string, ModelQueryPlan>()
+    let schemas: Record<string, EntryType> = {}
+    const mentioned = models.filter((entry) => entry.mention.test(prompt))
+    const shortlist = (mentioned.length ? mentioned : models).slice(
+      0,
+      query.routing.maxInlineModels,
+    )
+    for (const entry of shortlist) {
+      const plan = entry.prepare(context, `${entry.route}:`)
+      const nextQuestions = { ...questions, ...plan.questions }
+      const nextSchemas = { ...schemas, [entry.view.id]: plan.schema }
+      if (
+        Object.keys(nextQuestions).length > query.routing.maxInlineQuestions ||
+        new TextEncoder().encode(
+          JSON.stringify({ model, state: state(nextSchemas), questions: nextQuestions }),
+        ).byteLength > query.routing.maxInlineBytes
+      ) {
+        continue
+      }
+      questions = nextQuestions
+      schemas = nextSchemas
+      inline.set(entry.route, plan)
+    }
+    const result = await infer(
+      {
+        model,
+        questions,
+        state: inline.size ? state(schemas) : { request: prompt },
+      },
+      inline.size ? 'route-and-extract' : 'route',
+    )
+    const reader = createAnswerReader(result)
+    const route = reader.pick(ROUTE)
+    const target = modelRoutes.get(route)
+    if (target) {
+      const plan = inline.get(route)
+      if (plan) {
+        return plan.decode(result, reader.decisions)
+      }
+      const selected = target.prepare(context)
+      const extraction = await infer(
+        {
+          model: result.model,
+          state: state({ [target.view.id]: selected.schema }),
+          questions: selected.questions,
+        },
+        `model:${target.view.id}`,
+      )
+      return selected.decode(extraction, reader.decisions)
+    }
+    const toolPlan = toolPlans.get(route as AgentToolName)
+    const argumentsRead = toolPlan?.decode(reader) ?? {}
+    return {
+      tool: toolPlan ? (route as AgentToolName) : null,
+      args: Object.fromEntries(
+        Object.entries(argumentsRead).flatMap(([arg, value]) =>
+          value.omitted ? [] : [[arg, value.value!]],
+        ),
+      ),
+      arguments: reader.decisions,
+      ...summarizeDecisions(reader.decisions),
+      model: result.model,
+    }
+  }
+}

package/runtime/server/utils/jev-inference.ts

@@ -0,0 +1,87 @@
+import { createError, type H3Event } from 'h3'
+import type { SystemOneRequest } from '@typesafe-ai/sdk'
+
+import type { InferencePolicy } from '../../shared/prompt-config'
+import type { JevResult } from './jev-answers'
+import { useDecisionProvider } from './decision-provider'
+
+export type JevInference = (request: SystemOneRequest, stage: string) => Promise<JevResult>
+
+export function useJevInference(event: H3Event, policy: InferencePolicy, logMetrics: boolean) {
+  const controller = new AbortController()
+  const requestStarted = performance.now()
+  let attempts = 0
+  const provider = useDecisionProvider(event, policy, () => {
+    attempts++
+  })
+  const timer = setTimeout(
+    () => controller.abort(new DOMException('Inference deadline exceeded', 'TimeoutError')),
+    policy.deadlineMs,
+  )
+  const abort = () => controller.abort()
+  const disconnect = () => {
+    if (!event.node.res.writableEnded) {
+      abort()
+    }
+  }
+  const requestSignal = event.web?.request?.signal
+  requestSignal?.addEventListener('abort', abort, { once: true })
+  event.node.res.once('close', disconnect)
+  if (requestSignal?.aborted || event.node.req.aborted) {
+    abort()
+  }
+
+  const infer: JevInference = async (request, stage) => {
+    const started = performance.now()
+    const previousAttempts = attempts
+    let usage: JevResult['usage'] | undefined
+    let model = provider.id === 'openAI' ? provider.model : (request.model ?? provider.model)
+    let outcome = 'success'
+    try {
+      const result = await provider.infer(request, { signal: controller.signal })
+      usage = result.usage
+      model = result.model
+      return result
+    } catch (cause) {
+      outcome = 'error'
+      if (controller.signal.aborted) {
+        const timedOut = controller.signal.reason?.name === 'TimeoutError'
+        throw createError({
+          statusCode: timedOut ? 504 : 499,
+          statusMessage: timedOut
+            ? `${provider.name} took too long. Try a simpler request or try again.`
+            : 'The request was cancelled.',
+        })
+      }
+      throw cause
+    } finally {
+      if (logMetrics) {
+        console.info('[decisions]', {
+          provider: provider.id,
+          stage,
+          model,
+          outcome,
+          elapsedMs: Math.round(performance.now() - started),
+          requestElapsedMs: Math.round(performance.now() - requestStarted),
+          retries: Math.max(0, attempts - previousAttempts - 1),
+          questions: Object.keys(request.questions).length,
+          options: Object.values(request.questions).reduce(
+            (count, question) =>
+              count + (question.type === 'choice' ? Object.keys(question.criteria).length : 0),
+            0,
+          ),
+          payloadBytes: new TextEncoder().encode(JSON.stringify(request)).byteLength,
+          ...usage,
+        })
+      }
+    }
+  }
+  return {
+    infer,
+    close() {
+      clearTimeout(timer)
+      requestSignal?.removeEventListener('abort', abort)
+      event.node.res.off('close', disconnect)
+    },
+  }
+}

package/runtime/server/utils/jev-tool-plan.ts

@@ -0,0 +1,64 @@
+import { choice, noul, type Questions } from '@typesafe-ai/sdk'
+import type { ToolSpec, ToolCallArgument } from '../../shared/agent-tools'
+import {
+  NOT_MENTIONED,
+  VALUE_UNAVAILABLE,
+  throwUnrepresentableQuery,
+  type createAnswerReader,
+} from './jev-answers'
+
+type AnswerReader = ReturnType<typeof createAnswerReader>
+
+export function prepareToolArguments(tool: string, spec: ToolSpec, candidates: string[]) {
+  const questions: Questions = {}
+  const readers: Record<string, (reader: AnswerReader) => ToolCallArgument> = {}
+
+  for (const [arg, argument] of Object.entries(spec.args)) {
+    const key = `${tool}.${arg}`
+    if (argument.kind === 'flag') {
+      questions[key] = noul(argument.question)
+      readers[arg] = (reader) => {
+        reader.flag(key)
+        const decision = reader.decisions[key]!
+        decision.omitted = false
+        return decision
+      }
+      continue
+    }
+
+    const options =
+      argument.kind === 'span'
+        ? Object.fromEntries(candidates.map((value, index) => [`v${index}`, value]))
+        : argument.options
+    questions[key] = choice(
+      {
+        question: argument.question,
+        ...(argument.stated ? { presence: argument.stated } : {}),
+      },
+      {
+        ...options,
+        ...(argument.stated ? { [NOT_MENTIONED]: 'Not mentioned in the request' } : {}),
+        ...(argument.kind === 'span'
+          ? { [VALUE_UNAVAILABLE]: 'Mentioned, but the complete value is not a candidate' }
+          : {}),
+      },
+    )
+    readers[arg] = (reader) => {
+      const picked = reader.pick(key)
+      if (picked === VALUE_UNAVAILABLE) {
+        return throwUnrepresentableQuery()
+      }
+      const decision = reader.decisions[key]!
+      if (!decision.omitted && argument.kind === 'span') {
+        decision.value = candidates[Number(picked.slice(1))]!
+      }
+      return decision
+    }
+  }
+
+  return {
+    questions,
+    decode: (reader: AnswerReader) =>
+      Object.fromEntries(Object.entries(readers).map(([arg, read]) => [arg, read(reader)])),
+  }
+}

package/runtime/server/utils/model-query-condition.ts

@@ -0,0 +1,59 @@
+import type { ModelView } from '@nuxtagentic/data/runtime/shared/model-views'
+import {
+  createDatePeriodCondition,
+  type Comparison,
+  type Scalar,
+  type Where,
+} from '@nuxtagentic/data/runtime/shared/resource-query'
+import { throwUnrepresentableQuery } from './jev-answers'
+import type { ValueCandidate } from './prompt-candidates'
+
+export function combineConditions(nodes: Where[], logic: 'and' | 'or'): Where | null {
+  return nodes.reduce<Where | null>(
+    (left, right) => (left ? { type: logic, left, right } : right),
+    null,
+  )
+}
+
+export function createModelCondition(
+  view: ModelView,
+  field: string,
+  operator: string,
+  candidate: ValueCandidate,
+): Where {
+  const value = candidate.value
+  const compare = (comparison: Comparison, value: Scalar): Where => ({
+    type: 'cond',
+    column: field,
+    op: 'cmp',
+    comparison,
+    value,
+  })
+  if (operator === 'period' || operator === 'after_period') {
+    if (!candidate.end || typeof value !== 'string') {
+      return throwUnrepresentableQuery()
+    }
+    return createDatePeriodCondition(field, operator === 'period' ? '=' : '>', value, candidate.end)
+  }
+  if (['=', '!=', '>', '>=', '<', '<='].includes(operator)) {
+    if (operator === '=' && value === false && view.query?.nullAsFalse?.includes(field)) {
+      return { type: 'or', left: compare('=', false), right: compare('=', null) }
+    }
+    return candidate.end && typeof value === 'string'
+      ? createDatePeriodCondition(field, operator as Comparison, value, candidate.end)
+      : compare(operator as Comparison, value)
+  }
+  if (typeof value !== 'string') {
+    return throwUnrepresentableQuery()
+  }
+  const prefix = operator === 'starts_with' ? '' : '%'
+  const suffix = operator === 'ends_with' ? '' : '%'
+  const pattern = `${prefix}${value}${suffix}`
+  return {
+    type: 'cond',
+    column: field,
+    op: 'like',
+    isNegated: operator === 'not_contains',
+    value: pattern,
+  }
+}

package/runtime/server/utils/model-query.ts

@@ -0,0 +1,275 @@
+import { choice, noul, type EntryType, type Questions } from '@typesafe-ai/sdk'
+import type { ModelField, ModelView } from '@nuxtagentic/data/runtime/shared/model-views'
+import type { PromptConfig } from '../../shared/prompt-config'
+import type { AgentToolCall } from '../../shared/agent-tools'
+import {
+  toResourceTableQuery,
+  type ResourceQuery,
+  type Where,
+} from '@nuxtagentic/data/runtime/shared/resource-query'
+import {
+  createAnswerReader,
+  summarizeDecisions,
+  throwUnrepresentableQuery,
+  NO_CHOICE,
+  NOT_MENTIONED,
+  VALUE_UNAVAILABLE,
+  type Decisions,
+  type JevResult,
+} from './jev-answers'
+import {
+  findFieldCandidates,
+  type PromptCandidates,
+  type ValueCandidate,
+} from './prompt-candidates'
+import { combineConditions, createModelCondition } from './model-query-condition'
+
+export interface ModelQueryPlan {
+  schema: EntryType
+  questions: Questions
+  decode: (result: JevResult, routing?: Decisions) => AgentToolCall
+}
+
+const logic = { and: 'All constraints must hold', or: 'Any constraint may hold' }
+
+function fieldOperators(field: ModelField) {
+  const operators: Record<string, string> = {
+    '=': 'equals / is / implicit equality / one of several allowed values',
+    '!=': 'does not equal / is not / excluding a value',
+  }
+  if (['number', 'float', 'relation', 'date', 'datetime'].includes(field.kind)) {
+    Object.assign(operators, {
+      '>': 'greater than / after',
+      '>=': 'at least / since',
+      '<': 'less than / before',
+      '<=': 'at most / on or before',
+    })
+  }
+  if (field.kind === 'date' || field.kind === 'datetime') {
+    Object.assign(operators, {
+      period: 'during a named period or within the last/past N units',
+      after_period: 'after a named period ends',
+    })
+  }
+  if (['text', 'textarea', 'email', 'url'].includes(field.kind)) {
+    Object.assign(operators, {
+      contains: 'contains text',
+      not_contains: 'does not contain text',
+      starts_with: 'starts with text',
+      ends_with: 'ends with text',
+    })
+  }
+  return operators
+}
+
+export function compileModelQuery(view: ModelView, config: PromptConfig) {
+  const fieldMap = new Map(view.fields.map((field) => [field.key, field]))
+  const constraintLimit = (key: string) =>
+    view.prompt?.maxConstraints?.[key] ?? config.maxConstraintsPerField
+  const fields = view.filter.map((key) => {
+    const field = fieldMap.get(key)!
+    return { field, operators: fieldOperators(field), limit: constraintLimit(key) }
+  })
+  const schema: EntryType = {
+    name: view.model,
+    label: view.label,
+    aliases: [...view.aliases],
+    instructions: view.prompt?.instructions ?? '',
+    filter: [...view.filter],
+    search: [...view.search],
+    columns: [...view.columns],
+    sort: [...view.sort],
+    fields: view.fields.map((field) => ({
+      key: field.key,
+      label: field.label,
+      kind: field.kind,
+      options: [...(field.options ?? [])],
+      meaning: view.prompt?.fields?.[field.key] ?? '',
+      maxConstraints: constraintLimit(field.key),
+    })),
+  }
+  const sortOptions = Object.fromEntries(
+    view.sort.map((key) => [key, fieldMap.get(key)?.label ?? key]),
+  )
+
+  function prepare(context: PromptCandidates, prefix = ''): ModelQueryPlan {
+    const candidates: Record<string, ValueCandidate[]> = {}
+    const instructions = (question: string, field?: string, constraint?: number): EntryType => ({
+      question,
+      model: view.id,
+      ...(field ? { field } : {}),
+      ...(constraint ? { constraint } : {}),
+    })
+    const questions: Questions = {
+      supported: noul(
+        instructions(
+          'Can the WHOLE read-only request be represented by this model, its allowed fields and configured per-field constraint limits, AND/OR between fields and AND/OR within each field? Use interpretation rules and field meanings. Shorthand, synonyms, obvious typos and generic text search are supported. Modifications, unavailable properties, unsupported calculations and complex mixed grouping are not. Never ignore an unsupported part.',
+        ),
+      ),
+      logic: choice(instructions('How are constraints on different properties combined?'), logic),
+      search: choice(
+        instructions(
+          'Which candidate is a general search over configured search fields? Use none for explicit named-field filters or no search.',
+        ),
+        {
+          ...Object.fromEntries(context.text.map((value, index) => [`s${index}`, value])),
+          [NO_CHOICE]: 'No general search requested',
+          [VALUE_UNAVAILABLE]: 'A general search is requested but its complete text is unavailable',
+        },
+      ),
+      sort: choice(
+        instructions(
+          'Which property is explicitly requested for ordering? Newest/oldest means createdAt unless another date is named.',
+        ),
+        {
+          ...sortOptions,
+          [NO_CHOICE]: 'No ordering requested',
+          [VALUE_UNAVAILABLE]: 'Ordering is requested on an unavailable property',
+        },
+      ),
+      direction: choice(instructions('Which order direction is requested?'), {
+        asc: 'ascending / A-Z / oldest / smallest',
+        desc: 'descending / newest / largest',
+      }),
+      limit: choice(
+        instructions(
+          'Which number is explicitly the maximum result count? Dates and filter thresholds are not result limits.',
+        ),
+        {
+          ...Object.fromEntries(context.limits.map((value) => [value, value])),
+          [NO_CHOICE]: 'No result limit requested',
+          [VALUE_UNAVAILABLE]: 'A result limit is requested but its number is unavailable',
+        },
+      ),
+    }
+    for (const key of view.columns) {
+      questions[`column.${key}`] = noul(
+        instructions(
+          'Is this column explicitly requested for display? A filter or sort mention does not count.',
+          key,
+        ),
+      )
+    }
+    for (const { field, operators, limit } of fields) {
+      const values = findFieldCandidates(
+        context,
+        field,
+        view.prompt?.values?.[field.key],
+        view.query?.units?.[field.key],
+      )
+      candidates[field.key] = values
+      const options = {
+        ...Object.fromEntries(values.map((candidate, index) => [`v${index}`, candidate.label])),
+        [NOT_MENTIONED]: 'This numbered constraint is not mentioned',
+        [VALUE_UNAVAILABLE]: 'This constraint is mentioned but its complete value is unavailable',
+      }
+      questions[`logic.${field.key}`] = choice(
+        instructions(
+          'How are multiple constraints on this field combined? Ranges and exclusions use AND; one-of alternatives use OR.',
+          field.key,
+        ),
+        logic,
+      )
+      for (let slot = 0; slot < limit; slot++) {
+        const key = `${field.key}.${slot}`
+        questions[`operator.${key}`] = choice(
+          instructions(
+            'What is the operator of this distinct constraint, numbered by appearance? Resolve negation into the operator or boolean value, never both. BETWEEN uses >= then <=.',
+            field.key,
+            slot + 1,
+          ),
+          operators,
+        )
+        questions[`value.${key}`] = choice(
+          instructions(
+            'Select the complete value of this numbered constraint using interpretation rules and field meanings. Include multi-word names. Choose absent if this constraint is not mentioned, or unavailable if mentioned but its complete value is not a candidate. For negated boolean adjectives select the intended truth value with equality.',
+            field.key,
+            slot + 1,
+          ),
+          options,
+        )
+      }
+    }
+
+    function decode(result: JevResult, routing: Decisions = {}): AgentToolCall {
+      const { pick, flag, decisions } = createAnswerReader(result, routing, prefix)
+      if (!flag('supported')) {
+        return throwUnrepresentableQuery()
+      }
+
+      const fieldNodes: Where[] = []
+      for (const { field, limit } of fields) {
+        const nodes: Where[] = []
+        let absent = false
+        for (let slot = 0; slot < limit; slot++) {
+          const key = `${field.key}.${slot}`
+          const valueKey = pick(`value.${key}`)
+          if (valueKey === NOT_MENTIONED) {
+            absent = true
+            continue
+          }
+          if (absent || valueKey === VALUE_UNAVAILABLE) {
+            return throwUnrepresentableQuery()
+          }
+          const candidate = candidates[field.key]![Number(valueKey.slice(1))]
+          if (!candidate) {
+            return throwUnrepresentableQuery()
+          }
+          nodes.push(createModelCondition(view, field.key, pick(`operator.${key}`), candidate))
+        }
+        if (nodes.length) {
+          const logic = nodes.length > 1 ? (pick(`logic.${field.key}`) as 'and' | 'or') : 'and'
+          fieldNodes.push(combineConditions(nodes, logic)!)
+        }
+      }
+      const searchKey = pick('search')
+      if (searchKey !== NO_CHOICE) {
+        const value = context.text[Number(searchKey.slice(1))]
+        if (!value || !view.search.length || searchKey === VALUE_UNAVAILABLE) {
+          return throwUnrepresentableQuery()
+        }
+        fieldNodes.push({ type: 'search', value })
+      }
+      const columns = view.columns.filter((key) => flag(`column.${key}`))
+      const sort = pick('sort')
+      const limit = pick('limit')
+      if (sort === VALUE_UNAVAILABLE || limit === VALUE_UNAVAILABLE) {
+        return throwUnrepresentableQuery()
+      }
+
+      const query: ResourceQuery = {
+        columns: columns.length ? columns : null,
+        where: combineConditions(
+          fieldNodes,
+          fieldNodes.length > 1 ? (pick('logic') as 'and' | 'or') : 'and',
+        ),
+        order:
+          sort === NO_CHOICE
+            ? null
+            : { column: sort, direction: pick('direction') === 'asc' ? 1 : -1 },
+        limit: limit === NO_CHOICE ? null : Number(limit),
+      }
+      try {
+        toResourceTableQuery(query, view)
+      } catch {
+        return throwUnrepresentableQuery()
+      }
+      return {
+        tool: 'query_models',
+        args: {},
+        arguments: decisions,
+        ...summarizeDecisions(decisions),
+        model: result.model,
+        resource: { id: view.id, query },
+      }
+    }
+    return {
+      schema,
+      questions: Object.fromEntries(
+        Object.entries(questions).map(([key, question]) => [prefix + key, question]),
+      ),
+      decode,
+    }
+  }
+  return { view, prepare }
+}