# 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)

```mermaid
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.

```bash
# 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.

```bash
# 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.

```bash
# 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](./advanced.md#processing-multiple-items---each) and [Examples](./examples.md#iterating-with---each) for detailed usage and examples.