Liberator emits timestamps in the form YYYY-MM-DD HH:MM:59.999 (end of the 60-second bar). kti emits timestamps as YYYY-MM-DDTHH:MM:00 (start of bar). Both represent the same 60-second window. The Liberator-to-engine normalization rule is: parse as US/Eastern naive, subtract 59.999 seconds, localize to ET, convert to UTC. Verified against the cached Liberator + kti pairs.
2026-06-02 04:00:59.999 # bar 1 - covers 04:00:00 to 04:01:00 ET 2026-06-02 04:01:59.999 # bar 2 - covers 04:01:00 to 04:02:00 ET 2026-06-02 04:02:59.999 2026-06-02 04:03:59.999 2026-06-02 04:04:59.999
2026-06-02T09:30:00 # bar - covers 09:30:00 to 09:31:00 ET 2026-06-02T09:31:00 2026-06-02T09:32:00 2026-06-02T09:33:00 2026-06-02T09:34:00
| Source | Format | Anchor | Precision |
|---|---|---|---|
| Liberator | YYYY-MM-DD HH:MM:59.999 | End of bar | Millisecond |
| kti | YYYY-MM-DDTHH:MM:00 | Start of bar | Second |
Both represent the same 60-second window. To align Liberator with kti and the v1.1 engine's compute_features() expectations (which treat bar_timestamp as the bar's start), Liberator needs to be normalized.
Three equivalent formulations:
stage_a1_parity.py)# Liberator emits: "YYYY-MM-DD HH:MM:59.999" naive ET
parsed = pd.to_datetime(lib_df["timestamp"])
# Subtract 59.999 seconds to get the START of the bar
bar_start = parsed - pd.Timedelta(seconds=59, milliseconds=999)
# Localize to US/Eastern, then convert to UTC (engine expectation)
lib_df["timestamp"] = bar_start.dt.tz_localize("US/Eastern").dt.tz_convert("UTC")
# Floor each timestamp to the nearest minute below; same result
bar_start = parsed.dt.floor("min")
lib_df["timestamp"] = bar_start.dt.tz_localize("US/Eastern").dt.tz_convert("UTC")
Note: floor("min") on HH:MM:59.999 returns HH:MM:00 - exactly the kti start-of-bar form. This is the cleaner one-liner.
# Slightly more paranoid: subtract 60s, add 1ms to land exactly on minute boundary bar_start = parsed - pd.Timedelta(seconds=60) + pd.Timedelta(milliseconds=1)
Use floor("min") in production. The other forms are listed for clarity.
| Source | Timestamp string | Parsed |
|---|---|---|
| kti | 2026-06-02T09:30:00 | 2026-06-02 09:30:00 (naive ET) |
| Liberator | 2026-06-02 09:30:59.999 | 2026-06-02 09:30:59.999 (naive ET) |
Direct merge would fail - the strings don't match.
| Source | Original | Normalized (UTC) |
|---|---|---|
| kti | 2026-06-02T09:30:00 (ET) | 2026-06-02 13:30:00+00:00 |
| Liberator (after subtract 59.999s + tz) | 2026-06-02 09:30:59.999 (ET) | 2026-06-02 13:30:00+00:00 |
Match exact. The pandas merge on timestamp column will join on the same key.
Applied the normalization rule to 5 cached Liberator pairs. Compared against kti where overlap existed (only NVDA 6/2):
| Pair | Lib raw bars | Lib normalized RTH bars | kti RTH bars | Timestamp alignment |
|---|---|---|---|---|
| NVDA 2026-06-02 | 960 | 390 | 390 | All 390 align exactly |
| AAOI 2026-04-10 | 957 | 390 | (kti has no bars; older than window) | No kti to compare |
| CAR 2026-04-13 | 760 | 390 | (no kti) | — |
| WULF 2026-04-13 | 838 | 390 | (no kti) | — |
| CRWV 2026-04-13 | 960 | 390 | (no kti) | — |
All 5 produce exactly 390 RTH bars after normalization and RTH filtering. The single overlap pair (NVDA 6/2) aligns 100% with kti. The normalization rule is sound.
| Pitfall | Symptom | Fix |
|---|---|---|
| Forgetting timezone localization | Naive ET parsed as naive UTC (4-hour shift wrong direction) | Always .tz_localize("US/Eastern") after parsing |
| Not subtracting 59.999s | Liberator bar that covers 09:30-09:31 ET gets timestamp 09:31:00 UTC; off-by-one bar; merges miss | Use floor("min") after parsing |
Using round("min") instead of floor | HH:MM:59.999 rounds UP to HH:(MM+1):00 | Use floor not round; or subtract 1 second first |
Mixing Liberator's _seq ordering with timestamp ordering | _seq is a global counter, not a per-symbol time index | Always sort by parsed timestamp, never by _seq |
| Liberator bars sometimes have 0 vwap at premarket boundary | VWAP = 0 in the first premarket bar of the day | Filter or set to NaN; do not divide |
def liberator_to_df(bars: list) -> pd.DataFrame:
"""Normalize Liberator bars to start-of-bar UTC, kti-compatible schema."""
df = pd.DataFrame(bars)
parsed = pd.to_datetime(df["timestamp"])
bar_start = parsed.dt.floor("min")
df["timestamp"] = (
bar_start
.dt.tz_localize("US/Eastern")
.dt.tz_convert("UTC")
)
df = df[["timestamp", "open", "high", "low", "close", "volume", "vwap"]].copy()
for c in ("open", "high", "low", "close", "vwap"):
df[c] = df[c].astype(float)
df["volume"] = df["volume"].astype(float)
return df.sort_values("timestamp").reset_index(drop=True)
The vwap column is Liberator's native bar-level VWAP and is included for the §3 Liberator-VWAP-cross-check (deferred until entitlement is restored - see parity report).