Metadata-Version: 2.4
Name: quiz-me
Version: 0.1.1
Summary: AI-powered question generation library using Langgraph flows
Project-URL: Homepage, https://github.com/lfnovo/quiz-me
Project-URL: Repository, https://github.com/lfnovo/quiz-me
Project-URL: Issues, https://github.com/lfnovo/quiz-me/issues
Author-email: Luis Novo <luis@lfnovo.com>
License: MIT
License-File: LICENSE
Keywords: ai,education,educational-technology,langchain,langgraph,llm,question-generation,questions,quiz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: ai-prompter
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langgraph>=1.0.0
Requires-Dist: pydantic>=2.10
Provides-Extra: dev
Requires-Dist: esperanto; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# quiz-me

AI-powered question generation library using Langgraph flows. Generate high-quality educational questions from content or topics with optional AI supervision.

## Features

- **Single & Multi-Question Generation** - Generate one or multiple questions from content or topics
- **Three Question Types** - Multiple choice, open-ended (with grading rubric), and fill-in-the-blank
- **Optional AI Supervision** - A second model reviews and validates generated questions
- **Question Improvement** - Regenerate questions based on user feedback
- **Multi-Language Support** - Generate questions in any language
- **Automatic Retry Logic** - Retries on validation errors or supervision rejection
- **Domain-Specific Instructions** - Customize generation and supervision for your domain
- **LangChain Compatible** - Works with any LangChain-compatible model

## Installation

```bash
pip install quiz-me
```

Or with uv:
```bash
uv add quiz-me
```

## Quick Start

```python
from quiz_me import generate_question, SingleQuestionConfig, QuestionType

# Use any LangChain-compatible model
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-4o-mini")

# Generate a multiple choice question
config = SingleQuestionConfig(
    content="Python is a high-level programming language...",
    question_type=QuestionType.MULTIPLE_CHOICE,
    generator_model=model,
)

result = await generate_question(config)
print(result.question.statement)
print(result.question.alternatives)
print(result.question.correct_answer)
```

## Topic-Based Generation

Generate questions from a topic using the model's knowledge (no content required):

```python
config = SingleQuestionConfig(
    topic="The French Revolution and its impact on European politics",
    question_type=QuestionType.MULTIPLE_CHOICE,
    generator_model=model,
)

result = await generate_question(config)
```

## Multi-Question Generation

```python
from quiz_me import generate_questions, MultiQuestionConfig, QuestionTypeMix

config = MultiQuestionConfig(
    content="Your educational content here...",
    num_questions=5,
    question_mix=[
        QuestionTypeMix(question_type=QuestionType.MULTIPLE_CHOICE, count=3),
        QuestionTypeMix(question_type=QuestionType.OPEN_ENDED, count=2),
    ],
    generator_model=model,
    planning_instructions="Focus on key concepts and practical applications",
)

result = await generate_questions(config)
for q in result.questions:
    print(q.statement)
```

## With Supervision

```python
config = SingleQuestionConfig(
    content="Medical terminology content...",
    question_type=QuestionType.MULTIPLE_CHOICE,
    generator_model=model,
    supervisor_model=model,  # Can be same or different model
    supervision_enabled=True,
    generator_instructions="Focus on pharmacology terms",
    supervisor_instructions="Verify medical accuracy",
)

result = await generate_question(config)
print(f"Approved: {result.question.approved}")
```

## Multi-Language Support

Generate questions in any language by setting the `language` property:

```python
config = SingleQuestionConfig(
    content="Python é uma linguagem de programação...",
    question_type=QuestionType.MULTIPLE_CHOICE,
    generator_model=model,
    language="Portuguese",  # All content generated in Portuguese
)

result = await generate_question(config)
# Question, alternatives, and explanation will be in Portuguese
```

## Question Improvement

Improve an existing question based on feedback using the same pattern as supervision:

```python
from quiz_me import improve_question

# Original question that needs improvement
original = result.question

# Create config matching the original question
config = SingleQuestionConfig(
    content="Original content...",
    question_type=original.question_type,
    generator_model=model,
)

# Improve based on feedback
improved = await improve_question(
    question=original,
    feedback="The distractors are too obvious. Make them more plausible.",
    config=config,
)
print(improved.question.statement)
```

## Retry Configuration

Control retry behavior for generation failures:

```python
config = SingleQuestionConfig(
    content="Your content...",
    question_type=QuestionType.MULTIPLE_CHOICE,
    generator_model=model,
    max_retries=5,                    # Default is 3
    retry_on_validation_error=True,   # Retry on Pydantic validation errors
)
```

## Documentation

See [docs/](docs/) for detailed documentation.

## Development

```bash
# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v
```

## Stack

- **Langgraph** - Flow orchestration
- **Pydantic** - Data validation
- **ai-prompter** - Jinja-based prompt templates
- **LangChain** - Model abstraction

## License

MIT
