Skip to content

About

No description, website, or topics provided.

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

Virtual Learning Environment

A small, single-user learning environment for asking questions about the material you choose. Add your own EPUB books, articles, or papers, then use the web interface to search and chat with a local language model grounded in that material.

Table of contents

What you need

  • Python 3.13 or later
  • uv for Python dependencies
  • Ollama running locally
  • Node.js 22.23.4 and npm (for the web interface; see frontend/.nvmrc)

Docker Desktop and Docker Compose are recommended to run the backend and frontend in containers. However, you can run the frontend and backend separately if you choose to.

Run locally

  1. Clone the repository and install the Python dependencies:

    git clone https://github.com/noelcodesxo/virtual-learning-environment.git
    cd virtual-learning-environment
    uv sync
  2. Create local configuration files from the included templates:

    cp .local.env.example .local.env
    cp frontend/.env.local.example frontend/.env.local

    The defaults run chat with Ollama. To enable exam generation, set EXAM_BUILDER_ENABLED=true and add your OpenRouter API key to .local.env.

  3. Install and start a local model with Ollama. The default model is qwen3:8b:

    ollama pull qwen3:8b
    ollama serve
  4. Add the EPUB files you want to study. You can place them in src/resources/ before starting the app, or use the Add EPUB button in the Chat sidebar after it is running. Uploads are limited to 50 MB and refresh the local index.json search index automatically. Existing EPUB files in src/resources/ are examples and can be replaced with your own material.

  5. Start the API in one terminal:

    set -a
    source .local.env
    set +a
    uv run uvicorn vle.api.app:app --app-dir src --reload
  6. In a second terminal, start the web interface:

    cd frontend
    npm ci
    npm run dev
  7. Open http://localhost:3000 and select the local model to begin asking questions.

The API runs at http://localhost:8000. Set LLM_MODEL to use a different Ollama model, or set OLLAMA_BASE_URL if Ollama is available at a different address.

Run with Docker Compose

With Ollama running on your host machine and Docker Compose installed, run:

docker compose up --watch

Then open http://localhost:3000. The compose configuration connects the backend container to Ollama on the host at http://host.docker.internal:11434.

Study modes

Chat

Use Chat when you want to explore your library or get help understanding a topic. It searches the local index for the passages most relevant to your question, sends those passages and your question to your local Ollama model, and shows the sources alongside its answer. This is the best mode for open-ended questions such as “Explain this concept” or “What does this book say about …?”

Exams

Use Exams when you want to test your understanding of a specific source chapter. Choose a source and chapter, or describe the topic you want to be tested on. The exam builder reads the full selected chapter and generates a multiple-choice exam; after you submit it, it scores your answers and explains the correct choices.

Exam generation is optional and disabled by default. It uses OpenRouter-compatible models to select a chapter from a description, map its topics, and generate the final exam, so enabling it requires EXAM_BUILDER_ENABLED=true and an OPENROUTER_API_KEY. By default, topic mapping uses the same OpenRouter model as exam writing (EXAM_MODEL). To use Ollama for topic mapping, set EXAM_TOPIC_MAP_PROVIDER=ollama; when EXAM_TOPIC_MAP_MODEL is not set, it uses LLM_MODEL. Setting EXAM_TOPIC_MAP_MODEL explicitly overrides the selected provider's default model. Model requests time out after five minutes by default; set LLM_REQUEST_TIMEOUT_SECONDS to adjust that limit.

Before generating an exam, choose one or more Bloom's taxonomy levels: remember, understand, apply, analyze, evaluate, or create. Both topic mapping and question writing receive every ordered excerpt from the full selected document, chapter, or section. The question-writing model also receives the topic map and selected levels. A small question count cannot guarantee a question on every topic, even though the models receive the full source; they prioritize central ideas and any requested focus. If a model reports that the source exceeds its context window, generation fails without saving an exam; choose a model with a larger context window or a shorter selected source.

Generated exams, answers, and scores are saved locally as individual JSON files in data/exams/, so they remain available after restarting or rebuilding the application. The directory is excluded from Git; back it up if you want to keep your exam history. Set EXAMS_DIR to store it elsewhere. Docker Compose mounts ./data into the backend container so this history also survives container rebuilds.

How it works

The backend extracts and chunks your EPUBs, builds a local BM25 search index, retrieves the most relevant passages for each question, and sends those passages with your question to Ollama. The interface shows the answer together with its source passages so you can check the material it used.

Dependency maintenance

Direct npm and Python dependencies use exact versions; commit both lockfiles when updating them. Run npm ci in frontend/ and uv sync --locked at the root for reproducible installs. frontend/.npmrc saves future npm additions as exact versions. Use npm install package@VERSION and uv add 'package==VERSION' for reviewed updates.

Node is pinned in frontend/.nvmrc, CI, and the frontend Docker stages. Docker base images use immutable digests, and CI actions use commit SHAs. Update these pins regularly to receive security fixes; pinning alone does not make a package safe. The uv CLI and setuptools build backend are also pinned. Python's >=3.13 compatibility requirement and .python-version select a supported interpreter line; the production Docker interpreter is pinned separately.

Before accepting updates, run npm audit, npm audit --omit=dev, npm run lint, npm test, and npm run build in frontend/, then uv run pytest -q at the root. For a Python advisory check, export the locked third-party packages with uv export --locked --no-emit-project --no-hashes -o /tmp/vle-audit-requirements.txt, then run uvx pip-audit --disable-pip --no-deps -r /tmp/vle-audit-requirements.txt.

See the October 22, 2026 security review for the checked incidents, updates, and remaining development-tool advisory.

About

No description, website, or topics provided.

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages