amsdal_langgraph 0.1.0__py3-none-any.whl

amsdal_langgraph/Third-Party Materials - AMSDAL Dependencies - License Notices.md

@@ -0,0 +1,30 @@
+# Third-Party Materials - AMSDAL Dependencies - License Notices
+
+## **LangGraph v0.6.8 or later**
+
+### [https://github.com/langchain-ai/langgraph](https://github.com/langchain-ai/langgraph)
+
+### **MIT License**
+
+MIT License
+
+Copyright (c) 2024 LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

amsdal_langgraph/__about__.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

amsdal_langgraph/app.py

@@ -0,0 +1,8 @@
+from amsdal.contrib.app_config import AppConfig
+
+
+class AmsdalWorkflowAppConfig(AppConfig):
+    name = 'amsdal_langgraph'
+    verbose_name = 'AMSDAL Workflow Plugin'
+
+    def on_ready(self) -> None: ...

amsdal_langgraph/checkpoint.py

@@ -0,0 +1,616 @@
+import random
+from collections.abc import AsyncIterator
+from collections.abc import Iterator
+from collections.abc import Sequence
+from typing import Any
+from typing import cast
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import WRITES_IDX_MAP
+from langgraph.checkpoint.base import BaseCheckpointSaver
+from langgraph.checkpoint.base import ChannelVersions
+from langgraph.checkpoint.base import Checkpoint
+from langgraph.checkpoint.base import CheckpointMetadata
+from langgraph.checkpoint.base import CheckpointTuple
+from langgraph.checkpoint.base import get_checkpoint_id
+from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+from .models.checkpoint import Checkpoint as CheckpointModel
+from .models.checkpoint_writes import CheckpointWrites as CheckpointWritesModel
+from .utils import get_checkpoint_metadata
+from .utils import search_where
+
+
+class AmsdalCheckpointSaver(BaseCheckpointSaver[str]):
+    """AMSDAL-based checkpoint saver for LangGraph workflows."""
+
+    def __init__(self, *, serde: SerializerProtocol | None = None):
+        """Initialize the AMSDAL checkpoint saver.
+
+        Args:
+            serde: Optional serializer protocol for checkpoint serialization.
+        """
+        super().__init__(serde=serde)
+        self.jsonplus_serde = JsonPlusSerializer()
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple synchronously.
+
+        Args:
+            config: The runnable configuration.
+
+        Returns:
+            The checkpoint tuple or None if not found.
+        """
+        checkpoint_ns = config['configurable'].get('checkpoint_ns', '')
+
+        # Find the specific checkpoint or latest one
+        if checkpoint_id := get_checkpoint_id(config):
+            checkpoint_obj = (
+                CheckpointModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=checkpoint_ns,
+                    checkpoint_id=checkpoint_id,
+                )
+                .first()
+                .execute()
+            )
+        else:
+            checkpoint_obj = (
+                CheckpointModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=checkpoint_ns,
+                )
+                .order_by('-checkpoint_id')
+                .first()
+                .execute()
+            )
+
+        if not checkpoint_obj:
+            return None
+
+        (
+            thread_id,
+            checkpoint_id,
+            parent_checkpoint_id,
+            _type,
+            checkpoint,
+            metadata,
+        ) = (
+            checkpoint_obj.thread_id,
+            checkpoint_obj.checkpoint_id,
+            checkpoint_obj.parent_checkpoint_id,
+            checkpoint_obj.type,
+            checkpoint_obj.checkpoint,
+            checkpoint_obj.meta,
+        )
+
+        if not get_checkpoint_id(config):
+            config = {
+                'configurable': {
+                    'thread_id': thread_id,
+                    'checkpoint_ns': checkpoint_ns,
+                    'checkpoint_id': checkpoint_id,
+                }
+            }
+
+        # Get pending writes for this checkpoint
+        writes = (
+            CheckpointWritesModel.objects.filter(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=checkpoint_ns,
+                checkpoint_id=str(config['configurable']['checkpoint_id']),
+            )
+            .order_by('task_id', 'idx')
+            .execute()
+        )
+
+        # deserialize the checkpoint and metadata
+        return CheckpointTuple(
+            config,
+            self.serde.loads_typed((_type, checkpoint)),
+            cast(
+                CheckpointMetadata,
+                metadata if metadata is not None else {},
+            ),
+            (
+                {
+                    'configurable': {
+                        'thread_id': thread_id,
+                        'checkpoint_ns': checkpoint_ns,
+                        'checkpoint_id': parent_checkpoint_id,
+                    }
+                }
+                if parent_checkpoint_id
+                else None
+            ),
+            [(write.task_id, write.channel, self.serde.loads_typed((write.type, write.value))) for write in writes],
+        )
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,  # noqa: A002, ARG002
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints synchronously.
+
+        Args:
+            config: The runnable configuration.
+            filter: Optional filter criteria.
+            before: Optional before configuration.
+            limit: Optional limit on results.
+
+        Yields:
+            Checkpoint tuples.
+        """
+        query = CheckpointModel.objects.all().order_by('-checkpoint_id')
+        where = search_where(config, filter, before)
+
+        if where:
+            query = query.filter(where)
+
+        if limit:
+            checkpoints = query[0:limit].execute()
+        else:
+            checkpoints = query.execute()
+
+        for checkpoint_obj in checkpoints:
+            writes = (
+                CheckpointWritesModel.objects.filter(
+                    thread_id=checkpoint_obj.thread_id,
+                    checkpoint_ns=checkpoint_obj.checkpoint_ns,
+                    checkpoint_id=checkpoint_obj.checkpoint_id,
+                )
+                .order_by('task_id', 'idx')
+                .execute()
+            )
+
+            yield CheckpointTuple(
+                {
+                    'configurable': {
+                        'thread_id': checkpoint_obj.thread_id,
+                        'checkpoint_ns': checkpoint_obj.checkpoint_ns,
+                        'checkpoint_id': checkpoint_obj.checkpoint_id,
+                    }
+                },
+                self.serde.loads_typed((checkpoint_obj.type, checkpoint_obj.checkpoint)),
+                cast(
+                    CheckpointMetadata,
+                    checkpoint_obj.meta if checkpoint_obj.meta is not None else {},
+                ),
+                (
+                    {
+                        'configurable': {
+                            'thread_id': checkpoint_obj.thread_id,
+                            'checkpoint_ns': checkpoint_obj.checkpoint_ns,
+                            'checkpoint_id': checkpoint_obj.parent_checkpoint_id,
+                        }
+                    }
+                    if checkpoint_obj.parent_checkpoint_id
+                    else None
+                ),
+                [(write.task_id, write.channel, self.serde.loads_typed((write.type, write.value))) for write in writes],
+            )
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,  # noqa: ARG002
+    ) -> RunnableConfig:
+        """Put a checkpoint synchronously.
+
+        Args:
+            config: The runnable configuration.
+            checkpoint: The checkpoint data.
+            metadata: The checkpoint metadata.
+            new_versions: The new channel versions.
+
+        Returns:
+            The updated runnable configuration.
+        """
+        thread_id = config['configurable']['thread_id']
+        checkpoint_ns = config['configurable']['checkpoint_ns']
+        type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
+
+        # Create or update checkpoint
+        checkpoint_obj = CheckpointModel(
+            thread_id=str(config['configurable']['thread_id']),
+            checkpoint_ns=checkpoint_ns,
+            checkpoint_id=checkpoint['id'],
+            parent_checkpoint_id=config['configurable'].get('checkpoint_id'),
+            type=type_,
+            checkpoint=serialized_checkpoint,
+            meta=get_checkpoint_metadata(config, metadata),  # type: ignore[arg-type]
+        )
+
+        if (
+            CheckpointModel.objects.filter(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=checkpoint_ns,
+                checkpoint_id=checkpoint['id'],
+            )
+            .count()
+            .execute()
+        ):
+            checkpoint_obj.save()
+        else:
+            checkpoint_obj.save(force_insert=True)
+
+        return {
+            'configurable': {
+                'thread_id': thread_id,
+                'checkpoint_ns': checkpoint_ns,
+                'checkpoint_id': checkpoint['id'],
+            }
+        }
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = '',  # noqa: ARG002
+    ) -> None:
+        """Put writes synchronously.
+
+        Args:
+            config: The runnable configuration.
+            writes: The writes to store.
+            task_id: The task ID.
+            task_path: The task path.
+        """
+        _replace = all(w[0] in WRITES_IDX_MAP for w in writes)
+
+        for idx, (channel, value) in enumerate(writes):
+            type_name, serialized_value = self.serde.dumps_typed(value)
+            write_obj = CheckpointWritesModel(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=str(config['configurable']['checkpoint_ns']),
+                checkpoint_id=str(config['configurable']['checkpoint_id']),
+                task_id=task_id,
+                idx=WRITES_IDX_MAP.get(channel, idx),
+                channel=channel,
+                type=type_name,
+                value=serialized_value,
+            )
+
+            if (
+                CheckpointWritesModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=str(config['configurable']['checkpoint_ns']),
+                    checkpoint_id=str(config['configurable']['checkpoint_id']),
+                    task_id=task_id,
+                    idx=WRITES_IDX_MAP.get(channel, idx),
+                )
+                .count()
+                .execute()
+            ):
+                if _replace:
+                    write_obj.save()
+            else:
+                write_obj.save(force_insert=True)
+
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete a thread synchronously.
+
+        Args:
+            thread_id: The thread ID to delete.
+        """
+        # Delete all checkpoints for this thread
+        checkpoints = CheckpointModel.objects.filter(thread_id=str(thread_id)).execute()
+
+        for checkpoint in checkpoints:
+            checkpoint.delete()
+
+        # Delete all writes for this thread
+        writes = CheckpointWritesModel.objects.filter(thread_id=str(thread_id)).execute()
+
+        for write in writes:
+            write.delete()
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple asynchronously.
+
+        Args:
+            config: The runnable configuration.
+
+        Returns:
+            The checkpoint tuple or None if not found.
+        """
+        checkpoint_ns = config['configurable'].get('checkpoint_ns', '')
+
+        # Find the specific checkpoint or latest one
+        if checkpoint_id := get_checkpoint_id(config):
+            checkpoint_obj = (
+                await CheckpointModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=checkpoint_ns,
+                    checkpoint_id=checkpoint_id,
+                )
+                .first()
+                .aexecute()
+            )
+        else:
+            checkpoint_obj = await (
+                CheckpointModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=checkpoint_ns,
+                )
+                .order_by('-checkpoint_id')
+                .first()
+                .aexecute()
+            )
+
+        if not checkpoint_obj:
+            return None
+
+        (
+            thread_id,
+            checkpoint_id,
+            parent_checkpoint_id,
+            _type,
+            checkpoint,
+            metadata,
+        ) = (
+            checkpoint_obj.thread_id,
+            checkpoint_obj.checkpoint_id,
+            checkpoint_obj.parent_checkpoint_id,
+            checkpoint_obj.type,
+            checkpoint_obj.checkpoint,
+            checkpoint_obj.meta,
+        )
+
+        if not get_checkpoint_id(config):
+            config = {
+                'configurable': {
+                    'thread_id': thread_id,
+                    'checkpoint_ns': checkpoint_ns,
+                    'checkpoint_id': checkpoint_id,
+                }
+            }
+
+        # Get pending writes for this checkpoint
+        writes = await (
+            CheckpointWritesModel.objects.filter(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=checkpoint_ns,
+                checkpoint_id=str(config['configurable']['checkpoint_id']),
+            )
+            .order_by('task_id', 'idx')
+            .aexecute()
+        )
+
+        # deserialize the checkpoint and metadata
+        return CheckpointTuple(
+            config,
+            self.serde.loads_typed((_type, checkpoint)),
+            cast(
+                CheckpointMetadata,
+                metadata if metadata is not None else {},
+            ),
+            (
+                {
+                    'configurable': {
+                        'thread_id': thread_id,
+                        'checkpoint_ns': checkpoint_ns,
+                        'checkpoint_id': parent_checkpoint_id,
+                    }
+                }
+                if parent_checkpoint_id
+                else None
+            ),
+            [(write.task_id, write.channel, self.serde.loads_typed((write.type, write.value))) for write in writes],
+        )
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,  # noqa: A002, ARG002
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """List checkpoints asynchronously.
+
+        Args:
+            config: The runnable configuration.
+            filter: Optional filter criteria.
+            before: Optional before configuration.
+            limit: Optional limit on results.
+
+        Yields:
+            Checkpoint tuples.
+        """
+        query = CheckpointModel.objects.all().order_by('-checkpoint_id')
+        where = search_where(config, filter, before)
+
+        if where:
+            query = query.filter(where)
+
+        if limit:
+            checkpoints = await query[:limit].aexecute()
+        else:
+            checkpoints = await query.aexecute()
+
+        for checkpoint_obj in checkpoints:
+            writes = await (
+                CheckpointWritesModel.objects.filter(
+                    thread_id=checkpoint_obj.thread_id,
+                    checkpoint_ns=checkpoint_obj.checkpoint_ns,
+                    checkpoint_id=checkpoint_obj.checkpoint_id,
+                )
+                .order_by('task_id', 'idx')
+                .aexecute()
+            )
+
+            yield CheckpointTuple(
+                {
+                    'configurable': {
+                        'thread_id': checkpoint_obj.thread_id,
+                        'checkpoint_ns': checkpoint_obj.checkpoint_ns,
+                        'checkpoint_id': checkpoint_obj.checkpoint_id,
+                    }
+                },
+                self.serde.loads_typed((checkpoint_obj.type, checkpoint_obj.checkpoint)),
+                cast(
+                    CheckpointMetadata,
+                    checkpoint_obj.meta if checkpoint_obj.meta is not None else {},
+                ),
+                (
+                    {
+                        'configurable': {
+                            'thread_id': checkpoint_obj.thread_id,
+                            'checkpoint_ns': checkpoint_obj.checkpoint_ns,
+                            'checkpoint_id': checkpoint_obj.parent_checkpoint_id,
+                        }
+                    }
+                    if checkpoint_obj.parent_checkpoint_id
+                    else None
+                ),
+                [(write.task_id, write.channel, self.serde.loads_typed((write.type, write.value))) for write in writes],
+            )
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,  # noqa: ARG002
+    ) -> RunnableConfig:
+        """Put a checkpoint asynchronously.
+
+        Args:
+            config: The runnable configuration.
+            checkpoint: The checkpoint data.
+            metadata: The checkpoint metadata.
+            new_versions: The new channel versions.
+
+        Returns:
+            The updated runnable configuration.
+        """
+        thread_id = config['configurable']['thread_id']
+        checkpoint_ns = config['configurable']['checkpoint_ns']
+        type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
+
+        # Create or update checkpoint
+        checkpoint_obj = CheckpointModel(
+            thread_id=str(config['configurable']['thread_id']),
+            checkpoint_ns=checkpoint_ns,
+            checkpoint_id=checkpoint['id'],
+            parent_checkpoint_id=config['configurable'].get('checkpoint_id'),
+            type=type_,
+            checkpoint=serialized_checkpoint,
+            meta=get_checkpoint_metadata(config, metadata),  # type: ignore[arg-type]
+        )
+
+        if (
+            await CheckpointModel.objects.filter(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=checkpoint_ns,
+                checkpoint_id=checkpoint['id'],
+            )
+            .count()
+            .aexecute()
+        ):
+            await checkpoint_obj.asave()  # type: ignore[misc]
+        else:
+            await checkpoint_obj.asave(force_insert=True)  # type: ignore[misc]
+
+        return {
+            'configurable': {
+                'thread_id': thread_id,
+                'checkpoint_ns': checkpoint_ns,
+                'checkpoint_id': checkpoint['id'],
+            }
+        }
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = '',  # noqa: ARG002
+    ) -> None:
+        """Put writes asynchronously.
+
+        Args:
+            config: The runnable configuration.
+            writes: The writes to store.
+            task_id: The task ID.
+            task_path: The task path.
+        """
+        _replace = all(w[0] in WRITES_IDX_MAP for w in writes)
+
+        for idx, (channel, value) in enumerate(writes):
+            type_name, serialized_value = self.serde.dumps_typed(value)
+            write_obj = CheckpointWritesModel(
+                thread_id=str(config['configurable']['thread_id']),
+                checkpoint_ns=str(config['configurable']['checkpoint_ns']),
+                checkpoint_id=str(config['configurable']['checkpoint_id']),
+                task_id=task_id,
+                idx=WRITES_IDX_MAP.get(channel, idx),
+                channel=channel,
+                type=type_name,
+                value=serialized_value,
+            )
+
+            if await (
+                CheckpointWritesModel.objects.filter(
+                    thread_id=str(config['configurable']['thread_id']),
+                    checkpoint_ns=str(config['configurable']['checkpoint_ns']),
+                    checkpoint_id=str(config['configurable']['checkpoint_id']),
+                    task_id=task_id,
+                    idx=WRITES_IDX_MAP.get(channel, idx),
+                )
+                .count()
+                .aexecute()
+            ):
+                if _replace:
+                    await write_obj.asave()  # type: ignore[misc]
+            else:
+                await write_obj.asave(force_insert=True)  # type: ignore[misc]
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        """Delete a thread asynchronously.
+
+        Args:
+            thread_id: The thread ID to delete.
+        """
+        # Delete all checkpoints for this thread
+        checkpoints = await CheckpointModel.objects.filter(thread_id=str(thread_id)).aexecute()
+
+        for checkpoint in checkpoints:
+            await checkpoint.adelete()
+
+        # Delete all writes for this thread
+        writes = await CheckpointWritesModel.objects.filter(thread_id=str(thread_id)).aexecute()
+
+        for write in writes:
+            await write.adelete()
+
+    def get_next_version(self, current: str | None, channel: None) -> str:  # noqa: ARG002
+        """Generate the next version ID for a channel.
+
+        This method creates a new version identifier for a channel based on its current version.
+
+        Args:
+            current (Optional[str]): The current version identifier of the channel.
+
+        Returns:
+            str: The next version identifier, which is guaranteed to be monotonically increasing.
+        """
+        if current is None:
+            current_v = 0
+        elif isinstance(current, int):
+            current_v = current
+        else:
+            current_v = int(current.split('.')[0])
+        next_v = current_v + 1
+        next_h = random.random()  # noqa: S311
+        return f'{next_v:032}.{next_h:016}'

amsdal_langgraph/migrations/0000_initial.py

@@ -0,0 +1,66 @@
+from amsdal_models.migration import migrations
+from amsdal_utils.models.enums import ModuleType
+
+
+class Migration(migrations.Migration):
+    operations: list[migrations.Operation] = [
+        migrations.CreateClass(
+            module_type=ModuleType.CONTRIB,
+            class_name="Checkpoint",
+            new_schema={
+                "title": "Checkpoint",
+                "required": ["thread_id", "checkpoint_id", "checkpoint"],
+                "properties": {
+                    "created_at": {"type": "datetime", "title": "Created At", "format": "date-time"},
+                    "updated_at": {"type": "datetime", "title": "Updated At", "format": "date-time"},
+                    "thread_id": {"type": "string", "title": "Thread ID"},
+                    "checkpoint_ns": {"type": "string", "default": "", "title": "Checkpoint Namespace"},
+                    "checkpoint_id": {"type": "string", "title": "Checkpoint ID"},
+                    "parent_checkpoint_id": {"type": "string", "title": "Parent Checkpoint ID"},
+                    "type": {"type": "string", "title": "Type"},
+                    "checkpoint": {"type": "binary", "title": "Checkpoint Data"},
+                    "meta": {
+                        "type": "dictionary",
+                        "items": {"key": {"type": "string"}, "value": {"type": "anything"}},
+                        "title": "Metadata",
+                    },
+                },
+                "custom_code": "import datetime\n\n\nasync def apre_create(self) -> None:\n    self.created_at = datetime.datetime.now(tz=datetime.UTC)\n    await super().apre_create()\n\nasync def apre_update(self) -> None:\n    self.updated_at = datetime.datetime.now(tz=datetime.UTC)\n    if not self.created_at:\n        _metadata = await self.aget_metadata()\n        self.created_at = datetime.datetime.fromtimestamp(_metadata.created_at / 1000, tz=datetime.UTC)\n    await super().apre_update()\n\ndef pre_create(self) -> None:\n    self.created_at = datetime.datetime.now(tz=datetime.UTC)\n    super().pre_create()\n\ndef pre_update(self) -> None:\n    self.updated_at = datetime.datetime.now(tz=datetime.UTC)\n    if not self.created_at:\n        _metadata = self.get_metadata()\n        self.created_at = datetime.datetime.fromtimestamp(_metadata.created_at / 1000, tz=datetime.UTC)\n    super().pre_update()",
+                "storage_metadata": {
+                    "table_name": "checkpoints",
+                    "db_fields": {},
+                    "primary_key": ["thread_id", "checkpoint_ns", "checkpoint_id"],
+                    "foreign_keys": {},
+                },
+                "description": "AMSDAL model for storing LangGraph checkpoints.",
+            },
+        ),
+        migrations.CreateClass(
+            module_type=ModuleType.CONTRIB,
+            class_name="CheckpointWrites",
+            new_schema={
+                "title": "CheckpointWrites",
+                "required": ["thread_id", "checkpoint_id", "task_id", "idx", "channel"],
+                "properties": {
+                    "created_at": {"type": "datetime", "title": "Created At", "format": "date-time"},
+                    "updated_at": {"type": "datetime", "title": "Updated At", "format": "date-time"},
+                    "thread_id": {"type": "string", "title": "Thread ID"},
+                    "checkpoint_ns": {"type": "string", "default": "", "title": "Checkpoint Namespace"},
+                    "checkpoint_id": {"type": "string", "title": "Checkpoint ID"},
+                    "task_id": {"type": "string", "title": "Task ID"},
+                    "idx": {"type": "integer", "title": "Index"},
+                    "channel": {"type": "string", "title": "Channel"},
+                    "type": {"type": "string", "title": "Type"},
+                    "value": {"type": "binary", "title": "Value"},
+                },
+                "custom_code": "import datetime\n\n\nasync def apre_create(self) -> None:\n    self.created_at = datetime.datetime.now(tz=datetime.UTC)\n    await super().apre_create()\n\nasync def apre_update(self) -> None:\n    self.updated_at = datetime.datetime.now(tz=datetime.UTC)\n    if not self.created_at:\n        _metadata = await self.aget_metadata()\n        self.created_at = datetime.datetime.fromtimestamp(_metadata.created_at / 1000, tz=datetime.UTC)\n    await super().apre_update()\n\ndef pre_create(self) -> None:\n    self.created_at = datetime.datetime.now(tz=datetime.UTC)\n    super().pre_create()\n\ndef pre_update(self) -> None:\n    self.updated_at = datetime.datetime.now(tz=datetime.UTC)\n    if not self.created_at:\n        _metadata = self.get_metadata()\n        self.created_at = datetime.datetime.fromtimestamp(_metadata.created_at / 1000, tz=datetime.UTC)\n    super().pre_update()",
+                "storage_metadata": {
+                    "table_name": "checkpoint_writes",
+                    "db_fields": {},
+                    "primary_key": ["thread_id", "checkpoint_ns", "checkpoint_id", "task_id", "idx"],
+                    "foreign_keys": {},
+                },
+                "description": "AMSDAL model for storing checkpoint write operations.",
+            },
+        ),
+    ]

amsdal_langgraph/models/checkpoint.py

@@ -0,0 +1,24 @@
+from typing import Any
+from typing import ClassVar
+from typing import Optional
+
+from amsdal.models.mixins import TimestampMixin
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+
+class Checkpoint(TimestampMixin, Model):
+    """AMSDAL model for storing LangGraph checkpoints."""
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+    __table_name__ = 'checkpoints'
+    __primary_key__: ClassVar[list[str]] = ['thread_id', 'checkpoint_ns', 'checkpoint_id']
+
+    thread_id: str = Field(..., title='Thread ID')
+    checkpoint_ns: str = Field(default='', title='Checkpoint Namespace')
+    checkpoint_id: str = Field(..., title='Checkpoint ID')
+    parent_checkpoint_id: Optional[str] = Field(default=None, title='Parent Checkpoint ID')
+    type: Optional[str] = Field(default=None, title='Type')
+    checkpoint: bytes = Field(..., title='Checkpoint Data')
+    meta: dict[str, Any | None] | None = Field(..., title='Metadata')

amsdal_langgraph/models/checkpoint_writes.py

@@ -0,0 +1,24 @@
+from typing import ClassVar
+from typing import Optional
+
+from amsdal.models.mixins import TimestampMixin
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+
+class CheckpointWrites(TimestampMixin, Model):
+    """AMSDAL model for storing checkpoint write operations."""
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+    __table_name__ = 'checkpoint_writes'
+    __primary_key__: ClassVar[list[str]] = ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'idx']
+
+    thread_id: str = Field(..., title='Thread ID')
+    checkpoint_ns: str = Field(default='', title='Checkpoint Namespace')
+    checkpoint_id: str = Field(..., title='Checkpoint ID')
+    task_id: str = Field(..., title='Task ID')
+    idx: int = Field(..., title='Index')
+    channel: str = Field(..., title='Channel')
+    type: Optional[str] = Field(default=None, title='Type')
+    value: Optional[bytes] = Field(default=None, title='Value')

amsdal_langgraph/utils.py

@@ -0,0 +1,67 @@
+from typing import Any
+from typing import Optional
+
+from amsdal_utils.query.utils import Q
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import EXCLUDED_METADATA_KEYS
+from langgraph.checkpoint.base import CheckpointMetadata
+from langgraph.checkpoint.base import get_checkpoint_id
+
+
+def search_where(
+    config: RunnableConfig | None,
+    filter: dict[str, Any] | None,  # noqa: A002
+    before: RunnableConfig | None = None,
+) -> Optional[Q]:
+    conditions = None
+
+    # construct predicate for config filter
+    if config is not None:
+        conditions = Q(thread_id=config['configurable']['thread_id'])
+
+        checkpoint_ns = config['configurable'].get('checkpoint_ns')
+        if checkpoint_ns is not None:
+            conditions &= Q(checkpoint_ns=checkpoint_ns)
+
+        if checkpoint_id := get_checkpoint_id(config):
+            conditions &= Q(checkpoint_id=checkpoint_id)
+
+    # construct predicate for metadata filter
+    if filter:
+        for query_key, query_value in filter.items():
+            condition = Q(**{f'meta__{query_key}': query_value})
+
+            if not conditions:
+                conditions = condition
+            else:
+                conditions &= condition
+
+    # construct predicate for `before`
+    if before is not None:
+        condition = Q(checkpoint_id__lt=get_checkpoint_id(before))
+
+        if not conditions:
+            conditions = condition
+        else:
+            conditions &= condition
+
+    return conditions
+
+
+def get_checkpoint_metadata(config: RunnableConfig, metadata: CheckpointMetadata) -> CheckpointMetadata:
+    """Get checkpoint metadata in a backwards-compatible manner."""
+    metadata = {  # type: ignore[assignment]
+        k: v.replace('\u0000', '')
+        if isinstance(v, str) else v for k, v in metadata.items()
+    }
+    for obj in (config.get('metadata'), config.get('configurable')):
+        if not obj:
+            continue
+        for key, v in obj.items():
+            if key in metadata or key in EXCLUDED_METADATA_KEYS or key.startswith('__'):
+                continue
+            elif isinstance(v, str):
+                metadata[key] = v.replace('\u0000', '')  # type: ignore[literal-required]
+            elif isinstance(v, (int, bool, float)):
+                metadata[key] = v  # type: ignore[literal-required]
+    return metadata

amsdal_langgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: amsdal_langgraph
+Version: 0.1.0
+Summary: amsdal_langgraph plugin for AMSDAL Framework
+Requires-Python: >=3.11
+Requires-Dist: amsdal[cli]>=0.5.14
+Requires-Dist: langgraph>=0.6.8
+Provides-Extra: openai
+Requires-Dist: langchain[openai]; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# AMSDAL Workflow
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A LangGraph checkpoint persistence plugin for the [AMSDAL Framework](https://github.com/amsdal/amsdal). This plugin enables persistent and recoverable LangGraph workflows by storing checkpoint state in AMSDAL-managed databases.
+
+## Features
+
+- **Persistent Workflow State**: Store LangGraph checkpoints in any AMSDAL-supported database (SQLite, PostgreSQL, etc.)
+- **Dual Mode Support**: Both synchronous and asynchronous operations
+- **Thread-based Organization**: Manage multiple workflow threads with checkpoint namespacing
+- **Drop-in Replacement**: Compatible with LangGraph's `BaseCheckpointSaver` interface
+- **Production Ready**: Built on the robust AMSDAL ORM with comprehensive testing
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install amsdal-workflow
+```
+
+Or with optional dependencies:
+
+```bash
+# With OpenAI support
+pip install amsdal-workflow[openai]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from langgraph.graph import StateGraph
+from amsdal_langgraph.checkpoint import AmsdalCheckpointSaver
+
+# Initialize the checkpoint saver
+checkpointer = AmsdalCheckpointSaver()
+
+# Create your LangGraph workflow
+workflow = StateGraph(...)
+# ... define your workflow nodes and edges ...
+
+# Compile with checkpoint support
+app = workflow.compile(checkpointer=checkpointer)
+
+# Run with persistence
+config = {'configurable': {'thread_id': 'user-123'}}
+result = app.invoke(input_data, config=config)
+```
+
+### Async Usage
+
+```python
+from amsdal_langgraph.checkpoint import AmsdalCheckpointSaver
+
+# Same checkpointer works for async
+checkpointer = AmsdalCheckpointSaver()
+
+# Compile async workflow
+app = workflow.compile(checkpointer=checkpointer)
+
+# Run async with persistence
+config = {'configurable': {'thread_id': 'user-123'}}
+result = await app.ainvoke(input_data, config=config)
+```
+
+### Advanced Configuration
+
+```python
+from langchain_core.runnables import RunnableConfig
+from amsdal_langgraph.checkpoint import AmsdalCheckpointSaver
+
+checkpointer = AmsdalCheckpointSaver()
+
+# Configuration with checkpoint namespace
+config: RunnableConfig = {
+    'configurable': {
+        'thread_id': 'conversation-456',
+        'checkpoint_ns': 'production',  # Optional namespace
+    }
+}
+
+# Run workflow
+result = app.invoke(input_data, config=config)
+
+# Resume from checkpoint
+checkpoint_tuple = checkpointer.get_tuple(config)
+if checkpoint_tuple:
+    # Continue from last checkpoint
+    result = app.invoke(input_data, config=config)
+```
+
+## Architecture
+
+### Core Components
+
+- **AmsdalCheckpointSaver**: Main class implementing LangGraph's `BaseCheckpointSaver` protocol
+- **Checkpoint Model**: Stores checkpoint snapshots with metadata
+- **CheckpointWrites Model**: Stores pending write operations for each checkpoint
+
+### Data Models
+
+#### Checkpoint
+Stores workflow state snapshots:
+- `thread_id`: Workflow thread identifier
+- `checkpoint_ns`: Optional namespace for organization
+- `checkpoint_id`: Unique checkpoint identifier
+- `parent_checkpoint_id`: Reference to parent checkpoint
+- `checkpoint`: Serialized checkpoint data
+- `meta`: Checkpoint metadata
+
+#### CheckpointWrites
+Stores pending writes associated with checkpoints:
+- `thread_id`, `checkpoint_ns`, `checkpoint_id`: Links to checkpoint
+- `task_id`: Task identifier
+- `idx`: Write operation index
+- `channel`: Channel name
+- `value`: Serialized write value
+
+## API Reference
+
+### AmsdalCheckpointSaver
+
+#### Methods
+
+##### Synchronous Methods
+
+- `get_tuple(config: RunnableConfig) -> CheckpointTuple | None`
+  - Retrieve a checkpoint tuple by configuration
+
+- `list(config: RunnableConfig | None, *, filter: dict | None = None, before: RunnableConfig | None = None, limit: int | None = None) -> Iterator[CheckpointTuple]`
+  - List checkpoints with optional filtering
+
+- `put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, new_versions: ChannelVersions) -> RunnableConfig`
+  - Store a new checkpoint
+
+- `put_writes(config: RunnableConfig, writes: Sequence[tuple[str, Any]], task_id: str) -> None`
+  - Store pending writes for a checkpoint
+
+- `delete_thread(thread_id: str) -> None`
+  - Delete all checkpoints and writes for a thread
+
+##### Asynchronous Methods
+
+All synchronous methods have async equivalents prefixed with `a`:
+- `aget_tuple(...)`
+- `alist(...)`
+- `aput(...)`
+- `aput_writes(...)`
+- `adelete_thread(...)`
+
+## Configuration
+
+### Database Setup
+
+AMSDAL Workflow uses your existing AMSDAL configuration. Ensure you have configured your database connection:
+
+```python
+from amsdal.manager import AmsdalManager
+
+# Initialize AMSDAL
+manager = AmsdalManager()
+manager.setup()
+
+# Now use AmsdalCheckpointSaver
+checkpointer = AmsdalCheckpointSaver()
+```
+
+### Migration
+
+The plugin includes migration files for creating the required tables. Run migrations before first use:
+
+```bash
+amsdal migrate
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/amsdal/amsdal-workflow.git
+cd amsdal-workflow
+
+# Install dependencies
+hatch run sync
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+hatch run test
+
+# Run with coverage
+hatch run cov
+
+# Run specific test file
+hatch run test tests/test_checkpoint.py
+
+# Run with verbose output
+hatch run test -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+hatch run fmt
+
+# Check code style
+hatch run style
+
+# Run type checking
+hatch run typing
+
+# Run all checks
+hatch run all
+```
+
+### Project Structure
+
+```
+amsdal_langgraph/
+├── amsdal_langgraph/           # Main package
+│   ├── __init__.py
+│   ├── checkpoint.py          # AmsdalCheckpointSaver implementation
+│   ├── utils.py               # Utility functions
+│   ├── models/                # Data models
+│   │   ├── checkpoint.py      # Checkpoint model
+│   │   └── checkpoint_writes.py  # CheckpointWrites model
+│   └── migrations/            # Database migrations
+├── tests/                     # Test suite
+│   ├── conftest.py            # Test fixtures
+│   └── test_checkpoint.py     # Checkpoint tests
+├── pyproject.toml             # Project configuration
+├── README.md                  # This file
+```
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and code quality checks
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Code Standards
+
+- Python 3.11+ required
+- Follow PEP 8 style guide (enforced by Ruff)
+- Add type hints to all functions
+- Write tests for new features
+- Maintain test coverage above 90%
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built on [LangGraph](https://github.com/langchain-ai/langgraph) by LangChain
+- Powered by [AMSDAL Framework](https://github.com/amsdal/amsdal)
+
+## Support
+
+- **Documentation**: [AMSDAL Docs](https://docs.amsdal.com)
+- **Issues**: [GitHub Issues](https://github.com/amsdal/amsdal-workflow/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/amsdal/amsdal-workflow/discussions)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each release.

amsdal_langgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+amsdal_langgraph/Third-Party Materials - AMSDAL Dependencies - License Notices.md,sha256=y5L5esHBNdYnlmq34lyHCSiH_3N7M6SH7TFC92gFZ40,1285
+amsdal_langgraph/__about__.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+amsdal_langgraph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amsdal_langgraph/app.py,sha256=x2Hv4cyHUsiXIv6atviu20jiHGZiw6w0rFKhRv7wlXs,203
+amsdal_langgraph/checkpoint.py,sha256=AYuhIHdNRYr6QLWq25hq3RmP-MorOTX_rmuwQEOn0lg,21638
+amsdal_langgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amsdal_langgraph/utils.py,sha256=4IMu8_JMgmaprXL0MkFcxKIT2mgGKCp2lIccvzgg7HA,2355
+amsdal_langgraph/migrations/0000_initial.py,sha256=Ku40eJwP9VFO5oqE9U5LHYA_2IU-Up-Vxyxf5wDkM-Q,5198
+amsdal_langgraph/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amsdal_langgraph/models/checkpoint.py,sha256=vgxzmbdVs4vYKxodHklIzHMvDge6xH9QyfewgNctmHc,1014
+amsdal_langgraph/models/checkpoint_writes.py,sha256=sIBzKZZHjz5-HRjHblMSIA7eZwHHR-LeK9uCeFRGhlc,1004
+amsdal_langgraph-0.1.0.dist-info/METADATA,sha256=4nHshcbd7OH4wHSwauxApg3xtfd70uodhMyI0FlyoGo,7872
+amsdal_langgraph-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+amsdal_langgraph-0.1.0.dist-info/RECORD,,

amsdal_langgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any