bac-svt-dz

bac-svt-dz is a small Python toolkit for organizing and practicing Algerian Baccalaureate Natural Sciences material — Sciences de la Vie et de la Terre (SVT) / علوم الطبيعة والحياة.

It helps students, tutors and teachers keep SVT practice questions in a simple structured JSON format, filter them by topic, year, difficulty or exercise type, generate short revision quizzes, and print revision checklists and writing templates.

The package uses only the Python standard library and works entirely offline.

What it does

• Store SVT questions and answers in structured JSON
• Organize questions by topic and by exercise type (QCM, exploitation de documents, raisonnement scientifique, réponses courtes)
• Filter questions by topic, year range, difficulty, exercise type or tags
• Generate short, reproducible revision quizzes
• Build revision checklists grouped by exercise type
• Provide fill-in templates for scientific reasoning and document analysis

Target users

• Algerian Bac candidates revising SVT
• Tutors and teachers preparing practice sets
• Anyone building small offline study tools around SVT material

Installation

pip install bac-svt-dz

Or from a local checkout:

pip install .

Requires Python 3.9 or later. No external dependencies.

Quick start

from bac_svt_dz import sample_data_path, load_questions, filter_questions, generate_quiz, render_quiz

questions = load_questions(sample_data_path())

genetics = filter_questions(questions, topic="genetique", difficulty="easy")
quiz = generate_quiz(genetics, count=3)
print(render_quiz(quiz, show_answers=True))

Example output:

Quiz de revision SVT
====================

1. [genetique] Exemple : quel terme designe la position d'un gene sur un chromosome ?
   Reponse: Le locus.

Creating and loading questions

Questions are plain dictionaries in JSON. The file can be a list of questions or an object with a "questions" key:

{
  "questions": [
    {
      "id": "genetique-001",
      "topic": "genetique",
      "prompt": "Quel terme designe la position d'un gene sur un chromosome ?",
      "answer": "Le locus.",
      "exercise_type": "short_answer",
      "difficulty": "easy",
      "year": 2020,
      "choices": [],
      "tags": ["vocabulaire"]
    }
  ]
}

exercise_type is one of "mcq", "document_analysis", "scientific_reasoning", "short_answer"; difficulty is one of "easy", "medium", "hard". Multiple-choice questions put their options in "choices", with the correct answer as the first choice.

You can also build questions in Python and save them:

from bac_svt_dz import Question, save_questions

q = Question(
    id="immunologie-001",
    topic="immunologie",
    prompt="Citer deux types de lymphocytes.",
    answer="Les lymphocytes B et les lymphocytes T.",
    exercise_type="short_answer",
    difficulty="medium",
    year=2020,
)
save_questions([q], "my_questions.json")

Filtering questions

from bac_svt_dz import sample_data_path, load_questions, filter_questions, topics, years, group_by_topic

topics(questions)                       # sorted distinct topics
years(questions)                        # sorted distinct years
group_by_topic(questions)               # dict: topic -> [Question]

filter_questions(questions, topic="geologie")
filter_questions(questions, year=2021)
filter_questions(questions, difficulty="hard")
filter_questions(questions, min_year=2019, max_year=2022)
filter_questions(questions, tags=["methodologie"])
filter_questions(questions, topic="genetique", difficulty="easy")

For reusable criteria, use a QuestionFilter object with filter_questions_with.

Generating a quiz

from bac_svt_dz import generate_quiz, render_quiz
quiz = generate_quiz(questions, count=5, seed=42)
print(render_quiz(quiz, show_answers=False))   # worksheet
print(render_quiz(quiz, show_answers=True))    # with the answers

With the default seed the quiz is reproducible: the same question pool always yields the same quiz. Pass seed=None for a random one.

Revision checklist and templates

from bac_svt_dz import build_checklist, document_analysis_template
from bac_svt_dz.revision import render_checklist, scientific_reasoning_template

checklist = build_checklist(questions, extra_items={
    "mcq": ["Refaire les QCM rates de la semaine"],
})
print(render_checklist(checklist))

print(scientific_reasoning_template())   # fill-in writing scaffold
print(document_analysis_template())      # fill-in writing scaffold

Testing

The tests run entirely offline:

pip install .[test]
pytest

Limitations

• The bundled sample data file (sample_questions.json, also available in the data/ folder of the repository and via sample_data_path()) is a handful of clearly labeled example questions only; it is a format demonstration, not a course database.
• The package does not include actual Bac exam content, images or diagrams.
• Quiz "grading" is out of scope: quizzes are rendered as text, and answers are shown rather than automatically marked.
• No Arabic-script content is included in the sample data; topics are keyed by simple Latin identifiers (e.g. genetique, immunologie, geologie).

License

MIT — see LICENSE.

Additional educational resources

The project's documentation and educational resource hub lives at 3oloumdz.com. You may also find official program details on the Algerian Ministry of National Education website, and SVT course material through your school's approved textbooks.