Struct SystemPromptBuilder 

pub struct SystemPromptBuilder { /* private fields */ }

Builder for assembling a system prompt from multiple components.

The builder uses a fluent API to configure each component of the system prompt. Components are assembled in a fixed order optimized for LLM provider caching: stable sections first, then semi-stable, then dynamic.

Component Order

1. Identity (or custom prompt if provided)
2. Tool descriptions
3. Skill index (Level 0)
4. Context files (AGENTS.md)
5. User preferences
6. Append prompt (if provided)

Example

use talos_agent::prompt::SystemPromptBuilder;

let prompt = SystemPromptBuilder::new()
    .with_user_preferences("Always use British English.".into())
    .build();

Implementations

impl SystemPromptBuilder

pub fn new() -> Self

Creates a new builder with the default identity and no other components.

All optional components start empty. Use the builder methods to configure tools, skills, context files, and other components.

pub fn with_strict_tool_format(self) -> Self

pub fn with_tool_format(self, format: &'static str) -> Self

pub fn with_template_var( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Sets a template slot value for {{slot}} substitution.

pub fn with_workspace_info(self, value: impl Into<String>) -> Self

Sets workspace information for the default identity template.

pub fn with_model_info(self, value: impl Into<String>) -> Self

Sets model information for the default identity template.

pub fn with_tools(self, tools: Vec<ToolDescription>) -> Self

Sets the tool descriptions for inclusion in the system prompt.

Tools are sorted alphabetically by name to ensure stable ordering across turns, maximizing cache hit rates.

pub fn with_skill_index(self, skills: Vec<SkillIndex>) -> Self

Sets the skill index for inclusion in the system prompt.

Only Level 0 metadata (name, description, triggers) is included. Full skill bodies are not loaded at this stage.

pub fn with_activated_skill(self, skill: Option<ActivatedSkillContext>) -> Self

Sets the explicitly activated Skill context.

This content is cacheable after activation. The owning Agent invalidates the stable-prefix cache whenever activation changes.

pub fn with_context_files(self, files: Vec<ContextFile>) -> Self

Sets the context files for inclusion in the system prompt.

Typically loaded from AGENTS.md files via ContextLoader.

pub fn with_user_preferences(self, prefs: String) -> Self

Sets user-specific instructions for inclusion in the system prompt.

pub fn with_memory_section(self, section: Option<String>) -> Self

Sets a bounded memory section for inclusion in the system prompt.

Memory is advisory only — never authoritative over session context. When None, no memory section is injected.

pub fn with_todo_section(self, section: Option<String>) -> Self

Sets a bounded session todo section for inclusion in the dynamic prompt suffix.

Todo context is advisory orchestration state. It is intentionally not part of the stable cached prefix because it can change between turns.

pub fn with_custom_prompt(self, prompt: String) -> Self

Sets a custom prompt that replaces the default identity.

When provided, the custom prompt is used instead of the default identity. The rest of the prompt (tools, skills, etc.) is still assembled normally.

pub fn with_append_prompt(self, prompt: String) -> Self

Sets an append prompt that is added at the end of the system prompt.

The append prompt is always placed last, after all other components.

pub fn clear_append_prompt(&mut self)

Clears the append prompt, removing any previously set value.

pub fn set_append_prompt_opt(&mut self, prompt: Option<String>)

Sets the append prompt to an optional value.

Use None to clear the append prompt, or Some(prompt) to set it.

pub fn build(&self) -> String

Assembles and returns the final system prompt as a string.

Components are assembled in the optimal order for caching:

1. Identity (or custom prompt if provided)
2. Tools (sorted by name)
3. Skill index
4. Context files
5. User preferences
6. Append prompt (if provided)

Empty components are omitted from the output.

pub fn build_stable_prefix(&self) -> String

Builds only the stable prefix (Identity + Tools + Skills).

These sections are cacheable and do not change between turns unless tools, skills, or the identity/custom prompt are modified. The result can be cached by the caller and reused across turns.

Returns None if there are no stable sections (should not happen in practice since Identity is always present).

pub fn build_dynamic_suffix(&self) -> String

Builds only the dynamic suffix (Context + User Preferences + Runtime + Append).

These sections change every turn (e.g., datetime) or are semi-stable (context files, user preferences). Combined with a cached stable prefix, they form the complete system prompt.

pub fn build_with_cache_markers(&self) -> (String, Vec<CacheMarker>)

Assembles the system prompt with cache control markers.

Returns the prompt string and a list of CacheMarkers indicating which byte ranges are stable and suitable for provider caching.

Cacheable sections:

• Identity (or custom prompt)
• Tools
• Skill index

Semi-stable sections (context files, user preferences) and the append prompt are not marked for caching.

pub fn total_tokens(&self) -> usize

Estimates the total token count of the assembled prompt.

Uses a heuristic of 1 token per 4 characters, which is a reasonable approximation for English text. This is not exact and should not be used for billing purposes.

pub fn log_size(&self)

Logs the prompt size for debugging purposes.

Prints the character count and estimated token count to stderr. This is useful for monitoring prompt size during development.

Trait Implementations

impl Clone for SystemPromptBuilder

fn clone(&self) -> SystemPromptBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SystemPromptBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SystemPromptBuilder

fn default() -> Self

Returns the “default value” for a type.