feat: add Apec listing artifact models

src/job_research/models.py

@@ -21,6 +21,40 @@ class WarningItem(BaseModel):
     message: str
 
 
+class ListingWarning(BaseModel):
+    field: str
+    message: str
+
+
+class ListingError(BaseModel):
+    url: str
+    stage: str
+    message: str
+
+
+class ApecListing(BaseModel):
+    source: str
+    source_job_id: str | None = None
+    url: str
+    title: str | None = None
+    company: str | None = None
+    location: str | None = None
+    contract_type: str | None = None
+    description_text: str | None = None
+    published_at: str | None = None
+    fetched_at: str
+    warnings: list[ListingWarning] = Field(default_factory=list)
+
+
+class ApecRunMeta(BaseModel):
+    derived_queries: list[str] = Field(default_factory=list)
+    fetched_count: int = 0
+    normalized_count: int = 0
+    deduplicated_count: int = 0
+    failed_count: int = 0
+    listing_errors: list[ListingError] = Field(default_factory=list)
+
+
 class CandidateProfileOutput(BaseModel):
     name: str | None = None
     summary: str | None = None

tests/test_apec_storage.py

@@ -0,0 +1,34 @@
+from job_research.models import ApecListing, ApecRunMeta, ListingWarning
+
+
+def test_apec_models_serialize_expected_listing_shape() -> None:
+    listing = ApecListing(
+        source="apec",
+        source_job_id="123",
+        url="https://example.test/job/123",
+        title="Data Engineer",
+        company="Example",
+        location="Paris",
+        contract_type="CDI",
+        description_text="Build pipelines",
+        published_at="2026-06-01",
+        fetched_at="2026-06-01T10:00:00Z",
+        warnings=[
+            ListingWarning(
+                field="location",
+                message="Location inferred from page text",
+            )
+        ],
+    )
+    run_meta = ApecRunMeta(
+        derived_queries=["Data Engineer"],
+        fetched_count=1,
+        normalized_count=1,
+        deduplicated_count=1,
+        failed_count=0,
+        listing_errors=[],
+    )
+
+    assert listing.model_dump()["source"] == "apec"
+    assert listing.model_dump()["warnings"][0]["field"] == "location"
+    assert run_meta.model_dump()["derived_queries"] == ["Data Engineer"]