LibreChat Python SDK (librechat-python-sdk)

An enterprise-grade, resilient Python client SDK for interacting with LibreChat backend APIs.

Built specifically for long-running daemons, multi-day background processes, and DevOps/GitOps automation pipelines, this SDK handles LibreChat's Refresh Token Rotation (RTR), short-lived JWT expirations, network disconnects during system sleep, and session state persistence across reboots.

---

Key Features

• 🔄 Refresh Token Rotation (RTR) Support: Automatically captures newly rotated refresh tokens returned in Set-Cookie headers and updates active sessions.
• 💾 Multi-Day State Persistence: Saves updated session state to session_tokens.json on disk so long-running scripts survive laptop sleep/wake cycles and system reboots.
• ⏱️ Proactive Expiration Checks: Decodes JWT access token expiration timestamps (exp) and preemptively refreshes tokens before sending API calls.
• ⚡ Network Fault Tolerance: Built-in exponential backoff retries to handle intermittent Wi-Fi drops, sleep mode transitions, and network glitches.
• 🛡️ DevOps & GitOps Ready: Out-of-the-box examples for automated IaC security auditing, continuous folder watching, and CI/CD log analysis.

---

Architecture & Token Lifecycle

LibreChat uses short-lived JWT access tokens (15 minutes) paired with long-lived refresh tokens (7+ days). Whenever a token refresh occurs, LibreChat revokes the old refresh token and issues a new one.

sequenceDiagram
    participant PythonScript as Python Script / Daemon
    participant SDK as LibreChatClient SDK
    participant Disk as Local State File (session_tokens.json)
    participant Server as LibreChat Backend

    PythonScript->>SDK: send_agent_message(prompt)
    SDK->>SDK: Check JWT Expiration (exp timestamp)
    alt Access Token Expired or Missing
        SDK->>Server: POST /api/auth/refresh (with refreshToken cookie)
        Server-->>SDK: 200 OK + New Access Token + New Rotated RefreshToken
        SDK->>Disk: Persist new tokens to session_tokens.json
    end
    SDK->>Server: POST /api/agents/chat/agents (Bearer Access Token)
    Server-->>SDK: HTTP 200 OK (Agent Response Payload)
    SDK-->>PythonScript: Return JSON Response

Loading

---

Installation

Clone the repository and install in editable mode:

git clone https://github.com/your-username/librechat-python-sdk.git
cd librechat-python-sdk
pip install -e .

To include optional DevOps folder monitoring dependencies:

pip install -e .[devops]

---

Quickstart

1. Environment Setup

Create a .env file from the provided template:

cp .env.example .env

Fill in your LibreChat endpoint and browser session cookie:

LIBRECHAT_BASE_URL=https://chat.example.com
LIBRECHAT_REFRESH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
LIBRECHAT_CONNECT_SID=s%3A...

2. Basic Usage

import os
from dotenv import load_dotenv
from librechat_client import LibreChatClient

load_dotenv()

# Initialize resilient client
client = LibreChatClient(
    base_url=os.getenv("LIBRECHAT_BASE_URL"),
    refresh_token=os.getenv("LIBRECHAT_REFRESH_TOKEN"),
    connect_sid=os.getenv("LIBRECHAT_CONNECT_SID")
)

# Send a prompt to the agent endpoint
response = client.send_agent_message(
    prompt="Explain the benefits of Infrastructure-as-Code in DevSecOps."
)

print(response.get("text"))

---

DevOps & GitOps Showcase Examples

The examples/ directory includes real-world automation implementations:

1. GitOps IaC Security Auditor: Monitors a repository directory for Kubernetes YAMLs, Terraform files, and Dockerfiles, submitting changes to LibreChat for automated security compliance auditing.
2. Multi-Day File Monitor Daemon: A background folder watcher service with state tracking (processed_files.json) that survives system reboots and long idle periods.
3. Basic Chat Example: Minimal 15-line quickstart script.

---

Project Structure

librechat-python-sdk/
├── .env.example              # Environment template
├── .gitignore                # Production gitignore rules
├── LICENSE                   # MIT License
├── pyproject.toml            # Python packaging metadata
├── README.md                 # Project documentation
├── requirements.txt          # Package dependencies
├── librechat_client/
│   ├── __init__.py           # SDK package exports
│   ├── client.py             # Core LibreChat API client with RTR & retry logic
│   ├── exceptions.py         # Custom exception hierarchy
│   └── utils.py              # JWT decoding & helper utilities
└── examples/
    ├── basic_chat.py         # Minimal usage script
    ├── devops_iac_auditor/   # GitOps security auditor daemon example
    └── file_monitor/         # Resilient folder monitor daemon example

---

License

This project is licensed under the MIT License.