Skip to content

Text Replacements

Raikoo's text replacements are an essential tool for creating dynamic, data-driven, and highly-targeted prompts in your workflows. By using text replacements, you can transform static text into adaptive, responsive content based on the real-time state of your running workflow. This guide will walk you through how to use these powerful features effectively.

Syntax Overview

Raikoo uses Handlebars, a popular templating language that allows you to construct complex text content in a data-driven way. Handlebars provides a comprehensive set of features including:

  • Data binding
  • Conditionals
  • Loops
  • Comments

For complete information on Handlebars syntax and capabilities, refer to the Handlebars guide.

Available Text Replacements

Raikoo provides several context types for replacements, each offering specific data points you can reference in your operations. Here's a comprehensive list of all available replacement contexts:

System Replacement Context

This context contains general system information.

  • {{System.DateTime}}: The current system date and time in ISO 8601 format, e.g.: 

    2024-11-26T05:51:56.844Z

  • {{System.DateTimeString}}: The current system date and time in a prompt-friendly string format, e.g.: 

    The current date and time is 11/26/2024, 12:54:04 AM and the ISO 8601 representation of it is `2024-11-26T05:54:04.032Z`.

Persona Replacement Context

This context contains information about the selected persona.

  • {{Persona.Alignment}}: The selected persona alignment text.

Last Operation Replacement Context

This context contains information from the previous operation.

  • {{LastOperation.Output}}: The final output of the last operation performed.

Project Context Replacement Context

This context contains the Project Context entries of the project you are working within.

  • {{ProjectContext.<key>}}: Custom key-value pairs describing the context of a project. Replace <key> with a specific key from the project context.

Operation Replacement Context

This context contains information relating to the operation.

  • {{Operation.Request}}: The current user request driving the operation.

Operation Parameters Replacement Context

  • {{OperationParameters.<key>}}: Custom operation parameters defined for the operation. Replace <key> with a specific parameter name (case sensitive).

Operation Processor Replacement Context

This context contains information about the current operation processor that might be useful to control LLM output.

  • {{OperationProcessor.JSONSchema}}: The output format schema as JSON Schema.

  • {{OperationProcessor.OutputFormat}}: The output format schema formatted for presentation in prompts.

Workflow Parameters Replacement Context

This context contains the current values of the parent workflow's parameters.

  • {{WorkflowParameters.<key>}}: Custom workflow parameters. Replace <key> with the parameter name (case sensitive).

Workspace Replacement Context

This context contains a text representation of all current files in the workspace.

  • {{Workspace.[/path/to/file.ext]}}: Contents of a file in the workspace as text.

Wrapper Operation Replacement Context

This context contains information from a parent wrapper operation (such as an iterator operation). You can find more information about these wrapper operations and their replacements in the Iterator Operations guide.

  • {{WrapperOperation.<key>}}: Wrapper operation replacement value. Replace <key> with the specific value name (case sensitive).

Text Helpers

Available Text Helpers

  • guid or uuid: Generate a UUID.
{{uuid}}
{{guid}}
  • toUpperCase: Uppercase a string value.
{{toUpperCase "hello world"}}
  • toLowerCase: Lowercase a string value.
{{toLowerCase "HELLO WORLD"}}
  • replace: Replace a single instance match with another string.
{{replace "HAYSTACK" "needle" "replacement"}}
  • replaceAll: Replace all matches of a string with another string.
{{replaceAll "HAYSTACK" "needle" "replacement"}}
  • formatDate: Format a date using Day.js syntax.
{{formatDate}}
{{formatDate "YYYY-MM-DD"}}
{{formatDate "YYYY-MM-DD" "2024-12-31T12:00:00.000Z"}}
{{formatDate "MM/DD/YYYY" (readFile "/text.txt")}}

Working with Data

Beyond simply referencing files and text, you can use Handlebars syntax along with custom helpers to work with structured data. Raikoo supports the following data format types: JSON, YAML, and CSV.

Available Data Helpers

  • parseCsv: Parse a CSV string into a JSON array. Headers are not supported at this time.
{{!--
  Parse the workspace file as a CSV array, get the first data item
  of the first row
--}}
{{#with (parseCsv Workspace.[/data/array.csv]) as | data |}}
{{data.[0].[1]}}
{{/with}}
  • parseJson: Parse a JSON string into JSON.
{{!--
  Parse the workspace file as a JSON array, get the first message
--}}
{{#with (parseJson Workspace.[/data/array.json]) as | data |}}
{{data.[0].message}}
{{/with}}

{{!--
  Parse the workspace file as a JSON object, get the message
--}}
{{#with (parseJson Workspace.[/data/object.json]) as | data |}}
{{data.message}}
{{/with}}
  • parseYaml: Parse a YAML string into JSON.
{{!--
  Parse the workspace file as a YAML array, get the first message
--}}
{{#with (parseYaml Workspace.[/data/array.yaml]) as | data |}}
{{data.[0].message}}
{{/with}}

{{!--
  Parse the workspace file as a YAML object, get the message
--}}
{{#with (parseYaml Workspace.[/data/object.yml]) as | data |}}
{{data.message}}
{{/with}}
  • parse: Attempt to parse a file as data, falling back to using the file's text instead.
{{!--
  Parse the workspace file, get the first message
--}}
{{#with (parse Workspace.[/data/array.yaml]) as | data |}}
{{data.[0].message}}
{{/with}}

Advanced Usage Techniques

Conditional Content

You can use Handlebars conditional blocks to include or exclude content based on parameter values:

{{#if WorkflowParameters.includeDetails}}
## Detailed Analysis
This section includes a comprehensive breakdown of each component...
{{else}}
## Summary
This is a brief overview of the key points...
{{/if}}

Iteration Over Collections

Loop through arrays or collections to generate content for each item:

{{#each (parseJson Workspace.[/data/users.json])}}
## User Profile: {{this.name}}
- Email: {{this.email}}
- Role: {{this.role}}
- Access Level: {{this.accessLevel}}

{{/each}}

Nested Helpers

Combine multiple helpers for more complex transformations:

{{#with (parseJson (Workspace.[/data/config.json])) as |config|}}
  {{#each config.users}}
    {{#if this.active}}
      - {{this.name}} ({{this.email}})
    {{/if}}
  {{/each}}
{{/with}}

Using Built-in Block Helpers

Handlebars provides several built-in block helpers that can be useful:

  • {{#if}} / {{else}} - Conditional blocks
  • {{#each}} - Iteration over arrays
  • {{#with}} - Change the context for a block
  • {{#unless}} - Inverse of if (executes if the condition is falsy)

Custom Formatting

You can apply transformations to your data within templates:

{{!-- Format a date string --}}
Report generated on: {{formatDate System.DateTime "YYYY-MM-DD"}}

{{!-- Convert text to uppercase --}}
PROJECT NAME: {{uppercase WorkflowParameters.projectName}}

Best Practices

Organizing Complex Templates

For complex templates:

  1. Break down large templates into smaller components
  2. Store reusable template parts in separate workspace files
  3. Use comments to document complex logic
  4. Consider using helper functions for repeated operations

Performance Considerations

  • Avoid very large data structures in templates
  • Cache parsed data when used multiple times
  • Consider pre-processing complex data in a dedicated operation

Error Handling

Implement fallbacks for missing data:

{{WorkflowParameters.userName default="Anonymous User"}}

{{#if Workspace.[/optional-data.json]}}
  {{!-- Process the file if it exists --}}
  {{#with (parseJson Workspace.[/optional-data.json]) as |data|}}
    {{data.field}}
  {{/with}}
{{else}}
  {{!-- Default content if file doesn't exist --}}
  No additional data available.
{{/if}}

Example Scenarios

Dynamic Prompt Construction

Create AI prompts that adapt based on available data:

You are an AI assistant tasked with analyzing {{WorkflowParameters.documentType}} documents.

{{#if WorkflowParameters.specificIndustry}}
Use your knowledge of the {{WorkflowParameters.specificIndustry}} industry for this analysis.
{{/if}}

Please analyze the following content:

{{Workspace.[/input-document.txt]}}

{{#if WorkflowParameters.includeSummary}}
Provide a concise summary at the beginning of your response.
{{/if}}

{{#if WorkflowParameters.formatAsJSON}}
Return your analysis in JSON format.
{{/if}}

Data Transformation

Process and reformat data between operations:

{{#with (parseJson Workspace.[/api-response.json]) as |data|}}
# Analysis Results

## Overview
{{data.summary}}

## Key Metrics
{{#each data.metrics}}
- **{{this.name}}**: {{this.value}}{{#if this.unit}} {{this.unit}}{{/if}}
{{/each}}

## Recommendations
{{#each data.recommendations}}
1. {{this.title}}: {{this.description}}
{{/each}}
{{/with}}

Multi-file Processing

Reference multiple files to create consolidated output:

# Project Status Report

## Project: {{WorkflowParameters.projectName}}
**Date:** {{System.DateTimeString}}

## Recent Updates
{{Workspace.[/updates/recent.md]}}

## Issue Summary
{{#with (parseJson Workspace.[/issues/summary.json]) as |issues|}}
Total open issues: {{issues.totalOpen}}
Critical issues: {{issues.critical}}
High priority: {{issues.high}}
{{/with}}

## Team Productivity
{{Workspace.[/metrics/team-productivity.md]}}

Conclusion

Text replacements provide a powerful way to create dynamic, context-aware content in your Raikoo workflows. By mastering Handlebars templating and the various replacement contexts available, you can build sophisticated workflows that adapt to changing inputs and conditions, resulting in more flexible and robust AI solutions.