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.
- 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.
-
Clone the repository and install the Python dependencies:
git clone https://github.com/noelcodesxo/virtual-learning-environment.git cd virtual-learning-environment uv sync -
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=trueand add your OpenRouter API key to.local.env. -
Install and start a local model with Ollama. The default model is
qwen3:8b:ollama pull qwen3:8b ollama serve
-
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 localindex.jsonsearch index automatically. Existing EPUB files insrc/resources/are examples and can be replaced with your own material. -
Start the API in one terminal:
set -a source .local.env set +a uv run uvicorn vle.api.app:app --app-dir src --reload
-
In a second terminal, start the web interface:
cd frontend npm ci npm run dev -
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.
With Ollama running on your host machine and Docker Compose installed, run:
docker compose up --watchThen open http://localhost:3000. The compose configuration connects the backend container to Ollama on the host at http://host.docker.internal:11434.
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 …?”
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.
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.
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.