From 9496c325f855ab75712f3f664af4f3fbf9443853 Mon Sep 17 00:00:00 2001 From: masquare <11543761+masquare@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:53:27 -0800 Subject: [PATCH 1/6] feat(types)!: simplify the calls that build records, sources and tasks - add_record, add_task and add_tasks take their argument positionally. - The collection fields of Record, Source and Task accept any iterable and store a tuple. They reject a string, a mapping and a single item. - A task accepts one bare target, such as targets="normal". - Annotation takes key and value positionally, and Source takes name. - A Hugging Face connector sets SOURCE_FILES without an annotation. - Connectors and docs import from the package roots. The connectors and the docs use the new forms. --- .../references/connector-anatomy.md | 41 ++++++------- docs/connectors.md | 12 ++-- docs/data-model/annotations.md | 11 ++-- docs/data-model/records.md | 16 ++--- docs/data-model/sources.md | 29 ++++----- docs/data-model/tasks.md | 44 +++++++------- docs/data-model/time-series.md | 3 +- docs/timef-dataset.md | 29 +++++---- docs/types.md | 3 +- .../bases/edf/timeseries.py | 3 +- .../datasets/bash_lab/sensorcaps/connector.py | 20 +++---- .../sensorcaps/tests/test_connector.py | 2 +- .../datasets/chengsenwang/tsqa/connector.py | 23 +++---- .../chengsenwang/tsqa/tests/test_connector.py | 4 +- .../datasets/datadog/arfbench/connector.py | 8 +-- .../datasets/datadog/arfbench/questions.py | 16 ++--- .../datasets/datadog/arfbench/series.py | 19 +++--- .../datadog/arfbench_charts/connector.py | 11 ++-- .../datasets/opentslm/har_cot/connector.py | 11 ++-- .../opentslm/har_cot/tests/test_connector.py | 3 +- .../datasets/opentslm/sleep_cot/connector.py | 13 ++-- .../sleep_cot/tests/test_connector.py | 3 +- .../physionet/ecg_qa_cot/connector.py | 18 +++--- .../ecg_qa_cot/tests/test_connector.py | 3 +- .../datasets/physionet/ptb_xl/connector.py | 34 +++++------ .../physionet/ptb_xl/tests/test_connector.py | 3 +- .../physionet/sleep_edfx/connector.py | 6 +- .../datasets/physionet/sleep_edfx/metadata.py | 2 +- .../datasets/physionet/sleep_edfx/tasks.py | 14 ++--- .../physionet/sleep_edfx/tests/test_tasks.py | 4 +- .../datasets/timenet/hello_world/connector.py | 39 ++++++------ .../datasets/timenet/test_mean/connector.py | 15 ++--- .../timenet/test_mean/tests/test_connector.py | 3 +- .../tsaqa/tsaqa_benchmark/connector.py | 19 +++--- .../src/timenet_connectors/splitting/base.py | 2 +- .../splitting/stratified.py | 2 +- .../tests/test_splitting.py | 2 +- .../timenet/src/timenet/dataset/dataset.py | 6 +- .../timenet/src/timenet/dataset/record.py | 10 ++-- .../timenet/src/timenet/dataset/source.py | 20 +++++-- .../src/timenet/dataset/time_series.py | 9 +-- packages/timenet/src/timenet/types/_fields.py | 21 ++++++- .../timenet/src/timenet/types/annotations.py | 18 +++--- packages/timenet/src/timenet/types/tasks.py | 60 ++++++++++--------- .../timenet/tests/dataset/test_dataset.py | 9 +++ packages/timenet/tests/dataset/test_source.py | 52 +++++++++++++++- .../timenet/tests/types/test_annotations.py | 7 +++ packages/timenet/tests/types/test_tasks.py | 23 +++++++ packages/timenet/tests/types/test_text.py | 19 ++++-- pyproject.toml | 2 + 50 files changed, 423 insertions(+), 323 deletions(-) diff --git a/.agents/skills/add-dataset-connector/references/connector-anatomy.md b/.agents/skills/add-dataset-connector/references/connector-anatomy.md index 14574a14f..056b54e61 100644 --- a/.agents/skills/add-dataset-connector/references/connector-anatomy.md +++ b/.agents/skills/add-dataset-connector/references/connector-anatomy.md @@ -123,11 +123,12 @@ Populate a `TimeFDataset` (`from timenet.dataset import Record, Signal, Source, has gaps, say why on the spec: `missing=MissingValues(reason=MissingReason.SENSOR_GAP)`. The writer records how many timesteps each signal misses, as `Signal.null_count`. Keep a null a null: never fill a gap. -- Group signals under a `Source(name=..., signals=...)`. Then - `dataset.add_record(record=Record(sources=(source,)))` registers the record and returns it. A +- Group signals under a `Source("name", signals=[...])`. Then + `dataset.add_record(Record(sources=[source]))` registers the record and returns it. A collection + field such as `sources`, `signals`, or `inputs` takes any iterable and stores a tuple. A windowed record says so through its axis: `RegularAxis.at_index(...)` moves the origin into the recording. -- `record.annotate(Annotation(key=..., value=...))` attaches one annotation and returns it. +- `record.annotate(Annotation("key", value))` attaches one annotation and returns it. `record.add_annotations([...])` takes an iterable and returns a tuple. There is one annotation class, and its `span` gives its shape. No span means the whole record. `span=TimePoint.seconds(...)` means a time offset. `span=TimeInterval.seconds(...)` means a region. @@ -136,8 +137,9 @@ Populate a `TimeFDataset` (`from timenet.dataset import Record, Signal, Source, its number of characters, pass it as `length=n` and every read checks the result against it. The writer stores this text in a separate payload file so readers can load it on request. For a list of strings, use `LazyTextList`, with the number of strings as `length` if you know it. -- `dataset.add_task(task=(inputs=(record,), ...))` registers one task and returns it. - `dataset.add_tasks(tasks=[...])` takes an iterable and registers the batch all-or-nothing. The task +- `dataset.add_task((inputs=[record], ...))` registers one task and returns it. Pass one + target as a bare value: `targets="walking"`. + `dataset.add_tasks([...])` takes an iterable and registers the batch all-or-nothing. The task names its input records itself. Set `scope` and `from_tasks` on the task too. A batch can derive from its own members in any order. - You cannot pass ids. The dataset gives every record, signal, and task a read-only int `id` when @@ -178,12 +180,9 @@ the bounds of every `Span` the task carries. ```python import json -from collections.abc import Mapping -from typing import ClassVar from pydantic import ConfigDict, Field -from timenet.dataset import Record, Signal, Source, TimeFDataset -from timenet.dataset.axis import OrdinalAxis +from timenet.dataset import OrdinalAxis, Record, Signal, Source, TimeFDataset from timenet.types import Annotation, AnswerTask, TimeSeriesSpec, ureg from timenet_connectors.bases.huggingface import BaseHuggingFaceConnector, HubFileRef from timenet_connectors.sources.readers import DataRow, ParquetDataReader @@ -211,7 +210,7 @@ class TSQAConnector(BaseHuggingFaceConnector): HF_REPO = "ChengsenWang/TSQA" # the external Hub repo id (keeps its own casing) # The commit refs/convert/parquet pointed to: the Hub's parquet conversion of the CSV. SOURCE_REVISION = "22518209e3ee6302be4b4957f2692b3e8de849c3" - SOURCE_FILES: ClassVar[Mapping[str, str]] = {"train": "default/train/0000.parquet"} + SOURCE_FILES = {"train": "default/train/0000.parquet"} def convert(self, raw_refs: list[HubFileRef]) -> TimeFDataset: """Build one record per row: the parsed series plus its question-and-answer task. @@ -227,7 +226,7 @@ class TSQAConnector(BaseHuggingFaceConnector): for row in ParquetDataReader(ref.path, TSQARow).iter_rows(): series = json.loads(row.series) signals = series if series and isinstance(series[0], list) else [series] - time_series = tuple( + time_series = [ Signal.from_values( values, spec=_SPEC, @@ -235,19 +234,13 @@ class TSQAConnector(BaseHuggingFaceConnector): time_axis=OrdinalAxis(), ) for signal, values in enumerate(signals) - ) - record = Record(sources=(Source(name="TSQA series", signals=time_series),)) - dataset.add_record(record=record) - record.annotate(Annotation(key="task", value=row.task)) + ] + record = Record(sources=[Source("TSQA series", signals=time_series)]) + dataset.add_record(record) + record.annotate(Annotation("task", row.task)) if row.label: - record.annotate(Annotation(key="label", value=row.label)) - dataset.add_task( - task=AnswerTask( - inputs=(record,), - prompt=row.question, - targets=(row.answer,), - ) - ) + record.annotate(Annotation("label", row.label)) + dataset.add_task(AnswerTask(inputs=[record], prompt=row.question, targets=row.answer)) return dataset @@ -273,7 +266,7 @@ a local dict keyed by the PTB-XL `ecg_id`. It stores the `ecg_id` and the PTB-XL come from `ptbxl_database.csv`. Per-question metadata (question_type, template_id, answer_options, clinical_context) are value-deduped dataset annotations that the tasks reference. The connector builds the clinical context from `ptbxl_database.csv`. It streams one -`AnswerTask(inputs=(record,), prompt=..., rationale=, targets=(