Coluna da entrada com nome de campo ou de status levanta ValueError antes de qualquer chamada

CHANGELOG.md

@@ -42,6 +42,7 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR
 
 ### Corrigido
 
+- Sem a coluna de status, uma coluna da entrada com algum valor e com o nome de um campo do modelo levanta `ValueError` antes de qualquer chamada, com `resume=True` e com `resume=False`, a menos que esteja em `reprocess_columns`. O `Decimal` NaN e o NaN de campo float em coluna object contam como valores, como na retomada. Antes, com `resume=True`, a resposta do LLM a sobrescrevia sem aviso quando só parte das colunas do modelo existia, e só avisava quando existiam todas; com `resume=False`, avisava e devolvia a entrada. `status_column` igual à coluna de texto, a um campo do modelo, ao nome de outra coluna de controle do dataframeit ou a uma coluna existente com valores que não são de status também levanta `ValueError`. Antes, a coluna sumia da saída com a resposta que ocupava, ou a execução terminava sem chamar o LLM e a coluna de texto ou a do usuário sumia (#197).
 - As anotações dos geradores usados como context managers são verificadas pelo ty 0.0.88 (#270).
 
 - A criação das colunas de saída usa a opção `mode.chained_assignment` só no pandas 2, preservando entradas fatiadas sem emitir aviso de depreciação no pandas 3.1 (#269).

docs/en/guides/faq.md

@@ -47,7 +47,11 @@ With `resume=True` (default), only rows without status are processed. To redo th
 
 ### The model columns already exist and nothing was processed
 
-With `resume=False`, if the model columns are already in the DataFrame and `reprocess_columns` was not passed, dataframeit emits a warning and returns the data unprocessed, so as not to overwrite results. Use `resume=True` to continue, or `reprocess_columns=[...]` to redo specific columns.
+With `resume=False` and the status column in the DataFrame, if the model columns are already in it and `reprocess_columns` was not passed, dataframeit emits a warning and returns the data unprocessed, so as not to overwrite results. Use `resume=True` to continue, or `reprocess_columns=[...]` to redo specific columns.
+
+### `ValueError` because a column already exists with the name of a model field
+
+Without the status column, every row counts as new, and the model's answer would overwrite the input column that has the name of a field, such as a classification made by hand. dataframeit refuses the run before any call, with `resume=True` or `resume=False`; a column without any value and a column in `reprocess_columns` do not count. Rename or drop the column, or pass it in `reprocess_columns` to overwrite it on purpose. If the DataFrame is a dataframeit output, which comes without the status column when no row had an error, put the column back with `df["_dataframeit_status"] = "processed"` (or the name passed in `status_column`): the run resumes from it, and `reprocess_columns` redoes only the columns listed.
 
 ## Limits and costs
 

docs/en/guides/performance.md

@@ -105,7 +105,7 @@ result = dataframeit(
 )
 ```
 
-The format is inferred from the file extension (`.csv`, `.xlsx`, `.parquet`). In every format, the model's list, dict and tuple fields are saved as JSON text, and `Enum` values by their value; `read_df` turns the structures back, and resuming returns structures and date, time, `datetime`, `Enum`, `int` and `bool` fields with their declared type, also with `strict=True`: a date saved as text, an integer read back as a float and a tuple read back as a list come back as `date`, `int` and `tuple`. XLSX stores numbers as doubles, and an integer above 2**53 comes back rounded; for ids that large, use CSV or parquet. None of the three formats keeps the NaN of a `float` field apart from null: CSV and XLSX write both as an empty cell, and parquet as null. When resuming, the NaN comes back missing, and a required field that received it is flagged for reprocessing. In parquet, an integer above 2**63 - 1 next to a pending row and an integer above 2**53 next to a float in the same column are not saved, and the checkpoint save fails with a warning. If execution is interrupted, run the same call again with the same input: with `resume=True`, the default, and the file present, execution continues from the checkpoint. On every save, `<checkpoint>.dataframeit.json` is written next to it with the run's signature (prompt, provider, model, `model_kwargs` except `timeout`, schema, search, and the text and status columns), a hash of each row's text, and a hash of the checkpoint itself. The checkpoint is resumed only when all three match; with another configuration, another input, or a file that is not the one the signature describes, the run warns, starts over, and overwrites it. In a row already concluded, successfully or with an error, the model fields come from the checkpoint, over whatever the input carried in them; in a successful row, that is what an uninterrupted run would give, because it writes the answer over them. To keep an output corrected by hand as it is, pass it with the status column, and the checkpoint is not read again. A complete output is returned without it, and the column comes back with `output["_dataframeit_status"] = "processed"` (or the name passed in `status_column`). With `resume=False`, the file is ignored and overwritten.
+The format is inferred from the file extension (`.csv`, `.xlsx`, `.parquet`). In every format, the model's list, dict and tuple fields are saved as JSON text, and `Enum` values by their value; `read_df` turns the structures back, and resuming returns structures and date, time, `datetime`, `Enum`, `int` and `bool` fields with their declared type, also with `strict=True`: a date saved as text, an integer read back as a float and a tuple read back as a list come back as `date`, `int` and `tuple`. XLSX stores numbers as doubles, and an integer above 2**53 comes back rounded; for ids that large, use CSV or parquet. None of the three formats keeps the NaN of a `float` field apart from null: CSV and XLSX write both as an empty cell, and parquet as null. When resuming, the NaN comes back missing, and a required field that received it is flagged for reprocessing. In parquet, an integer above 2**63 - 1 next to a pending row and an integer above 2**53 next to a float in the same column are not saved, and the checkpoint save fails with a warning. If execution is interrupted, run the same call again with the same input: with `resume=True`, the default, and the file present, execution continues from the checkpoint. On every save, `<checkpoint>.dataframeit.json` is written next to it with the run's signature (prompt, provider, model, `model_kwargs` except `timeout`, schema, search, and the text and status columns), a hash of each row's text, and a hash of the checkpoint itself. The checkpoint is resumed only when all three match; with another configuration, another input, or a file that is not the one the signature describes, the run warns, starts over, and overwrites it. In a row already concluded, successfully or with an error, the model fields come from the checkpoint, over whatever the input carried in them. To keep an output corrected by hand as it is, pass it with the status column, and the checkpoint is not read again. A complete output is returned without it, and the column comes back with `output["_dataframeit_status"] = "processed"` (or the name passed in `status_column`). With `resume=False`, the file is ignored and overwritten.
 
 To inspect what has already been processed, `read_df` loads the file with lists, dicts and text in the model's types. That DataFrame also works as input for resuming, and then the file is not read again:
 

docs/en/reference/api.md

@@ -54,9 +54,9 @@ def dataframeit(
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `resume` | bool | `True` | With `True`, continues from where it stopped: processes only rows without status and keeps those with `'processed'` or `'error'`. With `False`, processes every row that is not `'processed'`; if the model columns already exist and `reprocess_columns` is not passed, it emits a warning and returns the data unprocessed |
+| `resume` | bool | `True` | With `True`, continues from where it stopped: processes only rows without status and keeps those with `'processed'` or `'error'`. With `False`, processes every row that is not `'processed'`; with the status column present, if the model columns already exist and `reprocess_columns` is not passed, it emits a warning and returns the data unprocessed. Without the status column, with `True` or `False`, every row counts as new, and an input column that holds any value and has the name of a model field raises `ValueError` before any call, unless it is in `reprocess_columns` |
 | `reprocess_columns` | list | `None` | Fields to force reprocessing; when resuming with a changed model, it must cover fields incompatible with previously processed rows |
-| `status_column` | str | `None` | Name of the status column; `None` uses `_dataframeit_status` |
+| `status_column` | str | `None` | Name of the status column; `None` uses `_dataframeit_status`. It cannot be the text column, a model field or another of the [added columns](#added-columns), and an existing column with that name is accepted only if it holds nothing but `'processed'`, `'error'` or empty cells; otherwise, raises `ValueError` |
 
 #### Model
 

docs/guides/faq.md

@@ -47,7 +47,11 @@ Com `resume=True` (padrão), só as linhas sem status são processadas. Para ref
 
 ### As colunas do modelo já existem e nada foi processado
 
-Com `resume=False`, se as colunas do modelo já estão no DataFrame e `reprocess_columns` não foi passado, o dataframeit emite um aviso e devolve os dados sem processar, para não sobrescrever resultados. Use `resume=True` para continuar, ou `reprocess_columns=[...]` para refazer colunas específicas.
+Com `resume=False` e a coluna de status no DataFrame, se as colunas do modelo já estão nele e `reprocess_columns` não foi passado, o dataframeit emite um aviso e devolve os dados sem processar, para não sobrescrever resultados. Use `resume=True` para continuar, ou `reprocess_columns=[...]` para refazer colunas específicas.
+
+### `ValueError` porque uma coluna já existe com o nome de um campo do modelo
+
+Sem a coluna de status, toda linha conta como nova, e a resposta do modelo sobrescreveria a coluna da entrada que tem o nome de um campo, como uma classificação feita à mão. O dataframeit recusa a execução antes de qualquer chamada, com `resume=True` ou `resume=False`; a coluna sem nenhum valor e a que está em `reprocess_columns` não contam. Renomeie ou remova a coluna, ou passe-a em `reprocess_columns` para sobrescrevê-la de propósito. Se o DataFrame é uma saída do dataframeit, que sai sem a coluna de status quando nenhuma linha teve erro, devolva a coluna com `df["_dataframeit_status"] = "processed"` (ou o nome passado em `status_column`): a execução retoma dela, e `reprocess_columns` refaz só as colunas indicadas.
 
 ## Limites e custos
 

docs/guides/performance.md

@@ -107,7 +107,7 @@ resultado = dataframeit(
 )
 ```
 
-Formato inferido pela extensão do arquivo (`.csv`, `.xlsx`, `.parquet`). Em qualquer formato, os campos de lista, dict e tupla do modelo são gravados como texto JSON, e o `Enum`, pelo valor; `read_df` devolve as estruturas, e a retomada devolve ao tipo declarado as estruturas e os campos de data, hora, `datetime`, `Enum`, `int` e `bool`, inclusive com `strict=True`: a data gravada como texto, o inteiro relido como float e a tupla relida como lista voltam a `date`, `int` e `tuple`. O XLSX guarda número como double, e um inteiro acima de 2**53 volta arredondado dele; para ids desse tamanho, use CSV ou parquet. Nenhum dos três formatos guarda o NaN de um campo `float` à parte do nulo: o CSV e o XLSX gravam os dois como célula vazia, e o parquet, como nulo. Na retomada, o NaN volta ausente, e o campo obrigatório que o recebeu é acusado para reprocessar. No parquet, o inteiro acima de 2**63 - 1 ao lado de uma linha pendente e o inteiro acima de 2**53 ao lado de um float na mesma coluna não são gravados, e a gravação do checkpoint falha com aviso. Em caso de interrupção, rode a mesma chamada de novo, com a mesma entrada: com `resume=True`, o padrão, e o arquivo presente, a execução continua do checkpoint. A cada gravação, `<checkpoint>.dataframeit.json` é gravado ao lado dele com a assinatura da execução (prompt, provider, modelo, `model_kwargs` menos `timeout`, schema, busca e as colunas de texto e de status), o hash do texto de cada linha e o hash do próprio checkpoint. O checkpoint só é retomado quando os três batem; com outra configuração, outra entrada ou um arquivo que não é o que a assinatura descreve, a execução avisa, começa do zero e o sobrescreve. Numa linha já concluída, com sucesso ou com erro, os campos do modelo vêm do checkpoint, sobre o que a entrada trazia neles; na linha com sucesso, é o que uma execução sem interrupção daria, porque ela grava a resposta por cima. Para manter uma saída corrigida à mão como está, passe-a com a coluna de status, e o checkpoint não é relido. A saída completa sai sem ela, e a coluna volta com `saida["_dataframeit_status"] = "processed"` (ou o nome passado em `status_column`). Com `resume=False`, o arquivo é ignorado e sobrescrito.
+Formato inferido pela extensão do arquivo (`.csv`, `.xlsx`, `.parquet`). Em qualquer formato, os campos de lista, dict e tupla do modelo são gravados como texto JSON, e o `Enum`, pelo valor; `read_df` devolve as estruturas, e a retomada devolve ao tipo declarado as estruturas e os campos de data, hora, `datetime`, `Enum`, `int` e `bool`, inclusive com `strict=True`: a data gravada como texto, o inteiro relido como float e a tupla relida como lista voltam a `date`, `int` e `tuple`. O XLSX guarda número como double, e um inteiro acima de 2**53 volta arredondado dele; para ids desse tamanho, use CSV ou parquet. Nenhum dos três formatos guarda o NaN de um campo `float` à parte do nulo: o CSV e o XLSX gravam os dois como célula vazia, e o parquet, como nulo. Na retomada, o NaN volta ausente, e o campo obrigatório que o recebeu é acusado para reprocessar. No parquet, o inteiro acima de 2**63 - 1 ao lado de uma linha pendente e o inteiro acima de 2**53 ao lado de um float na mesma coluna não são gravados, e a gravação do checkpoint falha com aviso. Em caso de interrupção, rode a mesma chamada de novo, com a mesma entrada: com `resume=True`, o padrão, e o arquivo presente, a execução continua do checkpoint. A cada gravação, `<checkpoint>.dataframeit.json` é gravado ao lado dele com a assinatura da execução (prompt, provider, modelo, `model_kwargs` menos `timeout`, schema, busca e as colunas de texto e de status), o hash do texto de cada linha e o hash do próprio checkpoint. O checkpoint só é retomado quando os três batem; com outra configuração, outra entrada ou um arquivo que não é o que a assinatura descreve, a execução avisa, começa do zero e o sobrescreve. Numa linha já concluída, com sucesso ou com erro, os campos do modelo vêm do checkpoint, sobre o que a entrada trazia neles. Para manter uma saída corrigida à mão como está, passe-a com a coluna de status, e o checkpoint não é relido. A saída completa sai sem ela, e a coluna volta com `saida["_dataframeit_status"] = "processed"` (ou o nome passado em `status_column`). Com `resume=False`, o arquivo é ignorado e sobrescrito.
 
 Para inspecionar o que já foi processado, `read_df` carrega o arquivo com listas, dicts e textos nos tipos do modelo. Esse DataFrame também serve de entrada para a retomada, e aí o arquivo não é lido de novo:
 

docs/reference/api.md

@@ -54,9 +54,9 @@ def dataframeit(
 
 | Parâmetro | Tipo | Padrão | Descrição |
 |-----------|------|--------|-----------|
-| `resume` | bool | `True` | Com `True`, continua de onde parou: processa só as linhas sem status e preserva as que têm `'processed'` ou `'error'`. Com `False`, processa toda linha que não esteja `'processed'`; se as colunas do modelo já existirem e `reprocess_columns` não for passado, emite um aviso e devolve os dados sem processar |
+| `resume` | bool | `True` | Com `True`, continua de onde parou: processa só as linhas sem status e preserva as que têm `'processed'` ou `'error'`. Com `False`, processa toda linha que não esteja `'processed'`; com a coluna de status presente, se as colunas do modelo já existirem e `reprocess_columns` não for passado, emite um aviso e devolve os dados sem processar. Sem a coluna de status, com `True` ou `False`, toda linha conta como nova, e uma coluna da entrada com algum valor e com o nome de um campo do modelo levanta `ValueError` antes de qualquer chamada, a menos que esteja em `reprocess_columns` |
 | `reprocess_columns` | list | `None` | Lista de colunas para forçar reprocessamento; ao retomar com modelo alterado, deve cobrir os campos incompatíveis das linhas já processadas |
-| `status_column` | str | `None` | Nome da coluna de status; `None` usa `_dataframeit_status` |
+| `status_column` | str | `None` | Nome da coluna de status; `None` usa `_dataframeit_status`. Não pode ser a coluna de texto, um campo do modelo nem outra das [colunas adicionadas](#colunas-adicionadas), e a coluna existente com esse nome só serve se trouxer apenas `'processed'`, `'error'` ou vazio; fora disso, levanta `ValueError` |
 
 #### Modelo