Skip to content

Planner

The Planner is the reasoning component that resolves Intents into Plan Drafts, Clarifications, or Conversational Responses. It is the system’s “brain” — the only component that performs non-deterministic reasoning (via LLM or other strategy). This specification defines its interface, internal pipeline, LLM integration model, and operational behavior.


  1. Produce executable plans. Every Plan Draft the Planner generates must be executable by the current user. Plans always succeed.
  2. Be policy-aware from the start. The Planner checks both system-level policy and capability-level constraints before selecting any capability. Policy denial is handled during generation, not after.
  3. Fall back gracefully. If the Planner cannot produce a plan, it either asks for clarification or explains why. It never fails silently or produces a plan it knows will be rejected.
  4. Be pluggable. The Planner is a defined interface. The default implementation uses an LLM, but it can be replaced with a rule-based matcher, a remote service, or any other strategy.
  5. Be stateless. The Planner does not maintain state between invocations. All context it needs (intent, user, capabilities, policies, plan library) is provided per request.
  6. Be inspectable. Every decision the Planner makes is recorded in a Planner Trace — a structured log of the reasoning process that feeds into the system-wide Trace.

The Planner receives a PlannerRequest:

interface PlannerRequest {
intent: Intent;
user_context: UserContext;
conversation_history?: ConversationTurn[]; // For multi-turn clarification
planning_context?: {
hints?: string[]; // Per-request planning hints
data?: Record<string, any>; // Additional data for gap resolution
};
execution_context?: {
environment: string; // 'production', 'staging', 'development'
default_execution_mode: ExecutionMode;
};
}
interface Intent {
raw_text?: string; // Natural language (expressed intent)
structured?: {
// Pre-parsed (packaged or structured intent)
action: string;
parameters: Record<string, any>;
};
source: 'expressed' | 'packaged' | 'structured';
}
interface UserContext {
user_id: string;
tenant_id?: string;
roles: string[];
}
interface ConversationTurn {
role: 'user' | 'planner';
content: string;
clarification_id?: string; // Links to a prior CLARIFY response
}

The Planner returns a PlannerResponse — exactly one of three modes:

type PlannerResponse = PlannerGenerateResponse | PlannerClarifyResponse | PlannerConverseResponse;
interface PlannerGenerateResponse {
mode: 'GENERATE';
plan_draft: PlanDraft; // As defined in Plan IR Specification, Section 2
planner_trace: PlannerTrace; // Reasoning log
confidence: number; // 0.0 to 1.0
goal_summary: string; // Human-readable: "Submit a deletion request for customer ABC-123"
goal_adjusted: boolean; // True if the goal was changed from the original intent (e.g., due to policy)
original_goal?: string; // If adjusted, what the user originally wanted
adjusted_reason?: string; // Why the goal was adjusted
}
interface PlannerClarifyResponse {
mode: 'CLARIFY';
clarification_id: string; // Unique ID for this clarification round
question: string; // Human-readable question
options?: ClarificationOption[]; // Structured options (if applicable)
context: string; // Why this clarification is needed
planner_trace: PlannerTrace;
}
interface ClarificationOption {
id: string;
label: string; // Human-readable
description?: string;
intent_refinement: Partial<Intent>; // How selecting this option refines the intent
}
interface PlannerConverseResponse {
mode: 'CONVERSE';
message: string; // Human-readable response
suggestions?: string[]; // Suggested follow-up intents
reason: ConverseReason;
planner_trace: PlannerTrace;
}
type ConverseReason =
| 'not_actionable' // Intent is exploratory, advisory, or conversational
| 'no_matching_capability' // No capability matches the goal
| 'policy_blocked' // All paths blocked by policy, no alternatives
| 'capability_unavailable' // Capability exists but is disabled/quarantined
| 'out_of_scope'; // Intent is outside the application's domain

The Planner reads from (but does not write to) the following:

DependencyInterfaceWhat the Planner Reads
Capability RegistryQuery APICapability definitions: name, description, input/output schemas, effect class, boundary, tags, constraints, alternatives
Plan LibrarySearch APIExisting validated plans: plan name, intent patterns, input schema, lifecycle state, trust score
Policy EnginePre-generation check APIALLOWED/DENIED for a given capability + user context
LLM ProviderChat completion APIReasoning, scoring, intent parsing (default Planner only)

The Planner does not access:

  • The Execution Engine (it does not execute anything)
  • The Trace Store (it produces traces, but does not read them)
  • Service Providers / business data (it has no access to application data)

The Planner processes each request through a sequential pipeline. Each stage may terminate the pipeline early by returning a CLARIFY or CONVERSE response.

Stage 1: INTENT CLASSIFICATION
Determine if the intent is actionable, exploratory, or ambiguous.
→ Not actionable: return CONVERSE
→ Ambiguous: return CLARIFY
→ Actionable: proceed
Stage 2: PLAN LIBRARY SEARCH
Search for an existing promoted plan that matches the intent.
→ Match found (high confidence): return GENERATE with the existing plan
→ Partial match: note it as a candidate, proceed to generation
→ No match: proceed to generation
Stage 3: GOAL IDENTIFICATION
Parse the intent into a goal: what output does the user want?
→ Clear goal: proceed
→ Unclear: return CLARIFY
Stage 4: BACKWARD CHAINING (capability selection + policy pre-check)
Find terminal capability, check policy, analyze gaps, resolve gaps.
→ Plan assembled: proceed
→ Gap unresolvable: return CLARIFY
→ All paths blocked: return CONVERSE
Stage 5: PLAN DRAFT ASSEMBLY
Arrange capabilities in execution order, wire input bindings.
→ Return GENERATE with Plan Draft
Stage 6: PLANNER TRACE ASSEMBLY
Package all decisions, scores, and reasoning into a PlannerTrace.
Attached to the response regardless of mode.

The Planner first classifies the intent to determine how to process it.

For expressed intents (natural language):

The LLM classifies the intent into one of:

ClassificationExamplesNext Action
Actionable”Delete customer ABC”, “Send the report”, “Create a new deal”Proceed to Stage 2
Exploratory”What can you do?”, “How does billing work?”, “Tell me about capabilities”CONVERSE (explain, list capabilities, describe features)
Advisory”Should I delete this account?”, “What’s the best approach for…”CONVERSE (give advice, recommend)
Ambiguous”Something about the customer”, “Fix it”, “Do the thing”CLARIFY (ask what specifically)
Conversational”Hello”, “Thanks”, “Never mind”CONVERSE (respond naturally)

For packaged intents (pre-built):

Skip classification. Packaged intents are always actionable. Proceed directly to Stage 2.

For structured intents (form/wizard):

Skip classification. Structured intents provide action and parameters. Proceed directly to Stage 2 (or Stage 3 if the action maps directly to a capability).

Before generating a new plan, the Planner searches the Plan Library for an existing plan that matches the intent.

Search criteria:

  1. Intent pattern matching: Plans in the library may be tagged with intent patterns they serve. The Planner matches the current intent against these patterns.
  2. Input compatibility: The plan’s required inputs must be satisfiable from the intent’s data.
  3. Lifecycle state: Only PROMOTED plans are considered. CANDIDATE and SHADOW plans are not returned for production use.
  4. Policy compatibility: The matched plan’s capabilities must pass policy pre-check for the current user.

Match outcomes:

ConfidenceAction
High (>0.9): exact or near-exact match to a promoted planReturn GENERATE with the existing plan’s Plan IR. Skip generation.
Medium (0.5-0.9): partial match, some adaptation neededNote as a starting point. Proceed to generation, using the match as a template.
Low (<0.5) or no matchProceed to generation from scratch.

Policy check on matched plans: Even for a high-confidence match from the Plan Library, the Planner runs a policy pre-check on all capabilities in the plan. If any capability is now blocked for this user (policies may have changed since the plan was promoted), the Planner either adapts the plan or falls through to generation.

The Planner identifies the desired output from the intent.

For expressed intents: The LLM parses the intent into:

  • Goal output: What the user wants to happen (e.g., “email sent”, “customer deleted”, “report generated”)
  • Explicit parameters: Data provided in the intent (e.g., customer_id = “ABC-123”, email = “[email protected]”)
  • Implicit context: Information available from the system context (e.g., current user, current tenant)

For structured intents: The action field maps to the goal, parameters map to explicit parameters. Minimal LLM involvement.

Failure modes:

  • If the LLM cannot extract a clear goal: CLARIFY (“What specifically would you like me to do?”)
  • If the goal is clear but too vague to match capabilities: CLARIFY (“Which customer do you mean?” / “What kind of report?“)

This is the core generation stage. The protocol is fully defined in the Plan IR Specification (Section 1A.2). Here we define the Planner-specific behavior at each step.

The runtime queries the Capability Registry for capabilities whose output matches the goal.

Query strategy:

  1. Schema match: Capabilities whose output_schema is structurally compatible with the goal output.
  2. Tag match: Capabilities whose tags overlap with keywords from the intent.
  3. Description match: LLM semantic similarity between the intent and capability descriptions.

The runtime returns a ranked candidate list. The LLM scores each candidate:

Candidate scoring prompt (conceptual):
Given the user's intent: "{intent}"
And the goal: "{goal}"
Score each capability (0.0 to 1.0) on how well it achieves the goal:
1. {capability_name}: {description}
Input: {input_schema_summary}
Output: {output_schema_summary}
Effect: {effect_class} / {boundary}
Score: ___
Select the highest-scoring capability, or indicate if none match.

Decision thresholds:

Score RangeAction
Single candidate > 0.85Select it. High confidence.
2-3 candidates > 0.7LLM selects best. Medium confidence.
Multiple candidates, all 0.5-0.7CLARIFY — present options to user
No candidates > 0.5CONVERSE — explain what’s possible

Tier selection (when capability tiers exist):

When the registry contains multiple capability variants for the same domain action (e.g., send_email, send_email_batch, start_email_campaign), the Planner uses the following heuristics to select the appropriate tier:

SignalSelect
Intent targets a single entity (“send alice an email”)Atomic (Tier 1)
Intent targets a small collection (“all”, “every”, “each” + small/medium counts up to the batch capability’s maxItems)Batch (Tier 2)
Intent signals large-scale or background operations (“campaign”, “bulk”, “export”, large counts, or unknown-size collections)Async Job (Tier 3)
A prior step produces an array and the next capability needs one itemBatch (Tier 2) — the batch variant accepts the array directly

The capability description and alternatives fields are the primary selection mechanism. A batch capability’s description should explicitly state its item limit and direct the Planner to the async alternative for larger sets. See Capability System Specification, Section 16C.

After selecting a candidate capability, the Planner queries the Policy Engine:

interface PolicyPreCheckRequest {
capability_name: string;
capability_version: string;
effect_class: EffectClass;
boundary: Boundary;
tags: string[];
constraints?: {
required_roles?: string[];
};
user_context: UserContext;
environment: string;
}
interface PolicyPreCheckResponse {
allowed: boolean;
reason?: string; // If denied: human-readable explanation
denied_by?: string; // Policy name or constraint that blocked
}

If DENIED: The Planner enters Alternative Capability Search (see Section 3.5.3).

If ALLOWED: Proceed to gap analysis.

When a capability is policy-blocked, the Planner searches for alternatives:

Search order:

  1. alternatives field: Check the blocked capability’s alternatives field for explicitly declared alternatives.
  2. Tag-based search: Query the registry for capabilities with the same domain tags (excluding the blocked one).
  3. Schema-based search: Query for capabilities whose output achieves a version of the goal (e.g., request_id instead of deletion_confirmation).

For each alternative found:

  1. Run policy pre-check. If also blocked, skip.
  2. LLM scores the alternative against the (possibly adjusted) goal.
  3. If score > 0.6: use it. Adjust the goal description.
  4. If no alternative passes: CONVERSE with explanation.

Goal adjustment:

When an alternative is selected, the Planner adjusts:

  • goal_summary: from “Delete customer ABC-123” to “Submit deletion request for customer ABC-123”
  • goal_adjusted: true
  • original_goal: “Delete customer ABC-123”
  • adjusted_reason: “Direct deletion requires admin role. A deletion request has been submitted instead.”

This information is included in the GENERATE response so the frontend can inform the user.

After selecting the terminal capability (direct or alternative), the runtime compares its input schema against available data:

Available data sources:

SourceContents
Intent parametersExplicit values from the intent (e.g., customer_id = “ABC-123”)
System contextCurrent user_id, tenant_id, roles, timestamp, environment
Conversation historyValues collected from prior CLARIFY rounds

Gap identification:

For each required field in the capability’s input schema:

  1. Is it available from intent parameters? (name match or type-compatible alias)
  2. Is it available from system context?
  3. Is it available from conversation history?
  4. If none: it’s a gap.

For each optional field:

  • If available: include it. If not: skip it (the capability handles defaults).

For each gap, the Planner recurses:

  1. Runtime queries: Capability Registry for capabilities whose output can fill the gap.
  2. Policy pre-check: on each candidate bridging capability.
  3. LLM selects: the best bridging capability.
  4. Recurse: if the bridging capability has its own gaps.
  5. Depth limit: Maximum chain depth of 10 capabilities. Beyond this, fall back to CLARIFY.
  6. Ask the user: If a gap cannot be filled by any capability (e.g., a free-text “reason” field), the Planner may include a CLARIFY for that specific field. Alternatively, it may treat the gap as a value the plan collects at runtime via an Interaction Point.

Once all gaps are resolved, the Planner assembles the Plan Draft:

  1. Reverse the chain: The backward chain is reversed to produce execution order (first capability to call is the one furthest from the goal).
  2. Wire input bindings: For each capability, specify where each input comes from (intent parameter, prior step output, system context).
  3. Add conditions: If any step is conditional (e.g., “only send email if user has email opt-in”), express as a natural language condition string (Plan Enrichment converts to structured conditions).
  4. Name the plan: LLM generates a concise plan name from the goal (e.g., “request_customer_deletion”).

The output is a Plan Draft as defined in Plan IR Specification, Section 2.

Every Planner invocation produces a PlannerTrace — a structured log of the reasoning process:

interface PlannerTrace {
trace_id: string;
timestamp: string;
duration_ms: number;
intent_classification: {
classification: 'actionable' | 'exploratory' | 'advisory' | 'ambiguous' | 'conversational';
confidence: number;
};
plan_library_search?: {
query: string;
matches: Array<{
plan_id: string;
plan_name: string;
confidence: number;
selected: boolean;
}>;
};
goal_identification?: {
goal_output: string;
explicit_parameters: Record<string, any>;
confidence: number;
};
capability_selection: Array<{
step: 'terminal' | 'bridging';
candidates: Array<{
capability_name: string;
score: number;
selected: boolean;
}>;
policy_pre_check: {
capability_name: string;
allowed: boolean;
reason?: string;
};
alternative_search?: {
triggered: boolean;
alternatives_found: number;
selected_alternative?: string;
goal_adjusted: boolean;
};
}>;
gaps: Array<{
field: string;
resolved_by: 'capability' | 'clarification' | 'default' | 'interaction_point';
bridging_capability?: string;
}>;
response_mode: 'GENERATE' | 'CLARIFY' | 'CONVERSE';
llm_calls: Array<{
purpose: string; // e.g., "intent_classification", "capability_scoring", "goal_extraction"
model: string;
prompt_tokens: number;
completion_tokens: number;
duration_ms: number;
}>;
}

The PlannerTrace is:

  • Attached to every PlannerResponse (regardless of mode).
  • Persisted as part of the system-wide Trace when a plan is executed.
  • Inspectable via the CLI (zakardo trace inspect) and the Zakardo Cloud dashboard.
  • Used by the Training System to evaluate Planner performance.

Clarification is not a single request-response. It’s a conversation loop.

Turn 1: User sends intent
Turn 2: Planner returns CLARIFY (asks a question)
Turn 3: User answers the question
Turn 4: Planner re-enters the pipeline with the refined intent
→ May return GENERATE, CLARIFY (again), or CONVERSE

Implementation:

  1. The Planner returns a PlannerClarifyResponse with a unique clarification_id.
  2. The frontend presents the question (and options, if provided) to the user.
  3. The user responds. The frontend sends a new PlannerRequest with:
    • The original intent
    • The answer appended to conversation_history
    • The clarification_id to link the answer to the question
  4. The Planner re-enters the pipeline at Stage 1 with the full context.
TypeWhenExample QuestionExample Options
DisambiguationMultiple viable goals”Do you want to delete the customer’s account or their billing profile?”Option A: “Account”, Option B: “Billing profile”
Missing parameterRequired input not in intent”Which customer do you want to delete? Please provide a customer ID or name.”(free-text)
Multiple pathsSeveral capabilities match with similar scores”I can generate a PDF report or a live dashboard. Which do you prefer?”Option A: “PDF report”, Option B: “Live dashboard”
ConfirmationHigh-impact action detected, Planner wants to confirm before building plan”You want to delete all inactive accounts (47 total). This is destructive. Should I proceed with building this plan?”Option A: “Yes, proceed”, Option B: “No, cancel”
  • Maximum turns: 5 clarification rounds per intent before the Planner gives up and returns CONVERSE (“I’m having trouble understanding your request. Could you try rephrasing it?”)
  • Timeout: If the user doesn’t respond to a clarification within a configurable timeout (default: 5 minutes), the session expires. The user must start over.

5.1 When the Plan Library Short-Circuits Generation

Section titled “5.1 When the Plan Library Short-Circuits Generation”

The Plan Library is the first thing the Planner checks. If a promoted plan matches the intent with high confidence, the Planner skips generation entirely:

Intent: "Send welcome email to user 123"
→ Plan Library: promoted plan "send_welcome_email" matches (confidence: 0.95)
→ Policy pre-check: all capabilities in the plan are allowed for this user
→ Return GENERATE with the existing plan (no LLM generation needed)

This is the fast path. For common intents with promoted plans, the Planner is essentially a lookup + policy check.

Plans in the library are indexed by:

  1. Intent patterns: Human-authored or auto-extracted patterns (e.g., “send _ email to _”, “delete _ account _”).
  2. Input schema: The plan’s required inputs. A match requires that the intent provides (or can provide) all required inputs.
  3. Tags: Domain tags for fuzzy matching.
  4. Semantic embedding: For LLM-based matching, a vector embedding of the plan’s purpose.

Matching algorithm:

1. Filter: Lifecycle state == PROMOTED
2. Filter: All plan capabilities pass policy pre-check for current user
3. Score: Combine pattern match score, schema compatibility, tag overlap, semantic similarity
4. Rank: Sort by composite score
5. Threshold: Top result must be > 0.9 for high-confidence match

When a medium-confidence match (0.5-0.9) is found, the Planner may adapt the existing plan:

  • Parameter adaptation: The plan expects input X, the intent provides a variation of X. The LLM maps the intent’s data to the plan’s expected inputs.
  • Step addition: The matched plan is close but missing a step. The Planner uses it as a starting point and adds the missing step via backward chaining.
  • Step removal: The matched plan has steps not needed for this specific intent. The Planner may propose a trimmed version.

Adapted plans are new CANDIDATE plans, not modifications to the promoted plan.


Every LLM call in the Planner is composed of layered context. Each layer adds information, and the developer controls several of them.

┌─────────────────────────────────────────────────────────┐
│ Layer 1: ZAKARDO CORE PROMPT (built-in, not editable) │
│ Defines: Planner role, backward chaining protocol, │
│ response modes, JSON output format, safety rules │
├─────────────────────────────────────────────────────────┤
│ Layer 2: APPLICATION CONTEXT (developer-configured) │
│ Defines: App domain, business rules, tone, constraints │
│ Source: config/llm.ts -> planner.application_prompt │
├─────────────────────────────────────────────────────────┤
│ Layer 3: CAPABILITY CONTEXT (auto-generated) │
│ Defines: Available capabilities for this call │
│ Source: Runtime queries Capability Registry, formats │
│ summaries for the LLM (name, description, I/O summary)│
├─────────────────────────────────────────────────────────┤
│ Layer 4: PLANNING HINTS (developer-injected, optional) │
│ Defines: Domain-specific guidance, preferences, rules │
│ Source: config/llm.ts -> planner.planning_hints │
│ or per-request via Runtime API │
├─────────────────────────────────────────────────────────┤
│ Layer 5: USER CONTEXT (per-request, auto-populated) │
│ Defines: User roles, tenant, environment, conversation │
│ history, prior clarifications │
├─────────────────────────────────────────────────────────┤
│ Layer 6: USER MESSAGE (the intent itself) │
│ Source: What the user typed or the packaged intent │
└─────────────────────────────────────────────────────────┘

Layer 1 and 3 are owned by Zakardo. The developer cannot modify them. Layer 2, 4 are developer-controlled. This is how developers customize the Planner for their application. Layer 5 and 6 are per-request, auto-populated from the PlannerRequest.

Layer 1: Zakardo Core Prompt (System Role)

Section titled “Layer 1: Zakardo Core Prompt (System Role)”

This is the foundation prompt, provided by @zakardo/runtime. It is stable across all applications and all LLM calls within a session. It defines:

  • The Planner’s identity and role (“You are a plan generator…”)
  • The backward chaining protocol (goal -> terminal capability -> gap analysis -> resolve)
  • The three response modes and when to use each
  • The JSON output schema expected for this specific call type
  • Safety rules: “Never fabricate capabilities”, “Never generate schemas”, “If unsure, ask for clarification”
  • The concept of capabilities, effect classes, and boundaries (so the LLM understands the domain model)

The developer cannot edit this layer. It ensures consistent Planner behavior across all Zakardo applications.

Layer 2: Application Context (Developer-Configured)

Section titled “Layer 2: Application Context (Developer-Configured)”

The developer provides an application-level prompt that describes their domain. This is configured once in config/llm.ts and injected into every LLM call as part of the system message.

config/llm.ts
{
planner: {
application_prompt: `
This is a CRM application for a B2B SaaS company.
Users are sales representatives, sales managers, and administrators.
Key domain concepts:
- Customers have accounts, contacts, and deals.
- Deals progress through stages: Lead → Qualified → Proposal → Negotiation → Closed Won/Lost.
- Sales reps can only see their own accounts. Managers see their team's accounts. Admins see all.
Tone: Professional but friendly. Use business terminology.
Important rules:
- Never suggest deleting a customer unless the user explicitly asks for deletion.
- Always prefer "update" over "delete + recreate" when modifying records.
- When the user says "my accounts", scope to their assigned accounts.
`,
}
}

This layer helps the LLM understand the application’s domain, make better capability selections, and generate more natural clarification questions.

Layer 3: Capability Context (Auto-Generated)

Section titled “Layer 3: Capability Context (Auto-Generated)”

For each LLM call that involves capability selection or scoring, the runtime generates a capability summary from the Capability Registry. The LLM receives only the relevant candidates (pre-filtered by the runtime), not the entire registry.

Format per capability:

Capability: get_customer_by_id
Description: Retrieves a customer record by ID. Returns full customer details.
Effect: READ | LOCAL
Input: { customer_id: string (uuid, required) }
Output: { id, name, email, status, assigned_to, created_at, ... }
Tags: [customer, account, read, crm]
Constraints: required_roles: [sales_rep, sales_manager, admin]

The runtime controls this formatting. The developer cannot modify how capabilities are presented to the LLM.

Layer 4: Planning Hints (Developer-Injected)

Section titled “Layer 4: Planning Hints (Developer-Injected)”

Planning hints are optional, domain-specific instructions that guide the Planner’s reasoning. They can be configured globally or injected per-request.

Global hints (in config/llm.ts):

{
planner: {
planning_hints: [
{
hint: "When a user asks to 'close' a deal, they mean move it to the 'Closed Won' stage, not delete it.",
tags: ["deals", "close"], // Only injected when these tags are relevant
},
{
hint: "For enterprise customers (tier: 'enterprise'), always include the audit_log_action capability in the plan.",
tags: ["enterprise", "audit"],
},
{
hint: "If the user asks about 'pipeline', they mean the deals pipeline dashboard, not a CI/CD pipeline.",
tags: ["pipeline", "deals"],
},
],
}
}

Per-request hints (via Runtime API):

// Submitted alongside the intent
{
intent: { raw_text: "Show me the Q4 forecast", source: "expressed" },
planning_context: {
hints: ["The user is preparing for a board meeting. Prefer summary views over detailed lists."],
data: {
current_quarter: "Q4-2026",
user_team_size: 12,
},
},
}

Hints are injected into the LLM call as additional system context. Tag-based hints are only included when the runtime determines they’re relevant (based on the capabilities being considered).

Per-request data provided in planning_context.data is made available as additional context during gap analysis. If the Planner has a gap for “quarter” and the planning context provides current_quarter: "Q4-2026", the gap is automatically resolved.

Populated automatically from the PlannerRequest:

User: user_id=u-456, roles=[sales_manager], tenant=acme-corp
Environment: production
Execution Mode: LIVE
Conversation History:
- User: "Show me inactive customers"
- Planner: [CLARIFY] "Inactive for how long? Last 30 days, 90 days, or all time?"
- User: "Last 90 days"

The intent itself. For expressed intents, this is the raw text. For packaged/structured intents, this is a formatted representation of the action and parameters.

The default Planner makes multiple focused LLM calls per pipeline execution, not one large prompt. Each call has a specific purpose:

CallPurposeInput LayersOutputRequired?
Intent classificationClassify intent as actionable/exploratory/ambiguousL1 + L2 + L3 (summaries only) + L5 + L6Classification + confidenceYes (expressed intents only)
Goal extractionParse intent into goal + parametersL1 + L2 + L4 (relevant hints) + L5 + L6Goal output, explicit parametersYes
Capability scoringScore candidate capabilities against the goalL1 + L2 + L3 (full candidates) + L4 + L5 + L6Scored listYes (per selection point)
Alternative evaluationScore alternative capabilities when blockedL1 + L2 + L3 (alternatives) + L4 + L5 + L6Scored listOnly when policy blocks
Gap interpretationDetermine if a gap can be defaulted or needs user inputL1 + L2 + L4 + L5 (+ planning_context.data)Resolution strategyOnly when gaps found
Condition generationExpress step conditions in natural languageL1 + L2 + L4 + step contextCondition stringOnly for conditional plans
Plan namingGenerate a concise plan nameL1 + L2 + goal + capabilities selectedPlan name stringYes
Clarification compositionFormulate a clear question for the userL1 + L2 + L4 + context of uncertaintyQuestion text + optionsOnly for CLARIFY mode
Conversational responseGenerate a helpful responseL1 + L2 + L4 + L5 + L6 + reasonResponse text + suggestionsOnly for CONVERSE mode
  1. Small, focused prompts. Each LLM call asks one question. No mega-prompts that try to do everything at once.
  2. Structured output. Every LLM call requests JSON output conforming to a defined schema. The runtime validates the response before proceeding.
  3. Capability context, not full registry. The LLM receives only the relevant candidates (filtered by the runtime’s registry queries), not the entire capability list.
  4. No schema generation. The LLM never generates JSON Schema. It selects from existing schemas. Plan Enrichment handles all schema-related computation.
  5. Incremental reasoning. For multi-step plans, each step is a separate LLM interaction. The runtime validates after each step before asking the LLM for the next one.
  6. System prompt stability. Layers 1-2 do not change between calls within a session. Only the capability context (L3), hints (L4), user context (L5), and user message (L6) change.
  7. Developer context is additive. The developer’s application prompt and hints add context. They cannot override Zakardo’s core protocol or safety rules.

Zakardo abstracts LLM access through a Provider Interface:

interface LLMProvider {
chat(request: LLMChatRequest): Promise<LLMChatResponse>;
supports_structured_output: boolean;
supports_streaming: boolean;
model_id: string;
}
interface LLMChatRequest {
messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>;
response_schema?: JSONSchema; // For structured output
temperature: number;
max_tokens: number;
}

Built-in providers (shipped with @zakardo/runtime):

ProviderModelsNotes
openaiGPT-4, GPT-4o, GPT-4o-mini, etc.Supports structured output (JSON mode)
anthropicClaude 3.5 Sonnet, Claude 3 Opus, etc.Supports structured output via tool use
ollamaAny Ollama-hosted modelFor local/self-hosted LLMs
customAny model via a developer-provided adapterImplements the LLMProvider interface

Configuration:

config/llm.ts
{
planner: {
llm: {
// Default provider for all calls
default: {
provider: 'anthropic',
model: 'claude-sonnet-4-20250514',
temperature: 0.1,
max_tokens: 4096,
timeout_ms: 30000,
},
// Override per call type (optional)
overrides: {
intent_classification: {
provider: 'anthropic',
model: 'claude-haiku-1', // Fast model for simple classification
temperature: 0.0,
max_tokens: 256,
},
capability_scoring: {
// Uses default (Sonnet) -- reasoning-heavy
},
conversational_response: {
temperature: 0.4, // Slightly more creative for conversation
max_tokens: 1024,
},
},
},
}
}

This allows developers to use a fast, cheap model for simple classification calls and a more powerful model for reasoning-heavy calls (capability scoring, gap resolution).

Zakardo does not require developers to use a Zakardo-managed LLM service. The developer provides their own API keys.

config/llm.ts
{
planner: {
llm: {
default: {
provider: 'openai',
model: 'gpt-4o',
api_key: process.env.OPENAI_API_KEY, // Developer's own key
api_base_url: process.env.OPENAI_BASE_URL, // Optional: custom endpoint (Azure OpenAI, proxy, etc.)
},
},
}
}

Multi-tenant BYOK (Zakardo Cloud scenario):

In multi-tenant deployments, different tenants may use different LLM providers or keys:

{
planner: {
llm: {
resolve: (user_context: UserContext) => {
// Per-tenant LLM configuration
const tenant_config = getTenantLLMConfig(user_context.tenant_id);
return {
provider: tenant_config.provider,
model: tenant_config.model,
api_key: tenant_config.api_key,
};
},
},
}
}

This enables:

  • Enterprise deployments: Each customer organization brings their own OpenAI/Anthropic key.
  • Compliance: Organizations that require data to stay in specific regions can point to region-specific LLM endpoints.
  • Cost control: Each tenant pays for their own LLM usage directly.

For LLM providers not built into Zakardo, developers implement the LLMProvider interface:

src/planner/my-llm-adapter.ts
import { defineLLMProvider } from '@zakardo/runtime';
export default defineLLMProvider({
model_id: 'my-company/internal-llm-v2',
supports_structured_output: true,
supports_streaming: false,
async chat(request) {
const response = await fetch('https://llm.internal.company.com/v1/chat', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.INTERNAL_LLM_KEY}` },
body: JSON.stringify({
messages: request.messages,
temperature: request.temperature,
max_tokens: request.max_tokens,
response_format: request.response_schema
? { type: 'json_object', schema: request.response_schema }
: undefined,
}),
});
const data = await response.json();
return {
content: data.choices[0].message.content,
usage: {
prompt_tokens: data.usage.prompt_tokens,
completion_tokens: data.usage.completion_tokens,
},
};
},
});
config/llm.ts
import myLLM from './src/planner/my-llm-adapter';
{
planner: {
llm: {
default: {
provider: myLLM,
},
},
}
}

If the primary LLM fails (timeout, invalid response, service down), the Planner can fall through a configured chain:

{
planner: {
llm: {
default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
fallback: [
{ provider: 'openai', model: 'gpt-4o' }, // Try OpenAI next
{ provider: 'ollama', model: 'llama3.1:70b' }, // Try local next
],
max_retries_per_provider: 2,
},
}
}

Fallback order:

  1. Retry the primary provider (up to max_retries_per_provider).
  2. Try each fallback provider in order.
  3. If all providers fail: fall back to Plan Library only (no generation).
  4. If no library match: return CONVERSE (“Planning service temporarily unavailable”).
  5. Record the full failure chain in the Planner Trace.

Every LLM call is recorded in the Planner Trace with token counts and timing:

interface LLMCallTrace {
call_type: string; // 'intent_classification', 'capability_scoring', etc.
provider: string;
model: string;
prompt_tokens: number;
completion_tokens: number;
duration_ms: number;
cached: boolean; // If the response was served from cache
retries: number;
fallback_used: boolean;
}

This enables:

  • Per-request cost attribution: How much did this planning session cost?
  • Per-tenant cost tracking: In multi-tenant BYOK, each tenant’s usage is tracked separately.
  • Optimization insights: Which call types are most expensive? Which could use a smaller model?

When a plan fails during execution, the Execution Engine may request the Planner to repair it.

interface PlanRepairRequest {
original_plan: PlanIR; // The plan that failed
failure: {
step_index: number; // Which step failed
error: CapabilityError; // The error that occurred
execution_trace: StepTrace[]; // What happened up to the failure
};
user_context: UserContext;
}

The Planner attempts repair in this order:

  1. Retry suggestion: If the error is TRANSIENT_ERROR and the capability is retry_safe: suggest retry (not a new plan, just a retry of the failed step).
  2. Step replacement: If the error is BUSINESS_ERROR and the failed capability has alternatives: propose a plan that replaces the failed step with an alternative capability.
  3. Partial re-plan: If the error invalidates downstream steps: re-run backward chaining from the point of failure, keeping successful steps.
  4. Full re-plan: If the plan is fundamentally broken: generate a new plan from scratch with the original intent + the failure context.
  5. Give up: If no repair is possible: return CONVERSE explaining the failure.

Repair returns a standard PlannerResponse:

  • GENERATE with a modified Plan Draft (for cases 2-4).
  • CONVERSE with explanation (for case 5).
  • The Planner Trace includes the repair context (what failed, what was attempted).

Any Planner implementation must conform to:

interface Planner {
resolve(request: PlannerRequest): Promise<PlannerResponse>;
repair(request: PlanRepairRequest): Promise<PlannerResponse>;
}

That’s it. Two methods.

The runtime ships with LLMPlanner, which implements the full pipeline described in this specification using an LLM for reasoning.

ImplementationStrategyWhen to Use
RuleBasedPlannerPattern matching on intent patterns, no LLMApplications with a fixed set of intents (kiosk, internal tools)
LibraryOnlyPlannerReturns only Plan Library matches, no generationProduction environments where all plans are pre-authored and validated
RemotePlannerForwards the PlannerRequest to an external HTTP serviceWhen the Planner logic lives in a separate service (microservice architecture)
HybridPlannerTries Library first, falls back to LLM only if no matchCost optimization — LLM calls only when needed

All implementations must:

  • Support all three response modes (GENERATE, CLARIFY, CONVERSE).
  • Perform policy pre-checks during capability selection.
  • Produce a PlannerTrace.
  • Respect the PlannerRequest/PlannerResponse contracts.

StageTarget LatencyNotes
Intent classification< 500msSingle LLM call
Plan Library search< 100msDatabase query + in-memory filtering
Goal identification< 500msSingle LLM call
Capability scoring (per selection)< 800msSingle LLM call with candidate list
Policy pre-check (per capability)< 50msIn-memory policy evaluation
Gap analysis< 100msSchema comparison, no LLM
Plan Draft assembly< 100msDeterministic, no LLM

Total target: < 3 seconds for a single-capability plan, < 5 seconds for a 3-step plan.

  1. Plan Library first: If a promoted plan matches, zero LLM calls. This is the most common production path.
  2. Packaged/structured intents: Skip intent classification. Save one LLM call.
  3. Capability pre-filtering by runtime: The LLM only scores capabilities the runtime has already filtered by schema, tags, and policy. The candidate list is typically 3-8 capabilities, not hundreds.
  4. Caching: Capability scores for common intent-capability pairs can be cached. Cache key: intent pattern + capability name + capability version.
  5. Low temperature: Using temperature 0.0-0.2 makes responses more deterministic and cacheable.

The Planner itself can fail (as distinct from returning CONVERSE, which is a graceful response):

ErrorCauseHandling
PLANNER_LLM_TIMEOUTLLM call exceeded timeoutRetry, then fallback to library-only
PLANNER_LLM_INVALID_RESPONSELLM returned unparseable outputRetry with same prompt
PLANNER_LLM_UNAVAILABLELLM service is downFallback to library-only
PLANNER_REGISTRY_ERRORCannot reach Capability RegistryReturn error to frontend (cannot plan without capabilities)
PLANNER_POLICY_ERRORPolicy Engine is unavailableReturn error to frontend (cannot plan without policy checks)
PLANNER_INTERNAL_ERRORUnexpected runtime errorReturn error to frontend with trace

All errors are recorded in the Planner Trace and propagated to the frontend as structured errors (not raw exceptions).

CONVERSE is a graceful, intentional response: “I can’t build a plan for this, and here’s why.” Error is an unexpected failure: “Something went wrong in the Planner itself.”

The frontend displays them differently. CONVERSE is conversational (“I can’t delete that account because you don’t have admin permissions. I can submit a deletion request instead.”). Errors are system-level (“The planning service is temporarily unavailable. Please try again.”).


The Planner’s LLM receives user input (the intent). This creates prompt injection risk.

Mitigations:

  1. Input sanitization: The Runtime API sanitizes intents before they reach the Planner (strip control characters, limit length, detect known injection patterns).
  2. Structured prompts: The system prompt and capability context are provided in system/assistant roles. User input is always in the user role. The LLM is instructed to treat user messages as data, not instructions.
  3. Output validation: Every LLM response is validated against its expected schema. If the response doesn’t conform, it’s rejected and retried.
  4. Capability-only execution: Even if an injection succeeds in influencing capability selection, the Planner can only select registered capabilities. It cannot invent new ones or execute arbitrary code.
  5. Policy enforcement: Even a manipulated plan goes through the Validator and per-step policy checks. A prompt injection cannot bypass policy.

The Planner’s LLM receives:

  • The user’s intent (expected — this is the input)
  • Capability names, descriptions, and schema summaries (not sensitive — these are metadata)
  • User roles (for policy context)

The Planner’s LLM does not receive:

  • Business data from the database
  • Other users’ data or intents
  • Full capability implementations
  • Policy rule details (only the ALLOWED/DENIED result)

DecisionResolution
Planner interfaceresolve(PlannerRequest): PlannerResponse + repair(PlanRepairRequest): PlannerResponse. Two methods.
Three response modesGENERATE (Plan Draft), CLARIFY (structured question with options), CONVERSE (conversational response with reason code)
StatelessNo state between invocations. All context provided per request. Multi-turn clarification uses conversation_history.
PluggableDefined interface. Default is LLM-based. Alternatives: rule-based, library-only, remote, hybrid.
Pipeline architectureSequential stages: classify → library search → goal ID → backward chaining → assembly → trace
Policy pre-check is mandatoryPart of the interface contract. All implementations must check both system-level policy and capability-level constraints.
Plan Library is the fast pathHigh-confidence matches skip generation entirely. Zero LLM calls for promoted plans.
Layered prompt architectureSix layers: Zakardo core (built-in) → application context (developer) → capability context (auto) → planning hints (developer) → user context (auto) → user message. Developer controls layers 2 and 4.
Multiple focused LLM callsNot one mega-prompt. Each call has one purpose, expects structured JSON output, and uses only the relevant prompt layers.
Application contextDeveloper provides domain description, business rules, and tone in config/llm.ts. Injected into every LLM call.
Planning hintsDeveloper-injected, domain-specific guidance. Can be global (tag-filtered) or per-request. Per-request planning data resolves gaps automatically.
Multi-provider supportAbstracted via LLMProvider interface. Built-in: OpenAI, Anthropic, Ollama, custom. Per-call-type model overrides supported.
BYOK (Bring Your Own Key)Developer provides their own LLM API keys. Multi-tenant BYOK via resolver function. No Zakardo-managed LLM required.
LLM fallback chainPrimary → fallback providers → Plan Library only → CONVERSE. Full failure chain recorded in trace.
Per-call-type model routingFast/cheap models for classification, powerful models for reasoning. Configured in planner.llm.overrides.
LLM cost trackingEvery call tracked: tokens, duration, provider, cache status. Enables per-request and per-tenant cost attribution.
Goal adjustment on policy blockWhen the original goal is blocked, the Planner adjusts and informs the user (goal_adjusted flag).
Clarification is multi-turnUp to 5 rounds. Conversation history passed in each request.
Plan repairRetry → step replacement → partial re-plan → full re-plan → give up.
Prompt injection defenseInput sanitization + role separation + output validation + capability-only execution + policy enforcement.
Planner TraceEvery invocation produces a structured trace of all decisions, scores, LLM calls, and timing.
Latency target< 3s for single-cap plans, < 5s for 3-step plans. Plan Library matches are < 200ms.
TypeScript-firstPlanner interface and default implementation are TypeScript. RemotePlanner allows any language.

QuestionDeferred To
How exactly are Plan Library intent patterns authored and managed?Plan Library and Lifecycle Specification
What is the exact prompt template for each LLM call?Implementation detail, not spec. Will be documented in the runtime codebase.
How does semantic embedding work for plan matching?Plan Library and Lifecycle Specification
How does the Planner handle concurrent requests?Runtime API and SDK Specification
How is Planner performance monitored?Trace System Specification
How does the Training System evaluate Planner quality?Training and Validation Specification
How does the frontend display CLARIFY options?Frontend Architecture Specification