Text classification

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

/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

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 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:

tracebloc data ingest ./tickets-train --task text_classification --name tickets_train --intent train --label-column label
tracebloc data ingest ./tickets-test  --task text_classification --name tickets_test  --intent test  --label-column label

--label-column is required for this task. Set it to the name of the label column in labels.csv. On a terminal, the CLI asks for it if you leave it out. 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

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.

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 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
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Text classification

Folder layout

Labels CSV

Ingest with the CLI

ingest.yaml

What the ingestor checks

Sample dataset

Score formulas

Next steps

​Folder layout

​Labels CSV

​Ingest with the CLI

​ingest.yaml

​What the ingestor checks

​Sample dataset

​Score formulas

​Next steps

Folder layout

Labels CSV

Ingest with the CLI

ingest.yaml

What the ingestor checks

Sample dataset

Score formulas

Next steps