mono/packages/kbot/docs/modes.md

KBot Run Modes

KBot supports several run modes that determine how it processes inputs and generates outputs. This document provides an overview of each mode and how they work.

Command Execution Flow

sequenceDiagram
    participant User
    participant KBot
    participant Client
    participant AI
    participant FileSystem

    User->>KBot: Run command with options
    KBot->>KBot: Parse options (OptionsSchema)
    KBot->>KBot: Process 'each' parameter (if present)
    
    loop For each item (if --each specified)
        KBot->>KBot: Create client
        KBot->>KBot: Load profile & variables
        KBot->>FileSystem: Gather files (--include)
        KBot->>KBot: Prepare messages
        KBot->>KBot: Configure tools (based on mode)
        KBot->>Client: Create request params
        Client->>AI: Send API request
        
        alt mode=completion
            AI->>Client: Generate text output
            Client->>FileSystem: Save to --dst location
        else mode=tools
            AI->>Client: Tool function calls
            Client->>FileSystem: Perform file operations
            Client->>FileSystem: Optional save to --output
        else mode=assistant
            AI->>Client: Process document content
            Client->>FileSystem: Save to --dst location
        end
        
        AI->>Client: Final response
        Client->>KBot: Return result
        KBot->>KBot: Apply filters (if specified)
        KBot->>KBot: Collect result in array
    end
    
    KBot->>User: Return results

Run Modes Overview

graph TD
    A[KBot Command] --> B{Mode Selection}
    B -->|mode=completion| C[Completion Mode]
    B -->|mode=tools| D[Tools Mode]
    B -->|mode=assistant| E[Assistant Mode]
    B -->|mode=custom| F[Custom Mode]
    
    C --> G[Simple Text Output]
    D --> H[Tool-Assisted Output]
    E --> I[Document Processing]
    F --> J[User-Defined Behavior]

Completion Mode

The simplest mode that generates text without using tools. Best for straightforward prompts.

graph LR
    A[Input] --> B[Completion Mode]
    B --> C[Text Output]
    C --> D[Save to --dst]
    C --> E[Apply Filters]

Key features:

• No support for tools
• Requires --dst parameter to save output
• Can use filters to process output
• Best for: summaries, transformations, simple Q&A

Example command:

kbot --mode=completion --prompt="Summarize this document" --include=README.md --dst=summary.md

Tools Mode

Allows the model to use tools to perform actions like modifying files or accessing external information.

graph TD
    A[Input] --> B[Tools Mode]
    B --> C{Tool Selection}
    C --> D[File Operations]
    C --> E[Web Search]
    C --> F[Shell Commands]
    C --> G[Other Tools...]
    D --> H[Output with File Changes]
    E --> H
    F --> H
    G --> H
    H --> I[Optional --output]

Key features:

• Enables AI to use various tools
• Can modify files directly
• Optional --output parameter for modified files
• Not all models support this mode
• Best for: code modifications, contextual tasks, complex file operations

Example command:

kbot --mode=tools --prompt="Refactor this function to be more efficient" --include=src/utils.js

Assistant Mode

Specialized for document processing, allowing PDF, DOCX and other document formats to be analyzed.

graph LR
    A[Documents] --> B[Assistant Mode]
    B --> C[Document Analysis]
    C --> D[Text Output]
    D --> E[Save to --dst]

Key features:

• Supports document formats (PDF, DOCX, etc.)
• No tool support
• Requires --dst to save output
• Best for: document analysis, content extraction

Example command:

kbot --mode=assistant --prompt="Extract key points" --include=docs/report.pdf --dst=key-points.md

Custom Mode

For specialized use cases with user-defined behavior.

The "each" Parameter

The each parameter allows KBot to iterate over multiple items, running the same process for each one.

graph TD
    A[KBot with --each] --> B{Source Type}
    B -->|Comma-separated list| C[List of strings]
    B -->|File path| D[JSON file]
    B -->|GLOB pattern| E[Matching files]
    B -->|Array| F[Array of items]
    
    C --> G[For each item]
    D --> G
    E --> G
    F --> G
    
    G --> H[Run process]
    H --> I[Collect results]
    
    J[Model names] --> G
    G --> K[Set ITEM variable]
    K --> L[Can be used in other parameters]
    L --> M["--dst=${ITEM}-output.md"]

How "each" Works

1. KBot accepts the --each parameter with various inputs:

   • Comma-separated string (e.g., --each="gpt-3.5-turbo,gpt-4o")
   • Path to a JSON file containing an array
   • GLOB pattern matching multiple files
   • Array of strings

2. For each item:

   • The value is exposed as the ITEM variable
   • If the item matches a model ID, it automatically sets that as the model
   • The item is added to the include list for processing
   • The process is run with these modified options
   • Results are collected into an array

Special Case: Model Testing

A powerful use case is testing multiple AI models with the same prompt:

kbot --mode=completion --prompt="Solve this problem" --each="gpt-3.5-turbo,gpt-4o,claude-3-opus" --dst="${ITEM}-solution.md"

This will:

1. Run the same prompt with three different models
2. Save each result to a separate file named after the model
3. Allow you to compare results across models

"each" Parameter Processing Flow

flowchart TD
    Start([Start]) --> ParseEach{Parse --each\nparameter}
    
    ParseEach -->|is Array| A[Use directly]
    ParseEach -->|is JSON file path| B[Read JSON array]
    ParseEach -->|is GLOB pattern| C[Get matching files]
    ParseEach -->|is single file| D[Use as one-item array]
    ParseEach -->|is comma-separated string| E[Split into array]
    
    A --> ItemsArray[Items Array]
    B --> ItemsArray
    C --> ItemsArray
    D --> ItemsArray
    E --> ItemsArray
    
    ItemsArray --> CheckEmpty{Items\nempty?}
    CheckEmpty -->|Yes| LogWarning[Log warning] --> End([End])
    
    CheckEmpty -->|No| LogInfo[Log processing info]
    LogInfo --> GetAllModels[Get all available models]
    
    GetAllModels --> ProcessItems[Process first item]
    
    subgraph ItemProcessing [Item Processing Loop]
        ProcessItems --> CreateItemOpts[Create item options:\n- Set ITEM variable\n- Add to variables]
        CreateItemOpts --> CheckModel{Item matches\nmodel ID?}
        CheckModel -->|Yes| SetModel[Set model to item]
        CheckModel -->|No| SkipModelSet[Skip model override]
        SetModel --> UpdateIncludes[Add item to includes]
        SkipModelSet --> UpdateIncludes
        UpdateIncludes --> RunProcess[Run processRun]
        RunProcess --> CheckResult{Result defined?}
        CheckResult -->|Yes| AddToResults[Add to results array]
        CheckResult -->|No| SkipAddResult[Skip]
        AddToResults --> NextItem{More items?}
        SkipAddResult --> NextItem
        NextItem -->|Yes| ProcessNext[Process next item] --> CreateItemOpts
    end
    
    NextItem -->|No| ReturnResults[Return results array]
    ReturnResults --> End

This detailed flow shows exactly how KBot processes the each parameter, from initial parsing through the execution loop for each item.

Variable Substitution

The ITEM variable can be used in other parameters:

• --dst="${ITEM}-output.md" - Creates unique output files
• Path templating with ${MODEL_NAME} and ${ROUTER}
• Accessible in prompts via variable substitution