# Campo IA

Un Campo IA es un campo de una colección con un prompt: la IA lo llena con los datos de cada fila (clasificar un lead, resumir una nota, sacar la ciudad de una dirección). Por API puedes llenar **una celda** o **una columna entera**.

> Scope `items:generate`, solo en keys **live**: una key `met_test_` recibe `403` con `test_mode_restricted`. **Consume Energía por cada celda**, como cuando la llenas en el panel; sin saldo responde `402` con `energy_depleted`. El prompt se configura en la colección desde el panel.

```ts
import { Met } from '@meteor.ia/sdk';

const met = new Met(process.env.MET_KEY!, { workspaceId: 42 });
```

## Una celda

Síncrono: la respuesta llega cuando la celda ya quedó escrita en el ítem.

```ts
const { value } = await met.aiFields.generate(5, 901, 'resumen');
```

## Una columna

Llena hasta **100 filas por llamada**, en segundo plano. Por defecto toma solo las celdas vacías. Para recorrer una colección grande, sigue el cursor: cada llamada empieza después del último ítem que miró la anterior, así que ninguna fila se cobra dos veces.

```ts
let desde: number | undefined;
do {
  const run = await met.aiFields.createRun(5, 'resumen', { only_empty: true, starting_after: desde });
  const fin = await met.aiFields.waitForRun(run.id);
  console.log(fin.status, fin.succeeded, fin.failed);
  if (fin.status !== 'completed') break; // se detuvo: mira stop_reason
  desde = fin.has_more ? fin.next_starting_after ?? undefined : undefined;
} while (desde !== undefined);
```

| Campo de la corrida | Qué significa |
|---|---|
| `status` | `queued`, `running`, `completed`, `stopped` o `failed`. |
| `requested` / `processed` / `succeeded` / `failed` | Filas tomadas, intentadas, escritas (cada una se cobró) y fallidas. Una fila que alguien llenó mientras la corrida avanzaba se salta sin cobrar: cuenta en `processed`, no en `succeeded` ni en `failed`. |
| `has_more` / `next_starting_after` | Puede haber más filas: cuando termine, vuelve a llamar con `starting_after` = `next_starting_after`. |
| `stop_reason` | `energy_depleted` (recarga y vuelve a llamar), `plan_inactive`, `interrupted` o `error`. |

Si la Energía se acaba a mitad, la corrida queda `stopped` y lo ya escrito se conserva. Mientras una corrida del mismo campo siga en curso, otra responde `409` con `ai_field_run_in_progress`.

Con `only_empty: false` vuelves a generar también las celdas que ya tenían valor, y cada una se cobra otra vez; con el cursor tampoco se repite ninguna fila. Con `item_ids` eliges las filas (hasta 100; ahí no hay cursor ni `has_more`, y mandar también `starting_after` responde `400`).

Si la IA deja una celda vacía, esa ejecución ya se cobró: las llamadas siguientes con `only_empty` no la vuelven a tomar. Lo mismo si falla después del cobro (la respuesta no es una opción del campo, o no se pudo escribir). Para intentarla otra vez, pásala en `item_ids`.

Si el campo es un **select**, la IA solo puede responder una de sus opciones. Si responde otra cosa, la celda no se escribe —la ejecución sí se cobra— y cuenta como fallida; en una celda suelta responde `422` con `ai_field_invalid_option`. Si pasa seguido, revisa el prompt del campo.

## Errores

| Código | Cuándo |
|---|---|
| `not_an_ai_field` (400) | El campo existe pero no tiene prompt. |
| `ai_field_not_found` (404) | La colección no tiene ese campo. |
| `collection_not_found` / `item_not_found` (404) | La colección o el ítem no son de tu workspace. |
| `ai_field_invalid_option` (422) | El campo es un select y la IA respondió algo que no es una de sus opciones. No se escribió. |
| `energy_depleted` (402) | Sin Energía. |
| `ai_field_run_in_progress` (409) | Ya hay una corrida de ese campo en curso. |