> For the complete documentation index, see [llms.txt](https://mapir.gitbook.io/chloros/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mapir.gitbook.io/chloros/ai-assistants.md).

# Using Chloros with AI Assistants

This manual is written for two audiences: humans, and the AI assistants humans increasingly work through. Every page publishes exact values, defaults, and copy-pasteable commands so an assistant (Claude, ChatGPT, Copilot, a coding agent, …) can write working Chloros automation on the first try.

Chloros version: **1.2.0**. CLI/SDK platforms: Windows 10/11 x64 and Linux (x86\_64 / Jetson aarch64).

## What to hand your assistant

| Resource                     | URL                                                        | What it's for                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **llms.txt**                 | `https://mapir.gitbook.io/chloros/llms.txt`                | Machine-readable index of every page in this manual.                                                                                                                     |
| **CLI Reference**            | `https://mapir.gitbook.io/chloros/reference/cli-reference` | The complete `chloros-cli` command surface: every command, flag, default, exit code, and output-folder rule. Written for LLM consumption.                                |
| **SDK Reference**            | `https://mapir.gitbook.io/chloros/reference/sdk-reference` | The complete `chloros_sdk` Python API: classes, signatures, exceptions, and worked examples. Written for LLM consumption.                                                |
| **Any page as raw Markdown** | append `.md` to the page URL                               | e.g. `https://mapir.gitbook.io/chloros/reference/sdk-reference.md` returns the page as raw Markdown — ideal for pasting into a context window or fetching from an agent. |

In-manual links: [CLI Reference](/chloros/reference-cli-and-sdk/cli-reference.md) · [SDK Reference](/chloros/reference-cli-and-sdk/sdk-reference.md).

{% hint style="info" %}
The two reference pages are self-contained: an assistant that has read one of them does not need the rest of the manual to write a correct script.
{% endhint %}

## Prompt recipes

Copy, fill in the `<placeholders>`, and paste into your assistant.

### 1. Process a flight folder into NDVI

```
Read https://mapir.gitbook.io/chloros/reference/cli-reference.md.
Then write a script for <Windows PowerShell | bash> that:
1. logs in with `chloros-cli login <email> '<password>'` (only needed once per machine),
2. processes the folder <path/to/flight_001> with reflectance and the NDVI index,
3. prints where each output product landed, using the reference's
   "Where the outputs land" folder rules.
```

### 2. Batch-watch a captures directory

```
Read https://mapir.gitbook.io/chloros/reference/sdk-reference.md (sections
"Quickstart" and "Post-Run Summary & Hints"). Write a Python script that
watches <path/to/captures> for new flight subfolders and runs
chloros_sdk.process_folder() with indices=["NDVI"] on each new one.
After each run, print every hint from result["summary"]["hints"] and treat
a run with zero image products as a failure for that folder.
```

### 3. Connect a LATTICE array and capture

```
Read https://mapir.gitbook.io/chloros/reference/sdk-reference.md (section
"connect_array"). Write a Python script that connects my LATTICE cameras
with serials <213800234, 214000533, ...> as one synchronized array, captures
a reflectance image set into <output/> every 10 seconds for one hour, and
disconnects cleanly when done (use the context-manager form).
```

### 4. Record DAQ light-sensor spectra

```
Read https://mapir.gitbook.io/chloros/reference/cli-reference.md (section
"chloros-cli daq" — use only the pool-* commands). Write a script that:
1. connects my DAQ-E sensor with `chloros-cli daq pool-connect --eth-host <daq-e-xxxxxx.local>`,
2. lists the pool with `pool-list` to get the sensor id,
3. records a 10-minute calibrated .daq file named "<field-A>" with `pool-record`,
4. disconnects with `pool-disconnect`.
```

{% hint style="warning" %}
DAQ scripting from the command line always goes through the `daq pool-*` family (`pool-connect`, `pool-list`, `pool-latest`, `pool-stream`, `pool-record`, `pool-set-cap`, `pool-disconnect`). Other `daq` subcommands your assistant may invent are not available in shipped builds and exit with an error.
{% endhint %}

## Why AI-written scripts work well with Chloros

Each of these is a real, verified behavior of Chloros 1.2.0 — they remove the classic failure modes of machine-written automation:

* **No setup dance.** The SDK's smart-connect helpers (`connect_camera`, `connect_array`, `connect_daq_sensor`) and the processing entry points (`ChlorosLocal`, `process_folder`) **auto-start the local backend**. A generated script does not need the GUI open or a manually started server — it needs only the desktop/CLI package installed.
* **The whole pipeline is one call.** `chloros_sdk.process_folder("path", indices=["NDVI"])` runs import → calibration → reflectance → index export end to end. Less surface area, fewer places for a generated script to go wrong.
* **Zero-output runs self-diagnose.** After `process()`, the run's summary is attached to the result, and every processing hint (e.g. *why* a run produced no output) is also re-emitted as a Python `UserWarning` — so even a script that never inspects the result dict surfaces the diagnosis.
* **The CLI fails loudly.** A `chloros-cli process` run that requested products but wrote none prints `Processing finished but wrote no image products.` and **exits non-zero**, so shell scripts and CI detect it with a plain exit-code check. Successful runs report `Image products written: N`.

One asymmetry an assistant should know: the SDK's `process()` deliberately does **not** raise on a zero-product run — it reports through the summary/hints instead. If a Python pipeline must stop on an empty run, check the summary (recipe 2 does).

## Caveats

* **Chloros+ login required.** The CLI and SDK require a **paid** Chloros+ tier, enforced server-side: requests fail with `401 AUTH_REQUIRED` when not logged in and `403 PLAN_UPGRADE_REQUIRED` on the free tier. Run `chloros-cli login` once per machine before running generated scripts. See [Chloros+ Login](/chloros/chloros+-login.md).
* **Capture commands drive real hardware.** `lattice` / `daq` / `project` commands and the SDK session objects connect, stream, and trigger physical cameras and sensors. Review a generated script before its first run, and run it with the hardware attended.
* **Spot-check the outputs.** Verify the product folders and a few pixel values before publishing results. In particular, reflectance TIFFs are scaled per source — read the `Chloros:PixelScale` XMP tag (LATTICE: 32768 = 1.0 reflectance; Survey3: 65535) instead of assuming a divisor. Both reference pages document this under "Reading reflectance pixels".
* **Small gotchas that trip up generated code:** `pool-record` writes to the **backend host's** filesystem (default `~/Documents/DAQ Live View/`); on machines with several network interfaces, prefer `daq pool-connect --eth-host <ip-or-hostname>` over auto-discovery; and use `http://127.0.0.1:5000` (never `localhost`) anywhere a backend URL appears.