auth0-ai-langchain 1.0.1__py3-none-any.whl

auth0_ai_langchain/FGARetriever.py

@@ -0,0 +1,158 @@
+import os
+
+from typing import Callable, Optional
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.documents import Document
+from openfga_sdk.client.client import ClientBatchCheckRequest
+from pydantic import PrivateAttr
+from openfga_sdk import ClientConfiguration, OpenFgaClient
+from openfga_sdk.client.models import ClientBatchCheckItem
+from openfga_sdk.sync import OpenFgaClient as OpenFgaClientSync
+from openfga_sdk.credentials import CredentialConfiguration, Credentials
+
+
+class FGARetriever(BaseRetriever):
+    """
+    FGARetriever integrates with OpenFGA to filter documents based on fine-grained authorization (FGA).
+    """
+
+    _retriever: BaseRetriever = PrivateAttr()
+    _fga_configuration: ClientConfiguration = PrivateAttr()
+    _query_builder: Callable[[Document], ClientBatchCheckItem] = PrivateAttr()
+
+    def __init__(
+        self,
+        retriever: BaseRetriever,
+        build_query: Callable[[Document], ClientBatchCheckItem],
+        fga_configuration: Optional[ClientConfiguration] = None,
+    ):
+        """
+        Initialize the FGARetriever with the specified retriever, query builder, and configuration.
+
+        Args:
+            retriever (BaseRetriever): The retriever used to fetch documents.
+            build_query (Callable[[Document], ClientBatchCheckItem]): Function to convert documents into FGA queries.
+            fga_configuration (ClientConfiguration, optional): Configuration for the OpenFGA client. If not provided, defaults to environment variables.
+        """
+        super().__init__()
+        self._retriever = retriever
+        self._fga_configuration = fga_configuration or ClientConfiguration(
+            api_url=os.getenv("FGA_API_URL") or "https://api.us1.fga.dev",
+            store_id=os.getenv("FGA_STORE_ID"),
+            credentials=Credentials(
+                method="client_credentials",
+                configuration=CredentialConfiguration(
+                    api_issuer=os.getenv("FGA_API_TOKEN_ISSUER") or "auth.fga.dev",
+                    api_audience=os.getenv("FGA_API_AUDIENCE")
+                    or "https://api.us1.fga.dev/",
+                    client_id=os.getenv("FGA_CLIENT_ID"),
+                    client_secret=os.getenv("FGA_CLIENT_SECRET"),
+                ),
+            ),
+        )
+        self._query_builder = build_query
+
+    async def _async_filter_FGA(self, docs: list[Document]) -> list[Document]:
+        """
+        Asynchronously filter documents using OpenFGA.
+
+        Args:
+            docs (List[Document]): List of documents to filter.
+
+        Returns:
+            List[Document]: Filtered list of documents authorized by FGA.
+        """
+        async with OpenFgaClient(self._fga_configuration) as fga_client:
+            all_checks = [self._query_builder(doc) for doc in docs]
+            unique_checks = list(
+                {
+                    (check.relation, check.object, check.user): check
+                    for check in all_checks
+                }.values()
+            )
+
+            doc_to_obj = {doc: check.object for check, doc in zip(all_checks, docs)}
+
+            fga_response = await fga_client.batch_check(
+                ClientBatchCheckRequest(checks=unique_checks)
+            )
+            await fga_client.close()
+
+            permissions_map = {
+                result.request.object: result.allowed for result in fga_response.result
+            }
+
+            return [
+                doc
+                for doc in docs
+                if doc_to_obj[doc] in permissions_map
+                and permissions_map[doc_to_obj[doc]]
+            ]
+
+    async def _aget_relevant_documents(self, query, *, run_manager) -> list[Document]:
+        """
+        Asynchronously retrieve relevant documents from the base retrieve and filter them using FGA.
+
+        Args:
+            query (str): The query for retrieving documents.
+            run_manager (object, optional): Optional manager for tracking runs.
+
+        Returns:
+            List[Document]: Filtered and relevant documents.
+        """
+        docs = await self._retriever._aget_relevant_documents(
+            query, run_manager=run_manager
+        )
+        docs = await self._async_filter_FGA(docs)
+        return docs
+
+    def _filter_FGA(self, docs: list[Document]) -> list[Document]:
+        """
+        Synchronously filter documents using OpenFGA.
+
+        Args:
+            docs (List[Document]): List of documents to filter.
+
+        Returns:
+            List[Document]: Filtered list of documents authorized by FGA.
+        """
+        with OpenFgaClientSync(self._fga_configuration) as fga_client:
+            all_checks = [self._query_builder(doc) for doc in docs]
+            unique_checks = list(
+                {
+                    (check.relation, check.object, check.user): check
+                    for check in all_checks
+                }.values()
+            )
+
+            doc_to_obj = {doc.id: check.object for check, doc in zip(all_checks, docs)}
+
+            fga_response = fga_client.batch_check(
+                ClientBatchCheckRequest(checks=unique_checks)
+            )
+
+            permissions_map = {
+                result.request.object: result.allowed for result in fga_response.result
+            }
+
+            return [
+                doc
+                for doc in docs
+                if doc_to_obj[doc.id] in permissions_map
+                and permissions_map[doc_to_obj[doc.id]]
+            ]
+
+    def _get_relevant_documents(self, query, *, run_manager) -> list[Document]:
+        """
+        Retrieve relevant documents and filter them using FGA.
+
+        Args:
+            query (str): The query for retrieving documents.
+            run_manager (object, optional): Optional manager for tracking runs.
+
+        Returns:
+            List[Document]: Filtered and relevant documents.
+        """
+        docs = self._retriever._get_relevant_documents(query, run_manager=run_manager)
+        docs = self._filter_FGA(docs)
+        return docs

auth0_ai_langchain/__init__.py

@@ -0,0 +1,3 @@
+from .FGARetriever import FGARetriever
+
+__all__ = ["FGARetriever"]

auth0_ai_langchain/async_authorization/__init__.py

@@ -0,0 +1,3 @@
+from auth0_ai.authorizers.async_authorization.async_authorizer_base import get_async_authorization_credentials as get_async_authorization_credentials
+from auth0_ai_langchain.async_authorization.async_authorizer import AsyncAuthorizer as AsyncAuthorizer
+from auth0_ai_langchain.async_authorization.graph_resumer import GraphResumer as GraphResumer

auth0_ai_langchain/async_authorization/async_authorizer.py

@@ -0,0 +1,17 @@
+from abc import ABC
+from typing import Union
+from auth0_ai.authorizers.async_authorization import AsyncAuthorizerBase
+from auth0_ai.interrupts.async_authorization_interrupts import AuthorizationPendingInterrupt, AuthorizationPollingInterrupt
+from auth0_ai_langchain.utils.interrupt import to_graph_interrupt
+from auth0_ai_langchain.utils.tool_wrapper import tool_wrapper
+from langchain_core.tools import BaseTool
+
+class AsyncAuthorizer(AsyncAuthorizerBase, ABC):
+    def _handle_authorization_interrupts(self, err: Union[AuthorizationPendingInterrupt, AuthorizationPollingInterrupt]) -> None:
+        raise to_graph_interrupt(err)
+    
+    def authorizer(self):
+        def wrap_tool(tool: BaseTool) -> BaseTool:
+            return tool_wrapper(tool, self.protect)
+        
+        return wrap_tool

auth0_ai_langchain/async_authorization/graph_resumer.py

@@ -0,0 +1,154 @@
+import asyncio
+from threading import Event
+from typing import Callable, Optional, Dict, Any, List, TypedDict
+from auth0_ai.authorizers.async_authorization import AsyncAuthorizationRequest
+from auth0_ai.interrupts.async_authorization_interrupts import AsyncAuthorizationInterrupt, AuthorizationPendingInterrupt, AuthorizationPollingInterrupt
+from auth0_ai_langchain.utils.interrupt import get_auth0_interrupts
+from langgraph_sdk.client import LangGraphClient
+from langgraph_sdk.schema import Thread, Interrupt
+
+class WatchedThread(TypedDict):
+    thread_id: str
+    assistant_id: str
+    interruption_id: str
+    auth_request: AsyncAuthorizationRequest
+    config: Dict[str, Any]
+    last_run: float
+
+class GraphResumerFilters(TypedDict):
+    graph_id: str
+
+class GraphResumer:
+    def __init__(self, lang_graph: LangGraphClient, filters: Optional[GraphResumerFilters] = None):
+        self.lang_graph = lang_graph
+        self.filters = filters or {}
+        self.map: Dict[str, WatchedThread] = {}
+        self._stop_event = Event()
+        self._loop_task: Optional[asyncio.Task] = None
+
+        # Event callbacks
+        self._resume_callbacks: List[Callable[[WatchedThread], None]] = []
+        self._error_callbacks: List[Callable[[Exception], None]] = []
+
+    # Public API to register event callbacks
+    def on_resume(self, callback: Callable[[WatchedThread], None]) -> "GraphResumer":
+        self._resume_callbacks.append(callback)
+        return self
+
+    def on_error(self, callback: Callable[[Exception], None]) -> "GraphResumer":
+        self._error_callbacks.append(callback)
+        return self
+
+    def _emit_resume(self, thread: WatchedThread) -> None:
+        for callback in self._resume_callbacks:
+            callback(thread)
+
+    def _emit_error(self, error: Exception) -> None:
+        for callback in self._error_callbacks:
+            callback(error)
+
+    async def _get_all_interrupted_threads(self) -> List[Thread]:
+        interrupted_threads: List[Thread] = []
+        offset = 0
+
+        while True:
+            page = await self.lang_graph.threads.search(
+                status="interrupted",
+                limit=100,
+                offset=offset,
+                metadata={"graph_id": self.filters["graph_id"]} if "graph_id" in self.filters else None
+            )
+
+            if not page:
+                break
+
+            for t in page:
+                interrupt = self._get_first_interrupt(t)
+                if interrupt and AsyncAuthorizationInterrupt.is_interrupt(interrupt["value"]) and AsyncAuthorizationInterrupt.has_request_data(interrupt["value"]):
+                    interrupted_threads.append(t)
+
+            offset += len(page)
+            if len(page) < 100:
+                break
+
+        return interrupted_threads
+
+    def _get_first_interrupt(self, thread: Thread) -> Optional[Interrupt]:
+        interrupts = thread["interrupts"]
+        if interrupts:
+            values = list(interrupts.values())
+            if values and values[0]:
+                return values[0][0]
+        return None
+
+    def _get_hash_map_id(self, thread: Thread) -> str:
+        return f"{thread['thread_id']}:{next(iter(thread['interrupts']))}"
+
+    async def _resume_thread(self, t: WatchedThread):
+        self._emit_resume(t)
+
+        await self.lang_graph.runs.wait(t["thread_id"], t["assistant_id"], config=t["config"])
+
+        t["last_run"] = asyncio.get_event_loop().time() * 1000
+
+    async def loop(self):
+        all_threads = await self._get_all_interrupted_threads()
+
+        # Remove old interrupted threads
+        active_keys = {self._get_hash_map_id(t) for t in all_threads}
+
+        for key in list(self.map.keys()):
+            if key not in active_keys:
+                del self.map[key]
+
+        # Add new interrupted threads
+        for thread in all_threads:
+            interrupt = next(
+                (i for i in get_auth0_interrupts(thread)
+                 if AuthorizationPendingInterrupt.is_interrupt(i["value"])
+                 or AuthorizationPollingInterrupt.is_interrupt(i["value"])),
+                None
+            )
+
+            if not interrupt or not interrupt["value"].get("_request"):
+                continue
+
+            key = self._get_hash_map_id(thread)
+            if key not in self.map:
+                self.map[key] = {
+                    "thread_id": thread["thread_id"],
+                    "assistant_id": thread["metadata"].get("graph_id"),
+                    "config": getattr(thread, "config", {}),
+                    "interruption_id": next(iter(thread["interrupts"])),
+                    "auth_request": interrupt["value"]["_request"],
+                }
+
+        threads_to_resume = [
+            t for t in self.map.values()
+            if "last_run" not in t or (t["last_run"] + t["auth_request"]["interval"] * 1000 < asyncio.get_event_loop().time() * 1000)
+        ]
+
+        await asyncio.gather(*[
+            self._resume_thread(t) for t in threads_to_resume
+        ])
+
+    def start(self):
+        if self._loop_task and not self._loop_task.done():
+            return
+
+        self._stop_event.clear()
+
+        async def _run_loop():
+            while not self._stop_event.is_set():
+                try:
+                    await self.loop()
+                except Exception as e:
+                    self._emit_error(e)
+                await asyncio.sleep(5)
+
+        self._loop_task = asyncio.create_task(_run_loop())
+
+    def stop(self):
+        self._stop_event.set()
+        if self._loop_task:
+            self._loop_task.cancel()

auth0_ai_langchain/auth0_ai.py

@@ -0,0 +1,114 @@
+from typing import Callable, Optional
+from langchain_core.tools import BaseTool
+from auth0_ai.authorizers.async_authorization import AsyncAuthorizerParams
+from auth0_ai.authorizers.token_vault_authorizer import TokenVaultAuthorizerParams
+from auth0_ai.authorizers.types import Auth0ClientParams
+from auth0_ai_langchain.async_authorization.async_authorizer import AsyncAuthorizer
+from auth0_ai_langchain.token_vault.token_vault_authorizer import TokenVaultAuthorizer
+
+
+class Auth0AI:
+    """Provides decorators to secure LangChain tools using Auth0 authorization flows.
+    """
+
+    def __init__(self, auth0: Optional[Auth0ClientParams] = None):
+        """Initializes the Auth0AI instance.
+
+        Args:
+            auth0 (Optional[Auth0ClientParams]): Parameters for the Auth0 client.
+                If not provided, values will be automatically read from environment
+                variables: `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, and `AUTH0_CLIENT_SECRET`.
+        """
+        self.auth0 = auth0
+
+    def with_async_authorization(self, **params: AsyncAuthorizerParams) -> Callable[[BaseTool], BaseTool]:
+        """Protects a tool with the CIBA (Client-Initiated Backchannel Authentication) flow.
+
+        Requires user confirmation via a second device (e.g., phone)
+        before allowing the tool to execute.
+
+        Args:
+            **params: Parameters defined in `AsyncAuthorizerParams`.
+
+        Returns:
+            Callable[[BaseTool], BaseTool]: A decorator to wrap a LangChain tool.
+
+        Example:
+            ```python
+            import os
+            from auth0_ai_langchain.auth0_ai import Auth0AI
+            from auth0_ai_langchain.async_authorization import get_async_authorization_credentials
+            from langchain_core.runnables import ensure_config
+            from langchain_core.tools import StructuredTool
+
+            auth0_ai = Auth0AI()
+
+            with_async_authorization = auth0_ai.with_async_authorization(
+                scopes=["stock:trade"],
+                audience=os.getenv("AUDIENCE"),
+                requested_expiry=os.getenv("REQUESTED_EXPIRY"),
+                binding_message=lambda ticker, qty: f"Authorize the purchase of {qty} {ticker}",
+                user_id=lambda *_, **__: ensure_config().get("configurable", {}).get("user_id")
+            )
+
+            def tool_function(ticker: str, qty: int) -> str:
+                credentials = get_async_authorization_credentials()
+                headers = {
+                    "Authorization": f"{credentials['token_type']} {credentials['access_token']}",
+                    # ...
+                }
+                # Call API
+
+            trade_tool = with_async_authorization(
+                StructuredTool(
+                    name="trade_tool",
+                    description="Use this function to trade a stock",
+                    func=tool_function,
+                )
+            )
+            ```
+        """
+        authorizer = AsyncAuthorizer(AsyncAuthorizerParams(**params), self.auth0)
+        return authorizer.authorizer()
+
+    def with_token_vault(self, **params: TokenVaultAuthorizerParams) -> Callable[[BaseTool], BaseTool]:
+        """Enables a tool to obtain an access token from a Token Vault identity provider (e.g., Google, Azure AD).
+
+        The token can then be used within the tool to call third-party APIs on behalf of the user.
+
+        Args:
+            **params: Parameters defined in `TokenVaultAuthorizerParams`.
+
+        Returns:
+            Callable[[BaseTool], BaseTool]: A decorator to wrap a LangChain tool.
+
+        Example:
+            ```python
+            from auth0_ai_langchain.auth0_ai import Auth0AI
+            from auth0_ai_langchain.token_vault import get_credentials_from_token_vault
+            from langchain_core.tools import StructuredTool
+            from datetime import datetime
+
+            auth0_ai = Auth0AI()
+
+            with_google_calendar_access = auth0_ai.with_token_vault(
+                connection="google-oauth2",
+                scopes=["openid", "https://www.googleapis.com/auth/calendar.freebusy"]
+            )
+
+            def tool_function(date: datetime):
+                credentials = get_credentials_from_token_vault()
+                # Call Google API using credentials["access_token"]
+
+            check_calendar_tool = with_google_calendar_access(
+                StructuredTool(
+                    name="check_user_calendar",
+                    description="Use this function to check if the user is available on a certain date and time",
+                    func=tool_function,
+                )
+            )
+            ```
+        """
+        authorizer = TokenVaultAuthorizer(
+            TokenVaultAuthorizerParams(**params), self.auth0)
+        return authorizer.authorizer()

auth0_ai_langchain/fga/__init__.py

@@ -0,0 +1,4 @@
+from auth0_ai.authorizers.fga_authorizer import (
+    FGAAuthorizer as FGAAuthorizer,
+    FGAAuthorizerOptions as FGAAuthorizerOptions
+)

auth0_ai_langchain/token_vault/__init__.py

@@ -0,0 +1,10 @@
+from auth0_ai.interrupts.token_vault_interrupt import (
+    TokenVaultError as TokenVaultError,
+    TokenVaultInterrupt as TokenVaultInterrupt
+)
+
+from auth0_ai.authorizers.token_vault_authorizer import (
+    get_credentials_from_token_vault as get_credentials_from_token_vault,
+    get_access_token_from_token_vault as get_access_token_from_token_vault
+)
+from .token_vault_authorizer import TokenVaultAuthorizer as TokenVaultAuthorizer

auth0_ai_langchain/token_vault/token_vault_authorizer.py

@@ -0,0 +1,38 @@
+import copy
+from abc import ABC
+from auth0_ai.authorizers.token_vault_authorizer import TokenVaultAuthorizerBase, \
+    TokenVaultAuthorizerParams
+from auth0_ai.authorizers.types import Auth0ClientParams
+from auth0_ai.interrupts.token_vault_interrupt import TokenVaultInterrupt
+from auth0_ai_langchain.utils.interrupt import to_graph_interrupt
+from auth0_ai_langchain.utils.tool_wrapper import tool_wrapper
+from langchain_core.tools import BaseTool
+from langchain_core.runnables import ensure_config
+
+
+async def default_get_refresh_token(*_, **__) -> str | None:
+    return ensure_config().get("configurable", {}).get("_credentials", {}).get("refresh_token")
+
+class TokenVaultAuthorizer(TokenVaultAuthorizerBase, ABC):
+    def __init__(
+        self,
+        params: TokenVaultAuthorizerParams,
+        auth0: Auth0ClientParams = None,
+    ):
+        missing_refresh = params.refresh_token.value is None
+        missing_access_token = params.access_token.value is None
+
+        if missing_refresh and missing_access_token and callable(default_get_refresh_token):
+            params = copy.copy(params)
+            params.refresh_token.value = default_get_refresh_token
+
+        super().__init__(params, auth0)
+
+    def _handle_authorization_interrupts(self, err: TokenVaultInterrupt) -> None:
+        raise to_graph_interrupt(err)
+
+    def authorizer(self):
+        def wrap_tool(tool: BaseTool) -> BaseTool:
+            return tool_wrapper(tool, self.protect)
+
+        return wrap_tool

auth0_ai_langchain/utils/interrupt.py

@@ -0,0 +1,30 @@
+from typing import List
+from auth0_ai.interrupts.auth0_interrupt import Auth0Interrupt
+from langgraph.errors import GraphInterrupt
+from langgraph.types import Interrupt
+from langgraph_sdk.schema import Thread
+
+
+def to_graph_interrupt(interrupt: Auth0Interrupt) -> GraphInterrupt:
+    return GraphInterrupt([
+        Interrupt(
+            value=interrupt.to_json(),
+            when="during",
+            resumable=True,
+            ns=[f"auth0AI:{interrupt.name}:{interrupt.code}"]
+        )
+    ])
+
+
+def get_auth0_interrupts(thread: Thread) -> List[Interrupt]:
+    result = []
+
+    if "interrupts" not in thread:
+        return result
+
+    for interrupt_list in thread["interrupts"].values():
+        for interrupt in interrupt_list:
+            if Auth0Interrupt.is_interrupt(interrupt["value"]):
+                result.append(interrupt)
+
+    return result

auth0_ai_langchain/utils/tool_wrapper.py

@@ -0,0 +1,34 @@
+from typing import Callable
+from typing_extensions import Annotated
+from pydantic import create_model
+from langchain_core.tools import BaseTool, tool as create_tool, InjectedToolCallId
+from langchain_core.runnables import RunnableConfig
+
+def tool_wrapper(tool: BaseTool, protect_fn: Callable) -> BaseTool:
+
+    # Workaround: extend existing args_schema to be able to get the tool_call_id value
+    args_schema = create_model(
+        tool.args_schema.__name__ + "Extended",
+        __base__=tool.args_schema,
+        **{"tool_call_id": (Annotated[str, InjectedToolCallId])}
+    )
+
+    @create_tool(
+        tool.name,
+        description=tool.description,
+        args_schema=args_schema
+    )
+    async def wrapped_tool(config: RunnableConfig, tool_call_id: Annotated[str, InjectedToolCallId], **input):
+        async def execute_fn(*_, **__):
+            return await tool.ainvoke(input, config)
+
+        return await protect_fn(
+            lambda *_, **__: {
+                "thread_id": config.get("configurable", {}).get("thread_id"),
+                "tool_call_id": tool_call_id,
+                "tool_name": tool.name,
+            },
+            execute_fn,
+        )(**input)
+
+    return wrapped_tool

auth0_ai_langchain-1.0.1.dist-info/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

auth0_ai_langchain-1.0.1.dist-info/METADATA

@@ -0,0 +1,371 @@
+Metadata-Version: 2.3
+Name: auth0-ai-langchain
+Version: 1.0.1
+Summary: This package is an SDK for building secure AI-powered applications using Auth0, Okta FGA and LangChain.
+License: Apache-2.0
+Author: Auth0
+Author-email: support@auth0.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: auth0-ai (>=1.0.2,<2.0.0)
+Requires-Dist: langchain (>=0.3.26,<0.4.0)
+Requires-Dist: langchain-core (>=0.3.69,<0.4.0)
+Requires-Dist: langgraph (>=0.5.3,<0.6.0)
+Requires-Dist: langgraph-sdk (>=0.1.73,<0.2.0)
+Requires-Dist: openfga-sdk (>=0.9.5,<0.10.0)
+Project-URL: Homepage, https://auth0.com
+Description-Content-Type: text/markdown
+
+# Auth0 AI for LangChain
+
+`auth0-ai-langchain` is an SDK for building secure AI-powered applications using [Auth0](https://www.auth0.ai/), [Okta FGA](https://docs.fga.dev/) and [LangChain](https://python.langchain.com/docs/tutorials/).
+
+![Release](https://img.shields.io/pypi/v/auth0-ai-langchain) ![Downloads](https://img.shields.io/pypi/dw/auth0-ai-langchain) [![License](https://img.shields.io/:license-APACHE%202.0-blue.svg?style=flat)](https://opensource.org/license/apache-2-0)
+
+## Installation
+
+> ⚠️ **WARNING**: `auth0-ai-langchain` is currently **under heavy development**. We strictly follow [Semantic Versioning (SemVer)](https://semver.org/), meaning all **breaking changes will only occur in major versions**. However, please note that during this early phase, **major versions may be released frequently** as the API evolves. We recommend locking versions when using this in production.
+
+```bash
+pip install auth0-ai-langchain
+```
+
+## Async Authorization
+
+`Auth0AI` uses CIBA (Client-Initiated Backchannel Authentication) to handle user confirmation asynchronously. This is useful when you need to confirm a user action before proceeding with a tool execution.
+
+Full Example of [Async Authorization](https://github.com/auth0/auth0-ai-python/tree/main/examples/async-authorization/langchain-examples).
+
+1. Define a tool with the proper authorizer specifying a function to resolve the user id:
+
+```python
+from auth0_ai_langchain.auth0_ai import Auth0AI
+from auth0_ai_langchain.async_authorization import get_async_authorization_credentials
+from langchain_core.runnables import ensure_config
+from langchain_core.tools import StructuredTool
+
+# If not provided, Auth0 settings will be read from env variables: `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, and `AUTH0_CLIENT_SECRET`
+auth0_ai = Auth0AI()
+
+with_async_authorization = auth0_ai.with_async_authorization(
+    scopes=["stock:trade"],
+    audience=os.getenv("AUDIENCE"),
+    requested_expiry=os.getenv("REQUESTED_EXPIRY"),
+    binding_message=lambda ticker, qty: f"Authorize the purchase of {qty} {ticker}",
+    user_id=lambda *_, **__: ensure_config().get("configurable", {}).get("user_id"),
+    # Optional:
+    # store=InMemoryStore()
+)
+
+def tool_function(ticker: str, qty: int) -> str:
+    credentials = get_async_authorization_credentials()
+    headers = {
+        "Authorization": f"{credentials["token_type"]} {credentials["access_token"]}",
+        # ...
+    }
+    # Call API
+
+trade_tool = with_async_authorization(
+    StructuredTool(
+        name="trade_tool",
+        description="Use this function to trade a stock",
+        func=trade_tool_function,
+        # ...
+    )
+)
+```
+
+2. Handle interruptions properly. For example, if user is not enrolled to MFA, it will throw an interruption. See [Handling Interrupts](#handling-interrupts) section.
+
+### Async Authorization with RAR (Rich Authorization Requests)
+
+`Auth0AI` supports RAR (Rich Authorization Requests) for CIBA. This allows you to provide additional authorization parameters to be displayed during the user confirmation request.
+
+When defining the tool authorizer, you can specify the `authorization_details` parameter to include detailed information about the authorization being requested:
+
+```python
+with_async_authorization = auth0_ai.with_async_authorization(
+    scopes=["stock:trade"],
+    audience=os.getenv("AUDIENCE"),
+    requested_expiry=os.getenv("REQUESTED_EXPIRY"),
+    binding_message=lambda ticker, qty: f"Authorize the purchase of {qty} {ticker}",
+    authorization_details=lambda ticker, qty: [
+        {
+            "type": "trade_authorization",
+            "qty": qty,
+            "ticker": ticker,
+            "action": "buy"
+        }
+    ],
+    user_id=lambda *_, **__: ensure_config().get("configurable", {}).get("user_id"),
+    # Optional:
+    # store=InMemoryStore()
+)
+```
+
+To use RAR with CIBA, you need to [set up authorization details](https://auth0.com/docs/get-started/apis/configure-rich-authorization-requests) in your Auth0 tenant. This includes defining the authorization request parameters and their types. Additionally, the [Guardian SDK](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian) is required to handle these authorization details in your authorizer app.
+
+For more information on setting up RAR with CIBA, refer to:
+
+- [Configure Rich Authorization Requests (RAR)](https://auth0.com/docs/get-started/apis/configure-rich-authorization-requests)
+- [User Authorization with CIBA](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba)
+
+## Authorization for Tools
+
+The `FGAAuthorizer` can leverage Okta FGA to authorize tools executions. The `FGAAuthorizer.create` function can be used to create an authorizer that checks permissions before executing the tool.
+
+Full example of [Authorization for Tools](https://github.com/auth0/auth0-ai-python/tree/main/examples/authorization-for-tools/langchain-examples).
+
+1. Create an instance of FGA Authorizer:
+
+```python
+from auth0_ai_langchain.fga import FGAAuthorizer
+
+# If not provided, FGA settings will be read from env variables: `FGA_STORE_ID`, `FGA_CLIENT_ID`, `FGA_CLIENT_SECRET`, etc.
+fga = FGAAuthorizer.create()
+```
+
+2. Define the FGA query (`build_query`) and, optionally, the `on_unauthorized` handler:
+
+```python
+from langchain_core.runnables import ensure_config
+
+async def build_fga_query(tool_input):
+    user_id = ensure_config().get("configurable",{}).get("user_id")
+    return {
+        "user": f"user:{user_id}",
+        "object": f"asset:{tool_input["ticker"]}",
+        "relation": "can_buy",
+        "context": {"current_time": datetime.now(timezone.utc).isoformat()}
+    }
+
+def on_unauthorized(tool_input):
+    return f"The user is not allowed to buy {tool_input["qty"]} shares of {tool_input["ticker"]}."
+
+use_fga = fga(
+    build_query=build_fga_query,
+    on_unauthorized=on_unauthorized,
+)
+```
+
+**Note**: The parameters given to the `build_query` and `on_unauthorized` functions are the same as those provided to the tool function.
+
+3. Wrap the tool:
+
+```python
+from langchain_core.tools import StructuredTool
+
+async def buy_tool_function(ticker: str, qty: int) -> str:
+    # TODO: implement buy operation
+    return f"Purchased {qty} shares of {ticker}"
+
+func=use_fga(buy_tool_function)
+
+buy_tool = StructuredTool(
+    func=func,
+    coroutine=func,
+    name="buy",
+    description="Use this function to buy stocks",
+)
+```
+
+## Calling APIs On User's Behalf
+
+The `Auth0AI.with_token_vault` function exchanges user's refresh token taken, by default, from the runnable configuration (`config.configurable._credentials.refresh_token`) for a Token Vault access token that is valid to call a third-party API.
+
+Full Example of [Calling APIs On User's Behalf](https://github.com/auth0/auth0-ai-python/tree/main/examples/calling-apis/langchain-examples).
+
+### Basic Usage
+
+1. Define a tool with the proper authorizer:
+
+```python
+from auth0_ai_langchain.auth0_ai import Auth0AI
+from auth0_ai_langchain.token_vault import get_credentials_from_token_vault
+from langchain_core.tools import StructuredTool
+
+# If not provided, Auth0 settings will be read from env variables: `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, and `AUTH0_CLIENT_SECRET`
+auth0_ai = Auth0AI()
+
+with_google_calendar_access = auth0_ai.with_token_vault(
+    connection="google-oauth2",
+    scopes=["openid", "https://www.googleapis.com/auth/calendar.freebusy"],
+    # Optional:
+    # refresh_token=lambda *_, **__: ensure_config().get("configurable", {}).get("_credentials", {}).get("refresh_token"),
+    # authorization_params={"login_hint": "user@example.com", "ui_locales": "en"}
+    # store=InMemoryStore(),
+)
+
+def tool_function(date: datetime):
+    credentials = get_credentials_from_token_vault()
+    # Call Google API using credentials["access_token"]
+
+check_calendar_tool = with_google_calendar_access(
+    StructuredTool(
+        name="check_user_calendar",
+        description="Use this function to check if the user is available on a certain date and time",
+        func=tool_function,
+        # ...
+    )
+)
+```
+
+2. Add a node to your graph for your tools:
+
+```python
+workflow = (
+    StateGraph(State)
+        .add_node(
+            "tools",
+            ToolNode(
+                [
+                    check_calendar_tool,
+                    # ...
+                ],
+                # The error handler should be disabled to allow interruptions to be triggered from within tools.
+                handle_tool_errors=False
+            )
+        )
+        # ...
+)
+```
+
+3. Handle interruptions properly. For example, if the tool does not have access to user's Google Calendar, it will throw an interruption. See [Handling Interrupts](#handling-interrupts) section.
+
+### Additional Authorization Parameters
+
+The `authorization_params` parameter is optional and can be used to pass additional authorization parameters needed to connect an account (e.g., `login_hint`, `ui_locales`):
+
+```python
+with_google_calendar_access = auth0_ai.with_token_vault(
+    connection="google-oauth2",
+    scopes=["openid", "https://www.googleapis.com/auth/calendar.freebusy"],
+    authorization_params={"login_hint": "user@example.com", "ui_locales": "en"}
+)
+```
+
+## RAG with FGA
+
+The `FGARetriever` can be used to filter documents based on access control checks defined in Okta FGA. This retriever performs batch checks on retrieved documents, returning only the ones that pass the specified access criteria.
+
+Full Example of [RAG Application](https://github.com/auth0/auth0-ai-python/tree/main/examples/authorization-for-rag/langchain-examples).
+
+Create a retriever instance using the `FGARetriever` class.
+
+```python
+from langchain.vectorstores import VectorStoreIndex
+from langchain.schema import Document
+from auth0_ai_langchain import FGARetriever
+from openfga_sdk.client.models import ClientCheckRequest
+from openfga_sdk import ClientConfiguration
+from openfga_sdk.credentials import CredentialConfiguration, Credentials
+
+# Define some docs:
+documents = [
+    Document(page_content="This is a public doc", metadata={"doc_id": "public-doc"}),
+    Document(page_content="This is a private doc", metadata={"doc_id": "private-doc"}),
+]
+
+# Create a vector store:
+vector_store = VectorStoreIndex.from_documents(documents)
+
+# Create a retriever:
+base_retriever = vector_store.as_retriever()
+
+# Create the FGA retriever wrapper.
+# If not provided, FGA settings will be read from env variables: `FGA_STORE_ID`, `FGA_CLIENT_ID`, `FGA_CLIENT_SECRET`, etc.
+retriever = FGARetriever(
+    base_retriever,
+    build_query=lambda node: ClientCheckRequest(
+        user=f'user:{user}',
+        object=f'doc:{node.metadata["doc_id"]}',
+        relation="viewer",
+    )
+)
+
+# Create a query engine:
+query_engine = RetrieverQueryEngine.from_args(
+    retriever=retriever,
+    llm=OpenAI()
+)
+
+# Query:
+response = query_engine.query("What is the forecast for ZEKO?")
+
+print(response)
+```
+
+## Handling Interrupts
+
+`Auth0AI` uses interrupts extensively and will never block a graph. Whenever an authorizer requires user interaction, the graph throws a `GraphInterrupt` exception with data that allows the client to resume the flow.
+
+It is important to disable error handling in your tools node as follows:
+
+```python
+    .add_node(
+        "tools",
+        ToolNode(
+            [
+                # your authorizer-wrapped tools
+            ],
+            # Error handler should be disabled in order to trigger interruptions from within tools.
+            handle_tool_errors=False
+        )
+    )
+```
+
+From the client side of the graph you get the interrupts:
+
+```python
+from auth0_ai_langchain.utils.interrupt import get_auth0_interrupts
+
+# Get the langgraph thread:
+thread = await client.threads.get(thread_id)
+
+# Filter the auth0 interrupts:
+auth0_interrupts = get_auth0_interrupts(thread)
+```
+
+Then you can resume the thread by doing this:
+
+```python
+await client.runs.wait(thread_id, assistant_id)
+```
+
+For the specific case of **CIBA (Client-Initiated Backchannel Authorization)** you might attach a `GraphResumer` instance that watches for interrupted threads in the `"Authorization Pending"` state and attempts to resume them automatically, respecting Auth0's polling interval.
+
+```python
+import os
+from auth0_ai_langchain.async_authorization import GraphResumer
+from langgraph_sdk import get_client
+
+resumer = GraphResumer(
+    lang_graph=get_client(url=os.getenv("LANGGRAPH_API_URL")),
+    # optionally, you can filter by a specific graph:
+    filters={"graph_id": "conditional-trade"},
+)
+
+resumer \
+    .on_resume(lambda thread: print(f"Attempting to resume thread {thread['thread_id']} from interruption {thread['interruption_id']}")) \
+    .on_error(lambda err: print(f"Error in GraphResumer: {str(err)}"))
+
+resumer.start()
+```
+
+---
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png"   width="150">
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
+    <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+  </picture>
+</p>
+<p align="center">Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a></p>
+<p align="center">
+This project is licensed under the Apache 2.0 license. See the <a href="https://github.com/auth0/auth0-ai-python/blob/main/LICENSE"> LICENSE</a> file for more info.</p>
+

auth0_ai_langchain-1.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+auth0_ai_langchain/FGARetriever.py,sha256=SQwxo2aDtQhwQtYmszoKw3BH-U5QVnvPAgVw9EDzKVM,6002
+auth0_ai_langchain/__init__.py,sha256=I331Kz-q97ZU7TfXaOR5UBbJamGEJ15twbf2HP1iCHs,67
+auth0_ai_langchain/async_authorization/__init__.py,sha256=ZZW3HLnRRuCr9rfcJCdqSSLdAs710gtX5TVnq2LcnT8,346
+auth0_ai_langchain/async_authorization/async_authorizer.py,sha256=fS3q2hqefN4ewxyVw-VhuC2DAFeVYcNdIbEjhT0bFs8,799
+auth0_ai_langchain/async_authorization/graph_resumer.py,sha256=mTCcsKiTcxB9QKaS8S4MKJUtXJqY6Y2DLcHrfFKQ7y0,5548
+auth0_ai_langchain/auth0_ai.py,sha256=fnlIJscocm0MRTbcFeNS7Vxy_zOJdSmmMuhjcwYeiDE,4784
+auth0_ai_langchain/fga/__init__.py,sha256=rgqTD4Gvz28jNdqhxTG5udbgyeUMsyvRj83fHBJdt4s,137
+auth0_ai_langchain/token_vault/__init__.py,sha256=Wr4QAAPUcaSDP3wOj46vWsPTSt0SNaHyP5w60wUy5eI,436
+auth0_ai_langchain/token_vault/token_vault_authorizer.py,sha256=KrgXdLFbNtGqELemeT7vjxhH2xj6KuETZzwZ-EkWBFM,1487
+auth0_ai_langchain/utils/interrupt.py,sha256=DZ1b9OAkg3SQru9mSaQGBC6UY0ODz7QSskS9RlVyEGw,860
+auth0_ai_langchain/utils/tool_wrapper.py,sha256=dHjcqykT2aohdFOm0mLZ9U6bXB6NHjfABb3aXef5174,1210
+auth0_ai_langchain-1.0.1.dist-info/LICENSE,sha256=Lu_2YH0oK8b_VVisAhNQ2WIdtwY8pSU2PLbll-y6Cj8,9792
+auth0_ai_langchain-1.0.1.dist-info/METADATA,sha256=3Cb-8K5O8HKnskAGxuXSGEhyK4f2uhC5CWtWe7jzre4,14511
+auth0_ai_langchain-1.0.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+auth0_ai_langchain-1.0.1.dist-info/RECORD,,

auth0_ai_langchain-1.0.1.dist-info/WHEEL

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