@viveka10/cap-ai-token-optimizer 0.0.0-stage → 0.1.0

package/lib/pipeline/steps/dedupe.js

@@ -0,0 +1,103 @@
+'use strict'
+/**
+ * dedupe: remove exact duplicate instructions within one request.
+ *  - messages: a system message identical to an earlier one is dropped; a user message
+ *    identical to the user message right before it is dropped.
+ *  - paragraphs: a paragraph (blank-line separated, at least `minParagraphLength` chars)
+ *    that repeats a system paragraph is removed from later system and user messages;
+ *    in user messages, an older copy of a paragraph that is repeated in a later user
+ *    message is removed (the latest copy stays where it is).
+ * Messages with code fences, tool and assistant messages are never edited, and a message
+ * is never emptied.
+ */
+const { isLocked, isSystem } = require('../messages')
+const { stableStringify } = require('../../util/hash')
+
+const DEFAULTS = { messages: true, paragraphs: true, minParagraphLength: 30 }
+const PARA_SPLIT = /\n[ \t]*\n/
+
+/**
+ * @param {import('../index').StepInput} input
+ * @param {object} options
+ */
+function dedupe ({ messages }, options) {
+  const opts = { ...DEFAULTS, ...options }
+  const notes = []
+  let out = messages
+  if (opts.messages) {
+    const before = out.length
+    out = dedupeMessages(out)
+    if (out.length < before) notes.push(`${before - out.length} duplicate message(s) removed`)
+  }
+  if (opts.paragraphs) {
+    const { messages: next, removed } = dedupeParagraphs(out, opts.minParagraphLength)
+    out = next
+    if (removed) notes.push(`${removed} duplicate paragraph(s) removed`)
+  }
+  return { messages: out, notes }
+}
+
+function dedupeMessages (messages) {
+  const seenSystem = new Set()
+  const out = []
+  for (const m of messages) {
+    const key = stableStringify({ role: m?.role, content: m?.content })
+    if (isSystem(m)) {
+      if (seenSystem.has(key) && !isLocked(m)) continue
+      seenSystem.add(key)
+    } else if (m?.role === 'user' && !isLocked(m)) {
+      const prev = out.at(-1)
+      if (prev?.role === 'user' && stableStringify({ role: prev.role, content: prev.content }) === key) continue
+    }
+    out.push(m)
+  }
+  return out
+}
+
+const editable = (m) => typeof m?.content === 'string' && !isLocked(m) && !/^[ \t]*(```|~~~)/m.test(m.content)
+const paragraphsOf = (text) => text.split(PARA_SPLIT)
+const norm = (p) => p.trim()
+
+function dedupeParagraphs (messages, minLength) {
+  const long = (p) => norm(p).length >= minLength
+  // paragraphs that appear in a system message, and in which user message a paragraph last appears
+  const systemParas = new Set()
+  const lastUserIndex = new Map()
+  messages.forEach((m, i) => {
+    if (typeof m?.content !== 'string') return
+    for (const p of paragraphsOf(m.content)) {
+      if (!long(p)) continue
+      if (isSystem(m)) systemParas.add(norm(p))
+      else if (m.role === 'user') lastUserIndex.set(norm(p), i)
+    }
+  })
+
+  let removed = 0
+  const seenSystem = new Set()
+  const out = messages.map((m, i) => {
+    if (!editable(m) || !(isSystem(m) || m.role === 'user')) {
+      if (isSystem(m) && typeof m?.content === 'string') for (const p of paragraphsOf(m.content)) if (long(p)) seenSystem.add(norm(p))
+      return m
+    }
+    const seenHere = new Set()
+    const kept = []
+    let dropped = 0
+    for (const p of paragraphsOf(m.content)) {
+      const key = norm(p)
+      const drop = long(p) && (
+        seenHere.has(key) ||
+        (isSystem(m) ? seenSystem.has(key) : (systemParas.has(key) || lastUserIndex.get(key) > i))
+      )
+      if (long(p)) seenHere.add(key)
+      if (drop) dropped++
+      else kept.push(p)
+    }
+    if (isSystem(m)) for (const p of kept) if (long(p)) seenSystem.add(norm(p))
+    if (!dropped || !kept.some(p => p.trim())) return m
+    removed += dropped
+    return { ...m, content: kept.join('\n\n') }
+  })
+  return { messages: out, removed }
+}
+
+module.exports = { dedupe, DEFAULTS }

package/lib/pipeline/steps/history.js

@@ -0,0 +1,63 @@
+'use strict'
+/**
+ * history: keep system messages plus the last N conversation turns.
+ *
+ * A turn starts at a user message and includes the assistant and tool messages that follow,
+ * so tool calls are never separated from their results. Locked (orchestration template)
+ * messages are always kept.
+ *
+ * Pluggable: `strategy` may be a function `({ messages, maxTurns }) => messages`.
+ * Optional `summarizer`: `async ({ dropped, kept }) => message | null`; the returned
+ * message is inserted after the leading system messages. No summarizer is built in.
+ */
+const { isLocked, isSystem, ORIGIN } = require('../messages')
+
+const DEFAULTS = { maxTurns: 10, strategy: 'sliding-window', summarizer: null }
+
+/**
+ * Default strategy.
+ * @param {{ messages: object[], maxTurns: number }} input
+ * @returns {object[]}
+ */
+function slidingWindow ({ messages, maxTurns }) {
+  // index where each turn starts
+  const starts = []
+  messages.forEach((m, i) => { if (m?.role === 'user' && !isSystem(m)) starts.push(i) })
+  if (starts.length <= maxTurns) return messages
+  const cut = starts[starts.length - maxTurns]
+  return messages.filter((m, i) => i >= cut || isSystem(m) || isLocked(m))
+}
+
+const STRATEGIES = { 'sliding-window': slidingWindow }
+
+/**
+ * @param {import('../index').StepInput} input
+ * @param {object} options
+ */
+async function history ({ messages, model }, options) {
+  const opts = { ...DEFAULTS, ...options }
+  if (!(opts.maxTurns > 0)) return { messages, notes: [] }
+  const strategy = typeof opts.strategy === 'function' ? opts.strategy : STRATEGIES[opts.strategy]
+  if (!strategy) throw new Error(`Unknown history strategy "${opts.strategy}"`)
+
+  const kept = strategy({ messages, maxTurns: opts.maxTurns, model })
+  if (!Array.isArray(kept)) throw new Error('history strategy must return an array of messages')
+  if (kept.length === messages.length) return { messages, notes: [] }
+  const keptSet = new Set(kept)
+  const dropped = messages.filter(m => !keptSet.has(m))
+  if (dropped.some(isLocked)) throw new Error('history strategy dropped a template message')
+  const notes = [`${dropped.length} message(s) outside the last ${opts.maxTurns} turns removed`]
+
+  if (typeof opts.summarizer === 'function') {
+    const summary = await opts.summarizer({ dropped, kept, model })
+    if (summary) {
+      const at = kept.findIndex(m => !isSystem(m))
+      const tagged = { ...summary, [ORIGIN]: dropped[0]?.[ORIGIN] }
+      kept.splice(at < 0 ? kept.length : at, 0, tagged)
+      notes.push('summary of removed turns inserted')
+    }
+  }
+  return { messages: kept, notes }
+}
+
+module.exports = { history, slidingWindow, STRATEGIES, DEFAULTS }

package/lib/pipeline/steps/normalize.js

@@ -0,0 +1,88 @@
+'use strict'
+/**
+ * normalize: trim, collapse repeated spaces and blank lines, minify JSON blocks.
+ * Fenced code blocks, inline code and indented (code-like) lines keep their whitespace.
+ * JSON is minified on the text itself, so numbers, key order and duplicate keys are kept.
+ */
+const { splitFences, joinSegments, tryMinifyJson, splitJsonBlocks } = require('../text')
+const { mapText, isLocked } = require('../messages')
+
+const DEFAULTS = { minifyJson: true, minifyJsonFences: true, collapseSpaces: true }
+
+/**
+ * @param {import('../index').StepInput} input
+ * @param {object} options
+ */
+function normalize ({ messages }, options) {
+  const opts = { ...DEFAULTS, ...options }
+  let changed = 0
+  const out = messages.map(m => {
+    let next = mapText(m, text => normalizeText(text, opts))
+    if (opts.minifyJson && Array.isArray(next?.tool_calls) && !isLocked(next)) {
+      next = minifyToolCallArguments(next)
+    }
+    if (next !== m) changed++
+    return next
+  })
+  return { messages: out, notes: changed ? [`${changed} message(s) normalized`] : [] }
+}
+
+function minifyToolCallArguments (m) {
+  let changed = false
+  const toolCalls = m.tool_calls.map(tc => {
+    const args = tc?.function?.arguments
+    if (typeof args !== 'string') return tc
+    const min = tryMinifyJson(args)
+    if (min === null || min === args) return tc
+    changed = true
+    return { ...tc, function: { ...tc.function, arguments: min } }
+  })
+  return changed ? { ...m, tool_calls: toolCalls } : m
+}
+
+/**
+ * @param {string} text
+ * @param {typeof DEFAULTS} opts
+ */
+function normalizeText (text, opts = DEFAULTS) {
+  const all = splitFences(text)
+  const segments = all.map((seg, i) => {
+    if (seg.type === 'code') return opts.minifyJsonFences && /^json\b/i.test(seg.info ?? '') ? minifyJsonFence(seg) : seg
+    const parts = splitJsonBlocks(seg.text).map(p => {
+      if (p.type === 'json') return opts.minifyJson ? tryMinifyJson(p.text) : p.text
+      return normalizeProse(p.text, opts)
+    })
+    // blank lines are collapsed in prose only; code keeps its blank lines.
+    // Next to a fence, the newline added when segments are joined counts too.
+    let prose = parts.join('').replace(/\n{3,}/g, '\n\n')
+    if (i > 0) prose = prose.replace(/^\n{2,}/, '\n')
+    if (i < all.length - 1) prose = prose.replace(/\n{2,}$/, '\n')
+    return { ...seg, text: prose }
+  })
+  return joinSegments(segments).trim()
+}
+
+function minifyJsonFence (seg) {
+  const lines = seg.text.split('\n')
+  if (lines.length < 3) return seg
+  const body = lines.slice(1, -1).join('\n')
+  const min = tryMinifyJson(body)
+  return min === null ? seg : { ...seg, text: `${lines[0].trim()}\n${min}\n${lines.at(-1).trim()}` }
+}
+
+/**
+ * @param {string} text
+ * @param {typeof DEFAULTS} opts
+ */
+function normalizeProse (text, opts) {
+  return text.split('\n').map(line => {
+    const trimmed = line.replace(/[ \t\r]+$/, '')
+    if (!opts.collapseSpaces || /^( {4,}|\t)/.test(trimmed)) return trimmed
+    const indent = /^[ \t]*/.exec(trimmed)[0]
+    // keep inline code spans as they are
+    const body = trimmed.slice(indent.length).split(/(`[^`\n]*`)/).map((part, i) => (i % 2 ? part : part.replace(/ {2,}/g, ' '))).join('')
+    return indent + body
+  }).join('\n')
+}
+
+module.exports = { normalize, normalizeText, DEFAULTS }

package/lib/pipeline/steps/outputCap.js

@@ -0,0 +1,28 @@
+'use strict'
+/**
+ * outputCap: set max_tokens from the (per-use-case) config when the caller set no limit.
+ * Reasoning models (o1/o3/o4, gpt-5) spend output tokens on hidden reasoning, so a cap can
+ * produce empty answers; they are skipped unless `reasoningModels: true`.
+ * Saves output tokens, which cannot be known before the call, so it reports 0 saved prompt tokens.
+ */
+const { baseModelName } = require('../../tokens/estimator')
+
+const DEFAULTS = { default: 1024, reasoningModels: false }
+const REASONING = /^(o\d|gpt-5)/
+
+/**
+ * @param {import('../index').StepInput} input
+ * @param {object} options
+ */
+function outputCap ({ params, model }, options) {
+  const opts = { ...DEFAULTS, ...options }
+  const p = params ?? {}
+  if (p.max_tokens != null || p.max_completion_tokens != null) return { params, notes: [] }
+  if (!(opts.default > 0)) return { params, notes: [] }
+  if (REASONING.test(baseModelName(model)) && !opts.reasoningModels) {
+    return { params, notes: ['skipped: reasoning model'] }
+  }
+  return { params: { ...p, max_tokens: opts.default }, notes: [`max_tokens set to ${opts.default}`] }
+}
+
+module.exports = { outputCap, DEFAULTS }

package/lib/pipeline/steps/tools.js

@@ -0,0 +1,157 @@
+'use strict'
+/**
+ * tools: for agents and MCP servers with many tools.
+ *  - When there are more than `maxTools` tool definitions, keep the most relevant ones.
+ *    Always kept: tools named in `pinned`, tools already used in the conversation, and the
+ *    tool forced by `tool_choice`. The rest are ranked by keyword overlap with the latest
+ *    user message (ties keep the original order). The original order is preserved.
+ *  - Descriptions longer than `maxDescriptionLength` are shortened (at a sentence end
+ *    when possible), for the tool and for its parameters.
+ *
+ * Pluggable: `selector` may be a function `({ tools, messages, maxTools, keep }) => tools`
+ * where `keep` is the Set of names that must be kept.
+ */
+const { toolName } = require('../messages')
+
+const DEFAULTS = { maxTools: 15, maxDescriptionLength: 600, pinned: [], selector: null }
+
+const STOPWORDS = new Set(('the and for with that this from have what which when where will would could should about into ' +
+  'your you are was were been can not but all any our out get set use using please there their them then than ' +
+  'also just like make need want show give tell does did has had its it\'s let me my mine how who why').split(' '))
+
+/** Lower-case keywords of a text, splitting snake_case and camelCase. */
+function keywords (text) {
+  return new Set(String(text ?? '')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(w => w.length >= 3 && !STOPWORDS.has(w)))
+}
+
+function toolKeywords (t) {
+  const fn = t?.function ?? t
+  const params = fn?.parameters?.properties ? Object.keys(fn.parameters.properties).join(' ') : ''
+  return keywords(`${toolName(t) ?? ''} ${fn?.description ?? ''} ${params}`)
+}
+
+/** Names of tools the conversation already used. */
+function usedToolNames (messages) {
+  const names = new Set()
+  for (const m of messages) {
+    for (const tc of m?.tool_calls ?? []) if (tc?.function?.name) names.add(tc.function.name)
+    if (m?.role === 'tool' && m.name) names.add(m.name)
+  }
+  return names
+}
+
+function contentText (content) {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) return content.map(p => (typeof p === 'string' ? p : p?.text ?? '')).join(' ')
+  return ''
+}
+
+/**
+ * Default selector: keyword overlap with the latest user message.
+ * @param {{ tools: object[], messages: object[], maxTools: number, keep: Set<string> }} input
+ */
+function keywordSelector ({ tools, messages, maxTools, keep }) {
+  const lastUser = [...messages].reverse().find(m => m?.role === 'user')
+  const query = keywords(contentText(lastUser?.content))
+  const scored = tools.map((t, i) => {
+    let score = 0
+    for (const w of toolKeywords(t)) if (query.has(w)) score++
+    return { t, i, score, must: keep.has(toolName(t)) || t?.type !== undefined && t.type !== 'function' }
+  })
+  const chosen = new Set(scored.filter(s => s.must).map(s => s.i))
+  const rest = scored.filter(s => !s.must).sort((a, b) => b.score - a.score || a.i - b.i)
+  for (const s of rest) {
+    if (chosen.size >= maxTools) break
+    chosen.add(s.i)
+  }
+  return tools.filter((_t, i) => chosen.has(i))
+}
+
+/**
+ * Shorten text to at most `max` characters, at a sentence end if one is in the second half.
+ * @param {string} text
+ * @param {number} max
+ */
+function shorten (text, max) {
+  if (typeof text !== 'string' || text.length <= max) return text
+  const head = text.slice(0, max)
+  const sentenceEnd = Math.max(head.lastIndexOf('. '), head.lastIndexOf('.\n'), head.lastIndexOf('! '), head.lastIndexOf('? '))
+  if (sentenceEnd >= max / 2) return head.slice(0, sentenceEnd + 1)
+  return `${head.slice(0, max - 1).trimEnd()}…`
+}
+
+function shortenSchema (schema, max) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema
+  let changed = false
+  const out = { ...schema }
+  if (typeof schema.description === 'string') {
+    const d = shorten(schema.description, max)
+    if (d !== schema.description) { out.description = d; changed = true }
+  }
+  for (const key of ['properties', '$defs', 'definitions']) {
+    if (schema[key] && typeof schema[key] === 'object') {
+      const next = {}
+      let sub = false
+      for (const [k, v] of Object.entries(schema[key])) {
+        next[k] = shortenSchema(v, max)
+        if (next[k] !== v) sub = true
+      }
+      if (sub) { out[key] = next; changed = true }
+    }
+  }
+  if (schema.items) {
+    const items = shortenSchema(schema.items, max)
+    if (items !== schema.items) { out.items = items; changed = true }
+  }
+  return changed ? out : schema
+}
+
+function shortenTool (t, max) {
+  const fn = t?.function
+  if (!fn) return t
+  const description = shorten(fn.description, max)
+  const parameters = shortenSchema(fn.parameters, max)
+  if (description === fn.description && parameters === fn.parameters) return t
+  return { ...t, function: { ...fn, ...(description !== undefined ? { description } : {}), ...(parameters !== undefined ? { parameters } : {}) } }
+}
+
+/**
+ * @param {import('../index').StepInput} input
+ * @param {object} options
+ */
+function tools ({ messages, tools: defs, params }, options) {
+  const opts = { ...DEFAULTS, ...options }
+  if (!Array.isArray(defs) || !defs.length) return { tools: defs, notes: [] }
+  const notes = []
+  let out = defs
+
+  if (opts.maxTools > 0 && defs.length > opts.maxTools) {
+    const keep = new Set([...(opts.pinned ?? []), ...usedToolNames(messages)])
+    const forced = params?.tool_choice?.function?.name
+    if (forced) keep.add(forced)
+    const selector = typeof opts.selector === 'function' ? opts.selector : keywordSelector
+    out = selector({ tools: defs, messages, maxTools: opts.maxTools, keep })
+    if (!Array.isArray(out)) throw new Error('tools selector must return an array')
+    const names = new Set(out.map(toolName))
+    const missing = [...keep].filter(n => defs.some(t => toolName(t) === n) && !names.has(n))
+    if (missing.length) throw new Error(`tools selector dropped required tools: ${missing.join(', ')}`)
+    if (out.length < defs.length) notes.push(`${defs.length - out.length} of ${defs.length} tools removed`)
+  }
+
+  if (opts.maxDescriptionLength > 0) {
+    let shortened = 0
+    out = out.map(t => {
+      const s = shortenTool(t, opts.maxDescriptionLength)
+      if (s !== t) shortened++
+      return s
+    })
+    if (shortened) notes.push(`${shortened} tool description(s) shortened`)
+  }
+  return { tools: out, notes }
+}
+
+module.exports = { tools, keywordSelector, keywords, shorten, usedToolNames, DEFAULTS }

package/lib/pipeline/text.js

@@ -0,0 +1,166 @@
+'use strict'
+/**
+ * Text helpers for the pipeline: split text into code / JSON / prose segments and
+ * minify JSON without changing its value.
+ */
+
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})(.*)$/
+
+/**
+ * @typedef {{ type: 'code'|'prose', text: string, info?: string }} Segment
+ */
+
+/**
+ * Split text into fenced code blocks and prose. Fence lines belong to the code segment.
+ * An unclosed fence runs to the end of the text (as in CommonMark).
+ * @param {string} text
+ * @returns {Segment[]}
+ */
+function splitFences (text) {
+  const lines = text.split('\n')
+  const out = []
+  let buf = []
+  let fence = null
+  const push = (type, info) => {
+    if (!buf.length) return
+    out.push({ type, text: buf.join('\n'), ...(info !== undefined ? { info } : {}) })
+    buf = []
+  }
+  for (const line of lines) {
+    if (!fence) {
+      const m = FENCE_OPEN.exec(line)
+      if (m && !(m[1][0] === '`' && m[2].includes('`'))) {
+        push('prose')
+        fence = { char: m[1][0], len: m[1].length, info: m[2].trim() }
+        buf.push(line)
+        continue
+      }
+      buf.push(line)
+    } else {
+      buf.push(line)
+      const close = new RegExp(`^[ \\t]*${fence.char === '`' ? '`' : '~'}{${fence.len},}[ \\t]*$`)
+      if (close.test(line)) {
+        push('code', fence.info)
+        fence = null
+      }
+    }
+  }
+  push(fence ? 'code' : 'prose', fence?.info)
+  // re-joining with '\n' between segments restores the original text
+  return out
+}
+
+/** Join segments produced by splitFences (or transformed copies of them). */
+const joinSegments = (segments) => segments.map(s => s.text).join('\n')
+
+/**
+ * Remove insignificant whitespace from valid JSON. Works on the text, so numbers,
+ * key order and duplicate keys stay exactly as written.
+ * @param {string} json must already be valid JSON
+ */
+function minifyJson (json) {
+  let out = ''
+  let inString = false
+  let escaped = false
+  for (const ch of json) {
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+    } else if (ch === '"') {
+      inString = true
+      out += ch
+    } else if (ch !== ' ' && ch !== '\t' && ch !== '\n' && ch !== '\r') {
+      out += ch
+    }
+  }
+  return out
+}
+
+/**
+ * Minify `text` if it is a JSON object or array; otherwise return null.
+ * @param {string} text
+ * @returns {string|null}
+ */
+function tryMinifyJson (text) {
+  const t = text.trim()
+  if (!(t.startsWith('{') || t.startsWith('['))) return null
+  let parsed
+  try { parsed = JSON.parse(t) } catch { return null }
+  if (parsed === null || typeof parsed !== 'object') return null
+  return minifyJson(t)
+}
+
+/**
+ * Find the end index (exclusive) of the JSON value that starts with a bracket at `start`,
+ * respecting strings. Returns -1 if the brackets never balance.
+ * @param {string} text
+ * @param {number} start
+ */
+function matchBracket (text, start) {
+  const stack = []
+  let inString = false
+  let escaped = false
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') inString = true
+    else if (ch === '{' || ch === '[') stack.push(ch)
+    else if (ch === '}' || ch === ']') {
+      const open = stack.pop()
+      if ((ch === '}' && open !== '{') || (ch === ']' && open !== '[')) return -1
+      if (!stack.length) return i + 1
+    }
+  }
+  return -1
+}
+
+/**
+ * Split prose into JSON blocks and the text around them. A JSON block starts with `{` or `[`
+ * at the beginning of a line (after indentation), ends at the end of a line, and parses
+ * as a JSON object or array.
+ * @param {string} text
+ * @returns {Array<{ type: 'json'|'text', text: string }>}
+ */
+function splitJsonBlocks (text) {
+  const out = []
+  let last = 0
+  let i = 0
+  while (i < text.length) {
+    const lineStart = i === 0 || text[i - 1] === '\n'
+    if (lineStart) {
+      let j = i
+      while (text[j] === ' ' || text[j] === '\t') j++
+      if (text[j] === '{' || text[j] === '[') {
+        const end = matchBracket(text, j)
+        if (end > 0) {
+          let k = end
+          while (text[k] === ' ' || text[k] === '\t' || text[k] === '\r') k++
+          if (k >= text.length || text[k] === '\n') {
+            const candidate = text.slice(j, end)
+            if (tryMinifyJson(candidate) !== null) {
+              if (j > last) out.push({ type: 'text', text: text.slice(last, j) })
+              out.push({ type: 'json', text: candidate })
+              last = end
+              i = end
+              continue
+            }
+          }
+        }
+      }
+    }
+    const nl = text.indexOf('\n', i)
+    if (nl < 0) break
+    i = nl + 1
+  }
+  if (last < text.length) out.push({ type: 'text', text: text.slice(last) })
+  return out
+}
+
+module.exports = { splitFences, joinSegments, minifyJson, tryMinifyJson, splitJsonBlocks, matchBracket }