mono/packages/kbot/docs_/modes.md

KBot Operational Modes

kbot operates in different modes specified by the --mode parameter. Each mode dictates how the AI processes input, whether it can use tools, and how output is handled.

Execution Flow Overview

(Mermaid diagrams illustrate the general flow for different modes - minor updates might be needed if diagrams become outdated)

sequenceDiagram
    participant User
    participant KBot
    participant Client
    participant AI
    participant FileSystem

    User->>KBot: Run command with options (prompt, mode, include, etc.)
    KBot->>KBot: Parse options (OptionsSchema)
    KBot->>KBot: Process `--each` parameter (if present)

    loop For each item (if --each specified)
        KBot->>KBot: Create API client (based on router, key)
        KBot->>KBot: Load profile & variables
        KBot->>FileSystem: Gather input content (--include: files, URLs)
        KBot->>KBot: Prepare messages (prompt, preferences, input content)
        KBot->>KBot: Load & configure tools (if mode supports tools)
        KBot->>Client: Create API request parameters (model, messages, tools)
        Client->>AI: Send API request

        alt mode=completion
            AI->>Client: Generate text response
            Client->>KBot: Return response
            KBot->>KBot: Apply filters (if specified)
            KBot->>FileSystem: Save filtered response to --dst location
        else mode=tools
            AI->>Client: Request tool calls
            Client->>KBot: Execute requested tools (e.g., FileSystem access)
            KBot->>Client: Provide tool results
            Client->>AI: Send tool results
            AI->>Client: Final response (may include summary of actions)
            Client->>KBot: Return final response
            KBot->>User: Output response (modified files handled by tools, optionally guided by --output)
        else mode=assistant
            AI->>Client: Process document content (using built-in retrieval/analysis)
            Client->>KBot: Return response
            KBot->>FileSystem: Save response to --dst location
        else mode=custom
            Note over KBot, AI: Custom interaction flow defined by implementation
            KBot->>User: Return custom result
        end

        AI->>Client: (Error Handling / Retries)
        Client->>KBot: Return final result/error for the item
        KBot->>KBot: Collect item result
    end

    KBot->>User: Return aggregated results (if --each used)

Mode Descriptions

1. completion Mode (--mode=completion)

• Purpose: Direct text generation based on the prompt and included context.
• Tools: Not supported.
• Output: The generated text response.
• Saving: Requires the --dst parameter to specify a file path for saving the output.
• Filters: Output can be processed by filters specified via the --filters parameter before saving.
• Use Cases: Summarization, translation, question answering, content generation where no external actions are needed.

# Example: Summarize a web page
kbot --mode=completion \
     --include "https://example.com/article" \
     --prompt "Provide a 3-sentence summary of this article" \
     --dst "./summary.txt"

2. tools Mode (--mode=tools, Default)

• Purpose: Allows the AI to interact with the local environment using available tools (e.g., file system operations, code execution, web searches).
• Tools: Supported and enabled by default (can be configured via --tools, --disable, --disableTools).
• Output: Typically involves actions performed by tools (e.g., files modified, commands run). The final AI response might summarize actions taken.
• Saving: File modifications are handled directly by tools. The --output parameter can sometimes guide tools on where to place results if they create new files relative to a target directory.
• Use Cases: Code refactoring, file generation, running tests, automating workflows, interacting with APIs via tools.
• Note: Tool support depends on the specific AI model being used.

# Example: Refactor code in specified files
kbot --mode=tools \
     --include "./src/**/*.js" \
     --prompt "Refactor all functions in these files to use arrow syntax"

3. assistant Mode (--mode=assistant)

• Purpose: Specialized for interacting with and analyzing document files (e.g., PDF, DOCX).
• Tools: Not supported. Relies on the AI provider's built-in document handling capabilities (if available).
• Output: An analysis or response based on the content of the included documents.
• Saving: Requires the --dst parameter to save the AI's response.
• Use Cases: Analyzing reports, extracting information from PDFs, question answering based on uploaded documents.

# Example: Extract key points from a PDF report
kbot --mode=assistant \
     --include "./reports/annual_report.pdf" \
     --prompt "Extract the main financial highlights from this report" \
     --dst "./financial_highlights.md"

4. custom Mode (--mode=custom)

• Purpose: Reserved for specific, user-defined operational flows that don't fit the standard modes.
• Behavior: Defined by the specific implementation integrating with kbot.

Iteration with --each

The --each parameter enables running a kbot task iteratively over multiple items (files, model names, strings). This is powerful for batch processing or comparative testing.

• It accepts comma-separated strings, GLOB patterns, JSON file paths, or arrays.
• The current item is available via the ${ITEM} variable for use in other parameters (--dst, --prompt, --include).
• If an item matches a known model ID, --model is automatically set for that iteration.

Refer to Advanced Topics and Examples for detailed usage and examples.