bytegrader 0.0.1__tar.gz

bytegrader-0.0.1/.devcontainer.json

@@ -0,0 +1 @@
+{"image":"mcr.microsoft.com/devcontainers/base:ubuntu"}

bytegrader-0.0.1/.dockerignore

@@ -0,0 +1,78 @@
+# Git
+.git
+.gitignore
+.github
+
+# Documentation
+*.md
+!README.md
+docs/
+
+# Tests
+tests/
+*.test.ts
+*.test.py
+*.spec.ts
+pytest.ini
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Development files
+.env
+.env.local
+.env.*.local
+*.log
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+
+# JupyterHub
+jupyterhub.sqlite
+jupyterhub_cookie_secret
+jupyterhub-proxy.pid
+
+# Docker
+docker/keys/
+docker/scripts/*.log
+
+# Temporary files
+*.tmp
+*.temp
+.DS_Store
+Thumbs.db

bytegrader-0.0.1/.gitignore

@@ -0,0 +1,108 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# built labextension
+tsconfig.tsbuildinfo
+bytegrader/extensions/labextension/
+# Yarn cache
+.yarn/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+nbgrader/docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter notebook checkpoints
+.ipynb_checkpoints/
+
+# Coverage files
+.coverage.*
+
+# components stuff
+node_modules
+bytegrader/server_extensions/formgrader/static/components/
+
+conda-bld
+gh_api.sqlite
+MANIFEST
+README
+.pytest_cache
+venv/
+gradebook.db
+.buildconfig
+*~
+.vscode/
+package-lock.json
+.goutputstream*
+.idea
+.mypy_cache
+
+
+# playwright output tests directory
+playwright-tests/
+playwright-report
+test-results
+/test-results/
+/playwright-report/
+/dist-pw/
+
+.pnpm-store/
+
+# Tests
+test/
+test_env/
+testenv/
+
+.venv/
+
+# Docker secrets
+.env
+docker/keys/*.pem
+docker/lti-config/

bytegrader-0.0.1/.npmrc

@@ -0,0 +1,3 @@
+save-exact=true
+engine-strict=false
+legacy-peer-deps=true

bytegrader-0.0.1/.python-version

@@ -0,0 +1 @@
+3.10

bytegrader-0.0.1/.yarnrc

@@ -0,0 +1 @@
+network-timeout 300000

bytegrader-0.0.1/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

bytegrader-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kamuyin
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bytegrader-0.0.1/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: bytegrader
+Version: 0.0.1
+Summary: BYTEGrader - JupyterHub assignment grading service
+License-File: LICENSE
+Keywords: Grading,Homework,Jupyter,JupyterLab,Notebooks
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Framework :: Jupyter :: JupyterLab :: 4
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: apscheduler>=3.11.0
+Requires-Dist: cachetools>=5.0.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: cryptography>=3.4.8
+Requires-Dist: ipython>=8.10.0
+Requires-Dist: ipywidgets>=7.6
+Requires-Dist: jinja2>=3
+Requires-Dist: jupyter-client<9
+Requires-Dist: jupyter-server>=2
+Requires-Dist: jupyterhub-systemdspawner>=1.0.2
+Requires-Dist: jupyterlab-server
+Requires-Dist: jupyterlab<5,>=4.2.0
+Requires-Dist: nbclient>=0.6.1
+Requires-Dist: nbconvert>=6
+Requires-Dist: notebook<8,>=7.2.0
+Requires-Dist: pydantic>=2.11.2
+Requires-Dist: pyjwt
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rapidfuzz>=1.8
+Requires-Dist: requests>=2.26
+Requires-Dist: rich>=14.0.0
+Requires-Dist: setuptools
+Requires-Dist: sqlalchemy<3,>=1.4
+Requires-Dist: tomli>=2.2.1
+Requires-Dist: traitlets>=5.14.3
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-exporter-otlp>=1.26.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-instrumentation-requests>=0.49b0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.49b0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-instrumentation-tornado>=0.49b0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-sdk>=1.26.0; extra == 'opentelemetry'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk>=2.0.0; extra == 'sentry'
+Provides-Extra: systemd
+Requires-Dist: bytegrader-executor-systemd; extra == 'systemd'
+Provides-Extra: wasm-executor
+Requires-Dist: wasmtime>=35.0.0; extra == 'wasm-executor'

bytegrader-0.0.1/README.md

@@ -0,0 +1,175 @@
+# BYTEGrader
+
+BYTE Grader is an autograding service designed for educational environments. It integrates with JupyterHub and Learning Management Systems through LTI 1.3, providing automated grading capabilities for Jupyter notebooks with support for custom test cases and modular execution environments. It's inspired of [nbgrader](https://github.com/jupyter/nbgrader) which is great but lacks support of LMS synchronization and isolated execution environments for the autograding.
+
+## Overview
+
+BYTEGrader consists of two main components:
+
+- **Backend Service**: A Tornado application that provides RESTful APIs for managing courses, assignments, and submissions with automated grading capabilities
+- **JupyterLab Extension**: A TypeScript/React frontend that extends JupyterLab with an interface for instructors and students
+
+The system supports LTI 1.3 integration with platforms like Moodle, allowing grade synchronization and user provisioning through LTI Advantage services (Assignment and Grade Services, Names and Role Provisioning Service).
+
+## Showcase
+
+### Courses
+
+![Courses](docs/public/showcase_courses.png)
+
+### Assignments
+
+![Assignments](docs/public/showcase_assignments.png)
+
+### Create Assignment (Step 1)
+
+![Create assignment step 1](docs/public/showcase_create_1.png)
+
+### Create Assignment (Step 2)
+
+![Create assignment step 2](docs/public/showcase_create_2.png)
+
+### Create Assignment (Step 3)
+
+![Create assignment step 3](docs/public/showcase_create_3.png)
+
+### Graded Submission
+
+![Graded submission](docs/public/showcase_graded.png)
+
+## Key Features
+
+### Assignment Management
+
+- Create and manage programming assignments with multiple notebook files
+- Configure automated tests and grading criteria
+- Set due dates, late submission policies, and point allocations
+- Allow students to fetch solutions for an assignment with conditions.
+
+### Automated Grading
+
+- Execute student submissions in isolated environments
+- Run automated test suites with timeout and resource limits
+- Aggregate scores across multiple notebooks and test cases
+
+### LTI 1.3 Integration
+
+- Secure authentication via LTI launch from LMS platforms
+- Automatic course and user synchronization through NRPS
+- Grade passback to LMS via Assignment and Grade Service (AGS)
+- Support for deep linking and resource selection
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11 or higher
+- Node.js 18 or higher
+- Database (SQLite, PostgreSQL, etc.)
+- JupyterHub
+
+### Setup
+
+1. Install the package
+
+```bash
+uv sync
+uv pip install -e .
+```
+
+2. Set up BYTEGrader configuration
+    Please see [example/bytegrader_config.py](example/bytegrader_config.py) for an example configuration.
+
+3. Add the service to JupyterHub (managed or external)
+
+```python
+c.JupyterHub.services = [
+    {
+        "name": "bytegrader",
+        "api_token": "1442555d6d82d96fc8a69776f19978e442873859c6a003f7be15e61d669e2e1c", # generate via `openssl rand -hex 32`
+        "url": "http://127.0.0.1:10101",
+    }
+]
+```
+
+4. Start the service
+
+```bash
+export JUPYTERHUB_SERVICE_PREFIX="/services/bytegrader/"
+export JUPYTERHUB_API_TOKEN="1442555d6d82d96fc8a69776f19978e442873859c6a003f7be15e61d669e2e1c"
+export JUPYTERHUB_API_URL="http://127.0.0.1:8000/hub/api"
+export JUPYTERHUB_SERVICE_NAME="bytegrader"
+export JUPYTERHUB_SERVICE_URL="http://0.0.0.0:10101"
+export BYTEGRADER_LOG_LEVEL="DEBUG"
+bytegrader serve --config bytegrader_config.py
+```
+
+### Docker Deployment
+
+WIP, currently broken.
+
+## Usage
+
+### For Instructors
+
+1. **Create a Course**: Navigate to the Courses panel in JupyterLab
+2. **Create Assignment Notebooks:**: Notebooks must be created via the `nbgrader` extension. BYTE Grader is compatible with nbgrader's notebooks format.
+3. **Create an Assignment**: Use the assignment wizard to configure:
+   - Notebook and asset files to include
+   - Due dates and late policies
+   - Solution policies
+4. **Distribute to Students**: Assignment notebooks are automatically preprocessed and distributed
+5. **Review Submissions**: View automated grades and provide manual feedback
+
+### For Students
+
+1. **Access Assignments**: Launch JupyterLab via LTI from your LMS
+2. **Fetch Assignment**: Open the assignment and get the starter notebook
+3. **Complete Work**: Write code in designated solution cells
+4. **Submit**: Click submit to send for automated grading
+5. **View Results**: See test results after autograding
+
+## Development
+
+### Building the Extension
+
+```bash
+jlpm build
+```
+
+## Project Structure
+
+```
+bytegrader/
+├── bytegrader/              # Python backend
+│   ├── autograde/          # Grading queue and workers
+│   ├── cli/                # Command-line interface
+│   ├── config/             # Configuration system
+│   ├── core/               # Core models, auth, database
+│   ├── extensions/         # JupyterLab server extension
+│   ├── handlers/           # Tornado request handlers
+│   ├── preprocessors/      # Notebook preprocessors
+│   ├── repositories/       # Data access layer
+│   ├── schemas/            # Pydantic request/response schemas
+│   ├── services/           # Business logic
+│   └── tasks/              # Background tasks
+├── src/                    # TypeScript frontend
+│   ├── components/         # React components
+│   ├── hooks/              # Custom React hooks
+│   ├── services/           # API client
+│   ├── stores/             # State management
+│   └── widgets/            # JupyterLab widgets
+├── docker/                 # Docker configurations
+├── tests/                  # Test suite (TBD)
+└── docs/                   # Documentation (TBD)
+```
+
+## License
+
+This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.
+
+## Acknowledgments
+
+Developed as part of the BYTE Challenge initiative to enhance computer science education for students.
+
+BYTE Grader builds upon the work of the [nbgrader](https://github.com/jupyter/nbgrader) project. The core project architecture, notebook format, preprocessor patterns, and notebook manipulation strategies were inspired by nbgrader's approach. I am grateful to the nbgrader team for providing their software as open source. Without them this project would have never existed.

bytegrader-0.0.1/bytegrader/__init__.py

@@ -0,0 +1,38 @@
+import json
+from pathlib import Path
+from typing import List, Dict
+
+from .extensions.lab import load_jupyter_server_extension as load_lab_extension
+
+__version__ = '0.0.1'
+
+HERE = Path(__file__).parent.resolve()
+
+if not (HERE / "extensions" / "labextension").exists():
+    with (HERE / "extensions" / "labextension" / "package.json").open() as fid:
+        data = json.load(fid)
+
+
+    def _jupyter_labextension_paths():
+        return [{
+            "src": "labextension",
+            "dest": data["name"]
+        }]
+
+
+def _jupyter_server_extension_points() -> List[Dict[str, str]]:
+    return [{
+        "module": "bytegrader",
+    }]
+
+
+def _load_jupyter_server_extension(app):
+    load_lab_extension(app)
+
+
+__all__ = [
+    '__version__',
+    '_jupyter_labextension_paths',
+    '_jupyter_server_extension_points',
+    '_load_jupyter_server_extension',
+]

bytegrader-0.0.1/bytegrader/__main__.py

@@ -0,0 +1,7 @@
+import sys
+
+from .cli.main import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bytegrader-0.0.1/bytegrader/autograde/executors/__init__.py

@@ -0,0 +1,16 @@
+from .simple import SimpleExecutor
+
+__all__ = ["SimpleExecutor"]
+# _all__ = []
+
+try:
+    from .systemd import SystemdExecutor, SystemdExecutorConfig
+    __all__.extend(["SystemdExecutor", "SystemdExecutorConfig"])
+except ImportError:
+    pass
+
+try:
+    from .wasm import WasmExecutor
+    __all__.append("WasmExecutor")
+except ImportError:
+    pass

bytegrader-0.0.1/bytegrader/autograde/executors/base.py

@@ -0,0 +1,15 @@
+from abc import abstractmethod
+
+from nbformat import NotebookNode
+from traitlets.config import LoggingConfigurable
+
+
+class BaseExecutor(LoggingConfigurable):
+
+    @abstractmethod
+    async def execute_cell(self, cell_source, globals_dict=None):
+        pass
+
+    @abstractmethod
+    async def execute_notebook(self, notebook: NotebookNode, cell_ids=None):
+        pass

bytegrader-0.0.1/bytegrader/autograde/executors/simple.py

@@ -0,0 +1,54 @@
+import logging
+import traceback
+from io import StringIO
+from contextlib import redirect_stdout, redirect_stderr
+import nbformat
+from traitlets.config import Configurable
+
+from bytegrader.autograde.executors.base import BaseExecutor
+
+# ! Only for demonstration purposes; must not be used in production due to security risks.
+class SimpleExecutor(BaseExecutor, Configurable):
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.log = logging.getLogger("SimpleExecutor")
+        self.log.info("SimpleExecutor initialized")
+
+    async def execute_cell(self, cell_source, globals_dict=None):
+        buf = StringIO()
+        env = globals_dict if globals_dict is not None else {}
+
+        try:
+            self.log.info(f"Executing cell: {cell_source[:30]}...")
+            with redirect_stdout(buf), redirect_stderr(buf):
+                exec(cell_source, env)
+            return {
+                "success": True,
+                "output": buf.getvalue(),
+                "error": None
+            }
+        except Exception:
+            return {
+                "success": False,
+                "output": buf.getvalue(),
+                "error": {"traceback": traceback.format_exc()}
+            }
+
+    async def execute_notebook(self, notebook: nbformat.NotebookNode, cell_ids=None):
+        nb_id = getattr(notebook, "metadata", {}).get("name", None)
+        total = len(notebook.cells)
+        self.log.info(f"Executing NotebookNode name={nb_id} with {total} cells")
+        results = {}
+        env = {}
+
+        for cell in notebook.cells:
+            cid = getattr(cell, "id", None)
+            if cell.cell_type != "code":
+                continue
+            if cell_ids and cid not in cell_ids:
+                continue
+            res = await self.execute_cell(cell.source, globals_dict=env)
+            results[cid] = res
+
+        return results

bytegrader-0.0.1/bytegrader/autograde/executors/systemd.py

@@ -0,0 +1,3 @@
+from bytegrader_systemd import SystemdExecutor, SystemdExecutorConfig
+
+__all__ = ["SystemdExecutor", "SystemdExecutorConfig"]