124 lines
6.0 KiB
Markdown
124 lines
6.0 KiB
Markdown
# 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. |