> ## 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. Every file must end in `.txt`. The ingestor also accepts `.text`, but training opens only `<filename>.txt`, so a `.text` dataset ingests and then fails to train.

## 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 a [reserved column name](https://docs.tracebloc.io/create-use-case/templates.md#rules-that-apply-to-every-csv) in `schema`: `filename`, `extension`, `id` and the others listed there fail 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 with the CLI

Each split is one folder laid out as above. Ingest the training and the test split separately:

```bash theme={null}
tracebloc data ingest ./tickets-train --task text_classification --name tickets_train --intent train --label-column label --holds open_data
tracebloc data ingest ./tickets-test  --task text_classification --name tickets_test  --intent test  --label-column label --holds open_data
```

`--holds open_data` marks the dataset as open data. If your data is about patients, pass `--holds patient_data`; if it was generated, pass `--holds synthetic_data`. Leave `--holds` out on a terminal and the CLI asks; in a script, the dataset is marked as patient data. The mark decides which [use case types](https://docs.tracebloc.io/create-use-case/define.md#step-2-data-&-evaluation) you can create on the dataset.

`--label-column` is required for this task. Set it to the name of the label column in `labels.csv`. On a terminal, `tracebloc data ingest <path>` works the task out from the folder; see [Guided ingest](https://docs.tracebloc.io/environment-setup/cli.md#guided-ingest). In a script (`--no-input`, `--output-json` or no terminal), leaving it out sends an empty label, and the spec fails validation before anything is ingested.

## 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 a reserved column name such as `filename` or `extension`; the label column is named by `label:` instead. |
| `spec.file_options.extension` | no | Leave it unset. The default `.txt` is the only extension training reads. |
| `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](https://docs.tracebloc.io/create-use-case/templates.md#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 manifest ships as `labels_file_sample.csv`: rename it to `labels.csv` before you ingest the folder, because the CLI reads only that name. For the Helm chart, stage the renamed folder so that it matches the paths in the `ingest.yaml` above.

## Score formulas

When you [define a use case](https://docs.tracebloc.io/create-use-case/define.md#supported-metrics-per-data-type-and-task) on this data, the platform currently accepts **Accuracy**, **F1 Score**, **Micro F1**, **F1 Weighted**, **Precision**, **Recall**, **AUC-ROC**, **Matthews Correlation Coefficient**, **Log Loss**, **Loss**, **Cohen’s Kappa**, **Quadratic Weighted Kappa (QWK)**, **Jaccard Score**, **Hamming Loss** and **Brier Score**.

## Next steps

* Ingest the data: [Prepare Data](https://docs.tracebloc.io/create-use-case/prepare-dataset.md)
* Shared rules for every template: [Dataset templates](https://docs.tracebloc.io/create-use-case/templates.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.