fix(core): support pydantic v2 on Python 3.14

[phall1]

Summary

• stop using pydantic.v1 imports in langfuse/api/core/pydantic_utilities.py when running under Pydantic v2
• lazy-load LangChain's Serializable type so import langfuse does not eagerly trigger optional dependency import warnings on Python 3.14
• add a regression test for python -W error::UserWarning -c "import langfuse"

Issue

Fixes langfuse/langfuse#12626

Verification

• python -m pytest tests/test_pydantic_compat.py tests/test_json.py tests/test_serializer.py -q
• python -W error::UserWarning -c "import langfuse"

Disclaimer: Experimental PR review

Greptile Summary

This PR fixes two import-time issues that broke import langfuse on Python 3.14 under Pydantic v2: it eliminates the use of pydantic.v1.* compatibility shims (which no longer exist in Python 3.14's Pydantic v2 build) and lazy-loads the optional LangChain Serializable type to prevent transitive pydantic.v1 imports from triggering UserWarning-as-error on Python 3.14.

Key changes:

• langfuse/api/core/pydantic_utilities.py: Under Pydantic v2, all pydantic.v1.* imports are replaced with native equivalents — FieldInfo for ModelField, typing_extensions.get_args/get_origin for type introspection, pydantic.TypeAdapter for date/datetime parsing, and inline functions for is_literal_type/is_union. The empty encoders_by_type = {} is intentional since Pydantic v2 handles its own JSON encoding.
• langfuse/_utils/serializer.py: The eager top-level import of langchain_core.load.serializable.Serializable is replaced with a lazy lru_cache-backed helper _get_langchain_serializable_type(), preventing import-time side effects from the optional dependency.
• tests/test_pydantic_compat.py: Adds a subprocess-based regression test that verifies import langfuse does not emit any UserWarning under -W error::UserWarning, plus a correctness test for the new parse_date/parse_datetime implementations.

Minor notes:

• The in-function import in _get_langchain_serializable_type is a deliberate trade-off for lazy loading, but it goes against the project's convention of top-level imports.
• pydantic.TypeAdapter(dt.date/dt.datetime) is re-instantiated on every parse_date/parse_datetime call; caching these at module level would be slightly more efficient.

Confidence Score: 5/5

Safe to merge — all changes are correct fixes for a real Python 3.14 / Pydantic v2 compatibility issue with no regressions identified.

All remaining findings are P2 (style/performance suggestions): one in-function import that violates the project convention but is intentionally justified by the lazy-load requirement, and one minor TypeAdapter re-instantiation pattern. No logic errors, data-integrity issues, or regressions were found. The types.UnionType usage in is_union is safe because pyproject.toml enforces python >= 3.10. The new tests directly cover the fixed scenarios.

No files require special attention; all three changed files are straightforward and well-targeted.

Important Files Changed

Filename	Overview
langfuse/_utils/serializer.py	Replaces eager top-level import of LangChain's Serializable with a lazy lru_cache-backed helper; fixes Python 3.14 import-time UserWarning caused by transitive pydantic.v1 usage in langchain_core. Logic is correct; one style note about in-function import per project convention.
langfuse/api/core/pydantic_utilities.py	Eliminates all pydantic.v1.* imports under Pydantic v2, replacing them with native Pydantic v2 / typing_extensions equivalents. ModelField aliased to FieldInfo, encoders_by_type set to empty dict (intentional), and is_union correctly includes types.UnionType (safe because python >= 3.10 is enforced in pyproject.toml). Minor: TypeAdapter re-created on each parse_date/parse_datetime call.
tests/test_pydantic_compat.py	New regression test covering both the import langfuse under -W error::UserWarning condition and the correctness of parse_date/parse_datetime on Pydantic v2. Well-structured and targeted.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["import langfuse"] --> B{IS_PYDANTIC_V2?}
    B -- "Yes (v2 path)" --> C["pydantic_utilities.py\nuse native Pydantic v2 APIs\n(FieldInfo, TypeAdapter, typing_extensions)"]
    B -- "No (v1 path)" --> D["pydantic_utilities.py\npydantic v1 imports\n(ModelField, ENCODERS_BY_TYPE, etc.)"]
    A --> E["serializer.py\nEventSerializer.default(obj)"]
    E --> F{Is obj a LangChain Serializable?}
    F -- "Lazy lookup (lru_cache)" --> G["_get_langchain_serializable_type()\ntry: from langchain_core...Serializable\nexcept: return None"]
    G -- "langchain_core present" --> H["return Serializable class\n→ obj.to_json()"]
    G -- "not installed" --> I["return None\n→ skip branch"]
    F -- "type cached after first call" --> J["isinstance check using cached type"]

Loading

_{Reviews (1): Last reviewed commit: "fix(serializer): lazy-load langchain Ser..." | Re-trigger Greptile}

_{(4/5) You can add custom instructions or style guidelines for the agent here!}

Context used:

• Rule used - Move imports to the top of the module instead of p... (source)

Learnt From
langfuse/langfuse-python#1387

[CLAassistant]

All committers have signed the CLA.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.