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