mono/packages/kbot/docs_/advanced.md

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

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 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 for detailed explanations and code examples of both methods.