by-qa 0.4.2__tar.gz → 0.4.3.dev1__tar.gz

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/.env.example

@@ -69,6 +69,23 @@ KNOWLEDGE_ENTITY_REAPER_SECONDS=30
 KNOWLEDGE_ENTITY_WORKER_STATUS_LOG_SECONDS=60
 # Maximum wait for active tasks during graceful service shutdown.
 KNOWLEDGE_ENTITY_SHUTDOWN_GRACE_SECONDS=60
+
+# Independent durable File Build background processing. This pool does not
+# share its process-local concurrency limit with KnowledgeEntity work.
+KNOWLEDGE_BUILD_WORKER_ENABLED=true
+# Leave blank to generate hostname:pid:random-suffix automatically.
+KNOWLEDGE_BUILD_WORKER_ID=
+# Maximum concurrent file builds per worker process.
+KNOWLEDGE_BUILD_WORKER_CONCURRENCY=16
+KNOWLEDGE_BUILD_WORKER_POLL_SECONDS=3
+# Timeout and lease loss are terminal failures and are not retried.
+KNOWLEDGE_BUILD_TASK_TIMEOUT_SECONDS=1200
+KNOWLEDGE_BUILD_LEASE_SECONDS=180
+# Must be shorter than KNOWLEDGE_BUILD_LEASE_SECONDS.
+KNOWLEDGE_BUILD_HEARTBEAT_SECONDS=30
+KNOWLEDGE_BUILD_REAPER_SECONDS=30
+KNOWLEDGE_BUILD_WORKER_STATUS_LOG_SECONDS=60
+KNOWLEDGE_BUILD_SHUTDOWN_GRACE_SECONDS=60
 # Optional module:attribute provider implementing KnowledgeEventPublisher.
 # It receives semantic Discovery/Enrich events and file/directory mutation events.
 BY_QA_EVENT_PUBLISHER_PROVIDER=

by_qa-0.4.3.dev1/CONTEXT.md

@@ -0,0 +1,54 @@
+# by-qa Domain Language
+
+by-qa manages knowledge files and the derived content that makes those files
+searchable and usable by question-answering flows.
+
+## Knowledge construction
+
+**Knowledge File**:
+A stable file identity inside a knowledge base, independent of its current name
+or path.
+_Avoid_: File path, document path
+
+**File Build**:
+The complete derivation of Markdown, chunks, embeddings, and retrieval data from
+one Knowledge File. Its only model dependency is the embedding model.
+_Avoid_: Embedding task, Markdown conversion
+
+**Build Batch**:
+One accepted File Build request and the newly created File Build Tasks that it
+owns. Files matched to existing tasks are reported as reuse hits but do not
+belong to the new batch.
+_Avoid_: Parent task, job
+
+**File Build Task**:
+One durable attempt to build one Knowledge File from a captured content checksum
+and Build Profile.
+_Avoid_: Batch item, file path task
+
+**Reuse Hit**:
+An acceptance outcome in which an equivalent active, successful, or unsupported
+File Build Task already exists, so the current Build Batch creates no task for
+that file.
+_Avoid_: Reused batch task, shared task
+
+**Build Profile**:
+The readable, canonical description of the parser, chunking, embedding, and
+retrieval protocol that determines File Build output.
+_Avoid_: Build hash, model version
+
+**Built Content**:
+Derived data whose latest task succeeded with the Knowledge File's current
+checksum and whose Markdown, chunks, embeddings, and retrieval data are still
+present.
+_Avoid_: Latest task, protocol freshness
+
+**Protocol Freshness**:
+Whether Built Content was produced by the current Build Profile. A profile
+change does not trigger File Build by itself.
+_Avoid_: Content freshness, file freshness
+
+**Inline File Build**:
+A File Build owned and synchronously completed by an Entity processing task,
+without joining an externally requested Build Batch.
+_Avoid_: Priority build, nested batch

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: by-qa
-Version: 0.4.2
+Version: 0.4.3.dev1
 Summary: Open-source knowledge-base ingestion and retrieval service.
 Author: AI Assistant
 License: MIT
@@ -22,7 +22,7 @@ Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: all
 Requires-Dist: aioboto3>=13.0.0; extra == 'all'
 Requires-Dist: aiosqlite>=0.20.0; extra == 'all'
-Requires-Dist: by-framework==0.2.2.dev11; extra == 'all'
+Requires-Dist: by-framework==v0.2.2.dev15; extra == 'all'
 Requires-Dist: fastapi>=0.115.0; extra == 'all'
 Requires-Dist: jieba>=0.42.1; extra == 'all'
 Requires-Dist: json-repair==0.52.2; extra == 'all'
@@ -61,7 +61,7 @@ Requires-Dist: requests>=2.32.0; extra == 'eval'
 Requires-Dist: tqdm>=4.67.0; extra == 'eval'
 Provides-Extra: knowledge
 Requires-Dist: aioboto3>=13.0.0; extra == 'knowledge'
-Requires-Dist: by-framework==0.2.2.dev11; extra == 'knowledge'
+Requires-Dist: by-framework==v0.2.2.dev15; extra == 'knowledge'
 Requires-Dist: fastapi>=0.115.0; extra == 'knowledge'
 Requires-Dist: jieba>=0.42.1; extra == 'knowledge'
 Requires-Dist: json-repair==0.52.2; extra == 'knowledge'
@@ -81,7 +81,7 @@ Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'knowledge'
 Requires-Dist: xlrd>=2.0.0; extra == 'knowledge'
 Provides-Extra: qa
 Requires-Dist: aiosqlite>=0.20.0; extra == 'qa'
-Requires-Dist: by-framework==0.2.2.dev11; extra == 'qa'
+Requires-Dist: by-framework==v0.2.2.dev15; extra == 'qa'
 Requires-Dist: json-repair==0.52.2; extra == 'qa'
 Requires-Dist: langchain-core==1.3.3; extra == 'qa'
 Requires-Dist: langchain-openai>=0.2.0; extra == 'qa'

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "by-qa"
-version = "0.4.2"
+version = "0.4.3.dev1"
 description = "Open-source knowledge-base ingestion and retrieval service."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -49,7 +49,7 @@ knowledge = [
     "python-pptx>=1.0.2",
     "xlrd>=2.0.0",
     "jieba>=0.42.1",
-    "by-framework==0.2.2.dev11",
+    "by-framework==v0.2.2.dev15",
     "json_repair==0.52.2",
     "lxml==6.1.0",
     "urllib3==2.7.0",
@@ -64,7 +64,7 @@ qa = [
     "langgraph-checkpoint-sqlite>=2.0.0",
     "psycopg[binary]>=3.2.0",
     "aiosqlite>=0.20.0",
-    "by-framework==0.2.2.dev11",
+    "by-framework==v0.2.2.dev15",
     "json_repair==0.52.2",
     "langsmith==0.8.0",
     "lxml==6.1.0",
@@ -91,7 +91,7 @@ all = [
     "langgraph-checkpoint-postgres>=2.0.0",
     "langgraph-checkpoint-sqlite>=2.0.0",
     "aiosqlite>=0.20.0",
-    "by-framework==0.2.2.dev11",
+    "by-framework==v0.2.2.dev15",
     "json_repair==0.52.2",
     "jieba>=0.42.1",
     "langsmith==0.8.0",

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/config.py

@@ -225,6 +225,54 @@ class Settings(BaseSettings):
         ge=0,
         alias="KNOWLEDGE_ENTITY_SHUTDOWN_GRACE_SECONDS",
     )
+    knowledge_build_worker_enabled: bool = Field(
+        default=True,
+        alias="KNOWLEDGE_BUILD_WORKER_ENABLED",
+    )
+    knowledge_build_worker_id: str = Field(
+        default="",
+        alias="KNOWLEDGE_BUILD_WORKER_ID",
+    )
+    knowledge_build_worker_concurrency: int = Field(
+        default=16,
+        ge=1,
+        alias="KNOWLEDGE_BUILD_WORKER_CONCURRENCY",
+    )
+    knowledge_build_worker_poll_seconds: float = Field(
+        default=3.0,
+        gt=0,
+        alias="KNOWLEDGE_BUILD_WORKER_POLL_SECONDS",
+    )
+    knowledge_build_task_timeout_seconds: float = Field(
+        default=1200.0,
+        gt=0,
+        alias="KNOWLEDGE_BUILD_TASK_TIMEOUT_SECONDS",
+    )
+    knowledge_build_lease_seconds: int = Field(
+        default=180,
+        ge=2,
+        alias="KNOWLEDGE_BUILD_LEASE_SECONDS",
+    )
+    knowledge_build_heartbeat_seconds: float = Field(
+        default=30.0,
+        gt=0,
+        alias="KNOWLEDGE_BUILD_HEARTBEAT_SECONDS",
+    )
+    knowledge_build_reaper_seconds: float = Field(
+        default=30.0,
+        gt=0,
+        alias="KNOWLEDGE_BUILD_REAPER_SECONDS",
+    )
+    knowledge_build_worker_status_log_seconds: float = Field(
+        default=60.0,
+        gt=0,
+        alias="KNOWLEDGE_BUILD_WORKER_STATUS_LOG_SECONDS",
+    )
+    knowledge_build_shutdown_grace_seconds: float = Field(
+        default=60.0,
+        ge=0,
+        alias="KNOWLEDGE_BUILD_SHUTDOWN_GRACE_SECONDS",
+    )
     entity_embedding_index_enabled: bool = Field(
         default=True,
         alias="ENTITY_EMBEDDING_INDEX_ENABLED",
@@ -298,6 +346,17 @@ class Settings(BaseSettings):
             )
         return value
 
+    @field_validator("knowledge_build_heartbeat_seconds")
+    @classmethod
+    def _validate_knowledge_build_heartbeat_seconds(cls, value: float, info) -> float:
+        lease_seconds = info.data.get("knowledge_build_lease_seconds", 180)
+        if value >= lease_seconds:
+            raise ValueError(
+                "KNOWLEDGE_BUILD_HEARTBEAT_SECONDS must be less than "
+                "KNOWLEDGE_BUILD_LEASE_SECONDS"
+            )
+        return value
+
     @field_validator(
         "llm_standard_extra_body", "llm_lightweight_extra_body", mode="before"
     )

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/knowledge_base/api/knowledge_entity_schemas.py

@@ -6,7 +6,14 @@ from datetime import datetime
 from enum import StrEnum
 from typing import Any, Protocol
 
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
 
 
 class _ApiModel(BaseModel):
@@ -54,6 +61,7 @@ class ProcessingEligibility(StrEnum):
 class ProcessingTaskType(StrEnum):
     ENTITY_DISCOVERY = "ENTITY_DISCOVERY"
     DOCUMENT_ENRICH = "DOCUMENT_ENRICH"
+    FILE_BUILD = "FILE_BUILD"
 
 
 class ProcessingTaskStatus(StrEnum):
@@ -63,6 +71,7 @@ class ProcessingTaskStatus(StrEnum):
     FAILED = "FAILED"
     CANCELLED = "CANCELLED"
     SKIPPED = "SKIPPED"
+    UNSUPPORTED = "UNSUPPORTED"
 
 
 class ProcessingScope(StrEnum):
@@ -72,6 +81,7 @@ class ProcessingScope(StrEnum):
 
 
 class ProcessingBatchStatus(StrEnum):
+    PENDING = "PENDING"
     PROCESSING = "PROCESSING"
     COMPLETED = "COMPLETED"
 
@@ -202,6 +212,16 @@ class ProcessingTaskStatusRequest(_ApiModel):
         min_length=1,
         validation_alias=AliasChoices("knCode", "kb_code"),
     )
+    task_id: int | None = Field(
+        default=None,
+        gt=0,
+        validation_alias=AliasChoices("taskId", "task_id"),
+    )
+    file_id: int | None = Field(
+        default=None,
+        gt=0,
+        validation_alias=AliasChoices("fileId", "file_id"),
+    )
     file_path: str | None = Field(
         default=None,
         validation_alias=AliasChoices("filePath", "file_path"),
@@ -251,6 +271,12 @@ class ProcessingTaskStatusRequest(_ApiModel):
             raise ValueError("statusList must not contain duplicate values")
         return value
 
+    @model_validator(mode="after")
+    def validate_exact_task_query(self) -> "ProcessingTaskStatusRequest":
+        if self.task_id is not None and self.task_type is None:
+            raise ValueError("taskType is required when taskId is provided")
+        return self
+
 
 class ProcessingBatchStatusRequest(_ApiModel):
     """Query one durable batch and its per-file progress."""
@@ -368,7 +394,32 @@ class ProcessingTaskItem(_ApiModel):
     current_stage: str | None = Field(default=None, serialization_alias="currentStage")
     progress: int | None = Field(default=None, ge=0, le=100)
     file_id: str | None = Field(serialization_alias="fileId")
-    file_path: str = Field(serialization_alias="filePath")
+    file_path: str | None = Field(default=None, serialization_alias="filePath")
+    file_path_snapshot: str | None = Field(
+        default=None, serialization_alias="filePathSnapshot"
+    )
+    origin: str | None = None
+    execution_mode: str | None = Field(
+        default=None, serialization_alias="executionMode"
+    )
+    parent_semantic_task_id: str | None = Field(
+        default=None, serialization_alias="parentSemanticTaskId"
+    )
+    input_checksum: str | None = Field(
+        default=None, serialization_alias="inputChecksum"
+    )
+    input_is_deleted: bool | None = Field(
+        default=None, serialization_alias="inputIsDeleted"
+    )
+    build_profile: dict[str, Any] | None = Field(
+        default=None, serialization_alias="buildProfile"
+    )
+    build_profile_hash: str | None = Field(
+        default=None, serialization_alias="buildProfileHash"
+    )
+    outcome_uncertain: bool | None = Field(
+        default=None, serialization_alias="outcomeUncertain"
+    )
     index_version: str | None = Field(default=None, serialization_alias="indexVersion")
     created_at: datetime = Field(serialization_alias="createdAt")
     started_at: datetime | None = Field(default=None, serialization_alias="startedAt")
@@ -393,6 +444,7 @@ class ProcessingBatchStatusResult(_ApiModel):
     kb_code: str = Field(serialization_alias="knCode")
     task_type: ProcessingTaskType = Field(serialization_alias="taskType")
     scope: ProcessingScope
+    target_path: str | None = Field(default=None, serialization_alias="targetPath")
     status: ProcessingBatchStatus
     version: int = Field(ge=0)
     total_count: int = Field(ge=0, serialization_alias="totalCount")
@@ -402,6 +454,24 @@ class ProcessingBatchStatusResult(_ApiModel):
     succeeded_count: int = Field(ge=0, serialization_alias="succeededCount")
     failed_count: int = Field(ge=0, serialization_alias="failedCount")
     skipped_count: int = Field(ge=0, serialization_alias="skippedCount")
+    unsupported_count: int = Field(
+        default=0, ge=0, serialization_alias="unsupportedCount"
+    )
+    candidate_count: int | None = Field(
+        default=None, ge=0, serialization_alias="candidateCount"
+    )
+    eligible_count: int | None = Field(
+        default=None, ge=0, serialization_alias="eligibleCount"
+    )
+    accepted_count: int | None = Field(
+        default=None, ge=0, serialization_alias="acceptedCount"
+    )
+    reused_count: int | None = Field(
+        default=None, ge=0, serialization_alias="reusedCount"
+    )
+    acceptance_skipped_count: int | None = Field(
+        default=None, ge=0, serialization_alias="acceptanceSkippedCount"
+    )
     progress: int = Field(ge=0, le=100)
     created_at: datetime = Field(serialization_alias="createdAt")
     completed_at: datetime | None = Field(

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/knowledge_base/api/routes.py

@@ -251,15 +251,6 @@ def register_routes(
 ):
     """Register knowledge base API routes on the FastAPI app."""
 
-    async def _run_file_to_markdown_index_task(service, request, *, build_task_id: int):
-        """Resolve heavy dependencies inside the background task itself."""
-        chunking_service = await _resolve_maybe_async(get_document_chunking_service)
-        await service.execute_file_to_markdown_index_task(
-            request,
-            document_chunking_service=chunking_service,
-            build_task_id=build_task_id,
-        )
-
     async def _get_knowledge_entity_service() -> KnowledgeEntityProcessingService:
         if get_knowledge_entity_processing_service is None:
             raise KnowledgeBaseConfigurationError(
@@ -1116,7 +1107,7 @@ def register_routes(
 
     @app.post("/api/v1/fileToMarkdownIndex")
     async def file_to_markdown_index(
-        background_tasks: BackgroundTasks, body: dict[str, Any] = Body(...)
+        body: dict[str, Any] = Body(...),
     ):
         logger.info(
             "file_to_markdown_index request received: body_keys=%s",
@@ -1132,13 +1123,7 @@ def register_routes(
 
         try:
             service = await get_knowledge_item_ingestion_service()
-            build_task_id = await service.create_file_to_markdown_index_task(request)
-            background_tasks.add_task(
-                _run_file_to_markdown_index_task,
-                service,
-                request,
-                build_task_id=build_task_id,
-            )
+            result = await service.accept_file_to_markdown_index(request)
         except KnowledgeBaseConfigurationError as exc:
             logger.warning("file_to_markdown_index configuration failed: error=%s", exc)
             return _documented_error_response(
@@ -1159,7 +1144,10 @@ def register_routes(
             request.kb_code,
             request.file_path,
         )
-        return _documented_success_response()
+        return _documented_success_response(
+            result_object=result,
+            result_msg="accepted",
+        )
 
     @app.post("/api/v1/fileBuildStatus")
     async def file_build_status(body: dict[str, Any] = Body(...)):
@@ -1915,8 +1903,15 @@ def register_routes(
             request.batch_id,
         )
         try:
-            service = await _get_knowledge_entity_service()
-            result = await service.get_processing_task_status(request)
+            ingestion_service = await get_knowledge_item_ingestion_service()
+            build_service = getattr(
+                ingestion_service, "file_build_processing_service", None
+            )
+            if build_service is not None:
+                result = await build_service.get_unified_processing_task_status(request)
+            else:
+                service = await _get_knowledge_entity_service()
+                result = await service.get_processing_task_status(request)
         except KnowledgeBaseConfigurationError as exc:
             return _documented_error_response(
                 result_msg=str(exc),
@@ -1956,8 +1951,15 @@ def register_routes(
             request.batch_id,
         )
         try:
-            service = await _get_knowledge_entity_service()
-            result = await service.get_processing_batch_status(request)
+            result = None
+            if request.batch_id.startswith("fb-"):
+                ingestion_service = await get_knowledge_item_ingestion_service()
+                result = await ingestion_service.file_build_processing_service.get_processing_batch_status(
+                    request
+                )
+            if result is None:
+                service = await _get_knowledge_entity_service()
+                result = await service.get_processing_batch_status(request)
         except KnowledgeBaseConfigurationError as exc:
             return _documented_error_response(
                 result_msg=str(exc),

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/knowledge_base/api/schemas.py

@@ -240,7 +240,7 @@ class MoveKnowledgeItemsResponse(BaseModel):
 
 
 class FileToMarkdownIndexRequest(BaseModel):
-    """Request body for triggering knowledge build on an uploaded file."""
+    """Request body for accepting a file or directory build batch."""
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -252,6 +252,7 @@ class FileToMarkdownIndexRequest(BaseModel):
         min_length=1,
         validation_alias=AliasChoices("filePath", "file_path"),
     )
+    force: bool = False
 
 
 class FileBuildStatusRequest(BaseModel):

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/knowledge_base/build_status.py

@@ -7,6 +7,7 @@ from typing import Final
 BUILD_STATUS_COMPLETE: Final[str] = "complete"
 BUILD_STATUS_FAILED: Final[str] = "failed"
 BUILD_STATUS_RUNNING: Final[str] = "running"
+BUILD_STATUS_SKIPPED: Final[str] = "skipped"
 BUILD_STATUS_UNSUPPORTED: Final[str] = "unsupported"
 
 BUILD_STEP_MARKDOWN: Final[str] = "markdown"
@@ -30,6 +31,11 @@ STATUS_DICT: Final[list[dict[str, str]]] = [
         "standDisplayValue": "构建中",
         "standDisplayValueEn": BUILD_STATUS_RUNNING,
     },
+    {
+        "standCode": BUILD_STATUS_SKIPPED,
+        "standDisplayValue": "已跳过",
+        "standDisplayValueEn": BUILD_STATUS_SKIPPED,
+    },
     {
         "standCode": BUILD_STATUS_UNSUPPORTED,
         "standDisplayValue": "不支持构建",
@@ -59,3 +65,36 @@ STEP_DICT: Final[list[dict[str, str]]] = [
         "standDisplayValueEn": BUILD_STEP_COMPLETE,
     },
 ]
+
+
+def legacy_build_status(status: str | None) -> str | None:
+    """Map the durable lifecycle onto the legacy status vocabulary."""
+    normalized = (status or "").lower()
+    if normalized in {"pending", "running"}:
+        return BUILD_STATUS_RUNNING
+    if normalized in {"succeeded", "complete"}:
+        return BUILD_STATUS_COMPLETE
+    if normalized in {
+        BUILD_STATUS_FAILED,
+        BUILD_STATUS_SKIPPED,
+        BUILD_STATUS_UNSUPPORTED,
+    }:
+        return normalized
+    return status
+
+
+def legacy_build_step(
+    *, status: str | None, current_step: str | None, current_stage: str | None
+) -> str | None:
+    """Map new milestones onto the four legacy build steps."""
+    if legacy_build_status(status) == BUILD_STATUS_COMPLETE:
+        return BUILD_STEP_COMPLETE
+    normalized_stage = (current_stage or "").lower()
+    stage_steps = {
+        "accepted": BUILD_STEP_MARKDOWN,
+        "extracting": BUILD_STEP_MARKDOWN,
+        "chunking": BUILD_STEP_CHUNKING,
+        "embedding": BUILD_STEP_VECTORIZING,
+        "committing": BUILD_STEP_VECTORIZING,
+    }
+    return stage_steps.get(normalized_stage, current_step)

{by_qa-0.4.2 → by_qa-0.4.3.dev1}/src/by_qa/knowledge_base/events.py

@@ -46,6 +46,7 @@ class SemanticEventType(StrEnum):
 
 class BuildEventType(StrEnum):
     FILE_COMPLETED = "build.file.completed"
+    BATCH_COMPLETED = "build.batch.completed"
 
 
 class _StrictEventModel(BaseModel):
@@ -198,6 +199,46 @@ class BuildFileCompletedPayload(_StrictEventModel):
         return self
 
 
+class FileBuildTerminalPayload(_StrictEventModel):
+    batch_id: str = Field(alias="batchId")
+    task_id: str = Field(alias="taskId")
+    task_type: Literal["FILE_BUILD"] = Field(default="FILE_BUILD", alias="taskType")
+    file_id: str = Field(alias="fileId")
+    file_path_snapshot: str = Field(alias="filePathSnapshot")
+    status: Literal["SUCCEEDED", "FAILED", "SKIPPED", "UNSUPPORTED"]
+    stage: Literal["ACCEPTED", "EXTRACTING", "CHUNKING", "EMBEDDING", "COMMITTING"]
+    progress: Literal[100] = 100
+    result: BuildFileCompletedResult | None
+    error: BuildProcessingError | None
+
+    @model_validator(mode="after")
+    def _validate_terminal_shape(self) -> FileBuildTerminalPayload:
+        if self.status == "SUCCEEDED":
+            if self.result is None or self.error is not None:
+                raise ValueError("successful file build requires result only")
+        elif self.result is not None or self.error is None:
+            raise ValueError("non-successful file build requires error only")
+        return self
+
+
+class FileBuildBatchTerminalPayload(_StrictEventModel):
+    batch_id: str = Field(alias="batchId")
+    task_type: Literal["FILE_BUILD"] = Field(default="FILE_BUILD", alias="taskType")
+    scope: Literal["SINGLE_FILE", "DIRECTORY"]
+    target_path: str = Field(alias="targetPath")
+    candidate_count: int = Field(ge=0, alias="candidateCount")
+    eligible_count: int = Field(ge=0, alias="eligibleCount")
+    accepted_count: int = Field(ge=0, alias="acceptedCount")
+    reused_count: int = Field(ge=0, alias="reusedCount")
+    acceptance_skipped_count: int = Field(ge=0, alias="acceptanceSkippedCount")
+    total_count: int = Field(ge=0, alias="totalCount")
+    completed_count: int = Field(ge=0, alias="completedCount")
+    succeeded_count: int = Field(ge=0, alias="succeededCount")
+    failed_count: int = Field(ge=0, alias="failedCount")
+    skipped_count: int = Field(ge=0, alias="skippedCount")
+    unsupported_count: int = Field(ge=0, alias="unsupportedCount")
+
+
 class _KnowledgeEventBase(_StrictEventModel):
     event_id: str = Field(alias="eventId")
     event_version: Literal[1] = Field(default=EVENT_VERSION, alias="eventVersion")
@@ -282,11 +323,29 @@ class EnrichBatchCompletedEvent(_KnowledgeEventBase):
     payload: SemanticBatchCompletedPayload
 
 
-class BuildFileCompletedEvent(_KnowledgeEventBase):
+class BuildFileCompletedEvent(_StrictEventModel):
+    event_id: str = Field(alias="eventId")
+    event_version: Literal[1, 2] = Field(default=1, alias="eventVersion")
+    kb_code: str = Field(alias="knCode")
+    occurred_at: datetime = Field(alias="occurredAt")
     event_type: Literal["build.file.completed"] = Field(
         default=BuildEventType.FILE_COMPLETED.value, alias="eventType"
     )
-    payload: BuildFileCompletedPayload
+    payload: BuildFileCompletedPayload | FileBuildTerminalPayload
+
+
+class _KnowledgeEventV2Base(_StrictEventModel):
+    event_id: str = Field(alias="eventId")
+    event_version: Literal[2] = Field(default=2, alias="eventVersion")
+    kb_code: str = Field(alias="knCode")
+    occurred_at: datetime = Field(alias="occurredAt")
+
+
+class FileBuildBatchTerminalEvent(_KnowledgeEventV2Base):
+    event_type: Literal["build.batch.completed"] = Field(
+        default=BuildEventType.BATCH_COMPLETED.value, alias="eventType"
+    )
+    payload: FileBuildBatchTerminalPayload
 
 
 _KnowledgeEventUnion: TypeAlias = (
@@ -302,6 +361,7 @@ _KnowledgeEventUnion: TypeAlias = (
     | EnrichFileCompletedEvent
     | EnrichBatchCompletedEvent
     | BuildFileCompletedEvent
+    | FileBuildBatchTerminalEvent
 )
 KnowledgeEvent: TypeAlias = Annotated[
     _KnowledgeEventUnion, Field(discriminator="event_type")
@@ -485,6 +545,71 @@ def build_file_completed_event(
     )
 
 
+def build_file_build_terminal_event(
+    task: Mapping[str, Any],
+) -> BuildFileCompletedEvent:
+    """Build the eventVersion 2 terminal event for an external Build task."""
+    status = str(task["status"]).upper()
+    result_payload = normalize_json_mapping(task.get("result_payload"))
+    result = None
+    error = None
+    if status == "SUCCEEDED":
+        result = BuildFileCompletedResult(
+            chunk_count=int((result_payload or {}).get("chunkCount") or 0),
+            line_count=int((result_payload or {}).get("lineCount") or 0),
+        )
+    else:
+        error = BuildProcessingError(
+            code=str(task.get("error_code") or "BUILD_FAILED"),
+            message=str(task.get("error_message") or "file build did not succeed"),
+        )
+    return BuildFileCompletedEvent(
+        **_event_fields(
+            kb_code=str(task.get("kb_code") or task["knowledge_base_id"]),
+            occurred_at=task.get("finished_at"),
+        ),
+        event_version=2,
+        payload=FileBuildTerminalPayload(
+            batch_id=str(task["batch_id"]),
+            task_id=str(task["kid"]),
+            file_id=str(task["fs_entry_id"]),
+            file_path_snapshot=str(task["file_path_snapshot"]),
+            status=status,
+            stage=str(task["current_stage"]).upper(),
+            result=result,
+            error=error,
+        ),
+    )
+
+
+def build_file_build_batch_terminal_event(
+    batch: Mapping[str, Any], counts: Mapping[str, int]
+) -> FileBuildBatchTerminalEvent:
+    """Build the eventVersion 2 aggregate event for a completed Build batch."""
+    return FileBuildBatchTerminalEvent(
+        **_event_fields(
+            kb_code=str(batch.get("kb_code") or batch["knowledge_base_id"]),
+            occurred_at=batch.get("completed_at"),
+        ),
+        payload=FileBuildBatchTerminalPayload(
+            batch_id=str(batch["batch_id"]),
+            scope=str(batch["scope"]).upper(),
+            target_path=str(batch["target_path_snapshot"]),
+            candidate_count=int(batch["candidate_count"]),
+            eligible_count=int(batch["eligible_count"]),
+            accepted_count=int(batch["accepted_count"]),
+            reused_count=int(batch["reused_count"]),
+            acceptance_skipped_count=int(batch["acceptance_skipped_count"]),
+            total_count=int(batch["accepted_count"]),
+            completed_count=int(batch["completed_count"]),
+            succeeded_count=int(counts.get("succeeded", 0)),
+            failed_count=int(counts.get("failed", 0)),
+            skipped_count=int(counts.get("skipped", 0)),
+            unsupported_count=int(counts.get("unsupported", 0)),
+        ),
+    )
+
+
 def _semantic_event_classes(task_type: str):
     if task_type == "ENTITY_DISCOVERY":
         return DiscoveryFileCompletedEvent, DiscoveryBatchCompletedEvent