features optimizer

Optimizer

Active contributors: ferdiiskandar

Purpose

The Optimizer is the LLM-backed tool that turns a raw idea into a structured, ready-to-hand prompt. It runs one of two output kinds and one of two lanes, resolves template or strategy guidance, calls the provider, and post-parses the response into a typed object. The desktop console exposes it and adds tier quota, model access checks, and provider-key resolution.

Key abstractions

Abstraction	Role	Source
optimizePrompt	Non-streaming entry point	lib/optimizer/engine.ts
optimizePromptStreaming	Streaming variant, calls onChunk per delta	lib/optimizer/engine.ts
OutputKind	SUPER_PROMPT or CODING_BRIEF	lib/optimizer/engine.ts
OptimizeLane	INTERACTIVE or DEEP	lib/optimizer/engine.ts
getStrategyHints	Task/tone/format emphasis and constraints	lib/optimizer/strategies.ts
buildOptimizeSystemPrompt / buildOptimizeUserPrompt	Provider prompts	lib/llm/prompt-builder.ts

How it works

The engine first resolves the output kind. An explicit outputKind wins; otherwise a CODING task type defaults to CODING_BRIEF and everything else defaults to SUPER_PROMPT. The two routes are described in Super Prompt and Coding Brief.

For the Super Prompt route the lane sets the budget. INTERACTIVE uses maxTokens 900 and temperature 0.4; DEEP uses 2200 and 0.7. The lane also chooses the system prompt: Interactive asks for a directly usable prompt, Deep asks for the full Super Prompt with reasoning and an example.

Template and strategy resolution comes next. If the request names a templateSlug, the engine loads that template. Otherwise, in the DEEP lane only, it calls matchTemplateWithEmbeddings to find a template semantically. When no template matches, getStrategyHints supplies emphasis areas and additional constraints for the task type. The chosen text is injected into the user prompt as template guidance. The Coding Brief route deliberately skips all of this: the brief standard fixes its own structure, so template hints would only add noise.

After the provider call, the engine parses the response. The Super Prompt route tries parseSuperPromptMarkdown; on failure it logs a warning and falls back to wrapping the raw text as fullPrompt with quality.reason = 'parse_failed'. If the Interactive lane returned finishReason === 'length', it makes one recovery call with a larger maxTokens (2200) before parsing, which is the length-recovery behaviour that keeps truncated prompts from being reported as complete.

The streaming variant is the same pipeline over collectProviderStream. It accumulates deltas, parses the accumulation, and on a parse failure in the Interactive lane makes the same recovery call. If the stream produced no visible output, it falls back to a non-streaming generate. Metadata model comes from provider.activeModel because streaming does not return a response envelope.

flowchart TD
  Q[OptimizeRequest] --> K{outputKind}
  K -->|CODING_BRIEF| CB[Coding Brief route]
  K -->|SUPER_PROMPT| L{lane}
  L --> T[template or strategy resolution]
  T --> G[provider.generate / stream]
  G --> P{parse ok?}
  P -->|yes| OK[SuperPrompt, complete]
  P -->|no| F[fallback, degraded parse_failed]
  G -->|finishReason length, INTERACTIVE| RC[recovery call]
  RC --> P

Loading

Integration points

• Providers, keys, and scoped overrides live in the registry; see LLM providers.
• The desktop router starts optimize:run streaming and pushes status, chunk, done, and error events; see Desktop console.
• Templates come from the catalog; see Workspace and library.

Entry points for modification

Change lane budgets in buildStreamingRequest and the Coding Brief constants in lib/optimizer/engine.ts. Change system wording in lib/llm/prompt-builder.ts. Change strategy hints in lib/optimizer/strategies.ts.

Key source files

File	Purpose
lib/optimizer/engine.ts	Routes, lanes, recovery, fallbacks
lib/optimizer/strategies.ts	Task/tone/format hints
lib/llm/prompt-builder.ts	System and user prompts
lib/optimizer/provider-stream.ts	Stream collection