Skip to content

[fix] Normalize offset-less ISO strings to UTC in to_utc_datetime - #10301

Open
Lesereingrape wants to merge 1 commit into
agno-agi:mainfrom
Lesereingrape:fix/to-utc-datetime-naive-iso
Open

Lesereingrape wants to merge 1 commit into
agno-agi:mainfrom
Lesereingrape:fix/to-utc-datetime-naive-iso

Conversation

@Lesereingrape

@Lesereingrape Lesereingrape commented Sep 18, 2026 •

Copy link
Copy Markdown

Summary

to_utc_datetime() promises a UTC datetime, and three of its four branches enforce that — the datetime branch
replaces a missing tzinfo, the date branch combines with tzinfo=timezone.utc, the numeric branch uses
fromtimestamp(..., tz=utc). The ISO-string branch returned datetime.fromisoformat(value) directly, so an
offset-less string came back naive: to_utc_datetime(date(2024, 1, 1)) is aware while
to_utc_datetime("2024-01-01") — the same instant, the spelling the JSON-ish backends persist — is naive, and
comparing the two raises TypeError: can't compare offset-naive and offset-aware datetimes.

Through the shipped model that means GET /metrics/daily renders "date": "2026-09-18T00:00:00" next to
"created_at": "2026-09-18T14:56:05Z": one payload, two offset conventions. A client parsing the offset-less
date-time reads it as local time, so the same daily bucket shifts a calendar day across viewer timezones.

The fix normalizes the parsed value exactly as the datetime branch already does, so an explicit offset
(...Z, ...+05:30) is still preserved rather than flattened.

Closes #10300

Type of change

  • Bug fix
  • New feature
  • Breaking change
  • Improvement
  • Model update
  • Other:

Checklist

  • Code complies with style guidelines
  • Ran format/validation scripts (./scripts/format.sh and ./scripts/validate.sh)
  • Self-review completed
  • Documentation updated (comments, docstrings)
  • Examples and guides: Relevant cookbook examples have been included or updated (if applicable)
  • Tested in clean environment
  • Tests added/updated (if applicable)

Duplicate and AI-Generated PR Check

  • I have searched existing open pull requests and confirmed that no other PR already addresses this issue
  • If a similar PR exists, I have explained below why this PR is a better approach
  • Check if this PR was entirely AI-generated (by Copilot, Claude Code, Cursor, etc.)

Additional Notes

How this was verified (Python 3.13 on Windows; no DB, server, network or API key):

  • Measured the four input spellings on unmodified main (85b6d1d): date(2024,1,1) → tzinfo=UTC,
    "2024-01-01" → tzinfo=None, "2024-01-01T12:00:00" → tzinfo=None, "…Z" → tzinfo=UTC, and
    to_utc_datetime(date(2024,1,1)) > to_utc_datetime("2024-01-01") → TypeError.
  • End-to-end through the real response model: DayAggregatedMetrics.from_dict({"date": "2026-09-18", …}) yielded
    date.tzinfo=None, created_at.tzinfo=UTC and a JSON body of 2026-09-18T00:00:00 vs 2026-09-18T14:56:05Z;
    after the change both render with Z. The persisted value really is an offset-less string on these backends —
    db/in_memory/utils.py:117 date_iso = date_to_process.isoformat() → :132 "date": date_iso (same in
    db/json/utils.py:132, db/gcs_json/utils.py:132), which their own readers treat as a string via
    datetime.strptime(metric.get("date", ""), "%Y-%m-%d") (in_memory_db.py:1063, json_db.py:1271,
    gcs_json_db.py:1253).
  • libs/agno/tests/unit/os/test_utils.py: 176 tests (173 existing + 3 new). With the change 175 pass; the one
    failure is test_handles_negative_timestamp, which fails identically on unmodified main on this box because
    Windows datetime.fromtimestamp() rejects a negative epoch. Nothing about that branch is touched here.
  • Reverting only the source change (keeping the tests) fails exactly test_adds_utc_to_offsetless_iso_string and
    test_iso_date_string_matches_date_object, so the new tests cover the bug rather than the harness.
  • Whole-suite fail-set diff for tests/unit/os (run with --continue-on-collection-errors): baseline
    103 failed / 1368 passed / 126 collection errors → patched 101 failed / 1370 passed / 126 collection errors;
    diffing the two FAILED lists shows the only change is my two new tests flipping, 0 regressions. The residual
    failures/errors are pre-existing and come from optional extras missing in this local env.
  • ruff check, ruff format --check and ruff check --select I are clean on both changed files; mypy reports no
    error in agno/os/utils.py (only the pre-existing missing-optional-stub and team/_run.py errors elsewhere).

Behaviour intentionally preserved: an ISO string that carries an explicit non-UTC offset keeps it
(test_preserves_non_utc_offset_in_iso_string), matching test_preserves_non_utc_timezone for datetime objects.
The only value that changes is an offset-less string, which previously produced a naive datetime.

Collision check — searched open issues/PRs for to_utc_datetime / fromisoformat / naive, then scanned the
changed-file lists of all 767 open PRs. 22 touch libs/agno/agno/os/utils.py, but none of their patches contains
fromisoformat
, so no one edits this branch. The closest hunk is #8540 (open since 2026-06-23) at
@@ -52,7 +52,7 @@, which replaces the numeric fallback (fromtimestamp → epoch + timedelta) three lines
below where my hunk ends — a different branch of the same function, no overlapping lines. Two PRs touch
tests/unit/os/test_utils.py (#8945, #8540) and both append at the end of the file (@@ -213,3 +…, for
format_sse_event and media-normalization tests); this PR inserts after test_preserves_non_utc_timezone near line
79, so the additions are independent.

AI-generated disclosure: the code and tests in this PR were written by an AI coding agent, and every line of the diff was read by that same agent, which also ran every check listed above. No human has reviewed this diff, so the self-review box above is the agent's own review. (This sentence replaced the wording “reviewed line by line by the author” on 2026-09-20; a body edit leaves no public trace, so the correction is stated here.)


AI assistance (per CONTRIBUTING.md §5): the investigation, the diff and this description were produced by an AI coding agent working under the account owner's standing instruction to find and fix defects of this kind and open PRs for them; no human read the diff before it was opened. Everything quoted in the validation section was run by that agent on a local checkout and is reproducible on a fresh clone of this branch. The commit carries no AI co-author trailer.

@Lesereingrape

Copy link
Copy Markdown
Author

Real CI has not run on this PR yet - it needs one click from someone with write access.

The three workflow runs on head 790c75ea (PR Lint twice and Validation) are all completed / action_required, i.e. queued and waiting for a maintainer to press Approve and run. The only check that has actually executed is the automatic Triage PR (success), which is why the merge box reads blocked: it is a missing approval, not a failing check.

The verification I do control - the ruff and mypy runs and the test results they produced - is recorded in the description above; I am not adding new claims here.

The other six PRs from this account are in the same state (#10281, #10287, #10297, #10320, #10323, #10325), each with 2-3 runs awaiting approval. The repo-wide queue is large, so I realise this is not a trivial ask; say the word and I will narrow the set down.

Disclosure: this account is being operated by an AI coding assistant on the owner's instruction, and the PR bodies say so as well.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] to_utc_datetime() returns a naive datetime for offset-less ISO strings, unlike its other branches

1 participant