langchain-google-classroom 0.1.0__tar.gz

langchain_google_classroom-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug Report
+about: Report a bug in langchain-google-classroom
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Description
+A clear description of the bug.
+
+## Steps to Reproduce
+1. ...
+2. ...
+
+## Expected Behavior
+What you expected to happen.
+
+## Actual Behavior
+What actually happened. Include error traceback if applicable.
+
+## Environment
+- Python version:
+- langchain-google-classroom version:
+- OS:

langchain_google_classroom-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest a new feature
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+## Description
+A clear description of the feature you'd like.
+
+## Use Case
+Why this feature would be useful. What problem does it solve?
+
+## Proposed API
+```python
+# How you'd expect to use this feature
+```

langchain_google_classroom-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[lint]"
+      - name: Lint with ruff
+        run: ruff check langchain_google_classroom/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/unit/ -v --tb=short

langchain_google_classroom-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Credentials (never commit)
+token.json
+credentials.json
+service_account.json
+*.json.bak

langchain_google_classroom-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-03-13
+
+### Added
+
+- **`GoogleClassroomLoader`** — LangChain `BaseLoader` for Google Classroom.
+  - Loads assignments (courseWork), announcements, and course materials.
+  - Selective loading via `load_assignments`, `load_announcements`, `load_materials` flags.
+  - Multi-course support with `course_ids` filter.
+- **Drive attachment resolution** via `DriveAttachmentResolver`.
+  - Google-native files (Docs, Slides, Sheets) exported as plain text / CSV.
+  - Binary files (PDF, DOCX, etc.) downloaded via streaming.
+  - Controlled by `load_attachments` and `parse_attachments` flags.
+- **File parser layer** using LangChain's `BaseBlobParser` + `Blob` interface.
+  - `PDFParser` (pypdf), `DocxParser` (python-docx), `TextParser` (built-in),
+    `ImageParser` (vision LLM).
+  - MIME-type registry with `get_parser()` factory function.
+  - `file_parser_cls` param for user-pluggable parsers (e.g. `PyMuPDFParser`).
+- **Vision LLM image description** for images embedded in PDFs and standalone
+  image attachments.  Pass a `vision_model` (e.g. Gemini, GPT-4V) to get
+  automatic image descriptions appended to page text.
+- **Retry / backoff** via `execute_with_retry()` on all Google API calls.
+  - Exponential backoff with jitter on HTTP 429, 500, 503.
+- **Authentication** support for service accounts, cached OAuth tokens, and interactive
+  OAuth flow.
+- **Text normalizer** — NFC, line ending cleanup, null byte removal.
+- **`Document` metadata** — rich metadata including course info, timestamps, due dates,
+  links, and parent item references for attachments.
+- **Project packaging** — `pyproject.toml` with hatchling, optional dependency groups
+  (`[parsers]`, `[test]`, `[lint]`, `[typing]`, `[dev]`), PEP 561 `py.typed` marker.
+- **92 unit tests** covering all modules with 100% pass rate.

langchain_google_classroom-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to langchain-google-classroom
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ayanokojix21/langchain-google-classroom.git
+cd langchain-google-classroom
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# .venv\Scripts\activate   # Windows
+
+# Install in development mode
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+# Run all unit tests
+pytest tests/unit/ -v
+
+# Run a specific test file
+pytest tests/unit/test_parsers.py -v
+
+# Run with coverage
+pytest tests/unit/ --cov=langchain_google_classroom --cov-report=term-missing
+```
+
+## Linting
+
+```bash
+# Check for lint errors
+ruff check langchain_google_classroom/ tests/
+
+# Auto-fix issues
+ruff check langchain_google_classroom/ tests/ --fix
+```
+
+## Code Style
+
+This project follows LangChain coding conventions:
+
+- **Type annotations** on all functions and methods
+- **Docstrings** in Google/NumPy style on all public functions
+- **`from __future__ import annotations`** at the top of every module
+- **`guard_import`** for optional dependencies (pypdf, python-docx)
+- **`BaseBlobParser` + `Blob`** interface for all file parsers
+- **`BaseLoader.lazy_load()`** as the main entry point
+
+## Adding a New Parser
+
+1. Create `langchain_google_classroom/parsers/your_parser.py`
+2. Implement `BaseBlobParser.lazy_parse(blob)` → `Iterator[Document]`
+3. Add the MIME type mapping in `parsers/__init__.py`
+4. Add tests in `tests/unit/test_parsers.py`
+5. Run `pytest` and `ruff check`
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes with tests
+4. Run `pytest tests/unit/ -v` and `ruff check`
+5. Commit with a descriptive message
+6. Push and open a Pull Request
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/ayanokojix21/langchain-google-classroom/issues) with:
+
+- **Bug reports**: Include Python version, error traceback, and steps to reproduce
+- **Feature requests**: Describe the use case and proposed API

langchain_google_classroom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nishchal Chandel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_google_classroom-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: langchain-google-classroom
+Version: 0.1.0
+Summary: An integration package connecting Google Classroom and LangChain
+Project-URL: Homepage, https://github.com/ayanokojix21/langchain-google-classroom
+Project-URL: Source, https://github.com/ayanokojix21/langchain-google-classroom
+Project-URL: Documentation, https://github.com/ayanokojix21/langchain-google-classroom#readme
+Author: Nishchal Chandel
+License: MIT
+License-File: LICENSE
+Keywords: document-loader,education,google-classroom,langchain,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: google-api-python-client<3.0.0,>=2.100.0
+Requires-Dist: google-auth-httplib2<1.0.0,>=0.2.0
+Requires-Dist: google-auth-oauthlib<2.0.0,>=1.2.0
+Requires-Dist: google-auth<3.0.0,>=2.25.0
+Requires-Dist: langchain-core<1.0.0,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: mypy<2.0.0,>=1.10.0; extra == 'dev'
+Requires-Dist: pypdf<5.0.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock<4.0.0,>=3.10.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=7.3.0; extra == 'dev'
+Requires-Dist: python-docx<2.0.0,>=1.0.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.5.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff<1,>=0.5.0; extra == 'lint'
+Provides-Extra: parsers
+Requires-Dist: pypdf<5.0.0,>=4.0.0; extra == 'parsers'
+Requires-Dist: python-docx<2.0.0,>=1.0.0; extra == 'parsers'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio<2.0.0,>=0.21.1; extra == 'test'
+Requires-Dist: pytest-mock<4.0.0,>=3.10.0; extra == 'test'
+Requires-Dist: pytest-socket<1.0.0,>=0.7.0; extra == 'test'
+Requires-Dist: pytest<10.0.0,>=7.3.0; extra == 'test'
+Provides-Extra: typing
+Requires-Dist: mypy<2.0.0,>=1.10.0; extra == 'typing'
+Description-Content-Type: text/markdown
+
+# 🎓 langchain-google-classroom
+
+[![CI](https://github.com/ayanokojix21/langchain-google-classroom/actions/workflows/ci.yml/badge.svg)](https://github.com/ayanokojix21/langchain-google-classroom/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/langchain-google-classroom.svg)](https://pypi.org/project/langchain-google-classroom/)
+[![Python](https://img.shields.io/pypi/pyversions/langchain-google-classroom.svg)](https://pypi.org/project/langchain-google-classroom/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A **LangChain** integration package that loads Google Classroom content — assignments, announcements, course materials, and Drive attachments — as `Document` objects for RAG pipelines, semantic search, AI teaching assistants, and course chatbots.
+
+## ✨ Features
+
+- **Full Classroom coverage** — assignments, announcements, and course materials
+- **Drive attachments** — auto-download and parse PDF, DOCX, text, CSV, HTML files
+- **Vision LLM image description** — embedded PDF images described by Gemini/GPT-4V
+- **Pluggable parsers** — bring your own `BaseBlobParser` (PyMuPDF, Unstructured, etc.)
+- **Retry/backoff** — exponential backoff with jitter on rate-limited API calls
+- **Flexible auth** — service accounts, OAuth, cached tokens, or pre-built credentials
+- **Rich metadata** — course info, timestamps, due dates, links on every Document
+- **Lazy loading** — memory-efficient streaming via `lazy_load()`
+
+## 📦 Installation
+
+```bash
+pip install langchain-google-classroom
+```
+
+With file attachment parsing (PDF, DOCX):
+
+```bash
+pip install langchain-google-classroom[parsers]
+```
+
+## 🚀 Quickstart
+
+```python
+from langchain_google_classroom import GoogleClassroomLoader
+
+# Load all accessible courses
+loader = GoogleClassroomLoader()
+docs = loader.load()
+
+for doc in docs:
+    print(doc.metadata["content_type"], "—", doc.metadata["title"])
+    print(doc.page_content[:200])
+    print()
+```
+
+## 🔐 Authentication
+
+### Service Account (recommended for production)
+
+```python
+loader = GoogleClassroomLoader(
+    service_account_file="service_account.json",
+)
+```
+
+### OAuth User Credentials
+
+```python
+loader = GoogleClassroomLoader(
+    client_secrets_file="credentials.json",
+    token_file="token.json",
+)
+```
+
+### Pre-built Credentials
+
+```python
+from google.oauth2 import service_account
+
+creds = service_account.Credentials.from_service_account_file(
+    "service_account.json",
+    scopes=["https://www.googleapis.com/auth/classroom.courses.readonly"],
+)
+loader = GoogleClassroomLoader(credentials=creds)
+```
+
+## 📎 Attachments & File Parsing
+
+```python
+loader = GoogleClassroomLoader(
+    course_ids=["123456789"],
+    load_attachments=True,      # Download Drive files
+    parse_attachments=True,     # Parse with BaseBlobParser
+)
+docs = loader.load()
+# Yields: assignment docs + parsed PDF/DOCX/text attachment docs
+```
+
+### Custom Parser
+
+```python
+from langchain_community.document_loaders.parsers.pdf import PyMuPDFParser
+
+loader = GoogleClassroomLoader(
+    course_ids=["123456789"],
+    file_parser_cls=PyMuPDFParser,
+)
+```
+
+## 🖼️ Vision LLM — Image Description
+
+Extract and describe images embedded in PDFs using any vision-capable LLM:
+
+```python
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+loader = GoogleClassroomLoader(
+    course_ids=["123456789"],
+    load_attachments=True,
+    vision_model=ChatGoogleGenerativeAI(model="gemini-2.0-flash"),
+)
+docs = loader.load()
+# PDF pages now include: "[Image: chart.png]\nA bar chart showing student grades..."
+```
+
+## 🎯 Selective Loading
+
+```python
+loader = GoogleClassroomLoader(
+    course_ids=["123456789"],
+    load_assignments=True,
+    load_announcements=False,
+    load_materials=False,
+    load_attachments=False,
+)
+```
+
+## 📄 Document Structure
+
+Each document includes rich metadata:
+
+```python
+Document(
+    page_content="Assignment: Homework 3\n\nComplete exercises 1-5...",
+    metadata={
+        "source": "google_classroom",
+        "course_id": "12345",
+        "course_name": "Machine Learning",
+        "content_type": "assignment",        # or "announcement", "material", "assignment_attachment"
+        "title": "Homework 3",
+        "item_id": "67890",
+        "created_time": "2024-01-15T10:00:00Z",
+        "updated_time": "2024-01-15T10:00:00Z",
+        "due_date": "2024-01-22T23:59:00",   # assignments only
+        "max_points": 100.0,                  # assignments only
+        "alternate_link": "https://classroom.google.com/...",
+    }
+)
+```
+
+## ⚙️ Configuration Reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `course_ids` | `list[str]` | `None` | Specific course IDs (`None` = all accessible) |
+| `load_assignments` | `bool` | `True` | Load courseWork items |
+| `load_announcements` | `bool` | `True` | Load announcements |
+| `load_materials` | `bool` | `True` | Load courseWorkMaterials |
+| `load_attachments` | `bool` | `True` | Download and process Drive attachments |
+| `parse_attachments` | `bool` | `True` | Parse files with BaseBlobParser |
+| `load_images` | `bool` | `False` | Process image MIME types |
+| `vision_model` | `BaseChatModel` | `None` | Vision LLM for image description |
+| `image_prompt` | `str` | `None` | Custom prompt for vision model |
+| `file_parser_cls` | `type[BaseBlobParser]` | `None` | Custom parser for all attachments |
+| `file_parser_kwargs` | `dict` | `None` | kwargs for custom parser |
+| `credentials` | `Credentials` | `None` | Pre-built Google credentials |
+| `service_account_file` | `str` | `None` | Service account key JSON path |
+| `token_file` | `str` | `None` | Cached OAuth token path |
+| `client_secrets_file` | `str` | `None` | OAuth client secrets path |
+| `scopes` | `list[str]` | Read-only | API scopes to request |
+
+## 🏗️ Architecture
+
+```
+GoogleClassroomLoader (BaseLoader)
+├── _utilities.py         — auth, retry/backoff, guard_import
+├── classroom_api.py      — paginated Classroom API fetcher
+├── document_builder.py   — raw API → LangChain Document
+├── drive_resolver.py     — Drive download/export
+├── normalizer.py         — text cleanup (Unicode NFC, whitespace)
+└── parsers/
+    ├── __init__.py       — MIME registry + get_parser()
+    ├── pdf_parser.py     — pypdf + vision LLM
+    ├── docx_parser.py    — python-docx
+    ├── text_parser.py    — built-in UTF-8
+    └── image_parser.py   — vision LLM + base64 fallback
+```
+
+## 🧪 Development
+
+```bash
+# Clone and install
+git clone https://github.com/ayanokojix21/langchain-google-classroom.git
+cd langchain-google-classroom
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/ -v
+
+# Lint
+ruff check langchain_google_classroom/ tests/
+```
+
+## 📝 License
+
+MIT — see [LICENSE](LICENSE) for details.