Metadata-Version: 2.4
Name: bac-svt-dz
Version: 0.1.0
Summary: Small toolkit for organizing and practicing Algerian Bac SVT (Sciences de la Vie et de la Terre) revision material.
Author: 3oloumdz
License: MIT
Project-URL: Homepage, https://3oloumdz.com
Project-URL: Documentation, https://3oloumdz.com
Keywords: education,algeria,bac,svt,revision,quiz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: French
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Education :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# 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

```bash
pip install bac-svt-dz
```

Or from a local checkout:

```bash
pip install .
```

Requires Python 3.9 or later. No external dependencies.

## Quick start

```python
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:

```json
{
  "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:

```python
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

```python
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

```python
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

```python
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:

```bash
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](LICENSE).

## Additional educational resources

The project's documentation and educational resource hub lives at
[3oloumdz.com](https://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.
