langgraph 0.0.8__tar.gz

langgraph-0.0.8/LICENSE

@@ -0,0 +1,51 @@
+# LangGraph License
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

langgraph-0.0.8/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.1
+Name: langgraph
+Version: 0.0.8
+Summary: langgraph
+Home-page: https://www.github.com/langchain-ai/langgraph
+License: LangGraph License
+Requires-Python: >=3.8.1,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: langchain-core (>=0.1.8,<0.2.0)
+Project-URL: Repository, https://www.github.com/langchain-ai/langgraph
+Description-Content-Type: text/markdown
+
+# `langgraph`
+
+## Get started
+
+`pip install langgraph`
+
+## Overview
+
+LangGraph is an alpha-stage library for building stateful, multi-actor applications with LLMs. It extends the [LangChain Expression Language](https://python.langchain.com/docs/expression_language/) with the ability to coordinate multiple chains (or actors) across multiple steps of computation. It is inspired by [Pregel](https://research.google/pubs/pub37252/) and [Apache Beam](https://beam.apache.org/).
+
+Some of the use cases are:
+
+- Recursive/iterative LLM chains
+- LLM chains with persistent state/memory
+- LLM agents
+- Multi-agent simulations
+- ...and more!
+
+## How it works
+
+### Channels
+
+Channels are used to communicate between chains. Each channel has a value type, an update type, and an update function – which takes a sequence of updates and modifies the stored value. Channels can be used to send data from one chain to another, or to send data from a chain to itself in a future step. LangGraph provides a number of built-in channels:
+
+#### Basic channels: LastValue and Topic
+
+- `LastValue`: The default channel, stores the last value sent to the channel, useful for input and output values, or for sending data from one step to the next
+- `Topic`: A configurable PubSub Topic, useful for sending multiple values between chains, or for accumulating output. Can be configured to deduplicate values, and/or to accummulate values over the course of multiple steps.
+
+#### Advanced channels: Context and BinaryOperatorAggregate
+
+- `Context`: exposes the value of a context manager, managing its lifecycle. Useful for accessing external resources that require setup and/or teardown. eg. `client = Context(httpx.Client)`
+- `BinaryOperatorAggregate`: stores a persistent value, updated by applying a binary operator to the current value and each update sent to the channel, useful for computing aggregates over multiple steps. eg. `total = BinaryOperatorAggregate(int, operator.add)`
+
+### Chains
+
+Chains are LCEL Runnables which subscribe to one or more channels, and write to one or more channels. Any valid LCEL expression can be used as a chain. Chains can be combined into a Pregel application, which coordinates the execution of the chains across multiple steps.
+
+### Pregel
+
+Pregel combines multiple chains (or actors) into a single application. It coordinates the execution of the chains across multiple steps, following the Pregel/Bulk Synchronous Parallel model. Each step consists of three phases:
+
+- **Plan**: Determine which chains to execute in this step, ie. the chains that subscribe to channels updated in the previous step (or, in the first step, chains that subscribe to input channels)
+- **Execution**: Execute those chains in parallel, until all complete, or one fails, or a timeout is reached. Any channel updates are invisible to other chains until the next step.
+- **Update**: Update the channels with the values written by the chains in this step.
+
+Repeat until no chains are planned for execution, or a maximum number of steps is reached.
+
+## Example
+
+```python
+from langgraph import Channel, Pregel
+
+grow_value = (
+    Channel.subscribe_to("value")
+    | (lambda x: x + x)
+    | Channel.write_to(value=lambda x: x if len(x) < 10 else None)
+)
+
+app = Pregel(
+    chains={"grow_value": grow_value},
+    input="value",
+    output="value",
+)
+
+assert app.invoke("a") == "aaaaaaaa"
+```
+
+Check `examples` for more examples.
+
+## Near-term Roadmap
+
+- [x] Iterate on API
+  - [x] do we want api to receive output from multiple channels in invoke()
+  - [x] do we want api to send input to multiple channels in invoke()
+  - [x] Finish updating tests to new API
+- [x] Implement input_schema and output_schema in Pregel
+- [ ] More tests
+  - [x] Test different input and output types (str, str sequence)
+  - [x] Add tests for Stream, UniqueInbox
+  - [ ] Add tests for subscribe_to_each().join()
+- [x] Add optional debug logging
+- [ ] Add an optional Diff value for Channels that implements `__add__`, returned by update(), yielded by Pregel for output channels. Add replacing_keys set to AddableDict. use an addabledict for yielding values. channels that dont implement it get marked with replacing_keys
+- [x] Implement checkpointing
+  - [x] Save checkpoints at end of each step/run
+  - [x] Load checkpoint at start of invocation
+  - [x] API to specify storage backend and save key
+  - [x] Tests
+- [ ] Add more examples
+  - [ ] multi agent simulation
+  - [ ] human in the loop
+  - [ ] combine documents
+  - [ ] agent executor (add current v total iterations info to read/write steps to enable doing a final update at the end)
+  - [ ] run over dataset
+- [ ] Fault tolerance
+  - [ ] Expose a unique id to each step, hash of (app, chain, checkpoint) (include input updates for first step)
+  - [ ] Retry individual processes in a step
+  - [ ] Retry entire step?
+- [ ] Pregel.stream_log to contain additional keys specific to Pregel
+  - [ ] tasks: inputs of each chain in each step, keyed by {name}:{step}
+  - [ ] task_results: same as above but outputs
+  - [ ] channels: channel values at end of each step, keyed by {name}:{step}
+

langgraph-0.0.8/README.md

@@ -0,0 +1,102 @@
+# `langgraph`
+
+## Get started
+
+`pip install langgraph`
+
+## Overview
+
+LangGraph is an alpha-stage library for building stateful, multi-actor applications with LLMs. It extends the [LangChain Expression Language](https://python.langchain.com/docs/expression_language/) with the ability to coordinate multiple chains (or actors) across multiple steps of computation. It is inspired by [Pregel](https://research.google/pubs/pub37252/) and [Apache Beam](https://beam.apache.org/).
+
+Some of the use cases are:
+
+- Recursive/iterative LLM chains
+- LLM chains with persistent state/memory
+- LLM agents
+- Multi-agent simulations
+- ...and more!
+
+## How it works
+
+### Channels
+
+Channels are used to communicate between chains. Each channel has a value type, an update type, and an update function – which takes a sequence of updates and modifies the stored value. Channels can be used to send data from one chain to another, or to send data from a chain to itself in a future step. LangGraph provides a number of built-in channels:
+
+#### Basic channels: LastValue and Topic
+
+- `LastValue`: The default channel, stores the last value sent to the channel, useful for input and output values, or for sending data from one step to the next
+- `Topic`: A configurable PubSub Topic, useful for sending multiple values between chains, or for accumulating output. Can be configured to deduplicate values, and/or to accummulate values over the course of multiple steps.
+
+#### Advanced channels: Context and BinaryOperatorAggregate
+
+- `Context`: exposes the value of a context manager, managing its lifecycle. Useful for accessing external resources that require setup and/or teardown. eg. `client = Context(httpx.Client)`
+- `BinaryOperatorAggregate`: stores a persistent value, updated by applying a binary operator to the current value and each update sent to the channel, useful for computing aggregates over multiple steps. eg. `total = BinaryOperatorAggregate(int, operator.add)`
+
+### Chains
+
+Chains are LCEL Runnables which subscribe to one or more channels, and write to one or more channels. Any valid LCEL expression can be used as a chain. Chains can be combined into a Pregel application, which coordinates the execution of the chains across multiple steps.
+
+### Pregel
+
+Pregel combines multiple chains (or actors) into a single application. It coordinates the execution of the chains across multiple steps, following the Pregel/Bulk Synchronous Parallel model. Each step consists of three phases:
+
+- **Plan**: Determine which chains to execute in this step, ie. the chains that subscribe to channels updated in the previous step (or, in the first step, chains that subscribe to input channels)
+- **Execution**: Execute those chains in parallel, until all complete, or one fails, or a timeout is reached. Any channel updates are invisible to other chains until the next step.
+- **Update**: Update the channels with the values written by the chains in this step.
+
+Repeat until no chains are planned for execution, or a maximum number of steps is reached.
+
+## Example
+
+```python
+from langgraph import Channel, Pregel
+
+grow_value = (
+    Channel.subscribe_to("value")
+    | (lambda x: x + x)
+    | Channel.write_to(value=lambda x: x if len(x) < 10 else None)
+)
+
+app = Pregel(
+    chains={"grow_value": grow_value},
+    input="value",
+    output="value",
+)
+
+assert app.invoke("a") == "aaaaaaaa"
+```
+
+Check `examples` for more examples.
+
+## Near-term Roadmap
+
+- [x] Iterate on API
+  - [x] do we want api to receive output from multiple channels in invoke()
+  - [x] do we want api to send input to multiple channels in invoke()
+  - [x] Finish updating tests to new API
+- [x] Implement input_schema and output_schema in Pregel
+- [ ] More tests
+  - [x] Test different input and output types (str, str sequence)
+  - [x] Add tests for Stream, UniqueInbox
+  - [ ] Add tests for subscribe_to_each().join()
+- [x] Add optional debug logging
+- [ ] Add an optional Diff value for Channels that implements `__add__`, returned by update(), yielded by Pregel for output channels. Add replacing_keys set to AddableDict. use an addabledict for yielding values. channels that dont implement it get marked with replacing_keys
+- [x] Implement checkpointing
+  - [x] Save checkpoints at end of each step/run
+  - [x] Load checkpoint at start of invocation
+  - [x] API to specify storage backend and save key
+  - [x] Tests
+- [ ] Add more examples
+  - [ ] multi agent simulation
+  - [ ] human in the loop
+  - [ ] combine documents
+  - [ ] agent executor (add current v total iterations info to read/write steps to enable doing a final update at the end)
+  - [ ] run over dataset
+- [ ] Fault tolerance
+  - [ ] Expose a unique id to each step, hash of (app, chain, checkpoint) (include input updates for first step)
+  - [ ] Retry individual processes in a step
+  - [ ] Retry entire step?
+- [ ] Pregel.stream_log to contain additional keys specific to Pregel
+  - [ ] tasks: inputs of each chain in each step, keyed by {name}:{step}
+  - [ ] task_results: same as above but outputs
+  - [ ] channels: channel values at end of each step, keyed by {name}:{step}

langgraph-0.0.8/langgraph/channels/__init__.py

@@ -0,0 +1,11 @@
+from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.context import Context
+from langgraph.channels.last_value import LastValue
+from langgraph.channels.topic import Topic
+
+__all__ = [
+    "LastValue",
+    "Topic",
+    "Context",
+    "BinaryOperatorAggregate",
+]

langgraph-0.0.8/langgraph/channels/base.py

@@ -0,0 +1,131 @@
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime, timezone
+from typing import (
+    Any,
+    AsyncGenerator,
+    Generator,
+    Generic,
+    Mapping,
+    Optional,
+    Sequence,
+    TypeVar,
+)
+
+from typing_extensions import Self
+
+from langgraph.checkpoint.base import Checkpoint
+
+Value = TypeVar("Value")
+Update = TypeVar("Update")
+C = TypeVar("C")
+
+
+class EmptyChannelError(Exception):
+    """Raised when attempting to get the value of a channel that hasn't been updated
+    for the first time yet."""
+
+    pass
+
+
+class InvalidUpdateError(Exception):
+    """Raised when attempting to update a channel with an invalid sequence of updates."""
+
+    pass
+
+
+class BaseChannel(Generic[Value, Update, C], ABC):
+    @property
+    @abstractmethod
+    def ValueType(self) -> Any:
+        """The type of the value stored in the channel."""
+
+    @property
+    @abstractmethod
+    def UpdateType(self) -> Any:
+        """The type of the update received by the channel."""
+
+    @contextmanager
+    @abstractmethod
+    def empty(self, checkpoint: Optional[C] = None) -> Generator[Self, None, None]:
+        """Return a new identical channel, optionally initialized from a checkpoint."""
+
+    @asynccontextmanager
+    async def aempty(
+        self, checkpoint: Optional[C] = None
+    ) -> AsyncGenerator[Self, None]:
+        """Return a new identical channel, optionally initialized from a checkpoint."""
+        with self.empty(checkpoint) as value:
+            yield value
+
+    @abstractmethod
+    def update(self, values: Sequence[Update]) -> None:
+        """Update the channel's value with the given sequence of updates.
+        The order of the updates in the sequence is arbitrary.
+
+        Raises InvalidUpdateError if the sequence of updates is invalid."""
+
+    @abstractmethod
+    def get(self) -> Value:
+        """Return the current value of the channel.
+
+        Raises EmptyChannelError if the channel is empty (never updated yet)."""
+
+    @abstractmethod
+    def checkpoint(self) -> C | None:
+        """Return a string representation of the channel's current state.
+
+        Raises EmptyChannelError if the channel is empty (never updated yet),
+        or doesn't supportcheckpoints."""
+
+
+@contextmanager
+def ChannelsManager(
+    channels: Mapping[str, BaseChannel],
+    checkpoint: Checkpoint,
+) -> Generator[Mapping[str, BaseChannel], None, None]:
+    """Manage channels for the lifetime of a Pregel invocation (multiple steps)."""
+    # TODO use https://docs.python.org/3/library/contextlib.html#contextlib.ExitStack
+    empty = {
+        k: v.empty(checkpoint["channel_values"].get(k)) for k, v in channels.items()
+    }
+    try:
+        yield {k: v.__enter__() for k, v in empty.items()}
+    finally:
+        for v in empty.values():
+            v.__exit__(None, None, None)
+
+
+@asynccontextmanager
+async def AsyncChannelsManager(
+    channels: Mapping[str, BaseChannel],
+    checkpoint: Checkpoint,
+) -> AsyncGenerator[Mapping[str, BaseChannel], None]:
+    """Manage channels for the lifetime of a Pregel invocation (multiple steps)."""
+    empty = {
+        k: v.aempty(checkpoint["channel_values"].get(k)) for k, v in channels.items()
+    }
+    try:
+        yield {k: await v.__aenter__() for k, v in empty.items()}
+    finally:
+        for v in empty.values():
+            await v.__aexit__(None, None, None)
+
+
+def create_checkpoint(
+    checkpoint: Checkpoint, channels: Mapping[str, BaseChannel]
+) -> Checkpoint:
+    """Create a checkpoint for the given channels."""
+    checkpoint = Checkpoint(
+        v=1,
+        ts=datetime.now(timezone.utc).isoformat(),
+        channel_values=checkpoint["channel_values"],
+        channel_versions=checkpoint["channel_versions"],
+        versions_seen=checkpoint["versions_seen"],
+    )
+    for k, v in channels.items():
+        try:
+            checkpoint["channel_values"][k] = v.checkpoint()
+        except EmptyChannelError:
+            pass
+    return checkpoint

langgraph-0.0.8/langgraph/channels/binop.py

@@ -0,0 +1,70 @@
+from contextlib import contextmanager
+from typing import Callable, Generator, Generic, Optional, Sequence, Type
+
+from typing_extensions import Self
+
+from langgraph.channels.base import BaseChannel, EmptyChannelError, Value
+
+
+class BinaryOperatorAggregate(Generic[Value], BaseChannel[Value, Value, Value]):
+    """Stores the result of applying a binary operator to the current value and each new value.
+
+    ```python
+    import operator
+
+    total = Channels.BinaryOperatorAggregate(int, operator.add)
+    ```
+    """
+
+    def __init__(self, typ: Type[Value], operator: Callable[[Value, Value], Value]):
+        self.typ = typ
+        self.operator = operator
+        try:
+            self.value = typ()
+        except Exception:
+            pass
+
+    @property
+    def ValueType(self) -> Type[Value]:
+        """The type of the value stored in the channel."""
+        return self.typ
+
+    @property
+    def UpdateType(self) -> Type[Value]:
+        """The type of the update received by the channel."""
+        return self.typ
+
+    @contextmanager
+    def empty(self, checkpoint: Optional[Value] = None) -> Generator[Self, None, None]:
+        empty = self.__class__(self.typ, self.operator)
+        if checkpoint is not None:
+            empty.value = checkpoint
+        try:
+            yield empty
+        finally:
+            try:
+                del empty.value
+            except AttributeError:
+                pass
+
+    def update(self, values: Sequence[Value]) -> None:
+        if not values:
+            return
+        if not hasattr(self, "value"):
+            self.value = values[0]
+            values = values[1:]
+
+        for value in values:
+            self.value = self.operator(self.value, value)
+
+    def get(self) -> Value:
+        try:
+            return self.value
+        except AttributeError:
+            raise EmptyChannelError()
+
+    def checkpoint(self) -> Value:
+        try:
+            return self.value
+        except AttributeError:
+            raise EmptyChannelError()

langgraph-0.0.8/langgraph/channels/context.py

@@ -0,0 +1,110 @@
+from contextlib import asynccontextmanager, contextmanager
+from typing import (
+    Any,
+    AsyncContextManager,
+    AsyncGenerator,
+    Callable,
+    ContextManager,
+    Generator,
+    Generic,
+    Optional,
+    Sequence,
+    Type,
+)
+
+from typing_extensions import Self
+
+from langgraph.channels.base import (
+    BaseChannel,
+    EmptyChannelError,
+    InvalidUpdateError,
+    Value,
+)
+
+
+class Context(Generic[Value], BaseChannel[Value, None, None]):
+    """Exposes the value of a context manager, for the duration of an invocation.
+    Context manager is entered before the first step, and exited after the last step.
+    Optionally, provide an equivalent async context manager, which will be used
+    instead for async invocations.
+
+    ```python
+    import httpx
+
+    client = Channels.Context(httpx.Client, httpx.AsyncClient)
+    ```
+    """
+
+    value: Value
+
+    def __init__(
+        self,
+        ctx: Optional[Callable[[], ContextManager[Value]]] = None,
+        actx: Optional[Callable[[], AsyncContextManager[Value]]] = None,
+        typ: Optional[Type[Value]] = None,
+    ) -> None:
+        if ctx is None and actx is None:
+            raise ValueError("Must provide either sync or async context manager.")
+
+        self.typ = typ
+        self.ctx = ctx
+        self.actx = actx
+
+    @property
+    def ValueType(self) -> Any:
+        """The type of the value stored in the channel."""
+        return (
+            self.typ
+            or (self.ctx if hasattr(self.ctx, "__enter__") else None)
+            or (self.actx if hasattr(self.actx, "__aenter__") else None)
+            or None
+        )
+
+    @property
+    def UpdateType(self) -> Type[None]:
+        """The type of the update received by the channel."""
+        raise InvalidUpdateError()
+
+    @contextmanager
+    def empty(self, checkpoint: None = None) -> Generator[Self, None, None]:
+        if self.ctx is None:
+            raise ValueError("Cannot enter sync context manager.")
+
+        empty = self.__class__(ctx=self.ctx, actx=self.actx, typ=self.typ)
+        # ContextManager doesn't have a checkpoint
+        ctx = self.ctx()
+        empty.value = ctx.__enter__()
+        try:
+            yield empty
+        finally:
+            ctx.__exit__(None, None, None)
+
+    @asynccontextmanager
+    async def aempty(
+        self, checkpoint: Optional[str] = None
+    ) -> AsyncGenerator[Self, None]:
+        if self.actx is not None:
+            empty = self.__class__(ctx=self.ctx, actx=self.actx, typ=self.typ)
+            # ContextManager doesn't have a checkpoint
+            actx = self.actx()
+            empty.value = await actx.__aenter__()
+            try:
+                yield empty
+            finally:
+                await actx.__aexit__(None, None, None)
+        else:
+            with self.empty() as empty:
+                yield empty
+
+    def update(self, values: Sequence[None]) -> None:
+        if values:
+            raise InvalidUpdateError()
+
+    def get(self) -> Value:
+        try:
+            return self.value
+        except AttributeError:
+            raise EmptyChannelError()
+
+    def checkpoint(self) -> None:
+        raise EmptyChannelError()

langgraph-0.0.8/langgraph/channels/last_value.py

@@ -0,0 +1,61 @@
+from contextlib import contextmanager
+from typing import Generator, Generic, Optional, Sequence, Type
+
+from typing_extensions import Self
+
+from langgraph.channels.base import (
+    BaseChannel,
+    EmptyChannelError,
+    InvalidUpdateError,
+    Value,
+)
+
+
+class LastValue(Generic[Value], BaseChannel[Value, Value, Value]):
+    """Stores the last value received, can receive at most one value per step."""
+
+    def __init__(self, typ: Type[Value]) -> None:
+        self.typ = typ
+
+    @property
+    def ValueType(self) -> Type[Value]:
+        """The type of the value stored in the channel."""
+        return self.typ
+
+    @property
+    def UpdateType(self) -> Type[Value]:
+        """The type of the update received by the channel."""
+        return self.typ
+
+    @contextmanager
+    def empty(self, checkpoint: Optional[Value] = None) -> Generator[Self, None, None]:
+        empty = self.__class__(self.typ)
+        if checkpoint is not None:
+            empty.value = checkpoint
+        try:
+            yield empty
+        finally:
+            try:
+                del empty.value
+            except AttributeError:
+                pass
+
+    def update(self, values: Sequence[Value]) -> None:
+        if len(values) == 0:
+            return
+        if len(values) != 1:
+            raise InvalidUpdateError()
+
+        self.value = values[-1]
+
+    def get(self) -> Value:
+        try:
+            return self.value
+        except AttributeError:
+            raise EmptyChannelError()
+
+    def checkpoint(self) -> Value:
+        try:
+            return self.value
+        except AttributeError:
+            raise EmptyChannelError()