langgraph-plainid 1.0.0__py3-none-any.whl

langgraph_plainid/__init__.py

@@ -0,0 +1,23 @@
+from langgraph_plainid.models.state.agent_state import (
+    AgentState,
+    AnonymizationState,
+    CategorizationState,
+    ErrorDetails,
+    RetrievalState,
+)
+from langgraph_plainid.nodes.anonymizer_node import AnonymizerNode
+from langgraph_plainid.nodes.base_node import BaseNode
+from langgraph_plainid.nodes.categorization_node import CategorizationNode
+from langgraph_plainid.nodes.retrieval_node import RetrievalNode
+
+__all__ = [
+    "AgentState",
+    "AnonymizationState",
+    "AnonymizerNode",
+    "BaseNode",
+    "CategorizationNode",
+    "CategorizationState",
+    "ErrorDetails",
+    "RetrievalNode",
+    "RetrievalState",
+]

langgraph_plainid/models/state/agent_state.py

@@ -0,0 +1,35 @@
+from typing import Optional, TypedDict
+
+from langchain_core.documents import Document
+
+from core_plainid.models.context.request_context import RequestContext
+
+
+class ErrorDetails(TypedDict):
+    error_message: Optional[str]
+    error: Exception
+
+
+class AnonymizationState(TypedDict):
+    query: str
+    output_text: Optional[str]
+    error_details: Optional[ErrorDetails]
+
+
+class RetrievalState(TypedDict):
+    query: str
+    resource_types: list[str]
+    retrieved_documents: Optional[list[Document]]
+    error_details: Optional[ErrorDetails]
+
+
+class CategorizationState(TypedDict):
+    query: str
+    error_details: Optional[ErrorDetails]
+
+
+class AgentState(TypedDict):
+    request_context: RequestContext
+    anonymization: Optional[AnonymizationState]
+    retrieval: Optional[RetrievalState]
+    categorization: Optional[CategorizationState]

langgraph_plainid/nodes/anonymizer_node.py

@@ -0,0 +1,56 @@
+from typing import Any, Optional
+
+from core_plainid.anonymization.base_anonymizer import BaseAnonymizer
+
+from langgraph_plainid.models.state.agent_state import AgentState
+from langgraph_plainid.nodes.base_node import BaseNode
+
+
+class AnonymizerNode(BaseNode):
+    """LangGraph node that anonymizes text via a PlainID anonymizer.
+
+    Reads the query from ``state["anonymization"]["query"]`` and writes the
+    result to ``state["anonymization"]["output_text"]``.
+    """
+
+    def __init__(
+        self,
+        anonymizer: BaseAnonymizer,
+        next_node: Optional[str] = None,
+        next_node_on_error: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            substate_key="anonymization",
+            next_node=next_node,
+            next_node_on_error=next_node_on_error,
+        )
+        self._anonymizer = anonymizer
+
+    def _execute(self, state: AgentState) -> dict[str, Any]:
+        anonymization = state["anonymization"]
+        request_context = state.get("request_context")
+
+        output_text = self._anonymizer.anonymize(
+            anonymization["query"],
+            request_context=request_context,
+        )
+
+        return self._build_updated_state(output_text)
+
+    async def _aexecute(self, state: AgentState) -> dict[str, Any]:
+        anonymization = state["anonymization"]
+        request_context = state.get("request_context")
+
+        output_text = await self._anonymizer.aanonymize(
+            anonymization["query"],
+            request_context=request_context,
+        )
+
+        return self._build_updated_state(output_text)
+
+    def _build_updated_state(self, output_text: str) -> dict[str, Any]:
+        return {
+            "anonymization": {
+                "output_text": output_text,
+            }
+        }

langgraph_plainid/nodes/base_node.py

@@ -0,0 +1,112 @@
+import logging
+from abc import abstractmethod
+from typing import Any, Optional, Union
+
+from langchain_core.runnables import Runnable, RunnableConfig
+from langgraph.types import Command
+
+from core_plainid.utils.validation_utils import validate_not_blank
+from langgraph_plainid.models.state.agent_state import AgentState, ErrorDetails
+
+logger = logging.getLogger(__name__)
+
+
+class BaseNode(Runnable[AgentState, Union[dict[str, Any], Command]]):
+    """Abstract base for LangGraph nodes that execute a PlainID operation.
+
+    Handles routing to the next node via :class:`Command`, and routes to
+    an error-handler node when ``next_node_on_error`` is configured.
+    """
+
+    def __init__(
+        self,
+        substate_key: str,
+        next_node: Optional[str] = None,
+        next_node_on_error: Optional[str] = None,
+    ) -> None:
+        """
+        Args:
+            substate_key: Key in :class:`AgentState` that this node reads/writes.
+            next_node: Node to route to on success. If ``None``, the updated
+                state dict is returned directly (graph edge routing applies).
+            next_node_on_error: Node to route to on error. If ``None``,
+                the exception propagates to the calling context.
+        """
+        validate_not_blank(substate_key=substate_key)
+
+        self._substate_key = substate_key
+        self._next_node = next_node
+        self._next_node_on_error = next_node_on_error
+
+    def invoke(
+        self,
+        input: AgentState,
+        config: Optional[RunnableConfig] = None,
+        **kwargs: Any,
+    ) -> Union[dict[str, Any], Command]:
+        """Execute the node synchronously.
+
+        Args:
+            input: The current agent state.
+            config: Optional LangChain runnable config.
+
+        Returns:
+            Updated state dict or a :class:`Command` that routes to the next node.
+        """
+        try:
+            updated_state = self._execute(input)
+        except Exception as e:
+            return self._handle_error(e)
+
+        return self._build_result(updated_state)
+
+    async def ainvoke(
+        self,
+        input: AgentState,
+        config: Optional[RunnableConfig] = None,
+        **kwargs: Any,
+    ) -> Union[dict[str, Any], Command]:
+        """Async version of :meth:`invoke`."""
+        try:
+            updated_state = await self._aexecute(input)
+        except Exception as e:
+            return self._handle_error(e)
+
+        return self._build_result(updated_state)
+
+    @abstractmethod
+    def _execute(self, state: AgentState) -> dict[str, Any]:
+        pass
+
+    @abstractmethod
+    async def _aexecute(self, state: AgentState) -> dict[str, Any]:
+        pass
+
+    def _build_result(
+        self, updated_state: dict[str, Any]
+    ) -> Union[dict[str, Any], Command]:
+        if self._next_node is not None:
+
+            return Command(update=updated_state, goto=self._next_node)
+
+        return updated_state
+
+    def _handle_error(self, error: Exception) -> Union[dict[str, Any], Command]:
+        logger.error("Error in node '%s': %s", self._substate_key, error)
+
+        if self._next_node_on_error is not None:
+            error_state = {
+                self._substate_key: {
+                    "error_details": self._create_error_details(error),
+                }
+            }
+
+            return Command(update=error_state, goto=self._next_node_on_error)
+
+        raise error
+
+    def _create_error_details(self, error: Exception) -> ErrorDetails:
+        return ErrorDetails(
+            error_message=str(error),
+            error=error,
+        )

langgraph_plainid/nodes/categorization_node.py

@@ -0,0 +1,49 @@
+from typing import Any, Optional
+
+from core_plainid.categorization.base_categorizer import BaseCategorizer
+
+from langgraph_plainid.models.state.agent_state import AgentState
+from langgraph_plainid.nodes.base_node import BaseNode
+
+
+class CategorizationNode(BaseNode):
+    """LangGraph node that categorizes prompts via a PlainID categorizer.
+
+    Reads the query from ``state["categorization"]["query"]`` and delegates
+    to the wrapped categorizer.
+    """
+
+    def __init__(
+        self,
+        categorizer: BaseCategorizer,
+        next_node: Optional[str] = None,
+        next_node_on_error: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            substate_key="categorization",
+            next_node=next_node,
+            next_node_on_error=next_node_on_error,
+        )
+        self._categorizer = categorizer
+
+    def _execute(self, state: AgentState) -> dict[str, Any]:
+        categorization = state["categorization"]
+        request_context = state.get("request_context")
+
+        self._categorizer.categorize(
+            categorization["query"],
+            request_context=request_context,
+        )
+
+        return {}
+
+    async def _aexecute(self, state: AgentState) -> dict[str, Any]:
+        categorization = state["categorization"]
+        request_context = state.get("request_context")
+
+        await self._categorizer.acategorize(
+            categorization["query"],
+            request_context=request_context,
+        )
+
+        return {}

langgraph_plainid/nodes/retrieval_node.py

@@ -0,0 +1,56 @@
+from typing import Any, Optional
+
+from core_plainid.retrieval.base_retriever import BaseRetriever
+
+from langgraph_plainid.models.state.agent_state import AgentState
+from langgraph_plainid.nodes.base_node import BaseNode
+
+
+class RetrievalNode(BaseNode):
+    """LangGraph node that retrieves documents via PlainID-authorized filters.
+
+    Reads the query from ``state["retrieval"]["query"]`` and writes the
+    result to ``state["retrieval"]["retrieved_documents"]``.
+    """
+
+    def __init__(
+        self,
+        retriever: BaseRetriever,
+        next_node: Optional[str] = None,
+        next_node_on_error: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            substate_key="retrieval",
+            next_node=next_node,
+            next_node_on_error=next_node_on_error,
+        )
+        self._retriever = retriever
+
+    def _execute(self, state: AgentState) -> dict[str, Any]:
+        retrieval = state["retrieval"]
+        request_context = state.get("request_context")
+
+        documents = self._retriever.retrieve(
+            retrieval["query"],
+            request_context=request_context,
+        )
+
+        return self._build_updated_state(documents)
+
+    async def _aexecute(self, state: AgentState) -> dict[str, Any]:
+        retrieval = state["retrieval"]
+        request_context = state.get("request_context")
+
+        documents = await self._retriever.aretrieve(
+            retrieval["query"],
+            request_context=request_context,
+        )
+
+        return self._build_updated_state(documents)
+
+    def _build_updated_state(self, documents: list) -> dict[str, Any]:
+        return {
+            "retrieval": {
+                "retrieved_documents": documents,
+            }
+        }

langgraph_plainid-1.0.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: langgraph-plainid
+Version: 1.0.0
+Summary: LangGraph integration for PlainID authorization
+Author: PlainID
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <=3.12,>=3.10
+Requires-Dist: core-plainid<2.0.0,>=1.0.0
+Requires-Dist: langchain-plainid<2.0.0,>=1.0.0
+Requires-Dist: langgraph<2.0.0,>=1.1.2
+Description-Content-Type: text/markdown
+
+# langgraph-plainid
+
+[PlainID](https://www.plainid.com/) authorization integration for [LangGraph](https://langchain-ai.github.io/langgraph/). Provides LangGraph nodes for prompt categorization, text anonymization, and policy-based document retrieval that can be composed into stateful agent graphs.
+
+This library depends on [core-plainid](https://pypi.org/project/core-plainid/) and [langchain-plainid](https://pypi.org/project/langchain-plainid/) for the underlying authorization components. Please refer to the **core-plainid README** for setting up permissions, categorizers, anonymizers, classifiers, and PlainID rulesets, and the **langchain-plainid README** for retrieval and vector store configuration.
+
+All nodes fully support both **synchronous** and **asynchronous** execution. The examples below use the async API; replace `ainvoke` with `invoke` for synchronous usage.
+
+## Installation
+
+```bash
+pip install langgraph-plainid
+```
+
+`core-plainid` and `langchain-plainid` are installed automatically as dependencies.
+
+## Agent State
+
+All nodes operate on a shared `AgentState` TypedDict that flows through the graph. The state contains the `request_context` for identity information and optional sub-states for each node type. Alternatively, `request_context` can be provided at construction time to the underlying components (e.g. `PlainIDPermissionsProvider`, `FilterDirectiveProvider`) — see the core-plainid README for details.
+
+```python
+from langgraph_plainid.models.state.agent_state import AgentState
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `request_context` | `RequestContext` | Identity context (entity ID, type, additional identities) |
+| `categorization` | `CategorizationState` | Sub-state with `query` and optional `error_details` |
+| `anonymization` | `AnonymizationState` | Sub-state with `query`, optional `output_text`, and `error_details` |
+| `retrieval` | `RetrievalState` | Sub-state with `query`, `resource_types`, optional `retrieved_documents`, and `error_details` |
+
+Multiple identities (e.g. a User and an AI Agent) are supported for agentic scenarios through the `additional_identities` field in `RequestContext` — see the core-plainid README for details.
+
+## Base Node
+
+All PlainID nodes extend `BaseNode`, which provides common behavior:
+
+- **`next_node`** — optional name of the next node to route to via LangGraph `Command`. If not set, the node returns the updated state directly and graph edges determine the flow.
+- **`next_node_on_error`** — optional name of a node to route to when an error occurs. If set, errors are caught and routed as `ErrorDetails` in the sub-state. If not set, exceptions propagate normally.
+
+## Categorization Node
+
+The `CategorizationNode` classifies the input prompt against PlainID policies. If the categories are not allowed, a `PlainIDCategorizerException` is raised (or routed to the error handler node if configured).
+
+For setting up the categorizer, classifier providers, and the PlainID `Prompt_Control` ruleset, see the **Category Filtering** section in the core-plainid README.
+
+```python
+from core_plainid.categorization.categorizer import Categorizer
+from core_plainid.utils.plainid_permissions_provider import PlainIDPermissionsProvider
+from langgraph_plainid.nodes.categorization_node import CategorizationNode
+
+permissions_provider = PlainIDPermissionsProvider(
+    base_url="https://platform-product.us1.plainid.io",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+categorizer = Categorizer(
+    classifier_provider=classifier,
+    permissions_provider=permissions_provider,
+    all_categories=["contract", "HR", "finance"],
+)
+
+categorization_node = CategorizationNode(
+    categorizer=categorizer,
+    next_node="anonymizer",
+    next_node_on_error="error_handler",
+)
+```
+
+The node reads its input from `state["categorization"]["query"]`.
+
+## Anonymization Node
+
+The `AnonymizerNode` detects and anonymizes PII in the input text based on PlainID policies. The anonymized text is written to `state["anonymization"]["output_text"]`.
+
+For setting up the anonymizer, encryption key, AHDS, and the PlainID `Output_Control` ruleset, see the **Anonymization** section in the core-plainid README.
+
+```python
+from core_plainid.anonymization.presidio_anonymizer import PresidioAnonymizer
+from core_plainid.utils.plainid_permissions_provider import PlainIDPermissionsProvider
+from langgraph_plainid.nodes.anonymizer_node import AnonymizerNode
+
+permissions_provider = PlainIDPermissionsProvider(
+    base_url="https://platform-product.us1.plainid.io",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+anonymizer = PresidioAnonymizer(
+    permissions_provider=permissions_provider,
+    encrypt_key="your_16_char_key!",
+)
+
+anonymizer_node = AnonymizerNode(
+    anonymizer=anonymizer,
+    next_node="retrieval",
+    next_node_on_error="error_handler",
+)
+```
+
+The node reads its input from `state["anonymization"]["query"]` and writes the result to `state["anonymization"]["output_text"]`.
+
+## Retrieval Node
+
+The `RetrievalNode` retrieves documents from vector stores with PlainID-enforced filters. The retrieved documents are written to `state["retrieval"]["retrieved_documents"]`.
+
+For setting up the retriever, filter provider, and vector store configuration, see the **Retrieval** section in the langchain-plainid README.
+
+```python
+from langchain_plainid.retrieval.filter_directive_provider import FilterDirectiveProvider
+from langchain_plainid.retrieval.multi_store_retriever import MultiStoreRetriever
+from langgraph_plainid.nodes.retrieval_node import RetrievalNode
+
+filter_provider = FilterDirectiveProvider(
+    base_url="https://platform-product.us1.plainid.io",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+retriever = MultiStoreRetriever(
+    filter_provider=filter_provider,
+    resource_types=["customer"],
+    vector_stores=[customer_store],
+    k=4,
+)
+
+retrieval_node = RetrievalNode(
+    retriever=retriever,
+    next_node_on_error="error_handler",
+)
+```
+
+The node reads its input from `state["retrieval"]["query"]` and writes the result to `state["retrieval"]["retrieved_documents"]`.
+
+## Building a Graph
+
+Nodes are composed into a LangGraph `StateGraph` to define the agent's execution flow. Here is an example graph that categorizes a prompt, anonymizes it, and then retrieves documents:
+
+```python
+from langgraph.graph import END, START, StateGraph
+from core_plainid.models.context.request_context import RequestContext
+from langgraph_plainid.models.state.agent_state import AgentState
+
+graph = StateGraph(AgentState)
+
+graph.add_node("categorization", categorization_node)
+graph.add_node("anonymizer", anonymizer_node)
+graph.add_node("retrieval", retrieval_node)
+
+graph.add_edge(START, "categorization")
+graph.add_edge("categorization", "anonymizer")
+graph.add_edge("anonymizer", "retrieval")
+graph.add_edge("retrieval", END)
+
+app = graph.compile()
+
+request_context = RequestContext(
+    entity_id="your_entity_id",
+    entity_id_type="your_entity_type",
+)
+
+result = await app.ainvoke({
+    "request_context": request_context,
+    "categorization": {"query": "What is John Smith's contract status?"},
+    "anonymization": {"query": "What is John Smith's contract status?"},
+    "retrieval": {"query": "What is John Smith's contract status?"},
+})
+
+print(result["anonymization"]["output_text"])       # anonymized text
+print(result["retrieval"]["retrieved_documents"])    # retrieved documents
+```
+
+### Using Command-Based Routing
+
+Instead of defining edges between all nodes, you can use the `next_node` parameter to let nodes route to the next step via LangGraph `Command`:
+
+```python
+categorization_node = CategorizationNode(
+    categorizer=categorizer,
+    next_node="anonymizer",
+)
+
+anonymizer_node = AnonymizerNode(
+    anonymizer=anonymizer,
+    next_node="retrieval",
+)
+
+retrieval_node = RetrievalNode(retriever=retriever)
+
+graph = StateGraph(AgentState)
+
+graph.add_node("categorization", categorization_node)
+graph.add_node("anonymizer", anonymizer_node)
+graph.add_node("retrieval", retrieval_node)
+
+graph.add_edge(START, "categorization")
+graph.add_edge("retrieval", END)
+
+app = graph.compile()
+```
+
+### Error Handling
+
+When `next_node_on_error` is set, errors are caught and the graph routes to the specified error handler node. The error details are available in the sub-state:
+
+```python
+def error_handler(state: AgentState) -> dict:
+    for key in ["categorization", "anonymization", "retrieval"]:
+        sub_state = state.get(key)
+        
+        if sub_state and sub_state.get("error_details"):
+            error_details = sub_state["error_details"]
+            
+            print(f"Error in {key}: {error_details['error_message']}")
+            print(f"Exception: {error_details['error']}")
+
+    return {}
+
+graph.add_node("error_handler", error_handler)
+```
+
+If `next_node_on_error` is not set, exceptions propagate normally and can be caught in the calling context of `invoke` / `ainvoke`.
+
+## Exceptions
+
+All exceptions are defined in the `core-plainid` library. See the **Exceptions** section in the core-plainid README for the full list.

langgraph_plainid-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+langgraph_plainid/__init__.py,sha256=9cW8m3y1Kz_HABi3hluIa8T4b-FlgfthCQXLT8Wy57o,637
+langgraph_plainid/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_plainid/models/state/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_plainid/models/state/agent_state.py,sha256=-wWItepXBdx3JBAhYyTvFrpTRrthKwu04rP7VluW6eI,846
+langgraph_plainid/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_plainid/nodes/anonymizer_node.py,sha256=oJKeZY40oO9lZMjnjVKnn9jsfED6uhQ2KNawKh4Cv9s,1771
+langgraph_plainid/nodes/base_node.py,sha256=AkTFnN-L5VXLwykEUk26HEDWhe06M6L989EGC2IBDeA,3574
+langgraph_plainid/nodes/categorization_node.py,sha256=9u0tZjJ7l3EBT_BSwGlpaVdEW9uyPq9fLDyqjuTL03A,1484
+langgraph_plainid/nodes/retrieval_node.py,sha256=Q1gEC42jANl4VIysE3obC_TnhcwIN4ylAzF6hknYHZ4,1731
+langgraph_plainid-1.0.0.dist-info/METADATA,sha256=xQONXETIEX5tRFExTeg03VTVx6PmCt6Y9l8X3wRmXU0,10047
+langgraph_plainid-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+langgraph_plainid-1.0.0.dist-info/RECORD,,

langgraph_plainid-1.0.0.dist-info/WHEEL

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