sec

packages/kbot/dist/README.md

@@ -0,0 +1,266 @@
+# @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.