Metadata-Version: 2.4
Name: librechat-python-sdk
Version: 0.1.0
Summary: A resilient, auto-refreshing Python client SDK for LibreChat API endpoints featuring Refresh Token Rotation (RTR) and multi-day state persistence.
Author: Open Source Developer
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: devops
Requires-Dist: watchdog>=3.0.0; extra == "devops"
Dynamic: license-file

# LibreChat Python SDK (`librechat-python-sdk`)

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An enterprise-grade, resilient Python client SDK for interacting with **[LibreChat](https://github.com/danny-avila/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.

```mermaid
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
```

---

## Installation

Clone the repository and install in editable mode:

```bash
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:

```bash
pip install -e .[devops]
```

---

## Quickstart

### 1. Environment Setup

Create a `.env` file from the provided template:

```bash
cp .env.example .env
```

Fill in your LibreChat endpoint and browser session cookie:

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

### 2. Basic Usage

```python
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/`](examples/) directory includes real-world automation implementations:

1. **[GitOps IaC Security Auditor](examples/gitops_iac_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](examples/file_monitor/)**: A background folder watcher service with state tracking (`processed_files.json`) that survives system reboots and long idle periods.
3. **[Basic Chat Example](examples/basic_chat.py)**: 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](LICENSE).
