Questioner

Natural-science literature learning workflow: extract knowledge points → generate quiz → grade answers.

Works across physics, chemistry, biology, earth science, astronomy, materials science, and related fields. Streamlit web UI + CLI.

中文文档： README.zh-CN.md

Features

• Upload TXT or PDF (with OCR for scanned pages)
• Extract entities, mechanisms, and findings with source quotes
• Normal mode: 5 variable-selection questions (5 options A–E, 1–5 correct, 10 pts each) + 3 logic (6 pts, all-or-nothing) + 2 short-answer (16 pts); total 100
• Easy mode: 4 single-choice (A–D) + 1 short-answer; feedback only
• Custom mode: configure your own question mix
• Multi-provider LLM: Google Gemini, OpenAI, Anthropic Claude, OpenAI-compatible, Ollama / LM Studio, and Unsloth Studio direct
• Dynamic API Overrides: Configure and change API Keys and Base URLs directly in the Web UI sidebar
• Obsidian Literature Exporter: One-click export distilled notes into your local Obsidian Vault (YAML frontmatter + wikilinks)
• UI languages via Google Translate (English, 中文, 日本語, 한국어, and more)
• Personal score history (local) with CJK-aware nickname validation; team leaderboard placeholder

Platform compatibility

Platform	Status	Recommended launcher
macOS	Tested — primary development platform (Python 3.11)	scripts/launch_questioner.sh
Windows 10/11	Compatibility implemented; use Python 3.10+	Double-click start.bat
Linux	Supported through the standard Python/Streamlit commands	python -m streamlit run app.py

The runtime and desktop launchers contain no fixed user or drive paths. The Obsidian Vault path is editable in the UI or through OBSIDIAN_VAULT_PATH.

Setup

macOS (tested)

git clone https://github.com/EinroyVan/Questioner.git
cd Questioner
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
./scripts/launch_questioner.sh

Windows 10/11

Install Python 3.10 or newer, clone/download this repository, then double-click start.bat. The launcher creates .venv, installs missing dependencies, starts port 8502, and opens the browser.

Manual setup from Command Prompt:

py -3.11 -m venv .venv
.venv\Scripts\activate
python -m pip install -e .
copy .env.example .env
python -m streamlit run app.py

API keys (.env)

Provider	Environment variables
Google Gemini (default)	GOOGLE_API_KEY, GOOGLE_MODEL
OpenAI	OPENAI_API_KEY, OPENAI_MODEL, optional OPENAI_BASE_URL
Anthropic	ANTHROPIC_API_KEY, ANTHROPIC_MODEL
OpenAI-compatible	OPENAI_COMPAT_API_KEY, OPENAI_COMPAT_BASE_URL, OPENAI_COMPAT_MODEL
Local model	LOCAL_LLM_HOST, LOCAL_LLM_PORT, LOCAL_LLM_MODEL; Ollama defaults to port 11434, while LM Studio commonly uses 1234
Unsloth Studio direct	UNSLOTH_HOST, UNSLOTH_PORT, UNSLOTH_MODEL, UNSLOTH_API_KEY; defaults to port 8888

Set OBSIDIAN_VAULT_PATH to the local Vault root if you want a persistent export location; it can also be changed in the final export screen.

Choose the active provider in the Streamlit sidebar (session only; .env is not modified). For “Local model”, configure host and port separately and use “Test model connection” to verify the endpoint and list its available models. No API key is required. For “Unsloth Studio (direct)”, start Studio with unsloth studio -p 8888, load a model, enable the API, and paste the API key generated by Studio. The connection test reads /v1/models and lists loaded models. On Windows, if Unsloth runs inside WSL or Docker, expose port 8888 to Windows and enter the reachable host in the sidebar.

UI translation uses Google Translate via deep-translator and does not consume LLM tokens.

Web UI (recommended)

python -m streamlit run app.py

Open http://localhost:8502

On macOS, scripts/launch_questioner.sh performs the same start-and-open flow. On Windows, double-click start.bat.

CLI

python main.py extract -i examples/literature_sample.txt -o output/knowledge.json
python main.py quiz -k output/knowledge.json -o output/quiz.json
python main.py grade -q output/quiz.json -I -o output/grading.json
python main.py pipeline -i examples/literature_sample.txt -d output

Set LLM_PROVIDER=google (or openai, anthropic, openai_compatible, local, unsloth) in .env for CLI defaults.

Project structure

Questioner/
├── app.py              # Streamlit entry
├── main.py             # CLI entry
├── questioner/         # Python package
├── examples/
└── .streamlit/         # Port 8502

Scoring notes

• Single-choice / variable-selection / logic: script-graded from generated answer keys (no LLM tokens).
• Logic questions: independent scoring — correct = 6 pts, wrong = 0 pts (not subject to variable-selection partial-credit rules).
• Short-answer: LLM grading with partial credit.

Security

Never commit .env. Use .env.example as a template only.

License

MIT