{"id":42217197,"url":"https://github.com/maremun/nlabot","last_synced_at":"2026-01-27T01:17:05.409Z","repository":{"id":26600586,"uuid":"105476371","full_name":"maremun/nlabot","owner":"maremun","description":"Telegram bot for checking homework.","archived":false,"fork":false,"pushed_at":"2022-12-08T01:13:42.000Z","size":83,"stargazers_count":6,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-19T08:24:18.328Z","etag":null,"topics":["bot","docker","docker-compose","edu","education","grading","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maremun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-01T21:39:01.000Z","updated_at":"2018-11-07T08:20:43.000Z","dependencies_parsed_at":"2023-01-14T05:00:33.038Z","dependency_job_id":null,"html_url":"https://github.com/maremun/nlabot","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/maremun/nlabot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maremun%2Fnlabot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maremun%2Fnlabot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maremun%2Fnlabot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maremun%2Fnlabot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maremun","download_url":"https://codeload.github.com/maremun/nlabot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maremun%2Fnlabot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28795283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"ssl_error","status_checked_at":"2026-01-27T01:07:06.974Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","docker","docker-compose","edu","education","grading","telegram-bot"],"created_at":"2026-01-27T01:17:04.909Z","updated_at":"2026-01-27T01:17:05.396Z","avatar_url":"https://github.com/maremun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NLAbot\nWelcome to **NLAbot**, Telegram bot for uploading and checking coding parts of\nhomework via Telegram. **NLAbot** is used at [Numerical Linear Algebra](http://nla.skoltech.ru/) class,\nhence the name. Check out our [Github repo](https://github.com/oseledets/nla2017).\nNLA Instructors team is from [Scientific Computing group](http://oseledets.github.io/).\n\n## Architecture Design\n**NLAbot** consists of three functional parts: Bot, TA and Jail. Bot interacts\nwith a student, registers and uploads submissions. TA brings up a container\nwith the checking process (Jail). Once Jail processing is over, TA grades the\nwork and sends a notification. Jail acts as an isolated checker, running\nstudent's code and testing it.\n\nQuick launch with docker-compose in detached mode:\n\n```bash\ndocker-compose build\ndocker-compose up -d --scale ta=4 bot ta\n```\n\nThe last command scales the number of TAs. In older docker-compose use\n\n```bash\ndocker-compose up -d bot ta\ndocker-compose scale ta=4\n```\nfor launch and scaling.\n\n### Bot\n\nBot is a primary point of contact. It handles all incoming Telegram updates,\ni.e. user messages, using long polling. It registers new students by updating\ndatabase entries. To distribute and allow for asynchronous homework checking\namong TAs, Bot relies on Redis Queue.\n\nYou can start bot locally like so:\n\n```bash\nnlabot serve\n```\n\nor run a container with the following commands:\n\n```bash\ndocker-compose build bot\ndocker-compose up bot\n```\n\n### TA\n\nNLABot has a pool of background workers called TAs. As soon as submission arrives,\nit is queued for a check. The job is picked up by one of TAs from the pool. TA\nruns in background and launches synchronously an isolated container (Jail) to\nrun a number of checks on a submitted homework solution. Once Jail finishes,\nTA reads the result (see details below) and calculates the grades and updates\ndatabase entries.\n\nRun locally:\n\n```bash\nnlabot work\n```\n\nor start a container with TA:\n\n```bash\ndocker-compose build ta\ndocker-compose up ta\n```\n\n### Jail\n\nJail is a part of NLAbot responsible for isolation of students' code.\nThe bot process in Jail imports student's Jupyter notebook,\nruns a set of tests and then tells the caller TA student's score. \n\nIn order to check a notebook manually one can run the following NLAbot CLI\ncommand. The command takes two positional arguments: checker identifier and\na path to the notebook.\n\nThis command demonstrates checking in a host system without any isolation:\n\n```bash\n    nlabot imprison test notebooks/testnotebook.ipynb\n```\n\nAnd this one uses predefined compose-file to check student notebook in\nisolation:\n\n```bash\n    docker-compose build cell\n    docker-compose run cell\n```\n\n#### Isolation\n\nThe key aspect is using cgroups via docker in order to limit\nmemory and CPU usage and to prohibit any networking (see docker-compose.yml).\n\n#### TA-Jail communication\n\nThere is no special IPC mechanism between TA and Jail. It is pretty straight\nforward and uses stdout, any shared file or FIFO.\nThe caller has a right to select communication resource with `--output` option.\nThe default value is stdout.\n\nCommunication protocol between TA and Jail is one directional from Jail to TA\nand it is based on JSON formatted messages. TA is waiting for any JSON\nencoded message on its side and Jail writes tests results as JSON\nformatted notification.\n\n#### Nuances\n\nThere is a couple of non-trivial bootstrapping procedures before homework\nchecking. \n\n**Importing notebooks**\n\nFortunately, there is a standard solution for importing Jupyter\nnotebooks as modules. It introduces specific module finder and module loader.\n\n**Handling notebooks content**\n\nDue to interactive nature of Jupyter notebooks one should restrict its\ncontent.\nJupyter cell magic `%matplotlib inline` is ubiquitous. Meanwhile it poses a\nproblem as it is an infeasible clause in a non-interactive mode. This is\nhandled with patching matplotlib magic with a stub function and setting\nmatplotlib backend as 'agg'.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaremun%2Fnlabot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaremun%2Fnlabot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaremun%2Fnlabot/lists"}