Skip to content

feat(connectors): add the OpenTSLM M4-Caption connector - #790

Open
karhu wants to merge 21 commits into
mainfrom
feature/m4-caption-connector
Open

karhu wants to merge 21 commits into
mainfrom
feature/m4-caption-connector

Conversation

@karhu

@karhu karhu commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Add opentslm/m4-caption. It converts the M4-Caption release of OpenTSLM: the train part of the 100,000 M4 competition series, each with a caption that GPT-4o wrote.

Each series becomes one Record and one AnswerTask. The task prompt is the prompt of the OpenTSLM loader (the post-prompt of M4QADataset), the same for every series. The Record keeps the M4 id and the frequency. The values stay float32, because the release holds the M4 values rounded to float32. The series use an ordinal axis, because the release has no timestamps and a month has no fixed length.

For 706 series, the release has an error message of the caption API instead of a caption, such as "Error generating caption: Connection error.". The connector leaves out these 253 daily, 57 monthly and 396 quarterly series, so the dataset has 99,294 series.

The release archive stores no split. generate_splits.py makes an 80/10/10 split with StratifiedSplitter, stratified by M4 frequency, and writes the validation and test series to splits.json.xz. Validation and test each hold a tenth of every frequency. M4 has 90 pairs of series whose histories are equal value for value, so the splitter groups the series by their values, and each pair stays in one split. This is not the split of the OpenTSLM paper. Its loader makes a random split of all frequencies together, and its test split holds only 6.5% of the hourly series. The result of the splitter depends on the version of scikit-learn, so the script ran once. The connector reads the 19 KB file with the lzma module of the standard library.

The M4 organizers state no license, so the card uses NONE. OpenTSLM releases the captions under MIT.

The connector folder has a README. It describes the records, the split, and how the release relates to the M4 data. It also describes future work: an M4 parent dataset, and calendar axes if #555 lands.

A full timenet-build build opentslm/m4-caption gives 99,294 records with a 79,436, 9,929 and 9,929 split, and a tenth of each frequency in validation and test. The values and captions read back from the build match the release.

@karhu
karhu added this pull request to stack #791 November 17, 2026 01:25
@karhu karhu added the area:connectors Changes packages/timenet-connectors label Nov 17, 2026
@karhu
karhu force-pushed the feature/m4-caption-connector branch 3 times, most recently from ef62ea1 to e4d1992 Compare November 17, 2026 18:43
@karhu
karhu marked this pull request as ready for review November 17, 2026 23:30
@karhu
karhu requested review from RealLast and TimoStoff November 17, 2026 23:30
@karhu
karhu force-pushed the feature/m4-caption-connector branch from 4153ed2 to 6a4148a Compare November 18, 2026 01:17
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

✅ CI checks passed

Check Status
Quick checks ✅ Passed
Tests (Python 3.13) ✅ Passed
Tests (Python 3.11) ✅ Passed

Updated for 1bdf0cf · run #8663

@karhu
karhu force-pushed the feature/m4-caption-connector branch from 6a4148a to f954d90 Compare November 18, 2026 01:23

@RealLast RealLast left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great direction! See a few points for simplification / clean up but otherwise strong

Base automatically changed from feature/csv-reader-max-field-chars to main November 20, 2026 17:30
@karhu
karhu force-pushed the feature/m4-caption-connector branch from e78b1a6 to 3175d5e Compare November 20, 2026 17:30
karhu added 16 commits November 20, 2026 09:31
Add opentslm/m4-caption. It converts the M4-Caption release of
OpenTSLM: the train part of the 100,000 M4 competition series, each
with a caption that GPT-4o wrote.

Each series becomes one Record and one AnswerTask without a prompt.
The Record keeps the M4 id and the frequency. The values stay float32,
because the release holds the M4 values rounded to float32. The series
use an ordinal axis, because the release has no timestamps and a month
has no fixed length.

The release has no split. The OpenTSLM loader splits the series at
load time with the datasets library. The connector computes the same
80/10/10 split with NumPy and stops with an error if the split does
not match a pinned digest. generate_splits.py computed that digest with
the datasets version from the OpenTSLM uv.lock.

The M4 organizers state no license, so the card uses NONE. OpenTSLM
releases the captions under MIT.
Add a README to the M4-Caption connector. It describes the records,
the split, and how the release relates to the M4 data.

It also describes future work: an M4 parent dataset that M4-Caption
can import its Records from.
Call CsvDataReader.raise_field_size_limit before the connector reads a
series file, in place of the removed max_field_chars option.
Call CsvDataReader.set_field_size_limit, the new name of
raise_field_size_limit.
The connector computed the OpenTSLM split with NumPy and compared it
with a digest from generate_splits.py. That meant two implementations
of one split.

generate_splits.py now runs the calls of the OpenTSLM loader once and
writes the 10,000 validation and 10,000 test series, by M4 id, to
splits.json.xz. The file is 19 KB, and the connector reads it with the
lzma module of the standard library. This is the frozen-file pattern
of sleep-cot. The file gives the same split as the digest did.

The README describes the frozen split. It also notes future work on
the axis type, if calendar axes (#555) land.
The series cell accepted values that are not numbers. Pydantic turned
true into 1.0 and "3.5" into 3.5. An empty list passed the row check
and failed later without the file or the row. The series cell now
takes strict finite floats and at least one value.

An M4Frequency enum now owns the six frequencies: their order, the id
letter, and the two release file names. The connector sets the CSV
cell limit once in convert, not once for each frequency.

The tests check a Boolean value and an empty series, and no longer
repeat the pydantic NaN check. The card and the README get small text
fixes.
The card said "the release" for the zip archive that OpenTSLM
publishes on Polybox. It now introduces that archive once and calls it
the Polybox release.
The pinned Polybox release parses fully, so the script does not need
to parse each series to mirror the rows that the OpenTSLM loader skips.
The split file is unchanged.
Introduce the Polybox archive in one sentence, and drop the sentence
about float32 values.
Shorten the M4Frequency docstring, the docstring of generate_splits.py
and the M4-Caption card.
The pinned Polybox release holds only exact float32 values, so the
connector converts each series to float32 without checking every
value again.
The release now assigns the split while it reads the series, so each
series carries its own split. One method creates the Record and its
caption task together, so convert no longer passes the Record and the
split back in.
Each AnswerTask now has the post-prompt of OpenTSLM's M4QADataset, the
same text for every series. The card and the README state it.

M4CaptionRelease is now M4CaptionReader, and the reader knows the file
names of each frequency, not M4Frequency. read_series is easier to read,
and the docstrings say that the release archive stores no split and that
OpenTSLM's loader makes it.
The split of OpenTSLM's loader is random over all frequencies, so the
small frequencies drift: its test split holds 6.5% of the hourly series.
generate_splits.py now makes an 80/10/10 split with StratifiedSplitter,
stratified by M4 frequency, and writes it to splits.json.xz as before.
Validation and test each hold a tenth of every frequency. The dataset no
longer has the split of the OpenTSLM paper.

The script now runs in the workspace and reads the M4 ids with the new
M4CaptionReader.read_m4_ids. Two runs write the same file.
…s in one split

For 706 series, the release has an error message of the caption API
instead of a caption, such as "Error generating caption: Connection
error.". The connector now leaves out these series, so the dataset has
99,294 series.

M4 has 90 pairs of series whose histories are equal value for value. The
split put 34 pairs across two splits, so a model could train on the
exact input of a test series. generate_splits.py now passes a digest of
the values as group_by to StratifiedSplitter, so each pair stays in one
split. The script reads the series with the new
M4CaptionReader.read_captioned_series, so it also leaves out the error
captions. Two runs write the same file.
@karhu
karhu force-pushed the feature/m4-caption-connector branch from 3175d5e to dae9fb0 Compare November 20, 2026 17:31
Main changed the connector API. A label set carries its name as an
annotation, a Hugging Face connector passes its Hub settings as class
keywords and reads a mapping from part to path, BaseConnector names the
whole download result, and Annotation takes its value by keyword.
@karhu
karhu requested a review from RealLast November 20, 2026 20:15

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:connectors Changes packages/timenet-connectors

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants