fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/samsara/driver_fuel_energy_report.py

@@ -0,0 +1,153 @@
+# src/fleetpull/models/samsara/driver_fuel_energy_report.py
+"""Samsara DriverFuelEnergyReport response model
+(``GET /fleet/reports/drivers/fuel-energy``, post-decoder
+window-stamped grain).
+
+Written from captured live responses (2026-07-20/21 probe session: a
+47/47 total census on the 1-day walk), never from docs. The vehicle
+arm's shape with the entity swapped: the same metric core plus
+``estFuelEnergyCost``, attributed to a ``driver {id, name}`` ref
+instead of the vehicle block -- and NO ``externalIds`` anywhere on this
+arm (never observed, so unmodeled as unobserved, never excluded).
+
+The model mirrors the record ``SamsaraWindowReportPageDecoder`` emits:
+``window_start`` / ``window_end`` are DECODER-SYNTHESIZED
+(``windowStartDate``/``windowEndDate``) -- report rows carry NO
+event-time key of any kind, so the decoder stamps each row with the
+window the SENT spec asked for, copied verbatim from its
+``startDate``/``endDate`` params (the request-sourced contrast with the
+stats triple's record-sourced identity keys); everything else is
+wire-verbatim.
+
+**NON-ADDITIVITY -- the rollup grain is the request window
+(2026-07-21).** Proven on this surface family twice: widening a 1-day
+window to 2 days GREW per-entity metrics, and summing two adjacent day
+rollups mismatched the two-day rollup on 89 of 267 vehicle reports.
+Each row is the provider's answer for exactly its window, nothing else:
+day rows MUST NOT be summed to reproduce a wider window's rollup --
+which is why the binding declares ``fixed_unit_days=1``.
+
+Requiredness posture: the window stamps, the ``driver`` ref, and its
+``id`` are required STRUCTURALLY (a rollup row without its window or
+its entity is meaningless); the metric core is required on the
+WHOLE-WALK posture (47/47 total census -- a per-window rollup surface
+has no absence mechanism to be conservative about, so a missing metric
+is a contract change worth a loud failure). The ref's ``name`` stays
+optional per the conservative posture.
+
+``efficiencyMpge``, ``estCarbonEmissionsKg``, and the cost ``amount``
+are MIXED int|float on the wire -- modeled ``float``; ``currencyCode``
+(observed only ``'USD'`` on a 100-report sample) is census-open, a
+plain ``str``.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator, except the decoder-synthesized window stamps, which
+take explicit aliases.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'DriverFuelEnergyCost',
+    'DriverFuelEnergyDriverRef',
+    'DriverFuelEnergyReport',
+]
+
+
+class DriverFuelEnergyCost(ResponseModel):
+    """The ``estFuelEnergyCost`` block: the window's estimated cost.
+
+    Both keys were 47/47 in census and required per the whole-walk
+    posture (module docstring).
+
+    Attributes:
+        amount: The monetary amount -- MIXED int|float on the wire,
+            modeled float.
+        currency_code: The currency code -- observed only ``'USD'`` on
+            a 100-report sample, census-open, so a plain ``str``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    amount: float
+    currency_code: str
+
+
+class DriverFuelEnergyDriverRef(ResponseModel):
+    """The ``driver`` block: the rollup's driver entity.
+
+    Both keys were 47/47 in census; only ``id`` is required by
+    structural judgment (a ref without an id references nothing), while
+    ``name`` stays optional per the conservative posture. No
+    ``externalIds`` was ever observed on this arm -- unmodeled as
+    unobserved.
+
+    Attributes:
+        id: Samsara's driver id -- a string, mirrored as string.
+        name: The driver's display name.
+    """
+
+    id: str
+    name: str | None = None
+
+
+class DriverFuelEnergyReport(ResponseModel):
+    """One driver's fuel-energy rollup over exactly one request window.
+
+    A pure mirror of the window-stamped post-decoder record (module
+    docstring: the window stamps are decoder-synthesized from the sent
+    spec; everything else is wire-verbatim). Field semantics and units
+    are Samsara's; no value is derived or interpreted here. Day rows
+    MUST NOT be summed to reproduce a wider window's rollup (module
+    docstring).
+
+    Attributes:
+        window_start: The request window's start (decoder-synthesized
+            ``windowStartDate``, verbatim from the sent ``startDate``)
+            -- the event-time column: the row's time identity is the
+            window that produced it.
+        window_end: The request window's end (decoder-synthesized
+            ``windowEndDate``, verbatim from the sent ``endDate``).
+        driver: The rollup's driver entity.
+        distance_traveled_meters: Distance traveled in the window, in
+            meters, a bare int.
+        efficiency_mpge: Efficiency in MPGe -- MIXED int|float on the
+            wire, modeled float.
+        energy_used_kwh: Energy used in the window, in kWh, a bare int.
+        engine_idle_time_duration_ms: Engine idle time in the window,
+            in milliseconds, a bare int.
+        engine_run_time_duration_ms: Engine run time in the window, in
+            milliseconds, a bare int.
+        est_carbon_emissions_kg: Estimated carbon emissions in the
+            window, in kilograms -- MIXED int|float on the wire,
+            modeled float.
+        fuel_consumed_ml: Fuel consumed in the window, in milliliters,
+            a bare int.
+        est_fuel_energy_cost: The window's estimated fuel/energy cost
+            block.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Decoder-synthesized window identity (the sent spec's own window).
+    window_start: datetime = Field(alias='windowStartDate')
+    window_end: datetime = Field(alias='windowEndDate')
+
+    # The rollup's entity.
+    driver: DriverFuelEnergyDriverRef
+
+    # The wire-verbatim metric core (whole-walk required; provider
+    # units mirrored verbatim).
+    distance_traveled_meters: int
+    efficiency_mpge: float
+    energy_used_kwh: int
+    engine_idle_time_duration_ms: int
+    engine_run_time_duration_ms: int
+    est_carbon_emissions_kg: float
+    fuel_consumed_ml: int
+    est_fuel_energy_cost: DriverFuelEnergyCost

fleetpull/models/samsara/driver_vehicle_assignment.py

@@ -0,0 +1,168 @@
+# src/fleetpull/models/samsara/driver_vehicle_assignment.py
+"""Samsara DriverVehicleAssignment response model
+(``GET /fleet/driver-vehicle-assignments``).
+
+Written from captured live responses (2026-07-20 probe session: a full
+24-hour walk of the fleet under BOTH ``filterBy`` values -- 216 records
+each, proven identical as tuple sets, so the two sweeps are one
+dataset), never from docs.
+
+The record census is total: EVERY key was present on 216/216 records --
+``startTime``/``endTime`` (RFC3339 strs, recovered tz-aware UTC; no
+empty or missing ``endTime`` was observed -- assignments were only
+ever observed complete), ``assignedAtTime`` (present on every record
+but the EMPTY STRING on all of them -- the 2026-07-21 live proof
+failed datetime parsing on record 0, and a 6,921-row week-wide value
+census found '' on every single row: the Samsara empty-string posture,
+mirrored verbatim as ``str``; a populated value's wire format is
+UNOBSERVED, so no datetime recovery is presumed -- revisit on a
+capture that shows one), ``assignmentType``
+(str), ``isPassenger`` (bool), ``driver {id: str, name: str}``, and
+``vehicle {id: str, name: str, externalIds}``.
+
+``assignmentType``'s 24h census observed ``{'static': 158, 'HOS': 58}``
+and the 2026-07-21 week-wide live proof added ``driverApp`` (25 of
+8,042 rows) -- an OPEN vocabulary, not API-enforced on output (the
+eldExemptReason lesson; contrast ``filterBy``'s INPUT vocabulary, which
+IS 400-enforced), so the field stays a plain ``str`` with the observed
+values documented here, never an enum -- exactly the posture that let
+the third value land without a failure.
+
+``vehicle.externalIds`` carries the LITERAL DOTTED wire keys
+``samsara.serial`` and ``samsara.vin`` (both str, 216/216) on a NESTED
+object, mirrored via explicit ``Field`` aliases -- the Samsara
+``VehicleExternalIds`` precedent. Note the contrast with the stats
+triple's ``vehicleSerial``/``vehicleVin``: those are flat keys the
+series-unnesting DECODER synthesizes; these are the wire's own dotted
+keys on the record, mirrored verbatim.
+
+Requiredness posture: 216/216 across one day's two-sweep walk is NOT a
+whole-population-over-time oath (the drivers conservative posture would
+leave everything optional), but the structural core is required anyway
+by structural judgment -- an assignment without its parties (``driver``,
+``vehicle``, and their ``id``\\s: a party ref without an id references
+nothing) or its bounds (``startTime``/``endTime``) is structurally
+meaningless, so a future record omitting them should fail loudly, never
+land an all-null row. Everything else (``assignedAtTime``,
+``assignmentType``, ``isPassenger``, the ref ``name``\\s, and
+``externalIds`` with its keys) stays optional per the conservative
+posture. This is the asset_locations judgment, recorded here and in
+DESIGN section 8.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator, except the dotted external-id keys, which take
+explicit aliases.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'AssignmentDriverRef',
+    'AssignmentVehicleExternalIds',
+    'AssignmentVehicleRef',
+    'DriverVehicleAssignment',
+]
+
+
+class AssignmentDriverRef(ResponseModel):
+    """The ``driver`` block: the assignment's driver party.
+
+    Both keys were 216/216 in census; only ``id`` is required by
+    structural judgment (module docstring) -- a party ref without an id
+    references nothing, while ``name`` stays optional per the
+    conservative posture.
+
+    Attributes:
+        id: Samsara's driver id -- a string, mirrored as string.
+        name: The driver's display name.
+    """
+
+    id: str
+    name: str | None = None
+
+
+class AssignmentVehicleExternalIds(ResponseModel):
+    """The vehicle ref's ``externalIds`` block: namespaced external ids.
+
+    The wire keys are the LITERAL DOTTED ``samsara.serial`` and
+    ``samsara.vin`` (both str, 216/216 in census), mirrored via explicit
+    aliases on this NESTED object -- the ``VehicleExternalIds``
+    precedent, and the contrast with the stats triple's
+    decoder-synthesized flat keys (module docstring). Each key is
+    independently optional (the conservative posture; the vehicles
+    surface proves ``externalIds`` variance exists in this fleet).
+
+    Attributes:
+        samsara_serial: The gateway serial (wire key ``samsara.serial``).
+        samsara_vin: The VIN (wire key ``samsara.vin``).
+    """
+
+    samsara_serial: str | None = Field(default=None, alias='samsara.serial')
+    samsara_vin: str | None = Field(default=None, alias='samsara.vin')
+
+
+class AssignmentVehicleRef(ResponseModel):
+    """The ``vehicle`` block: the assignment's vehicle party.
+
+    All three keys were 216/216 in census; only ``id`` is required by
+    structural judgment (module docstring), while ``name`` and
+    ``external_ids`` stay optional per the conservative posture.
+
+    Attributes:
+        id: Samsara's vehicle id -- a string, mirrored as string.
+        name: The vehicle's display name.
+        external_ids: The dotted-key external-id block (wire key
+            ``externalIds``).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    name: str | None = None
+    external_ids: AssignmentVehicleExternalIds | None = None
+
+
+class DriverVehicleAssignment(ResponseModel):
+    """One driver-vehicle assignment interval.
+
+    A pure mirror of the captured record. Field semantics and units are
+    Samsara's; no value is derived or interpreted here. The structural
+    core (``driver``, ``vehicle``, ``start_time``, ``end_time``) is
+    required by structural judgment; the rest is optional per the
+    conservative posture (module docstring).
+
+    Attributes:
+        driver: The driver party of the assignment.
+        vehicle: The vehicle party of the assignment.
+        start_time: The assignment interval's start (RFC3339, recovered
+            tz-aware UTC) -- the event-time column: retrieval is
+            overlap-anchored, and ownership anchors here via the
+            runner's post-fetch window filter.
+        end_time: The assignment interval's end (RFC3339, recovered
+            tz-aware UTC); never observed empty or missing --
+            assignments were only ever observed complete.
+        assigned_at_time: The instant the assignment was made --
+            observed as the EMPTY STRING on every one of 6,921
+            week-censused rows (live-proven 2026-07-21), mirrored
+            verbatim; a populated value has never been observed.
+        assignment_type: How the assignment arose. Observed values
+            ``static``, ``HOS``, and ``driverApp`` (the third surfaced
+            only at week scale) -- an open vocabulary, so a plain
+            ``str`` (module docstring).
+        is_passenger: Whether the driver rode as a passenger.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    driver: AssignmentDriverRef
+    vehicle: AssignmentVehicleRef
+    start_time: datetime
+    end_time: datetime
+    assigned_at_time: str | None = None
+    assignment_type: str | None = None
+    is_passenger: bool | None = None

fleetpull/models/samsara/engine_state.py

@@ -0,0 +1,92 @@
+# src/fleetpull/models/samsara/engine_state.py
+"""Samsara EngineState response model
+(``GET /fleet/vehicles/stats/history``, ``types=engineStates``,
+post-decoder reading grain).
+
+Written from captured live responses (2026-07-20 probe session: a
+1,045-reading census over a 24-hour window, 138 vehicles -- every
+vehicle returned per the requested type carried data; no empty-array
+padding was observed), never from docs. The model mirrors the FLAT
+record ``SamsaraVehicleSeriesPageDecoder`` emits, one row per reading
+-- the grain the records pipeline represents (scalars, not
+list-of-objects; DESIGN section 9) -- and its two field families have
+different provenance:
+
+- ``vehicle_id`` / ``vehicle_name`` / ``vehicle_serial`` /
+  ``vehicle_vin`` are DECODER-SYNTHESIZED: the unnesting lifts them
+  from the per-vehicle ``id``/``name`` keys and the ``externalIds``
+  object's literal dotted ``samsara.serial``/``samsara.vin`` wire keys
+  onto every reading. ``vehicle_id`` and ``vehicle_name`` were 74/74
+  on the censused mixed-type page and are required; ``vehicle_serial``
+  and ``vehicle_vin`` were also 74/74 there, but one page is not a
+  whole-population oath (an unplugged or serial-less unit could omit
+  its ``externalIds`` block -- the vehicles surface shows exactly that
+  variance), so both stay OPTIONAL -- the drivers conservative posture.
+- ``time`` / ``value`` are WIRE-VERBATIM reading keys: the series
+  census observed exactly ``{time, value}`` on every one of the 1,045
+  readings, so both are required.
+
+``value`` is a plain ``str``, NOT an enum: the observed vocabulary is
+exactly ``{'On': 475, 'Off': 301, 'Idle': 269}``, but that closure is
+census-only -- the API does not 400-enforce output values (unlike
+``driverActivationStatus``'s proven closure; the ``eldExemptReason``
+lesson), so an unobserved state lands as data, not a crash.
+
+``time`` is an RFC3339 string recovered as a tz-aware UTC datetime by
+Pydantic's standard parse. Readings fall strictly inside the requested
+``[startTime, endTime)`` window (probe-proven), so ``time`` is the
+endpoint's event-time column with retrieval and routing coinciding
+natively.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['EngineState']
+
+
+class EngineState(ResponseModel):
+    """One engine-state reading of one vehicle, at the reading grain.
+
+    A pure mirror of the flat post-decoder record (module docstring:
+    the identity fields are decoder-synthesized, the reading fields
+    wire-verbatim). Field semantics are Samsara's; no value is derived
+    or interpreted here.
+
+    Attributes:
+        vehicle_id: The vehicle's Samsara id -- a numeric string,
+            decoder-synthesized from the vehicle record's ``id``.
+        vehicle_name: The vehicle's display name, decoder-synthesized
+            from the vehicle record's ``name``.
+        vehicle_serial: The gateway serial, decoder-synthesized from
+            ``externalIds['samsara.serial']`` (74/74 on the censused
+            page; optional -- module docstring).
+        vehicle_vin: The VIN, decoder-synthesized from
+            ``externalIds['samsara.vin']`` (74/74 on the censused page;
+            optional -- module docstring).
+        time: The reading instant (RFC3339, recovered tz-aware UTC) --
+            the event-time column; readings fall strictly inside the
+            requested window.
+        value: The engine state -- a plain string; observed vocabulary
+            exactly ``On``/``Off``/``Idle``, census-closed only, so
+            membership is not enforced (module docstring).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Decoder-synthesized vehicle identity.
+    vehicle_id: str
+    vehicle_name: str
+    vehicle_serial: str | None = None
+    vehicle_vin: str | None = None
+
+    # Wire-verbatim reading payload.
+    time: datetime
+    value: str

fleetpull/models/samsara/gps_reading.py

@@ -0,0 +1,146 @@
+# src/fleetpull/models/samsara/gps_reading.py
+"""Samsara GpsReading response model
+(``GET /fleet/vehicles/stats/history``, ``types=gps``, post-decoder
+reading grain).
+
+Written from captured live responses (2026-07-20 probe session: a
+2,512-reading sample over 8 cursor pages of a 24-hour window whose
+full walk spanned 569 vehicles -- every vehicle returned per the
+requested type carried data; no empty-array padding was observed),
+never from docs. The model mirrors the FLAT record
+``SamsaraVehicleSeriesPageDecoder`` emits, one row per reading -- the
+grain the records pipeline represents (scalars, not list-of-objects;
+DESIGN section 9) -- and its two field families have different
+provenance:
+
+- ``vehicle_id`` / ``vehicle_name`` / ``vehicle_serial`` /
+  ``vehicle_vin`` are DECODER-SYNTHESIZED: the unnesting lifts them
+  from the per-vehicle ``id``/``name`` keys and the ``externalIds``
+  object's literal dotted ``samsara.serial``/``samsara.vin`` wire keys
+  onto every reading. ``vehicle_id`` and ``vehicle_name`` were 74/74
+  on the censused mixed-type page and are required; ``vehicle_serial``
+  and ``vehicle_vin`` were also 74/74 there, but one page is not a
+  whole-population oath (an unplugged or serial-less unit could omit
+  its ``externalIds`` block -- the vehicles surface shows exactly that
+  variance), so both stay OPTIONAL -- the drivers conservative posture.
+- The reading keys are WIRE-VERBATIM. Sampled presence out of 2,512:
+  ``time``, ``latitude``, ``longitude``, ``headingDegrees``,
+  ``speedMilesPerHour``, ``isEcuSpeed``, and ``reverseGeo``
+  (``{formattedLocation}``, the key always present in every carrying
+  block) rode every reading and are required; ``address``
+  (``{id, name}``, the defined-address-book reference) rode 401/2,512
+  and is optional.
+
+``speedMilesPerHour`` is MIXED int|float on the wire -- modeled
+``float``, lax coercion lifting the int shape (the idling_events
+``fuelConsumedMilliliters`` precedent). ``headingDegrees`` is a bare
+int on every sampled reading. ``time`` is an RFC3339 string recovered
+as a tz-aware UTC datetime by Pydantic's standard parse. Readings fall
+strictly inside the requested ``[startTime, endTime)`` window
+(probe-proven), so ``time`` is the endpoint's event-time column with
+retrieval and routing coinciding natively.
+
+The reverse-geocoded ``formattedLocation`` string is PII-adjacent --
+capture fixtures are fully synthetic (the trips precedent).
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'GpsReading',
+    'GpsReadingAddressRef',
+    'GpsReadingReverseGeo',
+]
+
+
+class GpsReadingReverseGeo(ResponseModel):
+    """The ``reverseGeo`` block: the reading's reverse-geocoded location.
+
+    Present on every sampled reading (2,512/2,512), with
+    ``formattedLocation`` present in every carrying block.
+
+    Attributes:
+        formatted_location: The reverse-geocoded location string,
+            mirrored verbatim (PII-adjacent; fixtures are synthetic).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    formatted_location: str
+
+
+class GpsReadingAddressRef(ResponseModel):
+    """The ``address`` block: a matched address-book reference (401/2,512).
+
+    Present when the reading fell inside a defined address/geofence --
+    the addresses surface is the book it references.
+
+    Attributes:
+        id: The defined address's id -- a string on the wire.
+        name: The defined address's display name.
+    """
+
+    id: str
+    name: str
+
+
+class GpsReading(ResponseModel):
+    """One GPS reading of one vehicle, at the reading grain.
+
+    A pure mirror of the flat post-decoder record (module docstring:
+    the identity fields are decoder-synthesized, the reading fields
+    wire-verbatim). Field semantics and units are Samsara's; no value
+    is derived or interpreted here.
+
+    Attributes:
+        vehicle_id: The vehicle's Samsara id -- a numeric string,
+            decoder-synthesized from the vehicle record's ``id``.
+        vehicle_name: The vehicle's display name, decoder-synthesized
+            from the vehicle record's ``name``.
+        vehicle_serial: The gateway serial, decoder-synthesized from
+            ``externalIds['samsara.serial']`` (74/74 on the censused
+            page; optional -- module docstring).
+        vehicle_vin: The VIN, decoder-synthesized from
+            ``externalIds['samsara.vin']`` (74/74 on the censused page;
+            optional -- module docstring).
+        time: The reading instant (RFC3339, recovered tz-aware UTC) --
+            the event-time column; readings fall strictly inside the
+            requested window.
+        latitude: Reading latitude, decimal degrees.
+        longitude: Reading longitude, decimal degrees.
+        heading_degrees: Heading in degrees, a bare int on every
+            sampled reading.
+        speed_miles_per_hour: Speed in miles per hour -- MIXED
+            int|float on the wire, modeled float (module docstring).
+        is_ecu_speed: Whether the speed came from the ECU.
+        reverse_geo: The reverse-geocoded location block (2,512/2,512).
+        address: The matched address-book reference (401/2,512).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Decoder-synthesized vehicle identity.
+    vehicle_id: str
+    vehicle_name: str
+    vehicle_serial: str | None = None
+    vehicle_vin: str | None = None
+
+    # Wire-verbatim reading payload.
+    time: datetime
+    latitude: float
+    longitude: float
+    heading_degrees: int
+    speed_miles_per_hour: float
+    is_ecu_speed: bool
+    reverse_geo: GpsReadingReverseGeo
+
+    # The partial block (absence-shaped).
+    address: GpsReadingAddressRef | None = None