> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Text classification

> Dataset template for text classification: one .txt per sample plus a labels CSV, ingest.yaml and the checks the data ingestor runs.

Sort texts into classes. Each sample is one `.txt` file plus one row in a labels CSV that names the file and its class.

## Folder layout

```text theme={null}
/data/shared/tickets/
├── labels.csv
└── texts/
    ├── sample1.txt
    ├── sample2.txt
    └── ...
```

* The text folder must be named `texts` and sit next to the labels CSV.
* One document per file, UTF-8 encoded. All files share one extension: `.txt` (default) or `.text`.

## Labels CSV

```csv theme={null}
filename,label
sample1,positive
sample2,negative
sample3,neutral
```

| Column      | Required               | Meaning                                                                                                                                        |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`  | yes, exactly this name | The text file, with or without extension (`sample1` resolves to `texts/sample1.txt`).                                                          |
| `label`     | yes                    | The class. Any column name works — set it with `label:`. At least two distinct classes are required.                                           |
| `extension` | no                     | The shipped sample carries an `extension` column (`'.txt'`). The ingestor does not read it; the stored extension is always the configured one. |

Do not declare `filename` in `schema` — it is a reserved column and a `schema` entry for it fails the ingest. The label column does not need to be in `schema` either: `label:` names it, and the ingestor removes it from the stored table schema if you declare it anyway. `schema` is only for additional typed columns you want stored alongside each sample.

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: text_classification
table: support_tickets_train
intent: train
csv: /data/shared/tickets/labels.csv
texts: /data/shared/tickets/texts/
label: label
```

| Field                         | Required | Meaning                                                                                                                                                      |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `csv`                         | yes      | Path to the labels CSV.                                                                                                                                      |
| `texts`                       | yes      | The `texts/` folder. Its parent becomes the dataset root.                                                                                                    |
| `label`                       | yes      | Name of the class column.                                                                                                                                    |
| `schema`                      | no       | Extra columns to type-check and store, for example `source: VARCHAR(64)`. Never `filename`; the label column is named by `label:` instead.                   |
| `spec.file_options.extension` | no       | `.txt` (default) or `.text`.                                                                                                                                 |
| `language`, `normalization`   | no       | The dataset language (for example `en`) and any normalization applied (for example `lowercase`), recorded for consistency checks when datasets are combined. |

## What the ingestor checks

| Check           | Rejects                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File type       | Files under `texts/` with an extension other than the configured one, or mixed extensions.                                                                       |
| Text content    | Files containing a NUL byte or bytes that are not valid UTF-8 (a sample of up to 500 files, first 64 KB each). Empty or whitespace-only files produce a warning. |
| Label column    | A CSV whose header has no column matching `label:`.                                                                                                              |
| Data types      | With a `schema`: values that do not match their declared type.                                                                                                   |
| Label diversity | Fewer than two distinct label values.                                                                                                                            |

Plus the [checks every ingest runs](/create-use-case/templates#checks-every-ingest-runs).

## Sample dataset

The template ships five product-review style `.txt` files and a labels CSV with the classes `positive`, `negative` and `neutral`. The `ingest.yaml` above ingests it with no overrides.

## Next steps

* Stage the data and run the ingest: [Prepare Data](/create-use-case/prepare-dataset)
* Shared rules for every template: [Dataset templates](/create-use-case/templates)