Skip to content

grip_hook.models

grip_hook.models

Data models shared across grip.

The pydantic models double as the JSON schemas sent to LLM providers for structured output, so keep field descriptions precise: the model reads them.

Stage

Bases: StrEnum

Where in the git workflow grip is running.

Source code in src/grip_hook/models.py 
17
18
19
20
21
22
class Stage(StrEnum):
    """Where in the git workflow grip is running."""

    PRE_COMMIT = "pre-commit"
    PRE_PUSH = "pre-push"
    MANUAL = "manual"

Difficulty

Bases: StrEnum

How demanding the questions and grading should be.

Source code in src/grip_hook/models.py 
25
26
27
28
29
30
class Difficulty(StrEnum):
    """How demanding the questions and grading should be."""

    EASY = "easy"
    NORMAL = "normal"
    HARD = "hard"

Question

Bases: BaseModel

One quiz question, generated from the diff.

Source code in src/grip_hook/models.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class Question(BaseModel):
    """One quiz question, generated from the diff."""

    question: str = Field(
        description=(
            "A single, specific question about the change, phrased so a developer who "
            "wrote the code could answer in one to three sentences."
        )
    )
    rubric: str = Field(
        description=(
            "The key points a fully correct answer must cover. Never shown to the "
            "developer; used only for grading."
        )
    )
    focus: str = Field(
        description=(
            "A short label for what the question tests, e.g. 'behaviour', 'edge case', "
            "'motivation', 'risk', 'testing', 'dependency'."
        )
    )

QuestionSet

Bases: BaseModel

The full set of questions for one quiz.

Source code in src/grip_hook/models.py 
56
57
58
59
60
61
62
63
64
65
66
class QuestionSet(BaseModel):
    """The full set of questions for one quiz."""

    summary: str = Field(
        description="One or two sentences describing what the change does, for the developer."
    )
    questions: list[Question] = Field(
        description=f"Exactly {QUESTION_COUNT} questions.",
        min_length=QUESTION_COUNT,
        max_length=QUESTION_COUNT,
    )

Answer

Bases: BaseModel

The developer's answer to a question.

Source code in src/grip_hook/models.py 
69
70
71
72
73
class Answer(BaseModel):
    """The developer's answer to a question."""

    question_index: int
    text: str

QuestionGrade

Bases: BaseModel

The grade for a single answer.

Source code in src/grip_hook/models.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class QuestionGrade(BaseModel):
    """The grade for a single answer."""

    question_index: int = Field(description="Zero-based index of the question being graded.")
    score: int = Field(
        ge=0,
        le=POINTS_PER_QUESTION,
        description=f"Points awarded, from 0 to {POINTS_PER_QUESTION} inclusive.",
    )
    feedback: str = Field(
        description=(
            "One or two sentences: what was right, what was missing or wrong. "
            "Be concrete and refer to the code."
        )
    )

GradeSheet

Bases: BaseModel

Grades for every answer plus an overall verdict.

Source code in src/grip_hook/models.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
class GradeSheet(BaseModel):
    """Grades for every answer plus an overall verdict."""

    grades: list[QuestionGrade] = Field(
        description=f"Exactly one grade per question, {QUESTION_COUNT} in total, in order.",
        min_length=QUESTION_COUNT,
        max_length=QUESTION_COUNT,
    )
    verdict: str = Field(
        description=(
            "One sentence for the developer summarising how well they understand this change."
        )
    )

    @property
    def total(self) -> int:
        """Sum of all per-question scores, capped at :data:`grip_hook.MAX_SCORE`."""
        return min(sum(g.score for g in self.grades), MAX_SCORE)

total property 

total: int

Sum of all per-question scores, capped at :data:grip_hook.MAX_SCORE.

Report

Bases: BaseModel

Everything about one quiz run, persisted as JSON for later inspection.

Source code in src/grip_hook/models.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class Report(BaseModel):
    """Everything about one quiz run, persisted as JSON for later inspection."""

    version: int = 1
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    stage: Stage
    provider: str
    model: str
    diff_digest: str
    passing_score: int
    score: int
    passed: bool
    summary: str
    questions: list[Question]
    answers: list[Answer]
    grades: list[QuestionGrade]
    verdict: str

    @property
    def max_score(self) -> int:
        """The maximum reachable score."""
        return MAX_SCORE

max_score property 

max_score: int

The maximum reachable score.