github/langchain
1
0
Fork 0
mirror of https://github.com/hwchase17/langchain.git synced 2025-08-18 09:01:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

[Integration]: Langchain-Permit (#29867)

Browse Source 
## Which area of LangChain is being modified?
- This PR adds a new "Permit" integration to the `docs/integrations/`
folder.
- Introduces two new Tools (`LangchainJWTValidationTool` and
`LangchainPermissionsCheckTool`)
- Introduces two new Retrievers (`PermitSelfQueryRetriever` and
`PermitEnsembleRetriever`)
- Adds demo scripts in `examples/` showcasing usage.

## Description of Changes
- Created `langchain_permit/tools.py` for JWT validation and permission
checks with Permit.
- Created `langchain_permit/retrievers.py` for custom Permit-based
retrievers.
- Added documentation in `docs/integrations/providers/permit.ipynb` (or
`.mdx`) to explain setup, usage, and examples.
- Provided sample scripts in `examples/demo_scripts/` to illustrate
usage of these tools and retrievers.
- Ensured all code is linted and tested locally.

Thank you again for reviewing!

---------

Co-authored-by: Chester Curme <chester.curme@gmail.com>
This commit is contained in:
Taofiq Aiyelabegan 2025-02-21 16:59:00 +01:00 committed by GitHub
parent ebe38baaf9
commit 5ee8a8f063
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 647 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/docs/integrations/providers/permit.mdx Normal file
View File

@ -0,0 +1,31 @@
# Permit
[Permit.io](https://permit.io/) offers fine-grained access control and policy
enforcement. With LangChain, you can integrate Permit checks to ensure only authorized
users can access or retrieve data in your LLM applications.
## Installation and Setup
```bash
pip install langchain-permit
pip install permit
```
Set environment variables for your Permit PDP and credentials:
```python
export PERMIT_API_KEY="your_permit_api_key"
export PERMIT_PDP_URL="http://localhost:7766" # or your real PDP endpoint
```
Make sure your PDP is running and configured. See
[Permit Docs](https://docs.permit.io/sdk/python/quickstart-python/#2-setup-your-pdp-policy-decision-point-container)
for policy setup.
## Tools
See detail on available tools [here](/docs/integrations/tools/permit).
## Retrievers
See detail on available retrievers [here](/docs/integrations/retrievers/permit).

330
docs/docs/integrations/retrievers/permit.ipynb Normal file
View File

@ -0,0 +1,330 @@
{
"cells": [
{
"cell_type": "raw",
"id": "afaf8039",
"metadata": {},
"source": [
"---\n",
"sidebar_label: Permit\n",
"---"
]
},
{
"cell_type": "markdown",
"id": "e49f1e0d",
"metadata": {},
"source": [
"# PermitRetriever\n",
"\n",
"Permit is an access control platform that provides fine-grained, real-time permission management using various models such as RBAC, ABAC, and ReBAC. It enables organizations to enforce dynamic policies across their applications, ensuring that only authorized users can access specific resources.\n",
"\n",
"### Integration details\n",
"\n",
"This notebook illustrates how to integrate [Permit.io](https://permit.io/) permissions into LangChain retrievers.\n",
"\n",
"We provide two custom retrievers:\n",
"\n",
"- PermitSelfQueryRetriever – Uses a self-query approach to parse the user’s natural-language prompt, fetch the user’s permitted resource IDs from Permit, and apply that filter automatically in a vector store search. \n",
" \n",
"- PermitEnsembleRetriever – Combines multiple underlying retrievers (e.g., BM25 + Vector) via LangChain’s EnsembleRetriever, then filters the merged results with Permit.io.\n",
"\n",
"## Setup\n",
"\n",
"Install the package with the command:\n",
"\n",
"```bash\n",
"pip install langchain-permit\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "72ee0c4b-9764-423a-9dbf-95129e185210",
"metadata": {},
"source": [
"If you want to get automated tracing from individual queries, you can also set your [LangSmith](https://docs.smith.langchain.com/) API key by uncommenting below:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a15d341e-3e26-4ca3-830b-5aab30ed66de",
"metadata": {},
"outputs": [],
"source": [
"# os.environ[\"LANGSMITH_API_KEY\"] = getpass.getpass(\"Enter your LangSmith API key: \")\n",
"# os.environ[\"LANGSMITH_TRACING\"] = \"true\""
]
},
{
"cell_type": "markdown",
"id": "0730d6a1-c893-4840-9817-5e5251676d5d",
"metadata": {},
"source": [
"### Installation\n",
"\n",
"```bash\n",
"pip install langchain-permit\n",
"```\n",
"\n",
"#### Environment Variables\n",
"\n",
"```bash\n",
"PERMIT_API_KEY=your_api_key\n",
"PERMIT_PDP_URL= # or your real deployment\n",
"OPENAI_API_KEY=sk-...\n",
"```\n",
"- A running Permit PDP. See [Permit docs](https://docs.permit.io/) for details on setting up your policy and container.\n",
"- A vector store or multiple retrievers that we can wrap."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "652d6238-1f87-422a-b135-f5abbb8652fc",
"metadata": {},
"outputs": [],
"source": [
"%pip install -qU langchain-permit"
]
},
{
"cell_type": "markdown",
"id": "a38cde65-254d-4219-a441-068766c0d4b5",
"metadata": {},
"source": [
"## Instantiation\n",
"\n",
"### PermitSelfQueryRetriever\n",
"\n",
"#### Basic Explanation\n",
"\n",
"1. Retrieves permitted document IDs from Permit. \n",
"\n",
"2. Uses an LLM to parse your query and build a “structured filter,” ensuring only docs with those permitted IDs are considered.\n",
"\n",
"#### Basic Usage\n",
"\n",
"```python\n",
"from langchain_openai import OpenAIEmbeddings\n",
"from langchain_community.vectorstores import FAISS\n",
"from langchain_permit.retrievers import PermitSelfQueryRetriever\n",
"\n",
"# Step 1: Create / load some documents and build a vector store\n",
"docs = [...]\n",
"embeddings = OpenAIEmbeddings()\n",
"vectorstore = FAISS.from_documents(docs, embeddings)\n",
"\n",
"# Step 2: Initialize the retriever\n",
"retriever = PermitSelfQueryRetriever(\n",
" api_key=\"...\",\n",
" pdp_url=\"...\",\n",
" user={\"key\": \"user-123\"},\n",
" resource_type=\"document\",\n",
" action=\"read\",\n",
" llm=..., # Typically a ChatOpenAI or other LLM\n",
" vectorstore=vectorstore,\n",
" enable_limit=True, # optional\n",
")\n",
"\n",
"# Step 3: Query\n",
"query = \"Give me docs about cats\"\n",
"results = retriever.get_relevant_documents(query)\n",
"for doc in results:\n",
" print(doc.metadata.get(\"id\"), doc.page_content)\n",
"```\n",
"\n",
"### PermitEnsembleRetriever\n",
"\n",
"#### Basic Explanation\n",
"\n",
"1. Uses LangChain’s EnsembleRetriever to gather documents from multiple sub-retrievers (e.g., vector-based, BM25, etc.).\n",
"2. After retrieving documents, it calls filter_objects on Permit to eliminate any docs the user isn’t allowed to see.\n",
"\n",
"#### Basic Usage\n",
"\n",
"```python\n",
"from langchain_community.retrievers import BM25Retriever\n",
"from langchain_core.documents import Document\n",
"from langchain_permit.retrievers import PermitEnsembleRetriever\n",
"\n",
"# Suppose we have two child retrievers: bm25_retriever, vector_retriever\n",
"...\n",
"ensemble_retriever = PermitEnsembleRetriever(\n",
" api_key=\"...\",\n",
" pdp_url=\"...\",\n",
" user=\"user_abc\",\n",
" action=\"read\",\n",
" resource_type=\"document\",\n",
" retrievers=[bm25_retriever, vector_retriever],\n",
" weights=None\n",
")\n",
"\n",
"docs = ensemble_retriever.get_relevant_documents(\"Query about cats\")\n",
"for doc in docs:\n",
" print(doc.metadata.get(\"id\"), doc.page_content)\n",
"```\n",
"\n",
"### Demo Scripts\n",
"\n",
"For more complete demos, check out the `/langchain_permit/examples/demo_scripts` folder:\n",
"\n",
"1. demo_self_query.py – Demonstrates PermitSelfQueryRetriever.\n",
"2. demo_ensemble.py – Demonstrates PermitEnsembleRetriever.\n",
"\n",
"Each script shows how to build or load documents, configure Permit, and run queries.\n",
"\n",
"### Conclusion\n",
"\n",
"With these custom retrievers, you can seamlessly integrate Permit.io’s permission checks into LangChain’s retrieval workflow. You can keep your application’s vector search logic while ensuring only authorized documents are returned.\n",
"\n",
"For more details on setting up Permit policies, see the official Permit docs. If you want to combine these with other tools (like JWT validation or a broader RAG pipeline), check out our docs/tools.ipynb in the examples folder."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "70cc8e65-2a02-408a-bbc6-8ef649057d82",
"metadata": {},
"outputs": [],
"source": [
"from langchain_permit import PermitRetriever\n",
"\n",
"retriever = PermitRetriever(\n",
" # ...\n",
")"
]
},
{
"cell_type": "markdown",
"id": "5c5f2839-4020-424e-9fc9-07777eede442",
"metadata": {},
"source": [
"## Usage"
]
},
{
"cell_type": "markdown",
"id": "c70ae8ab",
"metadata": {},
"source": []
},
{
"cell_type": "code",
"execution_count": null,
"id": "51a60dbe-9f2e-4e04-bb62-23968f17164a",
"metadata": {},
"outputs": [],
"source": [
"query = \"...\"\n",
"\n",
"retriever.invoke(query)"
]
},
{
"cell_type": "markdown",
"id": "dfe8aad4-8626-4330-98a9-7ea1ca5d2e0e",
"metadata": {},
"source": [
"## Use within a chain\n",
"\n",
"Like other retrievers, PermitRetriever can be incorporated into LLM applications via [chains](https://docs.permit.io/).\n",
"\n",
"We will need a LLM or chat model:\n",
"\n",
"import ChatModelTabs from \"@theme/ChatModelTabs\";\n",
"\n",
"<ChatModelTabs customVarName=\"llm\" />"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "25b647a3-f8f2-4541-a289-7a241e43f9df",
"metadata": {},
"outputs": [],
"source": [
"# | output: false\n",
"# | echo: false\n",
"\n",
"from langchain_openai import ChatOpenAI\n",
"\n",
"llm = ChatOpenAI(model=\"gpt-3.5-turbo-0125\", temperature=0)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "23e11cc9-abd6-4855-a7eb-799f45ca01ae",
"metadata": {},
"outputs": [],
"source": [
"from langchain_core.output_parsers import StrOutputParser\n",
"from langchain_core.prompts import ChatPromptTemplate\n",
"from langchain_core.runnables import RunnablePassthrough\n",
"\n",
"prompt = ChatPromptTemplate.from_template(\n",
" \"\"\"Answer the question based only on the context provided.\n",
"\n",
"Context: {context}\n",
"\n",
"Question: {question}\"\"\"\n",
")\n",
"\n",
"\n",
"def format_docs(docs):\n",
" return \"\\n\\n\".join(doc.page_content for doc in docs)\n",
"\n",
"\n",
"chain = (\n",
" {\"context\": retriever | format_docs, \"question\": RunnablePassthrough()}\n",
" | prompt\n",
" | llm\n",
" | StrOutputParser()\n",
")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d47c37dd-5c11-416c-a3b6-bec413cd70e8",
"metadata": {},
"outputs": [],
"source": [
"chain.invoke(\"...\")"
]
},
{
"cell_type": "markdown",
"id": "3a5bb5ca-c3ae-4a58-be67-2cd18574b9a3",
"metadata": {},
"source": [
"## API reference\n",
"\n",
"For detailed documentation of all PermitRetriever features and configurations head to the [Repo](https://github.com/permitio/langchain-permit/tree/master/langchain_permit/examples/demo_scripts)."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.4"
}
},
"nbformat": 4,
"nbformat_minor": 5
}

283
docs/docs/integrations/tools/permit.ipynb Normal file
View File

@ -0,0 +1,283 @@
{
"cells": [
{
"cell_type": "raw",
"id": "10238e62-3465-4973-9279-606cbb7ccf16",
"metadata": {},
"source": [
"---\n",
"sidebar_label: Permit\n",
"---"
]
},
{
"cell_type": "markdown",
"id": "a6f91f20",
"metadata": {},
"source": [
"# Permit\n",
"\n",
"Permit is an access control platform that provides fine-grained, real-time permission management using various models such as RBAC, ABAC, and ReBAC. It enables organizations to enforce dynamic policies across their applications, ensuring that only authorized users can access specific resources.\n",
"\n",
"## Overview\n",
"\n",
"This package provides two Langchain tools for JWT validation and permission checking using Permit:\n",
"\n",
"* LangchainJWTValidationTool: Validates JWT tokens against a JWKS endpoint\n",
"\n",
"* LangchainPermissionsCheckTool: Checks user permissions using Permit\n",
"\n",
"\n",
"## Setup\n",
"\n",
"Set up the following environment variables:\n",
"\n",
"```bash\n",
"PERMIT_API_KEY=your_permit_api_key\n",
"JWKS_URL=your_jwks_endpoint_url\n",
"PERMIT_PDP_URL=your_permit_pdp_url # Usually http://localhost:7766 for local development or your real deployment\n",
"```\n",
"\n",
"Make sure your PDP (Policy Decision Point) is running at PERMIT_PDP_URL.\n",
"See [Permit docs](https://docs.permit.io/concepts/pdp/overview/) for details on policy setup and how to launch the PDP container."
]
},
{
"cell_type": "markdown",
"id": "b15e9266",
"metadata": {},
"source": [
"### Credentials\n",
"\n",
"```bash\n",
"PERMIT_API_KEY=\n",
"JWKS_URL=your_jwks_endpoint_url # or your deployed url\n",
"PERMIT_PDP_URL=your_pdp_url # or your deployed url\n",
"TEST_JWT_TOKEN= # for quick test purposes\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "bc5ab717-fd27-4c59-b912-bdd099541478",
"metadata": {},
"source": [
"It's also helpful (but not needed) to set up [LangSmith](https://smith.langchain.com/) for best-in-class observability:"
]
},
{
"cell_type": "markdown",
"id": "1c97218f-f366-479d-8bf7-fe9f2f6df73f",
"metadata": {},
"source": [
"## Instantiation\n",
"\n",
"### JWT Validation Tool\n",
"The JWT Validation tool verifies JWT tokens against a JWKS (JSON Web Key Set) endpoint.\n",
"\n",
"```python\n",
"from langchain_permit.tools import LangchainJWTValidationTool\n",
"\n",
"# Initialize the tool\n",
"jwt_validator = LangchainJWTValidationTool(\n",
" jwks_url=#your url endpoint\n",
")\n",
"```\n",
"\n",
"### Configuration Options\n",
"You can initialize the tool with either:\n",
"\n",
"* A JWKS URL\n",
"* Direct JWKS JSON data\n",
"* Environment variable (JWKS_URL)\n",
"\n",
"```python\n",
"# Using direct JWKS JSON\n",
"jwt_validator = LangchainJWTValidationTool(\n",
" jwks_json={\n",
" \"keys\": [\n",
" {\n",
" \"kid\": \"key-id\",\n",
" \"kty\": \"RSA\",\n",
" ...\n",
" }\n",
" ]\n",
" }\n",
")\n",
"```\n",
"\n",
"### Permissions Check Tool\n",
"The Permissions Check tool integrates with Permit.io to verify user permissions against resources.\n",
"\n",
"```python\n",
"from permit import Permit\n",
"from langchain_permit.tools import LangchainPermissionsCheckTool\n",
"\n",
"# Initialize Permit client\n",
"permit_client = Permit(\n",
" token=\"your_permit_api_key\",\n",
" pdp=# Your PDP URL\n",
")\n",
"\n",
"# Initialize the tool\n",
"permissions_checker = LangchainPermissionsCheckTool(\n",
" permit=permit_client\n",
")\n",
"```\n",
"\n",
"This documentation demonstrates the key features and usage patterns of both tools."
]
},
{
"cell_type": "markdown",
"id": "74147a1a",
"metadata": {},
"source": [
"## Invocation\n",
"\n",
"### [Invoke directly with args](https://docs.permit.io/)\n",
"\n",
"### JWT Validation Tool\n",
"\n",
"```python\n",
"# Validate a token\n",
"async def validate_token():\n",
" claims = await jwt_validator._arun(\n",
" \"...\" # Your JWT token\n",
" )\n",
" print(\"Validated Claims:\", claims)\n",
"```\n",
"\n",
"### Permissions Check Tool\n",
"\n",
"```python\n",
"# Check permissions\n",
"async def check_user_permission():\n",
" result = await permissions_checker._arun(\n",
" user={\n",
" \"key\": \"user-123\",\n",
" \"firstName\": \"John\"\n",
" },\n",
" action=\"read\",\n",
" resource={\n",
" \"type\": \"Document\",\n",
" \"tenant\": \"default\"\n",
" }\n",
" )\n",
" print(\"Permission granted:\", result)\n",
"```\n",
"\n",
"#### Input Formats\n",
"The permissions checker accepts different input formats:\n",
"\n",
"1. Simple string for user (converts to user key):\n",
"\n",
"```python\n",
"result = await permissions_checker._arun(\n",
" user=\"user-123\",\n",
" action=\"read\",\n",
" resource=\"Document\"\n",
")\n",
"```\n",
"\n",
"2. Full user object:\n",
"\n",
"```python\n",
"result = await permissions_checker._arun(\n",
" user={\n",
" \"key\": \"user-123\",\n",
" \"firstName\": \"John\",\n",
" \"lastName\": \"Doe\",\n",
" \"email\": \"john@example.com\",\n",
" \"attributes\": {\"department\": \"IT\"}\n",
" },\n",
" action=\"read\",\n",
" resource={\n",
" \"type\": \"Document\",\n",
" \"key\": \"doc-123\",\n",
" \"tenant\": \"techcorp\",\n",
" \"attributes\": {\"confidentiality\": \"high\"}\n",
" }\n",
")\n",
"```\n"
]
},
{
"cell_type": "markdown",
"id": "d6e73897",
"metadata": {},
"source": [
"### [Invoke with ToolCall](https://docs.permit.io/)\n",
"\n",
"(TODO)"
]
},
{
"cell_type": "markdown",
"id": "659f9fbd-6fcf-445f-aa8c-72d8e60154bd",
"metadata": {},
"source": [
"## Chaining\n",
"\n",
"- TODO: Add user question and run cells\n",
"\n",
"We can use our tool in a chain by first binding it to a [tool-calling model](https://docs.permit.io/) and then calling it:\n",
"\n",
"import ChatModelTabs from \"@theme/ChatModelTabs\";\n",
"\n",
"<ChatModelTabs customVarName=\"llm\" />\n"
]
},
{
"cell_type": "markdown",
"id": "c1306ac4",
"metadata": {
"vscode": {
"languageId": "raw"
}
},
"source": [
"### Additional Demo Scripts\n",
"\n",
"For fully runnable demos, check out the `/langchain_permit/examples/demo_scripts` folder in this [repository](https://github.com/permitio/langchain-permit). You’ll find:\n",
"\n",
"* demo_jwt_validation.py – A quick script showing how to validate JWTs using LangchainJWTValidationTool.\n",
"\n",
"* demo_permissions_check.py – A script that performs Permit.io permission checks using LangchainPermissionsCheckTool.\n",
"\n",
"Just run `python demo_jwt_validation.py` or `python demo_permissions_check.py` (after setting your environment variables) to see these tools in action."
]
},
{
"cell_type": "markdown",
"id": "4ac8146c",
"metadata": {},
"source": [
"## API reference\n",
"\n",
"For detailed documentation of all Permit features and configurations head to the API reference: https://docs.permit.io/"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "poetry-venv-311",
"language": "python",
"name": "poetry-venv-311"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.9"
}
},
"nbformat": 4,
"nbformat_minor": 5
}

3
libs/packages.yml
View File

@ -459,3 +459,6 @@ packages:
repo: apisani1/langchain-prolog repo: apisani1/langchain-prolog
downloads: 0 downloads: 0
downloads_updated_at: '2025-02-15T16:00:00.000000+00:00' downloads_updated_at: '2025-02-15T16:00:00.000000+00:00'
- name: langchain-permit
path: .
repo: permitio/langchain-permit