busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

semantics: complete DEF-to-region migration, fix regressions

Browse Source 
- Convert legacy [DEF🆔Type] anchors to #region/#endregion across 329 files
- Reinstate _normalize_timestamp_value in sql_generator.py
- Fix MarkerLogger→logger migration in events.py (molecular CoT markers)
- Fix dataset_review orchestrator dependencies (_build_execution_snapshot)
- Fix config_manager stale-record deletion (moved to save path only)
- Add 77 missing [/DEF:] closers in 5 unbalanced test files
- Update assistant_chat.integration.test.js for #region format
- Apply molecular-cot-logging markers (REASON/REFLECT/EXPLORE) via logger.* methods
This commit is contained in:
busya
2026-05-12 23:54:55 +03:00
parent fe8978f716
commit 306c5ae742
331 changed files with 9630 additions and 10312 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
backend/src/models/__init__.py
View File

@@ -1,2 +1,3 @@
# #region ModelsPackage [C:1] [TYPE Package]
# #region ModelsPackage [TYPE Package]
# @BRIEF Domain model package root.
# #endregion ModelsPackage

72
backend/src/models/__tests__/test_clean_release.py
View File

@@ -1,7 +1,7 @@
# #region TestCleanReleaseModels [TYPE Module]
# @BRIEF Contract testing for Clean Release models
# @RELATION VERIFIES -> [CleanReleaseModels]
# #endregion TestCleanReleaseModels
# [DEF:TestCleanReleaseModels:Module]
# @RELATION: VERIFIES -> [CleanReleaseModels]
# @PURPOSE: Contract testing for Clean Release models
# [/DEF:TestCleanReleaseModels:Module]
import pytest
from datetime import datetime
@@ -38,21 +38,21 @@ def valid_candidate_data():
}
# #region test_release_candidate_valid [TYPE Function]
# @BRIEF Verify that a valid release candidate can be instantiated.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_release_candidate_valid:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that a valid release candidate can be instantiated.
def test_release_candidate_valid(valid_candidate_data):
rc = ReleaseCandidate(**valid_candidate_data)
assert rc.candidate_id == "RC-001"
assert rc.status == ReleaseCandidateStatus.DRAFT
# #endregion test_release_candidate_valid
# [/DEF:test_release_candidate_valid:Function]
# #region test_release_candidate_empty_id [TYPE Function]
# @BRIEF Verify that a release candidate with an empty ID is rejected.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_release_candidate_empty_id:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that a release candidate with an empty ID is rejected.
def test_release_candidate_empty_id(valid_candidate_data):
valid_candidate_data["candidate_id"] = " "
with pytest.raises(ValueError, match="candidate_id must be non-empty"):
@@ -60,7 +60,7 @@ def test_release_candidate_empty_id(valid_candidate_data):
# @TEST_FIXTURE: valid_enterprise_policy
# #endregion test_release_candidate_empty_id
# [/DEF:test_release_candidate_empty_id:Function]
@pytest.fixture
@@ -78,21 +78,21 @@ def valid_policy_data():
# @TEST_INVARIANT: policy_purity
# #region test_enterprise_policy_valid [TYPE Function]
# @BRIEF Verify that a valid enterprise policy is accepted.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_enterprise_policy_valid:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that a valid enterprise policy is accepted.
def test_enterprise_policy_valid(valid_policy_data):
policy = CleanProfilePolicy(**valid_policy_data)
assert policy.external_source_forbidden is True
# @TEST_EDGE: enterprise_policy_missing_prohibited
# #endregion test_enterprise_policy_valid
# [/DEF:test_enterprise_policy_valid:Function]
# #region test_enterprise_policy_missing_prohibited [TYPE Function]
# @BRIEF Verify that an enterprise policy without prohibited categories is rejected.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_enterprise_policy_missing_prohibited:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that an enterprise policy without prohibited categories is rejected.
def test_enterprise_policy_missing_prohibited(valid_policy_data):
valid_policy_data["prohibited_artifact_categories"] = []
with pytest.raises(
@@ -103,12 +103,12 @@ def test_enterprise_policy_missing_prohibited(valid_policy_data):
# @TEST_EDGE: enterprise_policy_external_allowed
# #endregion test_enterprise_policy_missing_prohibited
# [/DEF:test_enterprise_policy_missing_prohibited:Function]
# #region test_enterprise_policy_external_allowed [TYPE Function]
# @BRIEF Verify that an enterprise policy allowing external sources is rejected.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_enterprise_policy_external_allowed:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that an enterprise policy allowing external sources is rejected.
def test_enterprise_policy_external_allowed(valid_policy_data):
valid_policy_data["external_source_forbidden"] = False
with pytest.raises(
@@ -120,12 +120,12 @@ def test_enterprise_policy_external_allowed(valid_policy_data):
# @TEST_INVARIANT: manifest_consistency
# @TEST_EDGE: manifest_count_mismatch
# #endregion test_enterprise_policy_external_allowed
# [/DEF:test_enterprise_policy_external_allowed:Function]
# #region test_manifest_count_mismatch [TYPE Function]
# @BRIEF Verify that a manifest with count mismatches is rejected.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_manifest_count_mismatch:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify that a manifest with count mismatches is rejected.
def test_manifest_count_mismatch():
summary = ManifestSummary(
included_count=1, excluded_count=0, prohibited_detected_count=0
@@ -165,12 +165,12 @@ def test_manifest_count_mismatch():
# @TEST_INVARIANT: run_integrity
# @TEST_EDGE: compliant_run_stage_fail
# #endregion test_manifest_count_mismatch
# [/DEF:test_manifest_count_mismatch:Function]
# #region test_compliant_run_validation [TYPE Function]
# @BRIEF Verify compliant run validation logic and mandatory stage checks.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_compliant_run_validation:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify compliant run validation logic and mandatory stage checks.
def test_compliant_run_validation():
base_run = {
"check_run_id": "run1",
@@ -211,12 +211,12 @@ def test_compliant_run_validation():
ComplianceCheckRun(**base_run)
# #endregion test_compliant_run_validation
# [/DEF:test_compliant_run_validation:Function]
# #region test_report_validation [TYPE Function]
# @BRIEF Verify compliance report validation based on status and violation counts.
# @RELATION BINDS_TO -> [TestCleanReleaseModels]
# [DEF:test_report_validation:Function]
# @RELATION: BINDS_TO -> [TestCleanReleaseModels]
# @PURPOSE: Verify compliance report validation based on status and violation counts.
def test_report_validation():
# Valid blocked report
ComplianceReport(
@@ -246,4 +246,4 @@ def test_report_validation():
)
# #endregion test_report_validation
# [/DEF:test_report_validation:Function]

23
backend/src/models/__tests__/test_models.py
View File

@@ -1,7 +1,8 @@
# #region test_models [C:1] [TYPE Module]
# @BRIEF Unit tests for data models
# @LAYER Domain
# @RELATION VERIFIES -> [ModelsPackage]
# [DEF:test_models:Module]
# @COMPLEXITY: 1
# @PURPOSE: Unit tests for data models
# @LAYER: Domain
# @RELATION: VERIFIES -> [ModelsPackage]
import sys
from pathlib import Path
@@ -13,11 +14,11 @@ from src.core.config_models import Environment
from src.core.logger import belief_scope
# #region test_environment_model [TYPE Function]
# @BRIEF Tests that Environment model correctly stores values.
# @PRE Environment class is available.
# @POST Values are verified.
# @RELATION BINDS_TO -> [test_models]
# [DEF:test_environment_model:Function]
# @RELATION: BINDS_TO -> test_models
# @PURPOSE: Tests that Environment model correctly stores values.
# @PRE: Environment class is available.
# @POST: Values are verified.
def test_environment_model():
with belief_scope("test_environment_model"):
env = Environment(
@@ -32,7 +33,7 @@ def test_environment_model():
assert env.url == "http://localhost:8088/api/v1"
# #endregion test_environment_model
# [/DEF:test_environment_model:Function]
# #endregion test_models
# [/DEF:test_models:Module]

11
backend/src/models/__tests__/test_report_models.py
View File

@@ -1,7 +1,8 @@
# #region test_report_models [C:3] [TYPE Module]
# @BRIEF Unit tests for report Pydantic models and their validators
# @LAYER Domain
# @RELATION BELONGS_TO -> [SrcRoot]
# [DEF:test_report_models:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @PURPOSE: Unit tests for report Pydantic models and their validators
# @LAYER: Domain
import sys
from pathlib import Path
@@ -231,4 +232,4 @@ class TestReportDetailView:
assert detail.diagnostics["cause"] == "timeout"
assert "Retry" in detail.next_actions
# #endregion test_report_models
# [/DEF:test_report_models:Module]

24
backend/src/models/assistant.py
View File

@@ -1,8 +1,8 @@
# #region AssistantModels [C:3] [TYPE Module] [SEMANTICS assistant, audit, confirmation, chat]
# @BRIEF SQLAlchemy models for assistant audit trail and confirmation tokens.
# @LAYER Domain
# @INVARIANT Assistant records preserve immutable ids and creation timestamps.
# @RELATION DEPENDS_ON -> [MappingModels]
# @LAYER: Domain
# @RELATION DEPENDS_ON -> MappingModels
# @INVARIANT: Assistant records preserve immutable ids and creation timestamps.
from datetime import datetime
@@ -13,9 +13,9 @@ from .mapping import Base
# #region AssistantAuditRecord [C:3] [TYPE Class]
# @BRIEF Store audit decisions and outcomes produced by assistant command handling.
# @PRE user_id must identify the actor for every record.
# @POST Audit payload remains available for compliance and debugging.
# @RELATION INHERITS -> [MappingModels]
# @RELATION INHERITS -> MappingModels
# @PRE: user_id must identify the actor for every record.
# @POST: Audit payload remains available for compliance and debugging.
class AssistantAuditRecord(Base):
__tablename__ = "assistant_audit"
@@ -34,9 +34,9 @@ class AssistantAuditRecord(Base):
# #region AssistantMessageRecord [C:3] [TYPE Class]
# @BRIEF Persist chat history entries for assistant conversations.
# @PRE user_id, conversation_id, role and text must be present.
# @POST Message row can be queried in chronological order.
# @RELATION INHERITS -> [MappingModels]
# @RELATION INHERITS -> MappingModels
# @PRE: user_id, conversation_id, role and text must be present.
# @POST: Message row can be queried in chronological order.
class AssistantMessageRecord(Base):
__tablename__ = "assistant_messages"
@@ -57,9 +57,9 @@ class AssistantMessageRecord(Base):
# #region AssistantConfirmationRecord [C:3] [TYPE Class]
# @BRIEF Persist risky operation confirmation tokens with lifecycle state.
# @PRE intent/dispatch and expiry timestamp must be provided.
# @POST State transitions can be tracked and audited.
# @RELATION INHERITS -> [MappingModels]
# @RELATION INHERITS -> MappingModels
# @PRE: intent/dispatch and expiry timestamp must be provided.
# @POST: State transitions can be tracked and audited.
class AssistantConfirmationRecord(Base):
__tablename__ = "assistant_confirmations"

8
backend/src/models/auth.py
View File

@@ -1,22 +1,20 @@
# #region AuthModels [C:3] [TYPE Module] [SEMANTICS auth, models, user, role, permission, sqlalchemy]
# @BRIEF SQLAlchemy models for multi-user authentication and authorization.
# @LAYER Domain
# @INVARIANT Usernames and emails must be unique.
# @LAYER: Domain
# @RELATION INHERITS_FROM -> [Base]
#
# @INVARIANT: Usernames and emails must be unique.
# [SECTION: IMPORTS]
import uuid
from datetime import datetime
from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey, Table
from sqlalchemy.orm import relationship
from .mapping import Base
# [/SECTION]
# #region generate_uuid [TYPE Function]
# @BRIEF Generates a unique UUID string.
# @POST Returns a string representation of a new UUID.
# @POST: Returns a string representation of a new UUID.
# @RELATION DEPENDS_ON -> [uuid]
def generate_uuid():
return str(uuid.uuid4())

24
backend/src/models/clean_release.py
View File

@@ -1,12 +1,12 @@
# #region CleanReleaseModels [C:3] [TYPE Module] [SEMANTICS clean-release, models, lifecycle, compliance, evidence, immutability]
# @BRIEF Define canonical clean release domain entities and lifecycle guards.
# @LAYER Domain
# @PRE Base mapping model and release enums are available.
# @POST Provides SQLAlchemy and dataclass definitions for governance domain.
# @SIDE_EFFECT None (schema definition).
# @DATA_CONTRACT Model[ReleaseCandidate, CandidateArtifact, DistributionManifest, ComplianceRun, ComplianceReport]
# @INVARIANT Immutable snapshots are never mutated; forbidden lifecycle transitions are rejected.
# @RELATION DEPENDS_ON -> [MappingModels]
# @LAYER: Domain
# @RELATION DEPENDS_ON -> MappingModels
# @PRE: Base mapping model and release enums are available.
# @POST: Provides SQLAlchemy and dataclass definitions for governance domain.
# @SIDE_EFFECT: None (schema definition).
# @DATA_CONTRACT: Model[ReleaseCandidate, CandidateArtifact, DistributionManifest, ComplianceRun, ComplianceReport]
# @INVARIANT: Immutable snapshots are never mutated; forbidden lifecycle transitions are rejected.
from datetime import datetime
from dataclasses import dataclass
@@ -229,8 +229,8 @@ class ComplianceCheckRun:
# #region ReleaseCandidate [TYPE Class]
# @BRIEF Represents the release unit being prepared and governed.
# @PRE id, version, source_snapshot_ref are non-empty.
# @POST status advances only through legal transitions.
# @PRE: id, version, source_snapshot_ref are non-empty.
# @POST: status advances only through legal transitions.
class ReleaseCandidate(Base):
__tablename__ = "clean_release_candidates"
@@ -328,7 +328,7 @@ class ManifestSummary:
# #region DistributionManifest [TYPE Class]
# @BRIEF Immutable snapshot of the candidate payload.
# @INVARIANT Immutable after creation.
# @INVARIANT: Immutable after creation.
class DistributionManifest(Base):
__tablename__ = "clean_release_manifests"
@@ -579,7 +579,7 @@ class ComplianceViolation(Base):
# #region ComplianceReport [TYPE Class]
# @BRIEF Immutable result derived from a completed run.
# @INVARIANT Immutable after creation.
# @INVARIANT: Immutable after creation.
class ComplianceReport(Base):
__tablename__ = "clean_release_compliance_reports"
@@ -694,4 +694,4 @@ class CleanReleaseAuditLog(Base):
details_json = Column(JSON, default=dict)
# #endregion CleanReleaseAuditLog
# #endregion CleanReleaseModels
# #endregion CleanReleaseModels

24
backend/src/models/config.py
View File

@@ -1,10 +1,10 @@
# #region ConfigModels [C:3] [TYPE Module] [SEMANTICS database, config, settings, sqlalchemy, notification]
# @BRIEF Defines SQLAlchemy persistence models for application and notification configuration records.
# @LAYER Domain
# @INVARIANT Configuration payload and notification credentials must remain persisted as non-null JSON documents.
# @RELATION DEPENDS_ON -> [MappingModels:Base]
#
# @BRIEF Defines SQLAlchemy persistence models for application and notification configuration records.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [MappingModels:Base]
# @INVARIANT: Configuration payload and notification credentials must remain persisted as non-null JSON documents.
from sqlalchemy import Column, String, DateTime, JSON, Boolean
from sqlalchemy.sql import func
@@ -14,10 +14,10 @@ from .mapping import Base
# #region AppConfigRecord [TYPE Class]
# @BRIEF Stores persisted application configuration as a single authoritative record model.
# @PRE SQLAlchemy declarative Base is initialized and table metadata registration is active.
# @POST ORM table 'app_configurations' exposes id, payload, and updated_at fields with declared nullability/default semantics.
# @SIDE_EFFECT Registers ORM mapping metadata during module import.
# @DATA_CONTRACT Input -> persistence row {id:str, payload:json, updated_at:datetime}; Output -> AppConfigRecord ORM entity.
# @PRE: SQLAlchemy declarative Base is initialized and table metadata registration is active.
# @POST: ORM table 'app_configurations' exposes id, payload, and updated_at fields with declared nullability/default semantics.
# @SIDE_EFFECT: Registers ORM mapping metadata during module import.
# @DATA_CONTRACT: Input -> persistence row {id:str, payload:json, updated_at:datetime}; Output -> AppConfigRecord ORM entity.
class AppConfigRecord(Base):
__tablename__ = "app_configurations"
@@ -30,10 +30,10 @@ class AppConfigRecord(Base):
# #region NotificationConfig [TYPE Class]
# @BRIEF Stores persisted provider-level notification configuration and encrypted credentials metadata.
# @PRE SQLAlchemy declarative Base is initialized and uuid generation is available at instance creation time.
# @POST ORM table 'notification_configs' exposes id, type, name, credentials, is_active, created_at, updated_at fields with declared constraints/defaults.
# @SIDE_EFFECT Registers ORM mapping metadata during module import; may generate UUID values for new entity instances.
# @DATA_CONTRACT Input -> persistence row {id:str, type:str, name:str, credentials:json, is_active:bool, created_at:datetime, updated_at:datetime}; Output -> NotificationConfig ORM entity.
# @PRE: SQLAlchemy declarative Base is initialized and uuid generation is available at instance creation time.
# @POST: ORM table 'notification_configs' exposes id, type, name, credentials, is_active, created_at, updated_at fields with declared constraints/defaults.
# @SIDE_EFFECT: Registers ORM mapping metadata during module import; may generate UUID values for new entity instances.
# @DATA_CONTRACT: Input -> persistence row {id:str, type:str, name:str, credentials:json, is_active:bool, created_at:datetime, updated_at:datetime}; Output -> NotificationConfig ORM entity.
class NotificationConfig(Base):
__tablename__ = "notification_configs"

12
backend/src/models/connection.py
View File

@@ -1,17 +1,15 @@
# #region ConnectionModels [C:1] [TYPE Module] [SEMANTICS database, connection, configuration, sqlalchemy, sqlite]
#
# @BRIEF Defines the database schema for external database connection configurations.
# @LAYER Domain
# @INVARIANT All primary keys are UUID strings.
# @RELATION DEPENDS_ON -> [sqlalchemy]
#
# @LAYER: Domain
# @RELATION DEPENDS_ON -> sqlalchemy
#
# @INVARIANT: All primary keys are UUID strings.
# [SECTION: IMPORTS]
from sqlalchemy import Column, String, Integer, DateTime
from sqlalchemy.sql import func
from .mapping import Base
import uuid
# [/SECTION]
# #region ConnectionConfig [C:1] [TYPE Class]
# @BRIEF Stores credentials for external databases used for column mapping.
@@ -30,4 +28,4 @@ class ConnectionConfig(Base):
updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
# #endregion ConnectionConfig
# #endregion ConnectionModels
# #endregion ConnectionModels

6
backend/src/models/dashboard.py
View File

@@ -1,7 +1,7 @@
# #region DashboardModels [C:3] [TYPE Module] [SEMANTICS dashboard, model, metadata, migration]
# @BRIEF Defines data models for dashboard metadata and selection.
# @LAYER Model
# @RELATION USED_BY -> [MigrationApi]
# @LAYER: Model
# @RELATION USED_BY -> MigrationApi
from pydantic import BaseModel
from typing import List
@@ -25,4 +25,4 @@ class DashboardSelection(BaseModel):
fix_cross_filters: bool = True
# #endregion DashboardSelection
# #endregion DashboardModels
# #endregion DashboardModels

8
backend/src/models/dataset_review.py
View File

@@ -1,7 +1,6 @@
# #region DatasetReviewModels [C:2] [TYPE Module] [SEMANTICS dataset_review, session, profile, findings, semantics, clarification, execution, sqlalchemy]
# @BRIEF Thin facade re-exporting all dataset review domain models from the decomposed sub-package.
# @LAYER Domain
# @INVARIANT All public model classes and enums remain importable from `src.models.dataset_review` without changes.
# @LAYER: Domain
# @RELATION EXPORTS -> [DatasetReviewEnums:Module]
# @RELATION EXPORTS -> [DatasetReviewSessionModels:Module]
# @RELATION EXPORTS -> [DatasetReviewProfileModels:Module]
@@ -11,8 +10,9 @@
# @RELATION EXPORTS -> [DatasetReviewMappingModels:Module]
# @RELATION EXPORTS -> [DatasetReviewClarificationModels:Module]
# @RELATION EXPORTS -> [DatasetReviewExecutionModels:Module]
# @RATIONALE Original 984-line monolith violated INV_7 (400-line module limit). Decomposed into domain-focused sub-modules while preserving backward-compatible import paths.
# @REJECTED Keeping all models in a single file because it exceeded the fractal limit by 2.5x and accumulated structural erosion risk.
# @INVARIANT: All public model classes and enums remain importable from `src.models.dataset_review` without changes.
# @RATIONALE: Original 984-line monolith violated INV_7 (400-line module limit). Decomposed into domain-focused sub-modules while preserving backward-compatible import paths.
# @REJECTED: Keeping all models in a single file because it exceeded the fractal limit by 2.5x and accumulated structural erosion risk.
from src.models.dataset_review_pkg._enums import ( # noqa: F401
SessionStatus,

2
backend/src/models/dataset_review_pkg/__init__.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewModels [C:3] [TYPE Module] [SEMANTICS dataset_review, session, profile, findings, semantics, clarification, execution, sqlalchemy]
# @BRIEF Re-export all dataset review domain models from decomposed sub-modules for backward-compatible imports.
# @LAYER Domain
# @LAYER: Domain
from src.models.dataset_review_pkg._enums import (
SessionStatus,

4
backend/src/models/dataset_review_pkg/_clarification_models.py
View File

@@ -1,9 +1,9 @@
# #region DatasetReviewClarificationModels [C:3] [TYPE Module]
# @BRIEF Clarification session, question, option, and answer models for guided review flow.
# @LAYER Domain
# @INVARIANT Only one active clarification question may exist at a time per session.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]
# @INVARIANT: Only one active clarification question may exist at a time per session.
import uuid
from datetime import datetime

4
backend/src/models/dataset_review_pkg/_enums.py
View File

@@ -1,7 +1,7 @@
# #region DatasetReviewEnums [C:2] [TYPE Module]
# @BRIEF All enumeration types for the dataset review domain, grouped for stable cross-module reuse.
# @LAYER Domain
# @INVARIANT Enum values are string-based for JSON serialization compatibility.
# @LAYER: Domain
# @INVARIANT: Enum values are string-based for JSON serialization compatibility.
import enum

2
backend/src/models/dataset_review_pkg/_execution_models.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewExecutionModels [C:3] [TYPE Module]
# @BRIEF Compiled preview, run context, session event, and export artifact models for execution and audit.
# @LAYER Domain
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]

2
backend/src/models/dataset_review_pkg/_filter_models.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewFilterModels [C:3] [TYPE Module]
# @BRIEF Imported filter and template variable models for Superset context recovery and execution mapping.
# @LAYER Domain
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]

2
backend/src/models/dataset_review_pkg/_finding_models.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewFindingModels [C:2] [TYPE Module]
# @BRIEF Validation finding model for tracking blocking, warning, and informational issues during review.
# @LAYER Domain
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]

4
backend/src/models/dataset_review_pkg/_mapping_models.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewMappingModels [C:2] [TYPE Module]
# @BRIEF Execution mapping model linking imported filters to template variables with approval gates.
# @LAYER Domain
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]
@@ -29,8 +29,8 @@ from src.models.dataset_review_pkg._enums import (
# #region ExecutionMapping [C:2] [TYPE Class]
# @BRIEF One filter-to-variable mapping with approval gate, effective value, and transformation metadata.
# @INVARIANT Explicit approval is required before launch when requires_explicit_approval is true.
# @RELATION DEPENDS_ON -> [DatasetReviewSession]
# @INVARIANT: Explicit approval is required before launch when requires_explicit_approval is true.
class ExecutionMapping(Base):
__tablename__ = "execution_mappings"

2
backend/src/models/dataset_review_pkg/_profile_models.py
View File

@@ -1,6 +1,6 @@
# #region DatasetReviewProfileModels [C:2] [TYPE Module]
# @BRIEF Dataset profile model capturing business summary, confidence, and completeness metadata.
# @LAYER Domain
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]

6
backend/src/models/dataset_review_pkg/_semantic_models.py
View File

@@ -1,9 +1,9 @@
# #region DatasetReviewSemanticModels [C:3] [TYPE Module]
# @BRIEF Semantic source, field entry, and candidate models for dictionary-driven semantic enrichment.
# @LAYER Domain
# @INVARIANT Manual overrides are never silently replaced by imported, inferred, or AI-generated values.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]
# @INVARIANT: Manual overrides are never silently replaced by imported, inferred, or AI-generated values.
import uuid
from datetime import datetime
@@ -64,9 +64,9 @@ class SemanticSource(Base):
# #region SemanticFieldEntry [C:3] [TYPE Class]
# @BRIEF Per-field semantic metadata entry with provenance tracking, lock state, and candidate set.
# @INVARIANT Locked fields preserve their active value regardless of later candidate proposals.
# @RELATION DEPENDS_ON -> [DatasetReviewSession]
# @RELATION DEPENDS_ON -> [SemanticCandidate]
# @INVARIANT: Locked fields preserve their active value regardless of later candidate proposals.
class SemanticFieldEntry(Base):
__tablename__ = "semantic_field_entries"

6
backend/src/models/dataset_review_pkg/_session_models.py
View File

@@ -1,9 +1,9 @@
# #region DatasetReviewSessionModels [C:3] [TYPE Module]
# @BRIEF Session aggregate root and collaborator models for dataset review orchestration.
# @LAYER Domain
# @INVARIANT Session and profile entities are strictly scoped to an authenticated user.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [DatasetReviewEnums:Module]
# @RELATION DEPENDS_ON -> [MappingModels]
# @INVARIANT: Session and profile entities are strictly scoped to an authenticated user.
import uuid
from datetime import datetime
@@ -51,7 +51,6 @@ class SessionCollaborator(Base):
# #region DatasetReviewSession [C:3] [TYPE Class]
# @BRIEF Aggregate root for the dataset review lifecycle, owning all child entities and driving readiness transitions.
# @INVARIANT Optimistic-lock version column prevents lost-update races on concurrent mutations.
# @RELATION DEPENDS_ON -> [SessionCollaborator]
# @RELATION DEPENDS_ON -> [DatasetProfile]
# @RELATION DEPENDS_ON -> [ValidationFinding]
@@ -65,6 +64,7 @@ class SessionCollaborator(Base):
# @RELATION DEPENDS_ON -> [DatasetRunContext]
# @RELATION DEPENDS_ON -> [ExportArtifact]
# @RELATION DEPENDS_ON -> [SessionEvent]
# @INVARIANT: Optimistic-lock version column prevents lost-update races on concurrent mutations.
class DatasetReviewSession(Base):
__tablename__ = "dataset_review_sessions"

20
backend/src/models/filter_state.py
View File

@@ -1,18 +1,16 @@
# #region FilterStateModels [C:2] [TYPE Module] [SEMANTICS superset, native, filters, pydantic, models, dataclasses]
# @BRIEF Pydantic models for Superset native filter state extraction and restoration.
# @LAYER Models
# @RELATION DEPENDS_ON -> [pydantic]
#
# @BRIEF Pydantic models for Superset native filter state extraction and restoration.
# @LAYER: Models
# @RELATION DEPENDS_ON -> [pydantic]
# [SECTION: IMPORTS]
from typing import Any, Dict, List, Optional
from pydantic import BaseModel, ConfigDict, Field
# [/SECTION]
# #region FilterState [C:2] [TYPE Model]
# @BRIEF Represents the state of a single native filter.
# @DATA_CONTRACT Input[extraFormData: Dict, filterState: Dict, ownState: Optional[Dict]] -> Model[FilterState]
# @DATA_CONTRACT: Input[extraFormData: Dict, filterState: Dict, ownState: Optional[Dict]] -> Model[FilterState]
class FilterState(BaseModel):
"""Single native filter state with extraFormData, filterState, and ownState."""
@@ -26,7 +24,7 @@ class FilterState(BaseModel):
# #region NativeFilterDataMask [C:2] [TYPE Model]
# @BRIEF Represents the dataMask containing all native filter states.
# @DATA_CONTRACT Input[Dict[filter_id, FilterState]] -> Model[NativeFilterDataMask]
# @DATA_CONTRACT: Input[Dict[filter_id, FilterState]] -> Model[NativeFilterDataMask]
class NativeFilterDataMask(BaseModel):
"""Container for all native filter states in a dashboard."""
@@ -49,7 +47,7 @@ class NativeFilterDataMask(BaseModel):
# #region ParsedNativeFilters [C:2] [TYPE Model]
# @BRIEF Result of parsing native filters from permalink or native_filters_key.
# @DATA_CONTRACT Input[dataMask: Dict, metadata: Dict] -> Model[ParsedNativeFilters]
# @DATA_CONTRACT: Input[dataMask: Dict, metadata: Dict] -> Model[ParsedNativeFilters]
class ParsedNativeFilters(BaseModel):
"""Result of extracting native filters from a Superset URL."""
@@ -76,7 +74,7 @@ class ParsedNativeFilters(BaseModel):
# #region DashboardURLFilterExtraction [C:2] [TYPE Model]
# @BRIEF Result of parsing a complete dashboard URL for filter information.
# @DATA_CONTRACT Input[url: str, dashboard_id: Optional, filter_type: Optional, filters: Dict] -> Model[DashboardURLFilterExtraction]
# @DATA_CONTRACT: Input[url: str, dashboard_id: Optional, filter_type: Optional, filters: Dict] -> Model[DashboardURLFilterExtraction]
class DashboardURLFilterExtraction(BaseModel):
"""Result of parsing a Superset dashboard URL to extract filter state."""
@@ -93,7 +91,7 @@ class DashboardURLFilterExtraction(BaseModel):
# #region ExtraFormDataMerge [C:2] [TYPE Model]
# @BRIEF Configuration for merging extraFormData from different sources.
# @DATA_CONTRACT Input[append_keys: List[str], override_keys: List[str]] -> Model[ExtraFormDataMerge]
# @DATA_CONTRACT: Input[append_keys: List[str], override_keys: List[str]] -> Model[ExtraFormDataMerge]
class ExtraFormDataMerge(BaseModel):
"""Configuration for merging extraFormData between original and new filter values."""
@@ -141,4 +139,4 @@ class ExtraFormDataMerge(BaseModel):
# #endregion ExtraFormDataMerge
# #endregion FilterStateModels
# #endregion FilterStateModels

6
backend/src/models/llm.py
View File

@@ -1,7 +1,7 @@
# #region LlmModels [C:3] [TYPE Module] [SEMANTICS llm, models, sqlalchemy, persistence]
# @BRIEF SQLAlchemy models for LLM provider configuration and validation results.
# @LAYER Domain
# @RELATION INHERITS_FROM -> [MappingModels:Base]
# @LAYER: Domain
# @RELATION INHERITS_FROM -> MappingModels:Base
from sqlalchemy import Column, String, Boolean, DateTime, JSON, Text, Time, ForeignKey
from datetime import datetime
@@ -63,4 +63,4 @@ class ValidationRecord(Base):
raw_response = Column(Text, nullable=True)
# #endregion ValidationRecord
# #endregion LlmModels
# #endregion LlmModels

15
backend/src/models/mapping.py
View File

@@ -1,20 +1,18 @@
# #region MappingModels [C:3] [TYPE Module] [SEMANTICS database, mapping, environment, migration, sqlalchemy, sqlite]
# @BRIEF Defines the database schema for environment metadata and database mappings using SQLAlchemy.
# @LAYER Domain
# @INVARIANT All primary keys are UUID strings.
# @RELATION DEPENDS_ON -> [sqlalchemy]
#
# @BRIEF Defines the database schema for environment metadata and database mappings using SQLAlchemy.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> sqlalchemy
#
# @INVARIANT: All primary keys are UUID strings.
# @CONSTRAINT: source_env_id and target_env_id must be valid environment IDs.
# [SECTION: IMPORTS]
from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey, Enum as SQLEnum
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.sql import func
import uuid
import enum
# [/SECTION]
Base = declarative_base()
@@ -39,7 +37,7 @@ class MigrationStatus(enum.Enum):
# #region Environment [C:3] [TYPE Class]
# @BRIEF Represents a Superset instance environment.
# @RELATION DEPENDS_ON -> [MappingModels]
# @RELATION DEPENDS_ON -> MappingModels
class Environment(Base):
__tablename__ = "environments"
@@ -80,7 +78,7 @@ class MigrationJob(Base):
# #region ResourceMapping [C:3] [TYPE Class]
# @BRIEF Maps a universal UUID for a resource to its actual ID on a specific environment.
# @TEST_DATA: resource_mapping_record -> {'environment_id': 'prod-env-1', 'resource_type': 'chart', 'uuid': '123e4567-e89b-12d3-a456-426614174000', 'remote_integer_id': '42'}
# @RELATION: DEPENDS_ON -> MappingModels
# @RELATION DEPENDS_ON -> MappingModels
class ResourceMapping(Base):
__tablename__ = "resource_mappings"
@@ -94,3 +92,4 @@ class ResourceMapping(Base):
# #endregion ResourceMapping
# #endregion MappingModels

12
backend/src/models/profile.py
View File

@@ -1,25 +1,23 @@
# #region ProfileModels [C:3] [TYPE Module] [SEMANTICS profile, preferences, persistence, user, dashboard-filter, git, ui-preferences, sqlalchemy]
#
# @BRIEF Defines persistent per-user profile settings for dashboard filter, Git identity/token, and UX preferences.
# @LAYER Domain
# @INVARIANT Exactly one preference row exists per user_id.
# @INVARIANT Sensitive Git token is stored encrypted and never returned in plaintext.
# @LAYER: Domain
# @RELATION DEPENDS_ON -> [AuthModels]
# @RELATION INHERITS_FROM -> [MappingModels:Base]
#
#
# @INVARIANT: Exactly one preference row exists per user_id.
# @INVARIANT: Sensitive Git token is stored encrypted and never returned in plaintext.
# [SECTION: IMPORTS]
import uuid
from datetime import datetime
from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey
from sqlalchemy.orm import relationship
from .mapping import Base
# [/SECTION]
# #region UserDashboardPreference [C:3] [TYPE Class]
# @BRIEF Stores Superset username binding and default "my dashboards" toggle for one authenticated user.
# @RELATION INHERITS -> [MappingModels:Base]
# @RELATION INHERITS -> MappingModels:Base
class UserDashboardPreference(Base):
__tablename__ = "user_dashboard_preferences"

42
backend/src/models/report.py
View File

@@ -1,26 +1,24 @@
# #region ReportModels [C:3] [TYPE Module] [SEMANTICS reports, models, pydantic, normalization, pagination]
# @BRIEF Canonical report schemas for unified task reporting across heterogeneous task types.
# @LAYER Domain
# @PRE Pydantic library and task manager models are available.
# @POST Provides validated schemas for cross-plugin reporting and UI consumption.
# @SIDE_EFFECT None (schema definition).
# @DATA_CONTRACT Model[TaskReport, ReportCollection, ReportDetailView]
# @INVARIANT Canonical report fields are always present for every report item.
# @LAYER: Domain
# @PRE: Pydantic library and task manager models are available.
# @POST: Provides validated schemas for cross-plugin reporting and UI consumption.
# @SIDE_EFFECT: None (schema definition).
# @DATA_CONTRACT: Model[TaskReport, ReportCollection, ReportDetailView]
# @RELATION DEPENDS_ON -> [TaskModels]
# @INVARIANT: Canonical report fields are always present for every report item.
# [SECTION: IMPORTS]
from datetime import datetime
from enum import Enum
from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field, field_validator, model_validator
# [/SECTION]
# #region TaskType [C:3] [TYPE Class] [SEMANTICS enum, type, task]
# @INVARIANT: Must contain valid generic task type mappings.
# @RELATION DEPENDS_ON -> ReportModels
# @BRIEF Supported normalized task report types.
# @INVARIANT Must contain valid generic task type mappings.
# @RELATION DEPENDS_ON -> [ReportModels]
class TaskType(str, Enum):
LLM_VERIFICATION = "llm_verification"
BACKUP = "backup"
@@ -34,9 +32,9 @@ class TaskType(str, Enum):
# #region ReportStatus [C:3] [TYPE Class] [SEMANTICS enum, status, task]
# @INVARIANT: TaskStatus enum mapping logic holds.
# @BRIEF Supported normalized report status values.
# @INVARIANT TaskStatus enum mapping logic holds.
# @RELATION DEPENDS_ON -> [ReportModels]
# @RELATION DEPENDS_ON -> ReportModels
class ReportStatus(str, Enum):
SUCCESS = "success"
FAILED = "failed"
@@ -48,8 +46,8 @@ class ReportStatus(str, Enum):
# #region ErrorContext [C:3] [TYPE Class] [SEMANTICS error, context, payload]
# @INVARIANT: The properties accurately describe error state.
# @BRIEF Error and recovery context for failed/partial reports.
# @INVARIANT The properties accurately describe error state.
#
# @TEST_CONTRACT: ErrorContextModel ->
# {
@@ -63,7 +61,7 @@ class ReportStatus(str, Enum):
# }
# @TEST_FIXTURE: basic_error -> {"message": "Connection timeout", "code": "ERR_504", "next_actions": ["retry"]}
# @TEST_EDGE: missing_message -> {"code": "ERR_504"}
# @RELATION: DEPENDS_ON -> ReportModels
# @RELATION DEPENDS_ON -> ReportModels
class ErrorContext(BaseModel):
code: Optional[str] = None
message: str
@@ -74,8 +72,8 @@ class ErrorContext(BaseModel):
# #region TaskReport [C:3] [TYPE Class] [SEMANTICS report, model, summary]
# @INVARIANT: Must represent canonical task record attributes.
# @BRIEF Canonical normalized report envelope for one task execution.
# @INVARIANT Must represent canonical task record attributes.
#
# @TEST_CONTRACT: TaskReportModel ->
# {
@@ -106,7 +104,7 @@ class ErrorContext(BaseModel):
# @TEST_EDGE: empty_summary -> {"report_id": "rep-123", "task_id": "task-456", "task_type": "migration", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": ""}
# @TEST_EDGE: invalid_task_type -> {"report_id": "rep-123", "task_id": "task-456", "task_type": "invalid_type", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": "Done"}
# @TEST_INVARIANT: non_empty_validators -> verifies: [empty_report_id, empty_summary]
# @RELATION: DEPENDS_ON -> ReportModels
# @RELATION DEPENDS_ON -> ReportModels
class TaskReport(BaseModel):
report_id: str
task_id: str
@@ -132,8 +130,8 @@ class TaskReport(BaseModel):
# #region ReportQuery [C:3] [TYPE Class] [SEMANTICS query, filter, search]
# @INVARIANT: Time and pagination queries are mutually consistent.
# @BRIEF Query object for server-side report filtering, sorting, and pagination.
# @INVARIANT Time and pagination queries are mutually consistent.
#
# @TEST_CONTRACT: ReportQueryModel ->
# {
@@ -153,7 +151,7 @@ class TaskReport(BaseModel):
# @TEST_EDGE: invalid_sort_by -> {"sort_by": "unknown_field"}
# @TEST_EDGE: invalid_time_range -> {"time_from": "2026-02-26T12:00:00Z", "time_to": "2026-02-25T12:00:00Z"}
# @TEST_INVARIANT: attribute_constraints_enforced -> verifies: [invalid_page_size_large, invalid_sort_by, invalid_time_range]
# @RELATION: DEPENDS_ON -> ReportModels
# @RELATION DEPENDS_ON -> ReportModels
class ReportQuery(BaseModel):
page: int = Field(default=1, ge=1)
page_size: int = Field(default=20, ge=1, le=100)
@@ -191,8 +189,8 @@ class ReportQuery(BaseModel):
# #region ReportCollection [C:3] [TYPE Class] [SEMANTICS collection, pagination]
# @INVARIANT: Represents paginated data correctly.
# @BRIEF Paginated collection of normalized task reports.
# @INVARIANT Represents paginated data correctly.
#
# @TEST_CONTRACT: ReportCollectionModel ->
# {
@@ -203,7 +201,7 @@ class ReportQuery(BaseModel):
# }
# @TEST_FIXTURE: empty_collection -> {"items": [], "total": 0, "page": 1, "page_size": 20, "has_next": False, "applied_filters": {}}
# @TEST_EDGE: negative_total -> {"items": [], "total": -5, "page": 1, "page_size": 20, "has_next": False, "applied_filters": {}}
# @RELATION: DEPENDS_ON -> ReportModels
# @RELATION DEPENDS_ON -> ReportModels
class ReportCollection(BaseModel):
items: List[TaskReport]
total: int = Field(ge=0)
@@ -217,8 +215,8 @@ class ReportCollection(BaseModel):
# #region ReportDetailView [C:3] [TYPE Class] [SEMANTICS view, detail, logs]
# @INVARIANT: Incorporates a report and logs correctly.
# @BRIEF Detailed report representation including diagnostics and recovery actions.
# @INVARIANT Incorporates a report and logs correctly.
#
# @TEST_CONTRACT: ReportDetailViewModel ->
# {
@@ -227,7 +225,7 @@ class ReportCollection(BaseModel):
# }
# @TEST_FIXTURE: valid_detail -> {"report": {"report_id": "rep-1", "task_id": "task-1", "task_type": "backup", "status": "success", "updated_at": "2026-02-26T12:00:00Z", "summary": "Done"}}
# @TEST_EDGE: missing_report -> {}
# @RELATION: DEPENDS_ON -> ReportModels
# @RELATION DEPENDS_ON -> ReportModels
class ReportDetailView(BaseModel):
report: TaskReport
timeline: List[Dict[str, Any]] = Field(default_factory=list)

2
backend/src/models/storage.py
View File

@@ -34,4 +34,4 @@ class StoredFile(BaseModel):
mime_type: Optional[str] = Field(None, description="MIME type of the file.")
# #endregion StoredFile
# #endregion StorageModels
# #endregion StorageModels

16
backend/src/models/task.py
View File

@@ -1,17 +1,15 @@
# #region TaskModels [C:1] [TYPE Module] [SEMANTICS database, task, record, sqlalchemy, sqlite]
#
# @BRIEF Defines the database schema for task execution records.
# @LAYER Domain
# @INVARIANT All primary keys are UUID strings.
# @RELATION DEPENDS_ON -> [sqlalchemy]
#
# @LAYER: Domain
# @RELATION DEPENDS_ON -> sqlalchemy
#
# @INVARIANT: All primary keys are UUID strings.
# [SECTION: IMPORTS]
from sqlalchemy import Column, String, DateTime, JSON, ForeignKey, Text, Integer, Index
from sqlalchemy.sql import func
from .mapping import Base
import uuid
# [/SECTION]
# #region TaskRecord [C:1] [TYPE Class]
# @BRIEF Represents a persistent record of a task execution.
@@ -33,8 +31,8 @@ class TaskRecord(Base):
# #region TaskLogRecord [C:3] [TYPE Class]
# @BRIEF Represents a single persistent log entry for a task.
# @INVARIANT Each log entry belongs to exactly one task.
# @RELATION DEPENDS_ON -> [TaskRecord]
# @RELATION DEPENDS_ON -> TaskRecord
# @INVARIANT: Each log entry belongs to exactly one task.
#
# @TEST_CONTRACT: TaskLogCreate ->
# {
@@ -109,4 +107,4 @@ class TaskLogRecord(Base):
)
# #endregion TaskLogRecord
# #endregion TaskModels
# #endregion TaskModels

48
backend/src/models/translate.py
View File

@@ -1,6 +1,7 @@
# #region TranslateModels [C:2] [TYPE Module]
# #region TranslateModels [C:3] [TYPE Module] [SEMANTICS translate, models, sqlalchemy, persistence]
# @BRIEF SQLAlchemy ORM models for LLM-based SQL/dashboard translation across dialects.
# @LAYER Domain
# @LAYER: Domain
# @RELATION INHERITS_FROM -> MappingModels:Base
from sqlalchemy import (
Column, String, Boolean, DateTime, JSON, Text,
@@ -13,13 +14,14 @@ import hashlib
from .mapping import Base
# #region generate_uuid [C:1] [TYPE Function]
def generate_uuid():
return str(uuid.uuid4())
# #endregion generate_uuid
# #region TranslationJob [C:1] [TYPE Class]
# #region TranslationJob [TYPE Class]
# @BRIEF A translation job representing a multi-dialect conversion task with column mappings, LLM config, and dictionary attachments.
# @RATIONALE: Snapshot isolation — in-progress runs use config snapshot; config edits affect future runs only.
# @REJECTED: Invalidating in-progress runs on config edit would break scheduled run continuity.
class TranslationJob(Base):
__tablename__ = "translation_jobs"
@@ -51,7 +53,6 @@ class TranslationJob(Base):
# Environment association
environment_id = Column(String, nullable=True, comment="Superset environment ID for datasource access")
target_database_id = Column(String, nullable=True, comment="Superset database ID for INSERT via SQL Lab")
created_by = Column(String, nullable=True)
created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
@@ -59,7 +60,8 @@ class TranslationJob(Base):
# #endregion TranslationJob
# #region TranslationRun [C:1] [TYPE Class]
# #region TranslationRun [TYPE Class]
# @BRIEF Represents a single execution of a translation job, capturing status, timing, and Superset execution metadata.
class TranslationRun(Base):
__tablename__ = "translation_runs"
@@ -86,7 +88,8 @@ class TranslationRun(Base):
# #endregion TranslationRun
# #region TranslationBatch [C:1] [TYPE Class]
# #region TranslationBatch [TYPE Class]
# @BRIEF Groups translation records within a run into manageable batches with timing and record counts.
class TranslationBatch(Base):
__tablename__ = "translation_batches"
@@ -103,7 +106,8 @@ class TranslationBatch(Base):
# #endregion TranslationBatch
# #region TranslationRecord [C:1] [TYPE Class]
# #region TranslationRecord [TYPE Class]
# @BRIEF Individual translation result for a single SQL statement or dashboard element, tracking source, target, and error state.
class TranslationRecord(Base):
__tablename__ = "translation_records"
@@ -120,7 +124,6 @@ class TranslationRecord(Base):
token_count_input = Column(Integer, nullable=True)
token_count_output = Column(Integer, nullable=True)
translation_duration_ms = Column(Integer, nullable=True)
source_data = Column(JSON, nullable=True, comment="Snapshot of source row key/context column values for INSERT phase")
created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
__table_args__ = (
@@ -129,7 +132,8 @@ class TranslationRecord(Base):
# #endregion TranslationRecord
# #region TranslationEvent [C:1] [TYPE Class]
# #region TranslationEvent [TYPE Class]
# @BRIEF Audit/event log for translation operations, with optional run_id for context.
class TranslationEvent(Base):
__tablename__ = "translation_events"
@@ -143,7 +147,8 @@ class TranslationEvent(Base):
# #endregion TranslationEvent
# #region TranslationPreviewSession [C:1] [TYPE Class]
# #region TranslationPreviewSession [TYPE Class]
# @BRIEF A preview session allowing users to review proposed translations before applying them.
class TranslationPreviewSession(Base):
__tablename__ = "translation_preview_sessions"
@@ -157,7 +162,8 @@ class TranslationPreviewSession(Base):
# #endregion TranslationPreviewSession
# #region TranslationPreviewRecord [C:1] [TYPE Class]
# #region TranslationPreviewRecord [TYPE Class]
# @BRIEF Individual preview entry within a preview session, showing original and translated content side by side.
class TranslationPreviewRecord(Base):
__tablename__ = "translation_preview_records"
@@ -170,12 +176,12 @@ class TranslationPreviewRecord(Base):
source_object_name = Column(String, nullable=True)
status = Column(String, nullable=False, default="PENDING") # PENDING, APPROVED, REJECTED
feedback = Column(Text, nullable=True)
source_data = Column(JSON, nullable=True, comment="Snapshot of source row values for key/context columns")
created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
# #endregion TranslationPreviewRecord
# #region TerminologyDictionary [C:1] [TYPE Class]
# #region TerminologyDictionary [TYPE Class]
# @BRIEF A named collection of terminology mappings used during translation to ensure consistent term translation.
class TerminologyDictionary(Base):
__tablename__ = "terminology_dictionaries"
@@ -191,7 +197,8 @@ class TerminologyDictionary(Base):
# #endregion TerminologyDictionary
# #region DictionaryEntry [C:1] [TYPE Class]
# #region DictionaryEntry [TYPE Class]
# @BRIEF A single term mapping entry with case-insensitive unique constraint on source_term_normalized and origin tracking.
class DictionaryEntry(Base):
__tablename__ = "dictionary_entries"
@@ -216,7 +223,8 @@ class DictionaryEntry(Base):
# #endregion DictionaryEntry
# #region TranslationSchedule [C:1] [TYPE Class]
# #region TranslationSchedule [TYPE Class]
# @BRIEF Defines a cron-based schedule for recurring translation jobs.
class TranslationSchedule(Base):
__tablename__ = "translation_schedules"
@@ -233,7 +241,8 @@ class TranslationSchedule(Base):
# #endregion TranslationSchedule
# #region TranslationJobDictionary [C:1] [TYPE Class]
# #region TranslationJobDictionary [TYPE Class]
# @BRIEF Many-to-many association between translation jobs and terminology dictionaries.
class TranslationJobDictionary(Base):
__tablename__ = "translation_job_dictionaries"
@@ -251,7 +260,8 @@ class TranslationJobDictionary(Base):
# #endregion TranslationJobDictionary
# #region MetricSnapshot [C:1] [TYPE Class]
# #region MetricSnapshot [TYPE Class]
# @BRIEF Captures translation performance metrics at a point in time with config/content/dictionary hash keys for aggregation.
class MetricSnapshot(Base):
__tablename__ = "translation_metric_snapshots"