contracts.py 3.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. """Validated model wire contracts. Evidence always points to supplied source text."""
  2. from dataclasses import dataclass
  3. from typing import Literal
  4. from pydantic import BaseModel, ConfigDict, Field
  5. Level = Literal["unknown", "secondary", "associate", "bachelor", "master", "doctorate"]
  6. class Contract(BaseModel):
  7. """Strict wire model rejecting unexpected fields and implicit type coercion."""
  8. model_config = ConfigDict(extra="forbid", strict=True)
  9. class Evidence(Contract):
  10. """A verbatim CV quotation with inclusive physical line numbers."""
  11. start_line: int = Field(ge=1)
  12. end_line: int = Field(ge=1)
  13. quote: str = Field(min_length=1)
  14. class Section(Contract):
  15. """One CV category's explicit parsing status and source facts."""
  16. status: Literal["ok", "missing", "unparseable"]
  17. facts: list[Evidence]
  18. class Sections(Contract):
  19. """The five supported CV categories, independent of Markdown chapter order."""
  20. summary: Section
  21. skills: Section
  22. history: Section
  23. education: Section
  24. achievements: Section
  25. def all_sections(self) -> tuple[Section, ...]:
  26. """Expose categories without depending on Pydantic storage internals."""
  27. return (
  28. self.summary,
  29. self.skills,
  30. self.history,
  31. self.education,
  32. self.achievements,
  33. )
  34. class CV(Contract):
  35. """Extracted candidate facts and explicitly evidenced highest education level."""
  36. sections: Sections
  37. education_level: Level
  38. class Requirement(Contract):
  39. """One independently checkable job qualification with its original wording."""
  40. id: str = Field(min_length=1)
  41. quote: str = Field(min_length=1)
  42. category: Literal["mandatory", "general", "bonus"]
  43. minimum_education: Level
  44. class ParsedJob(Contract):
  45. """A source job's scoring requirements and quoted non-scoring background."""
  46. row: int = Field(ge=2)
  47. status: Literal["ok", "missing", "unparseable"]
  48. requirements: list[Requirement]
  49. background: list[str] = Field(default_factory=list)
  50. class ParsedJobs(Contract):
  51. """Every parsed job, preserving original CSV record order."""
  52. jobs: list[ParsedJob]
  53. class Assessment(Contract):
  54. """An evidence-based judgment for one identified qualification."""
  55. requirement_id: str
  56. verdict: Literal["match", "mismatch", "unknown"]
  57. reason: str = Field(min_length=1)
  58. cv_evidence: list[Evidence]
  59. class Match(Contract):
  60. """Model-reasoned score, rationale and assessments for one source job."""
  61. row: int = Field(ge=2)
  62. score: float | None = Field(ge=0, le=100, allow_inf_nan=False)
  63. reason: str = Field(min_length=1)
  64. assessments: list[Assessment]
  65. class Matches(Contract):
  66. """One model evaluation per source job, validated before presentation."""
  67. jobs: list[Match]
  68. @dataclass(frozen=True)
  69. class JobRow:
  70. """Raw CSV display fields paired with a stable physical record identity."""
  71. row: int # physical starting line, including quoted multiline CSV records
  72. fields: dict[str, str]
  73. EvaluationState = Literal["ranked", "unable", "eliminated"]
  74. @dataclass(frozen=True)
  75. class EvaluatedJob:
  76. """Source, parsed requirements and validated evaluation kept together."""
  77. source: JobRow
  78. parsed: ParsedJob
  79. match: Match
  80. state: EvaluationState