266 lines
12 KiB
Markdown
266 lines
12 KiB
Markdown
# @plastichub/kbot
|
|
|
|
AI-powered command-line tool for code modifications and project management that supports multiple AI models and routers.
|
|
|
|
## Overview
|
|
|
|
Code-bot is a powerful CLI tool that helps developers automate code modifications, handle project management tasks, and integrate with various AI models for intelligent code and content assistance.
|
|
|
|
## Quick Start
|
|
|
|
### Installation Steps
|
|
|
|
KBot requires Node.js to run. It's recommended to use Node.js version 18 or higher.
|
|
|
|
1. Visit the official [Node.js website](https://nodejs.org/)
|
|
2. Download the LTS (Long Term Support) version for your operating system
|
|
3. Follow the installation wizard
|
|
4. Verify installation by opening a terminal and running:
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
### API Keys
|
|
|
|
KBot supports both OpenRouter and OpenAI APIs. You'll need at least one of these set up.
|
|
|
|
#### OpenRouter API (Recommended)
|
|
|
|
1. Visit [OpenRouter](https://openrouter.ai/)
|
|
2. Sign up for an account
|
|
3. Navigate to the API Keys section
|
|
4. Create a new API key
|
|
|
|
#### OpenAI API (Optional)
|
|
|
|
1. Go to [OpenAI's platform](https://platform.openai.com/)
|
|
2. Create an account or sign in
|
|
3. Navigate to API keys section
|
|
4. Create a new secret key
|
|
|
|
### Installation using Node NPM package manager
|
|
|
|
```bash
|
|
npm install -g @plastichub/kbot
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### API Keys Setup
|
|
|
|
Create configuration at `$HOME/.osr/.config.json` (or export OSR_CONFIG with path to config.json):
|
|
|
|
```json
|
|
{
|
|
"openrouter": {
|
|
"key": "your-openrouter-key"
|
|
},
|
|
"openai": {
|
|
"key": "your-openai-key"
|
|
},
|
|
"email": {
|
|
"newsletter": {
|
|
"host": "host.org",
|
|
"port": 465,
|
|
"debug": true,
|
|
"transactionLog": true,
|
|
"auth": {
|
|
"user": "foo@bar.com",
|
|
"pass": "pass"
|
|
}
|
|
}
|
|
},
|
|
"google": {
|
|
"cse": "custom search engine id",
|
|
"api_key": "google custom search api key"
|
|
},
|
|
"serpapi": {
|
|
"key": "your SerpAPI key (optional, used for web searches(places, google maps))"
|
|
},
|
|
"deepseek": {
|
|
"key": "your SerpAPI key (optional, used for web searches(places, google maps))"
|
|
},
|
|
}
|
|
```
|
|
|
|
### Preferences Setup
|
|
|
|
Optionally, create `.kbot/preferences.md` in your project directory to customize AI interactions:
|
|
|
|
```markdown
|
|
## My Preferences
|
|
|
|
Gender : male
|
|
Location : New York, USA (eg: `send me all saunas next to me`)
|
|
Language : English
|
|
Occupation : software developer, Typescript
|
|
Age : 30+
|
|
|
|
## Contacts
|
|
|
|
My email address : example@email.com (eg: `send me latest hacker news`)
|
|
My wife's email address ("Anne") : example@email.com (eg: `send email to my wife, with latest local news')
|
|
|
|
## Content
|
|
|
|
When creating content
|
|
- always Markdown
|
|
- always add links
|
|
- when sending emails, always add 'Best regards, [Your Name]'
|
|
```
|
|
# Main Commands
|
|
|
|
The primary way to interact with `kbot` for processing tasks is by invoking it with a prompt and various options. While often used implicitly, this typically corresponds to the `run` command.
|
|
|
|
## Running Tasks
|
|
|
|
```bash
|
|
kbot run [options...] "Your prompt here..."
|
|
# or simply (if 'run' is the default):
|
|
kbot [options...] "Your prompt here..."
|
|
```
|
|
|
|
This command executes the main AI processing pipeline based on the provided prompt and options. Key aspects controlled by options include:
|
|
|
|
* **Input:** Specified via `--include` (files, directories, web URLs), `--path`.
|
|
* **Task:** Defined by the `--prompt`.
|
|
* **Behavior:** Controlled by `--mode` (e.g., `tools`, `completion`).
|
|
* **Output:** Directed using `--dst` or `--output`.
|
|
* **Model & API:** Configured with `--model`, `--router`, `--api_key`, etc.
|
|
|
|
Refer to [Parameters](./parameters.md) and [Modes](./modes.md) for detailed options.
|
|
|
|
## Utility Commands
|
|
|
|
Other potential utility commands might include:
|
|
|
|
* `kbot fetch`: Fetch updated information, such as the latest available models.
|
|
* `kbot init`: Initialize a directory or project for use with `kbot` (e.g., create default config files).
|
|
* `kbot help-md`: Generate extended help documentation in Markdown format.
|
|
* `kbot examples`: Show example usage patterns.
|
|
|
|
*(Note: Availability and exact behavior of utility commands may vary.)*
|
|
# Command Line Parameters
|
|
|
|
This document describes the command line parameters available for `kbot`.
|
|
|
|
**Note:** Many parameters support environment variable substitution (e.g., `${VAR_NAME}`).
|
|
|
|
## Core Parameters
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `prompt` | The main instruction or question for the AI. Can be a string, a file path (e.g., `file:./my_prompt.md`), or an environment variable. | - | Yes (or implied by context) |
|
|
| `model` | AI model ID to use for processing (e.g., `openai/gpt-4o`). See available models via helper functions or router documentation. | Depends on router/config | No |
|
|
| `router` | The API provider to use. | `openrouter` | No |
|
|
| `mode` | The operational mode. See [Modes](./modes.md) for details. | `tools` | No |
|
|
|
|
## Input & File Selection
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `path` | Target directory for local file operations or context. | `.` | No |
|
|
| `include` | Specify input files or content. Accepts comma-separated glob patterns (e.g., `src/**/*.ts`), file paths, directory paths, or **web URLs** (e.g., `https://example.com/page`). | `[]` | No |
|
|
| `exclude` | Comma-separated glob patterns or paths to exclude from processing (e.g., `src/**/*.test.ts,temp/`). | `[]` | No |
|
|
| `globExtension` | Specify a glob extension behavior to find related files. Available presets: `match-cpp`. Also accepts a custom glob pattern with variables like `${SRC_DIR}`, `${SRC_NAME}`, `${SRC_EXT}` (e.g., `"${SRC_DIR}/${SRC_NAME}*.h"` to find headers for a .cpp file). | - | No |
|
|
| `query` | JSONPath query to extract specific data from input objects (often used with structured input files). | `null` | No |
|
|
|
|
## Output & Formatting
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `output` | Output path for modified files (primarily for `tools` mode operations like refactoring). | - | No |
|
|
| `dst` | Destination path/filename for the main result (primarily for `completion` or `assistant` mode). Supports `${MODEL_NAME}` and `${ROUTER}` substitutions. | - | No |
|
|
| `format` | Defines the desired structure for the AI's output. Can be a Zod schema object, a Zod schema string, a JSON schema string, or a path to a JSON schema file (e.g., `file:./schema.json`). Ensures the output conforms to the specified structure. | - | No |
|
|
| `filters` | Post-processing filters applied to the output (primarily `completion` mode with `--dst`). Can be a comma-separated string of filter names (e.g., `unwrapMarkdown,trim`). | `''` | No |
|
|
|
|
## Tool Usage
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `tools` | Comma-separated list of tool names or paths to custom tool files to enable. | (List of default tools) | No |
|
|
| `disable` | Comma-separated list of tool *categories* to disable (e.g., `filesystem,git`). | `[]` | No |
|
|
| `disableTools` | Comma-separated list of specific tool *names* to disable. | `[]` | No |
|
|
|
|
## Iteration & Advanced Control
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `each` | Iterate the task over multiple items. Accepts a GLOB pattern, path to a JSON file (array), or comma-separated strings. The current item is available as the `${ITEM}` variable in other parameters (e.g., `--dst="${ITEM}-output.md"`). Can be used to test different models (e.g., `--each="openai/gpt-3.5-turbo,openai/gpt-4o"`). | - | No |
|
|
| `variables` | Define custom key-value variables for use in prompts or other parameters (e.g., `--variables.PROJECT_NAME=MyProject`). Access via `${variableName}`. | `{}` | No |
|
|
|
|
## Configuration & Authentication
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `api_key` | Explicit API key for the selected router. Overrides keys from config files. | - | No |
|
|
| `baseURL` | Custom base URL for the API endpoint (e.g., for local LLMs via Ollama). Set automatically for known routers or can be specified directly. | - | No |
|
|
| `config` | Path to a JSON configuration file containing API keys and potentially other settings. | - | No |
|
|
| `profile` | Path to a profile file (JSON or .env format) for loading environment-specific variables. | - | No |
|
|
| `env` | Specifies the environment section to use within the profile file. | `default` | No |
|
|
| `preferences` | Path to a preferences file (e.g., containing user details like location, email). Used to provide context to the AI. | (System-specific default, often `~/.kbot/Preferences`) | No |
|
|
|
|
## Debugging & Logging
|
|
|
|
| Parameter | Description | Default | Required |
|
|
|-----------|-------------|---------|----------|
|
|
| `logLevel` | Logging verbosity level (e.g., 0=error, 4=debug). | `4` | No |
|
|
| `logs` | Directory to store log files and temporary outputs (like `params.json`). | `./logs` | No |
|
|
| `dry` | Perform a dry run: log parameters and configurations without executing the AI request. | `false` | No |
|
|
| `dump` | Path to generate a script file representing the current command invocation. | - | No |
|
|
|
|
# Advanced Topics
|
|
|
|
This section covers more advanced usage patterns and concepts.
|
|
|
|
## Processing Multiple Items (`--each`)
|
|
|
|
Instead of relying on external scripting for batch processing, `kbot` provides the built-in `--each` parameter. This allows you to iterate a task over multiple inputs efficiently.
|
|
|
|
**How it Works:**
|
|
|
|
The `--each` parameter accepts:
|
|
|
|
* A comma-separated list of strings (e.g., `--each="file1.txt,file2.txt"`).
|
|
* A file path to a JSON file containing an array of strings.
|
|
* A GLOB pattern matching multiple files (e.g., `--each="./src/**/*.ts"`).
|
|
* A list of model IDs to test a prompt against different models (e.g., `--each="openai/gpt-4o,anthropic/claude-3.5-sonnet"`).
|
|
|
|
**Using the `${ITEM}` Variable:**
|
|
|
|
Within the loop initiated by `--each`, the current item being processed is available as the `${ITEM}` variable. You can use this variable in other parameters, such as `--dst`, `--include`, or within the `--prompt` itself.
|
|
|
|
**Example: Generating Documentation for Multiple Files**
|
|
|
|
```bash
|
|
kbot --each "./src/modules/*.ts" \
|
|
--dst "./docs/api/${ITEM}.md" \
|
|
--prompt "Generate API documentation in Markdown format for the module defined in ${ITEM}"
|
|
```
|
|
|
|
This command will:
|
|
|
|
1. Find all `.ts` files in `./src/modules/`.
|
|
2. For each file (e.g., `moduleA.ts`):
|
|
* Set `${ITEM}` to the file path (`./src/modules/moduleA.ts`).
|
|
* Execute `kbot` with the prompt, including the specific file via `${ITEM}`.
|
|
* Save the output to `./docs/api/./src/modules/moduleA.ts.md` (Note: path handling might vary).
|
|
|
|
Refer to the [Examples](./examples.md#iterating-with---each) for more use cases.
|
|
|
|
## Choosing a Transformation Method: `transform` vs. `createIterator`
|
|
|
|
When transforming data structures (often JSON) using LLMs, you have two primary approaches:
|
|
|
|
1. **`transform` Helper Function:**
|
|
* **Pros:** Simple, minimal setup, good for basic field transformations.
|
|
* **Cons:** Less control over network, caching, logging details.
|
|
* **Use Case:** Quickly applying straightforward transformations to data fields without needing deep customization.
|
|
|
|
2. **`createIterator` Factory:**
|
|
* **Pros:** Full control over network options (retries, concurrency), caching (namespace, expiration), logging, custom transformer logic, and callbacks (`onTransform`, `onTransformed`).
|
|
* **Cons:** More verbose setup required.
|
|
* **Use Case:** Complex transformations requiring fine-tuned control over the entire process, advanced caching strategies, or integration with custom logging/transformation logic.
|
|
|
|
Consult the [Iterator Documentation](./iterator.md) for detailed explanations and code examples of both methods. |