haive.core.persistence.serializers
==================================

.. py:module:: haive.core.persistence.serializers

.. autoapi-nested-parse::

   Custom serializers for LangGraph persistence with SecretStr support.

   This module provides secure serialization for SecretStr and other sensitive data
   while maintaining security and avoiding the pickle_fallback security issue.
   Supports both basic secure serialization and production-grade encryption.



Classes
-------

.. autoapisummary::

   haive.core.persistence.serializers.SecretStrSerializer
   haive.core.persistence.serializers.SecureSecretStrSerializer


Functions
---------

.. autoapisummary::

   haive.core.persistence.serializers.create_encrypted_serializer_for_postgres
   haive.core.persistence.serializers.create_production_serializer


Module Contents
---------------

.. py:class:: SecretStrSerializer(*, pickle_fallback = False, __unpack_ext_hook__ = None)

   Bases: :py:obj:`langgraph.checkpoint.serde.jsonplus.JsonPlusSerializer`


   Alternative serializer that preserves SecretStr values using model_dump.

   WARNING: This approach exposes the actual secret values during serialization.
   Only use this if you have proper encryption at the storage layer.


.. py:class:: SecureSecretStrSerializer(*, pickle_fallback = False, __unpack_ext_hook__ = None)

   Bases: :py:obj:`langgraph.checkpoint.serde.jsonplus.JsonPlusSerializer`


   Custom serializer that handles SecretStr securely.

   This serializer extends JsonPlusSerializer to handle SecretStr objects
   by converting them to masked values during serialization, preserving
   security while avoiding serialization errors.


   .. py:method:: dumps(obj)

      Override dumps to handle SecretStr objects before JSON serialization.



   .. py:method:: loads_typed(data)

      Override to handle loading of masked secrets.



.. py:function:: create_encrypted_serializer_for_postgres(connection_string, encryption_key = None)

   Create an encrypted serializer specifically optimized for PostgreSQL.

   This function creates a production-ready encrypted serializer that's
   optimized for PostgreSQL storage. It includes additional security
   measures and PostgreSQL-specific optimizations.

   :param connection_string: PostgreSQL connection string for logging/validation
   :param encryption_key: AES encryption key. If not provided, will try
                          LANGGRAPH_AES_KEY environment variable.

   :returns: Production-ready encrypted serializer
   :rtype: JsonPlusSerializer

   :raises ValueError: If no encryption key is available in production

   .. rubric:: Examples

   Production PostgreSQL setup::

       serializer = create_encrypted_serializer_for_postgres(
           connection_string="postgresql://user:pass@host:5432/db",
           encryption_key=os.getenv("LANGGRAPH_AES_KEY")
       )


.. py:function:: create_production_serializer(encryption_key = None)

   Create a production-ready serializer with optional encryption.

   This function creates the appropriate serializer based on environment and
   security requirements. For production, it uses EncryptedSerializer when
   an encryption key is available, otherwise falls back to SecureSecretStrSerializer.

   :param encryption_key: Optional AES encryption key. If not provided, will try
                          to load from LANGGRAPH_AES_KEY environment variable.

   :returns: Either EncryptedSerializer or SecureSecretStrSerializer
   :rtype: JsonPlusSerializer

   .. rubric:: Examples

   Basic usage with environment key::

       # Set LANGGRAPH_AES_KEY environment variable
       serializer = create_production_serializer()

   With explicit key::

       serializer = create_production_serializer("your-32-byte-key-here")

   Development (no encryption)::

       serializer = create_production_serializer(encryption_key=None)