QuantumChecker 0.4.0__tar.gz → 1.0.0__tar.gz

{quantumchecker-0.4.0 → quantumchecker-1.0.0}/PKG-INFO

@@ -1,52 +1,52 @@
-Metadata-Version: 2.4
-Name: QuantumChecker
-Version: 0.4.0
-Summary: A package to evaluate homework submissions in Python, SQL, PowerBI, and SSIS.
-Author: Qobiljon
-Author-email: qobiljonkhayrullayev@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: tenacity>=8.2.3
-Requires-Dist: pdf2image>=1.16.3
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: Pillow>=10.0.0
-Requires-Dist: PyPDF2>=3.0.1
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-Sample usage: 
-```
-import asyncio
-from your_evaluator_module import HomeworkEvaluator
-
-async def main():
-    evaluator = HomeworkEvaluator()
-    question_content = """
-Q1: What is a Python list? Explain with an example.
-
-Q2: Write an SQL query to select all records from a table named 'students'.
-"""
-    answer_path = "sample_submissions/student1_answer.py"
-    question_type = "python"
-
-    result = await evaluator.evaluate_from_content(
-        question_content=question_content,
-        answer_path=answer_path,
-        api_key="your_api_key",
-        question_type=question_type
-    )
-    print(result)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
+Metadata-Version: 2.4
+Name: QuantumChecker
+Version: 1.0.0
+Summary: AI-powered homework evaluation for Python, SQL, Power BI, and SSIS.
+Author: Qobiljon
+Author-email: qobiljonkhayrullayev@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: PyPDF2>=3.0.1
+Provides-Extra: pdf
+Requires-Dist: pdf2image>=1.16.3; extra == "pdf"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Sample usage: 
+```
+import asyncio
+from your_evaluator_module import HomeworkEvaluator
+
+async def main():
+    evaluator = HomeworkEvaluator()
+    question_content = """
+Q1: What is a Python list? Explain with an example.
+
+Q2: Write an SQL query to select all records from a table named 'students'.
+"""
+    answer_path = "sample_submissions/student1_answer.py"
+    question_type = "python"
+
+    result = await evaluator.evaluate_from_content(
+        question_content=question_content,
+        answer_path=answer_path,
+        api_key="your_api_key",
+        question_type=question_type
+    )
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

quantumchecker-1.0.0/QuantumCheck/__init__.py

@@ -0,0 +1,33 @@
+"""QuantumCheck - AI-powered homework evaluation package."""
+
+from .quantum_check import QuantumCheck
+from .evaluator import HomeworkEvaluator
+from .model import GeminiModel
+from .powerbi_mentor import PowerBIMentor
+from .python_mentor import PythonMentor
+from .sql_mentor import SQLMentor
+from .ssis_mentor import SSISMentor
+from .parsers.lesson import parse_lesson_questions
+from .exceptions import (
+    QuantumCheckError,
+    ParsingError,
+    EvaluationError,
+    ProcessingError,
+    ModelError,
+)
+
+__all__ = [
+    "QuantumCheck",
+    "HomeworkEvaluator",
+    "GeminiModel",
+    "PowerBIMentor",
+    "PythonMentor",
+    "SQLMentor",
+    "SSISMentor",
+    "parse_lesson_questions",
+    "QuantumCheckError",
+    "ParsingError",
+    "EvaluationError",
+    "ProcessingError",
+    "ModelError",
+]

quantumchecker-1.0.0/QuantumCheck/config.py

@@ -0,0 +1,101 @@
+"""Centralized configuration and constants."""
+
+DEFAULT_MODEL_NAME = "gemini-2.5-flash"
+DEFAULT_TEMPERATURE = 0.3
+RATE_LIMIT_SECONDS = 0  # Set >0 only for free-tier keys
+
+# Retry settings for transient API errors (429, 503, etc.)
+RETRY_MAX_ATTEMPTS = 5
+RETRY_BASE_DELAY = 1.0   # seconds
+RETRY_MAX_DELAY = 30.0   # seconds
+RETRY_BACKOFF_FACTOR = 2  # exponential multiplier
+OFF_TOPIC_SCORE = 20
+MAX_SCORE = 100
+BASELINE_SSIS_SCORE = 60
+PDF_MAX_PAGES = 3
+IMAGE_MAX_SIZE = (1024, 1024)
+
+# Legacy DAX vs visual weights (kept for backward compat, no longer used internally)
+POWERBI_DAX_WEIGHT = 0.7
+POWERBI_VISUAL_WEIGHT = 0.3
+
+# File extension to evaluator type mapping
+EXTENSION_TO_TYPE = {
+    ".py": "python",
+    ".ipynb": "python",
+    ".pyw": "python",
+    ".pyi": "python",
+    ".pyx": "python",
+    ".pxd": "python",
+    ".pyd": "python",
+    ".so": "python",
+    ".sql": "sql",
+    ".pbit": "powerbi",
+    ".pdf": "powerbi",
+    ".dtsx": "ssis",
+    ".txt": "text",
+    ".md": "text",
+}
+
+PYTHON_EXTENSIONS = (".py", ".ipynb", ".pyw", ".pyi", ".pyx", ".pxd", ".pyd", ".so")
+
+# JSON schema for structured model output
+EVALUATION_SCHEMA = {
+    "type": "OBJECT",
+    "properties": {
+        "score": {
+            "type": "INTEGER",
+            "description": "Overall score out of 100",
+        },
+        "feedback": {
+            "type": "STRING",
+            "description": "Detailed feedback including strengths and areas for improvement",
+        },
+        "issues": {
+            "type": "ARRAY",
+            "items": {"type": "STRING"},
+            "description": "Specific issues found in the submission",
+        },
+        "recommendations": {
+            "type": "ARRAY",
+            "items": {"type": "STRING"},
+            "description": "Actionable recommendations for improvement",
+        },
+    },
+    "required": ["score", "feedback", "issues", "recommendations"],
+}
+
+VISUAL_EVALUATION_SCHEMA = {
+    "type": "OBJECT",
+    "properties": {
+        "score": {
+            "type": "INTEGER",
+            "description": "Visual evaluation score out of 100",
+        },
+        "feedback": {
+            "type": "STRING",
+            "description": "Feedback on visual quality",
+        },
+        "issues": {
+            "type": "ARRAY",
+            "items": {"type": "STRING"},
+            "description": "Visual issues found",
+        },
+        "recommendations": {
+            "type": "ARRAY",
+            "items": {"type": "STRING"},
+            "description": "Recommendations for visual improvement",
+        },
+    },
+    "required": ["score", "feedback", "issues", "recommendations"],
+}
+
+
+def empty_result(feedback="", score=0):
+    """Return a consistently shaped empty evaluation result."""
+    return {
+        "score": score,
+        "feedback": feedback,
+        "issues": [],
+        "recommendations": [],
+    }

quantumchecker-1.0.0/QuantumCheck/evaluator.py

@@ -0,0 +1,130 @@
+"""HomeworkEvaluator - main entry point for the QuantumCheck package."""
+
+import asyncio
+import logging
+import os
+import shutil
+import zipfile
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from .config import EXTENSION_TO_TYPE, RATE_LIMIT_SECONDS, empty_result
+from .evaluators import PythonEvaluator, SQLEvaluator, PowerBIEvaluator, SSISEvaluator
+from .model import GeminiModel
+
+logger = logging.getLogger(__name__)
+
+
+class HomeworkEvaluator:
+    """Evaluate homework submissions across Python, SQL, Power BI, and SSIS."""
+
+    _EVALUATOR_MAP = {
+        "python": PythonEvaluator,
+        "sql": SQLEvaluator,
+        "powerbi": PowerBIEvaluator,
+        "ssis": SSISEvaluator,
+    }
+
+    def __init__(
+        self,
+        api_key=None,
+        model_name="gemini-2.5-flash",
+        vertexai=False,
+        project_id=None,
+        location=None,
+        log_level=logging.INFO,
+        rate_limit=RATE_LIMIT_SECONDS,
+    ):
+        logging.basicConfig(level=log_level)
+        self._rate_limit_seconds = rate_limit
+        self._last_request_time = None
+        self._lock = asyncio.Lock() if rate_limit > 0 else None
+
+        self._model = GeminiModel(
+            api_key=api_key,
+            model_name=model_name,
+            vertexai=vertexai,
+            project_id=project_id,
+            location=location,
+        )
+
+    async def evaluate_from_content(
+        self,
+        question_content,
+        answer_path,
+        question_type,
+        api_key=None,
+    ):
+        """Evaluate a student submission asynchronously."""
+        if self._lock:
+            async with self._lock:
+                await self._rate_limit()
+
+        questions = self._parse_questions(question_content)
+        if isinstance(questions, dict):
+            return questions
+
+        answer_path = answer_path.strip()
+        if not os.path.exists(answer_path):
+            return empty_result(feedback="Answer file not found: {}".format(answer_path))
+
+        eval_type = self._resolve_type(question_type, answer_path)
+        evaluator_cls = self._EVALUATOR_MAP.get(eval_type, PythonEvaluator)
+        evaluator = evaluator_cls(self._model)
+
+        temp_dir = "temp_extract_{}_{}".format(os.getpid(), id(asyncio.current_task()))
+        try:
+            result = evaluator.evaluate(
+                questions, answer_path,
+                temp_dir=temp_dir
+            )
+            return {
+                "score": result.get("score", 0),
+                "feedback": result.get("feedback", "No feedback provided"),
+                "issues": result.get("issues", []),
+                "recommendations": result.get("recommendations", []),
+                **{k: v for k, v in result.items()
+                   if k not in ("score", "feedback", "issues", "recommendations")},
+            }
+        except Exception as exc:
+            logger.error("Evaluation failed: %s", exc)
+            return empty_result(feedback="Evaluation failed: {}".format(exc))
+        finally:
+            if os.path.exists(temp_dir):
+                shutil.rmtree(temp_dir, ignore_errors=True)
+
+    async def _rate_limit(self):
+        if self._rate_limit_seconds <= 0:
+            return
+        now = datetime.now()
+        if self._last_request_time:
+            elapsed = (now - self._last_request_time).total_seconds()
+            if elapsed < self._rate_limit_seconds:
+                await asyncio.sleep(self._rate_limit_seconds - elapsed)
+        self._last_request_time = datetime.now()
+
+    @staticmethod
+    def _parse_questions(content):
+        questions = [q.strip() for q in content.split("\n\n") if q.strip()]
+        if not questions:
+            return empty_result(feedback="No valid questions found in content")
+        return questions
+
+    @staticmethod
+    def _resolve_type(question_type, answer_path):
+        if question_type in ("python", "sql", "powerbi", "ssis"):
+            return question_type
+        _, ext = os.path.splitext(answer_path)
+        ext = ext.lower()
+        if ext == ".zip":
+            try:
+                with zipfile.ZipFile(answer_path, "r") as zf:
+                    extensions = {os.path.splitext(n)[1].lower() for n in zf.namelist()}
+                    types = [EXTENSION_TO_TYPE.get(e, "text") for e in extensions if e]
+                    for t in ("python", "sql", "powerbi", "ssis"):
+                        if t in types:
+                            return t
+            except zipfile.BadZipFile:
+                pass
+            return "text"
+        return EXTENSION_TO_TYPE.get(ext, "text")

quantumchecker-1.0.0/QuantumCheck/evaluators/__init__.py

@@ -0,0 +1,6 @@
+"""Homework evaluators."""
+
+from .python import PythonEvaluator
+from .sql import SQLEvaluator
+from .ssis import SSISEvaluator
+from .powerbi import PowerBIEvaluator

quantumchecker-1.0.0/QuantumCheck/evaluators/base.py

@@ -0,0 +1,44 @@
+"""Base evaluator with shared parse-combine-evaluate pattern."""
+
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+from ..config import empty_result
+
+logger = logging.getLogger(__name__)
+
+
+class BaseEvaluator(ABC):
+    """Template-method evaluator.
+
+    Subclasses implement ``_parse_answers`` and ``_build_prompt``.
+    The ``evaluate`` method orchestrates: parse -> combine -> call model.
+    """
+
+    def __init__(self, model):
+        self.model = model
+
+    def evaluate(self, questions: List[str], answer_path: str, temp_dir: str = None) -> Dict:
+        try:
+            answers = self._parse_answers(answer_path, temp_dir)
+
+            combined_questions = "\n".join(q.strip() for q in questions if q.strip())
+            combined_answers = "\n".join(a.strip() for a in answers if a.strip())
+            raw = "Questions:\n{}\n\nAnswers:\n{}".format(combined_questions, combined_answers)
+
+            prompt = self._build_prompt(raw)
+            return self.model.evaluate(prompt)
+
+        except Exception as exc:
+            logger.error("Evaluation failed for %s: %s", answer_path, exc)
+            return empty_result(feedback="Evaluation failed: {}".format(exc))
+
+    @abstractmethod
+    def _parse_answers(self, answer_path: str, temp_dir: str = None) -> List[str]:
+        """Return a list of answer strings from the submission file."""
+
+    @abstractmethod
+    def _build_prompt(self, combined_content: str) -> str:
+        """Wrap combined Q&A content in the appropriate prompt template."""

quantumchecker-1.0.0/QuantumCheck/evaluators/powerbi.py

@@ -0,0 +1,162 @@
+"""Power BI homework evaluator - combines DAX, visual, and written evaluations."""
+
+import json
+import logging
+import os
+from typing import Dict, List, Optional
+
+from ..config import empty_result
+from ..parsers.powerbi import PowerBIProcessor
+from ..prompts.powerbi import build_powerbi_dax_prompt, POWERBI_VISUAL_PROMPT, POWERBI_WRITTEN_PROMPT
+
+logger = logging.getLogger(__name__)
+
+
+class PowerBIEvaluator:
+    """Evaluates Power BI submissions across three sections."""
+
+    def __init__(self, model):
+        self.model = model
+        self._processor = PowerBIProcessor()
+
+    def evaluate(self, questions, answer_path, temp_dir="temp_extract",
+                 dax_question=None, visual_question=None, written_question=None):
+        """Evaluate a Power BI submission (legacy interface)."""
+        output_images = os.path.join(temp_dir, "outputimages")
+        combined = "\n\n".join(q.strip() for q in questions if q.strip())
+        if dax_question is None and visual_question is None and written_question is None:
+            dax_q = combined
+            visual_q = combined
+            written_q = combined
+            all_from_legacy = True
+        else:
+            dax_q = dax_question
+            visual_q = visual_question
+            written_q = written_question
+            all_from_legacy = False
+        try:
+            pbit_path, pdf_path, txt_path = self._processor.resolve_paths(answer_path, temp_dir)
+            return self._run_sections(
+                dax_q, visual_q, written_q,
+                pbit_path, pdf_path, txt_path,
+                questions, output_images, all_from_legacy,
+            )
+        except Exception as exc:
+            logger.error("PowerBI evaluation failed: %s", exc)
+            result = empty_result(feedback="Error processing file: {}".format(exc))
+            result["dax_score"] = 0
+            result["visual_score"] = 0
+            result["written_score"] = 0
+            return result
+        finally:
+            self._processor._cleanup(temp_dir, output_images)
+
+    def evaluate_all(self, answer_path, dax_question=None, visual_question=None,
+                     written_question=None, temp_dir="temp_extract"):
+        """Evaluate with per-section questions. None = skip section."""
+        output_images = os.path.join(temp_dir, "outputimages")
+        try:
+            pbit_path, pdf_path, txt_path = self._processor.resolve_paths(answer_path, temp_dir)
+            return self._run_sections(
+                dax_question, visual_question, written_question,
+                pbit_path, pdf_path, txt_path,
+                [], output_images, False,
+            )
+        except Exception as exc:
+            logger.error("PowerBI evaluation failed: %s", exc)
+            result = empty_result(feedback="Error processing file: {}".format(exc))
+            result["dax_score"] = 0
+            result["visual_score"] = 0
+            result["written_score"] = 0
+            return result
+        finally:
+            self._processor._cleanup(temp_dir, output_images)
+
+    def _run_sections(self, dax_q, visual_q, written_q,
+                      pbit_path, pdf_path, txt_path,
+                      raw_questions, output_images, all_from_legacy):
+        sections = []
+        all_issues = []
+        all_recommendations = []
+        dax_score = 0
+        visual_score = 0
+        written_score = 0
+
+        if dax_q is not None:
+            if pbit_path:
+                r = self._evaluate_dax(raw_questions or [dax_q], pbit_path)
+                dax_score = r["score"]
+                sections.append(("DAX", dax_score, r["feedback"]))
+                all_issues.extend(r.get("issues", []))
+                all_recommendations.extend(r.get("recommendations", []))
+            else:
+                sections.append(("DAX", 0, "No .pbit file provided for DAX evaluation."))
+                all_issues.append("No .pbit file provided for DAX evaluation")
+
+        if visual_q is not None:
+            if pdf_path:
+                r = self._evaluate_visuals(visual_q, pdf_path, output_images)
+                visual_score = r["score"]
+                sections.append(("Visual", visual_score, r["feedback"]))
+                all_issues.extend("Visual: {}".format(i) for i in r.get("issues", []))
+                all_recommendations.extend(r.get("recommendations", []))
+            else:
+                sections.append(("Visual", 0, "No .pdf file provided for visual evaluation."))
+                all_issues.append("No .pdf file provided for visual evaluation")
+
+        if written_q is not None:
+            if txt_path:
+                r = self._evaluate_written(written_q, txt_path)
+                written_score = r["score"]
+                sections.append(("Written", written_score, r["feedback"]))
+                all_issues.extend(r.get("issues", []))
+                all_recommendations.extend(r.get("recommendations", []))
+            else:
+                sections.append(("Written", 0, "No .txt file provided for written evaluation."))
+                all_issues.append("No .txt file provided for written evaluation")
+
+        if not sections:
+            return {
+                "score": 0,
+                "feedback": "No evaluations were completed.",
+                "issues": [],
+                "recommendations": [],
+                "dax_score": 0,
+                "visual_score": 0,
+                "written_score": 0,
+            }
+
+        overall_score = int(sum(s[1] for s in sections) / len(sections))
+        feedback_parts = []
+        for name, score, fb in sections:
+            feedback_parts.append("{} (Score: {}/100):\n{}".format(name, score, fb))
+        combined_feedback = "\n\n".join(feedback_parts)
+
+        return {
+            "score": overall_score,
+            "feedback": combined_feedback,
+            "issues": all_issues,
+            "recommendations": all_recommendations,
+            "dax_score": dax_score,
+            "visual_score": visual_score,
+            "written_score": written_score,
+        }
+
+    def _evaluate_dax(self, questions, pbit_path):
+        data_model = self._processor.extract_datamodel(pbit_path)
+        summary = self._processor.extract_model_summary(data_model)
+        combined = "\n\n".join(
+            "Question {}:\n{}\n\nAnswer {}:\n{}\n".format(i, q, i, json.dumps(summary))
+            for i, q in enumerate(questions, 1)
+        )
+        return self.model.evaluate(build_powerbi_dax_prompt(combined))
+
+    def _evaluate_visuals(self, question, pdf_path, output_dir):
+        image_paths = self._processor.pdf_to_images(pdf_path, output_dir=output_dir)
+        prompt = POWERBI_VISUAL_PROMPT.format(question=question)
+        return self.model.evaluate_with_images(prompt, image_paths)
+
+    def _evaluate_written(self, question, txt_path):
+        answer_text = self._processor.read_text_file(txt_path)
+        prompt = POWERBI_WRITTEN_PROMPT.format(question=question, answer=answer_text)
+        return self.model.evaluate(prompt)

quantumchecker-1.0.0/QuantumCheck/evaluators/python.py

@@ -0,0 +1,19 @@
+"""Python homework evaluator."""
+
+import os
+from typing import List
+
+from .base import BaseEvaluator
+from ..parsers.python import PythonParser
+from ..prompts.python import build_python_prompt
+
+
+class PythonEvaluator(BaseEvaluator):
+    _parser = PythonParser()
+
+    def _parse_answers(self, answer_path: str, temp_dir: str = None) -> List[str]:
+        td = temp_dir or "temp_python_{}".format(os.getpid())
+        return self._parser.parse(answer_path, temp_dir=td)
+
+    def _build_prompt(self, combined_content: str) -> str:
+        return build_python_prompt(combined_content)

quantumchecker-1.0.0/QuantumCheck/evaluators/sql.py

@@ -0,0 +1,19 @@
+"""SQL homework evaluator."""
+
+import os
+from typing import List
+
+from .base import BaseEvaluator
+from ..parsers.sql import SQLParser
+from ..prompts.sql import build_sql_prompt
+
+
+class SQLEvaluator(BaseEvaluator):
+    _parser = SQLParser()
+
+    def _parse_answers(self, answer_path: str, temp_dir: str = None) -> List[str]:
+        td = temp_dir or "temp_sql_{}".format(os.getpid())
+        return self._parser.parse(answer_path, temp_dir=td)
+
+    def _build_prompt(self, combined_content: str) -> str:
+        return build_sql_prompt(combined_content)

quantumchecker-1.0.0/QuantumCheck/evaluators/ssis.py

@@ -0,0 +1,54 @@
+"""SSIS homework evaluator."""
+
+import logging
+import os
+from typing import Dict, List
+
+from ..config import empty_result
+from ..parsers.ssis import SSISParser
+from ..prompts.ssis import build_ssis_prompt
+
+logger = logging.getLogger(__name__)
+
+
+class SSISEvaluator:
+    """Evaluates SSIS .dtsx submissions.
+
+    Unlike the text-based evaluators, SSIS requires structured XML parsing,
+    so it does not extend BaseEvaluator.
+    """
+
+    def __init__(self, model):
+        self.model = model
+        self._parser = SSISParser()
+
+    def evaluate(self, questions: List[str], answer_path: str, temp_dir: str = None) -> Dict:
+        try:
+            td = temp_dir or "temp_ssis_{}".format(os.getpid())
+            parsed = self._parser.parse(answer_path, temp_dir=td)
+
+            answers = parsed.get("text_answers", [])
+            structured = parsed.get("structured_data", {"issues": []})
+
+            # Align answer count with questions
+            if not answers:
+                answers = ["No valid SSIS components found"] * len(questions)
+            elif len(answers) < len(questions):
+                answers = [answers[i % len(answers)] for i in range(len(questions))]
+            elif len(answers) > len(questions):
+                answers = answers[: len(questions)]
+
+            combined_q = "\n".join(q.strip() for q in questions if q.strip())
+            combined_a = "\n".join(a.strip() for a in answers if a.strip())
+            issues = structured.get("issues", [])
+            raw = "Questions:\n{}\n\nAnswers:\n{}\n\nIssues:\n{}".format(
+                combined_q, combined_a, ", ".join(issues) if issues else "None"
+            )
+
+            result = self.model.evaluate(build_ssis_prompt(raw))
+            result["issues"] = result.get("issues", []) + issues
+            return result
+
+        except Exception as exc:
+            logger.error("SSIS evaluation failed: %s", exc)
+            return empty_result(feedback="Evaluation failed: {}".format(exc))