Pre-release

This release is a pre-release and may not be stable for production use.

telemachus

Python SDK for the Telemachus open telematics format — read, validate, convert, and introspect high-frequency GNSS+IMU datasets.

pip install telemachus

Try it in 5 minutes: the AEGIS demo notebook (open in Colab) downloads a real Zenodo dataset, loads it, and plots one trip.

Read a dataset

import telemachus as tele

df = tele.read("path/to/manifest.yaml")   # → pandas DataFrame
print(tele.sensor_profile(df))             # → "gps+imu+gyro"

Sensor introspection

tele.has_gps(df)       # True if lat, lon, speed_mps non-NaN
tele.has_imu(df)       # True if ax, ay, az non-NaN
tele.has_gyro(df)      # True if gx, gy, gz present
tele.has_magneto(df)   # True if mx, my, mz present
tele.has_obd(df)       # True if speed_obd or rpm present
tele.has_io(df)        # True if ignition or voltage present
tele.is_full_imu(df)   # accel + gyro
tele.is_gps_only(df)   # GPS but no IMU

Validate

report = tele.validate(df, profile="imu")
print(report)
# ValidationReport(PASS, profile=imu, level=basic, errors=0, warnings=0)

report = tele.validate_dataset("path/to/dataset/", level="full")

Three profiles adapt validation to hardware capabilities:

Profile	Required columns	Use case
`core`	ts, lat, lon, speed_mps	GPS trackers, fleet APIs
`imu`	core + ax, ay, az	Telematics devices with accelerometer
`full`	imu + gx, gy, gz	Research platforms with gyroscope

Convert Open datasets

tele convert aegis /path/to/aegis/csvs -o datasets/aegis/
tele convert pvs /path/to/pvs/trips -o datasets/pvs/ --placement dashboard
tele convert stride /path/to/stride/road_data -o datasets/stride/ --category driving

Supported Open datasets:

Adapter	Source	Sensors	License
`aegis`	Zenodo 820576 (Austria)	GPS 5Hz + Accel 24Hz + Gyro + OBD	CC-BY-4.0
`pvs`	Kaggle (Brazil)	GPS 1Hz + Accel 100Hz + Gyro + Magneto	CC-BY-NC-ND-4.0
`stride`	Figshare (Bangladesh)	GPS 1Hz + Accel 100Hz + Gyro + Magneto	CC-BY-4.0

CLI

tele validate path/to/manifest.yaml          # validate manifest
tele validate path/to/dataset/ --level full   # validate dataset
tele info path/to/manifest.yaml               # dataset summary
tele convert aegis /data/aegis -o out/        # convert Open dataset

Telemachus record format

A Telemachus record is a flat Parquet row with 7 functional groups:

#	Group	Columns	Status
1	Datetime	`ts`	Mandatory
2	GNSS	`lat`, `lon`, `speed_mps`, `heading_deg`, `altitude_gps_m`, `hdop`, `h_accuracy_m`, `n_satellites`	Mandatory (lat/lon/speed)
3	IMU	`ax_mps2`, `ay_mps2`, `az_mps2`, `gx_rad_s`, `gy_rad_s`, `gz_rad_s`, `mx_uT`, `my_uT`, `mz_uT`	Profile-dependent
4	OBD	`speed_obd_mps`, `rpm`, `odometer_m`	Optional
5	CAN	`x_can_<signal>`	Future
6	I/O	`ignition`, `vehicle_voltage_v`	Optional
7	Extra	`x_<source>_<field>`	Optional

Full specification: SPEC-01 | SPEC-02 | SPEC-03

Development

git clone https://github.com/telemachus3/telemachus
cd telemachus/python-sdk
pip install -e .[dev]
pytest                  # 31 tests

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

telemachus-1.0.0a4.tar.gz (138.5 kB view details)

Uploaded Aug 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

telemachus-1.0.0a4-py3-none-any.whl (119.4 kB view details)

Uploaded Aug 16, 2026 Python 3

File details

Details for the file telemachus-1.0.0a4.tar.gz.

File metadata

Download URL: telemachus-1.0.0a4.tar.gz
Upload date: Aug 16, 2026
Size: 138.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for telemachus-1.0.0a4.tar.gz
Algorithm	Hash digest
SHA256	`ea9cf0250af9860d13041ddb49a4c2b8bdb94e5a5bc3a254d08c9047eb0038cd`
MD5	`f2d93cedf38011e8fa6122f12ac4fefb`
BLAKE2b-256	`f03b65edcf8a163d221406415b7f3f24500db811e6702424ad37e5068e0908c8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for telemachus-1.0.0a4.tar.gz:

Publisher: release.yml on telemachus3/telemachus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: telemachus-1.0.0a4.tar.gz
- Subject digest: ea9cf0250af9860d13041ddb49a4c2b8bdb94e5a5bc3a254d08c9047eb0038cd
- Sigstore transparency entry: 2487315695
- Sigstore integration time: Aug 16, 2026
Source repository:
- Permalink: telemachus3/telemachus@eb44686b4ef13b753d043e54a2df334ea1d2a001
- Branch / Tag: refs/tags/v1.0.0a4
- Owner: https://github.com/telemachus3
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@eb44686b4ef13b753d043e54a2df334ea1d2a001
- Trigger Event: push