Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (48 loc) · 3.17 KB

AGENTS.md

File metadata and controls

65 lines (48 loc) · 3.17 KB
Raw

Agent & Assistant Handoff Guide (AGENTS.md)

This document provides context, architectural design principles, and guidelines for AI agents (Antigravity, Claude Code, Cursor, Windsurf, Copilot, etc.) working on librechat-python-sdk.

1. Repository Purpose

librechat-python-sdk is an open-source, production-ready Python client SDK for LibreChat backend APIs. It is designed specifically for long-running daemons, multi-day background processing, and DevOps/GitOps automation pipelines.

2. Core Architecture & Concepts

Key Authentication Lifecycle:

  • Short-Lived Access Token: JWT Bearer token issued by LibreChat expires in 15 minutes (exp - iat = 900s).
  • Long-Lived Refresh Token: Browser cookie refreshToken valid for 7+ days.
  • Refresh Token Rotation (RTR): Upon calling POST /api/auth/refresh, LibreChat invalidates the old refreshToken and returns a NEW refreshToken in Set-Cookie.
  • State Persistence: LibreChatClient saves active rotated tokens to session_tokens.json (or configured state file) on disk so background daemons survive laptop sleep/wake cycles and system reboots.

3. Directory Layout

librechat-python-sdk/
├── librechat_client/           # Core Python Package
│   ├── __init__.py             # Exports LibreChatClient, exceptions, utils
│   ├── client.py               # Main API client with RTR, retries, and proactive exp check
│   ├── exceptions.py           # Custom exception hierarchy
│   └── utils.py                # JWT decoding & expiration checking
├── examples/                   # Showcase Examples
│   ├── basic_chat.py           # Minimal 15-line client usage
│   ├── gitops_iac_auditor/     # DevSecOps IaC security reviewer daemon
│   └── file_monitor/           # Continuous folder watcher daemon
├── pyproject.toml              # Build & packaging configuration (PEP 621)
├── requirements.txt            # Main dependencies
├── .env.example                # Environment variable template
├── README.md                   # Main GitHub documentation
└── AGENTS.md                   # AI Agent & Handoff Guide

4. Development & Build Instructions

Installation for Local Development:

pip install -e .[devops]

Building Distribution Packages:

pip install build twine
python3 -m build

(Build artifacts are output to ./dist/librechat_python_sdk-0.1.0-py3-none-any.whl and .tar.gz)

5. Guidelines for Future Agentic Sessions

  1. Privacy & Anonymization Rule: NEVER commit real personal or company credentials, emails, domains, or bearer tokens to this repository. Always use generic placeholders (https://chat.example.com, YOUR_REFRESH_TOKEN_HERE).
  2. Pure Python Compatibility: Maintain compatibility across Python 3.8 to 3.14+. Do not introduce OS-specific C extensions unless isolated behind optional dependencies.
  3. Token Rotation Guard: When modifying librechat_client/client.py, ensure that _save_state() is always triggered whenever a new rotated refreshToken is received from the server.