[Kayvan Zahiri (Kayvan-Zahiri)]

Constructing a Document or calling DocumentRenderer.render_document() raises PydanticUserError: Document is not fully defined, even when last_modified is omitted. Generating the model's JSON schema fails for the same reason: the datetime module is imported only inside TYPE_CHECKING, so Pydantic cannot resolve the field at runtime.

Import datetime at runtime, with a targeted TC003 exemption documenting the Pydantic requirement. Add five regressions covering omitted and null timestamps, an ISO timestamp, record rendering, and JSON-schema generation.

This bug exists on both main and release-candidate/v1; the patch targets main per AGENTS.md.

Validation on Python 3.12 with the release branch's frozen development environment:

• All five new regressions fail before the fix and pass afterward through normal PyAirbyte imports.
• Full unit suite: 1,279 passed, one existing Python 3.12 PokeAPI skip, 13 warnings.
• Full repository Ruff lint and formatting pass (262 files formatted).
• Full Pyrefly check passes with the locked interpreter explicitly selected; two existing redundant-cast warnings also occur on an untouched baseline. Default interpreter discovery initially produced ten dependency-related diagnostics, corrected by selecting the environment.
• Wheel and source distribution build; whitespace check passes.

No live Airbyte sync, database deployment, or paid service was used. Tests run with telemetry disabled. Full integration and generated-documentation suites are outside this validation.

[github-actions]

👋 Welcome to PyAirbyte!

Thank you for your contribution from Kayvan-Zahiri/PyAirbyte! We're excited to have you in the Airbyte community.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/Kayvan-Zahiri/PyAirbyte.git@codex/fix-document-runtime-type' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/Kayvan-Zahiri/PyAirbyte.git@codex/fix-document-runtime-type'

PR Slash Commands

As needed or by request, Airbyte Maintainers can execute the following slash commands on your PR:

• /fix-pr - Fixes most formatting and linting issues
• /uv-lock - Updates uv.lock file
• /test-pr - Runs tests with the updated PyAirbyte
• /prerelease - Builds and publishes a prerelease version to PyPI
• /evals - Runs the Cloud MCP evals that use the MCP tools this PR changed (/evals full=true runs the full suite)

📚 Show Repo Guidance

Helpful Resources

• Contributing Guidelines
• PyAirbyte Documentation
• API Reference

If you have any questions, feel free to ask in the PR comments or join our community:

• Airbyte Slack - Join the #pyairbyte channel
• GitHub Discussions

📝 Edit this welcome message.

[Aaron ("AJ") Steers (aaronsteers)]

Kayvan Zahiri (@Kayvan-Zahiri) - Thanks for your contribution! Reviewing now.

Heads up: I'm happy to accept this contriubution on main but please note that our active iterations are going into the release-candidate/v1 branch and our 1.0 RC releases.

[Copilot]

🟢 Approval recommended

The narrowly scoped import fix addresses the reported failure, and the regression coverage exercises the affected paths with no blocking issues identified.

No open issues 🎉

What changed in this PR

Fixes document construction and JSON-schema generation by making the timestamp type available to Pydantic at runtime.

Changes:

• Moves the datetime import out of TYPE_CHECKING, with a targeted lint exemption.
• Adds five regression cases covering omitted, null, and ISO timestamps, record rendering, and schema generation.

File	Description
tests/​unit_tests/​test_documents.py	Adds regression coverage for document validation, rendering, and schema generation.
airbyte/​documents.py	Makes datetime available for runtime annotation resolution.

_{Review effort: Balanced}

[Aaron ("AJ") Steers (aaronsteers)]

Kayvan Zahiri (@Kayvan-Zahiri) - Approved and merged! Thanks very much for contributing to Airbyte! 🚀