features transform

Transform

Active contributors: ferdiiskandar

Purpose

Transform turns a raw prompt into a structured scaffold without calling any model. It detects the task intent, selects a persona and style, and compiles the prompt into the input shape a specific target model handles best. It is a pure function: same input, same output, no network. The desktop console runs it as transform:run.

Key abstractions

Abstraction	Role	Source
transformPrompt	Entry point: persona, intent, dispatch, token estimate	lib/transform/engine.ts
detectIntent	Bilingual keyword classifier over eight intents	lib/transform/engine.ts
ModelId	Transform's model namespace (claude-sonnet, openai-gpt4o, ...)	lib/transform/schemas.ts
CompilerProfile	claude, codex, gemini, grok	lib/transform/schemas.ts
compileProfilePrompt	Dispatches to a profile handler	lib/transform/compiler/index.ts
buildCommonConstraints	Shared constraint list all profiles reuse	lib/transform/compiler/shared.ts

How it works

transformPrompt reads mode (persona), model, temperature, maxTokens, locale, optional profile, effort, and target. It runs detectIntent first. Intent detection checks specific intents before the broad generation branch, so "buatkan ringkasan" lands on summarization, not generation. Specific intents are translation, summarization, analysis, comparison, debugging, and explanation; generation is the catch-all before general.

The persona and style come from MODE_PERSONAS, keyed by TransformMode (professional, creative, technical, academic, casual). Each intent maps to an intent instruction in Indonesian or English via getIntentInstruction.

When a compiler profile is set and recognised by hasCompilerProfile, the engine calls compileProfilePrompt and the matching handler builds the scaffold:

Profile	Shape
claude	XML tags: <instructions>, <context>, <task>, <constraints>, <output_format>; task text is XML-escaped
codex	Markdown acceptance criteria, repository context, and a verification section
gemini	System instruction, context, task, constraints, and a numbered output schema
grok	Objective, context, an evidence-and-uncertainty block, constraints, output

With no profile, the engine falls back to a universal path that uses Claude XML when the model is claude-sonnet or claude-opus, otherwise markdown, and appends a Model optimization hint from MODEL_HINTS.

estimateTokens divides character count by a per-model divisor (3.2 for Claude, 3.5 for GPT-4o, and so on) and multiplies by 1.15 for Indonesian. It is an estimate, not a tokenizer.

flowchart LR
  I[raw prompt] --> D[detectIntent]
  D --> M[MODE_PERSONAS]
  D --> P{profile set?}
  P -->|yes| C[compileProfilePrompt]
  C --> H[claude / codex / gemini / grok]
  P -->|no| U[universal path + MODEL_HINTS]
  H --> E[estimateTokens]
  U --> E

Loading

Integration points

• TransformRequestSchema validates input in lib/transform/schemas.ts; the IPC router parses against it.
• The desktop renderer sends profile and effort state set by the profile and effort commands; see Desktop console.

Entry points for modification

Add an intent by widening detectIntent and getIntentInstruction in lib/transform/engine.ts. Add or change a profile in lib/transform/compiler/ and register it in compiler/index.ts.

Note on namespaces

ModelId (claude-sonnet, openai-gpt4o) is Transform's namespace and is not the same as the provider registry's LLMProviderName (CLAUDE, OPENAI). The schemas file documents that reconciliation is tracked under a planned P2 migration; do not mix the two.

Key source files

File	Purpose
lib/transform/engine.ts	Intent, persona, dispatch, token estimate
lib/transform/schemas.ts	Zod contracts and namespaces
lib/transform/compiler/index.ts	Profile registry and dispatch
lib/transform/compiler/shared.ts	Shared constraints and escaping
lib/transform/compiler/claude.ts	Claude XML compiler
lib/transform/compiler/codex.ts	Codex compiler
lib/transform/compiler/gemini.ts	Gemini compiler
lib/transform/compiler/grok.ts	Grok compiler