cs-models 0.0.627__py3-none-any.whl → 0.0.847__py3-none-any.whl

cs_models/resources/SellSideSource/models.py

@@ -0,0 +1,25 @@
+from sqlalchemy import (
+    Column,
+    Integer,
+    String,
+    DateTime,
+)
+from datetime import datetime
+
+from ...database import Base
+
+
+class SellSideSourceModel(Base):
+    __tablename__ = "sell_side_sources"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(255), nullable=False, unique=True)  # "Morgan Stanley"
+    code = Column(String(64), nullable=False, unique=True)    # "MS", "JPM"
+
+    created_at = Column(DateTime, default=lambda: datetime.utcnow(), nullable=False)
+    updated_at = Column(
+        DateTime,
+        default=lambda: datetime.utcnow(),
+        onupdate=lambda: datetime.utcnow(),
+        nullable=False,
+    )

cs_models/resources/SellSideSource/schemas.py

@@ -0,0 +1,13 @@
+from marshmallow import Schema, fields, validate
+
+
+class SellSideSourceResourceSchema(Schema):
+    id = fields.Integer(dump_only=True)
+
+    # e.g. "Morgan Stanley"
+    name = fields.String(required=True, validate=validate.Length(min=1))
+    # e.g. "MS", "JPM"
+    code = fields.String(allow_none=True)
+
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)

cs_models/resources/Signature13F/models.py

@@ -0,0 +1,15 @@
+from sqlalchemy import Column, Integer, String, Date
+from ...database import Base
+
+
+class Signature13FModel(Base):
+    __tablename__ = '13fsignature'
+
+    ACCESSION_NUMBER = Column(String(25), primary_key=True)
+    NAME = Column(String(150), nullable=False)
+    TITLE = Column(String(60), nullable=False)
+    PHONE = Column(String(20))
+    SIGNATURE = Column(String(150), nullable=False)
+    CITY = Column(String(30), nullable=False)
+    STATEORCOUNTRY = Column(String(2), nullable=False)
+    SIGNATUREDATE = Column(Date, nullable=False)

cs_models/resources/Signature13F/schemas.py

@@ -0,0 +1,13 @@
+from marshmallow import Schema, fields
+from ...utils.utils import Safe13FDate
+
+
+class Signature13FSchema(Schema):
+    ACCESSION_NUMBER = fields.String(required=True)
+    NAME = fields.String(required=True)
+    TITLE = fields.String(required=True)
+    PHONE = fields.String()
+    SIGNATURE = fields.String(required=True)
+    CITY = fields.String(required=True)
+    STATEORCOUNTRY = fields.String(required=True)
+    SIGNATUREDATE = Safe13FDate(required=True)

cs_models/resources/SmartDefGrid/models.py

@@ -0,0 +1,30 @@
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, JSON
+from sqlalchemy.orm import relationship
+from ...database import Base
+
+
+class SmartDefGridModel(Base):
+    """
+    One extracted BlockNote table artifact.
+    You can link to your workbook/doc via source_* fields.
+    """
+    __tablename__ = "smart_def_grids"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)  # table_id (uuid string)
+    workbook_id = Column(
+        Integer,
+        ForeignKey('workbooks.id'),
+        nullable=True,
+        primary_key=True,
+    )
+    source_block_id = Column(String(64), nullable=True)     # BlockNote block id (if any)
+
+    outline_version = Column(Integer, nullable=False, default=1)   # your normalize() version
+    outline_json = Column(JSON, nullable=False)                     # semantic outline payload
+    original_table_json = Column(JSON, nullable=False)              # raw BlockNote table node (for rebuilds)
+
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    cells = relationship("SmartDefGridCellModel", back_populates="table", cascade="all, delete-orphan")

cs_models/resources/SmartDefGrid/schemas.py

@@ -0,0 +1,52 @@
+from marshmallow import Schema, fields, validate
+from ..SmartDefGridCell.schemas import SmartDefGridCellResourceSchema
+
+
+class SmartDefGridResourceSchema(Schema):
+    """
+        The user-defined table artifact (aka 'SmartDefGrid' resource).
+        - id is your table_id (UUID string or int—your choice).
+        - outline_json/original_table_json can be dicts (preferred) or JSON strings if you’d rather store serialized blobs.
+        """
+    not_blank = validate.Length(min=1, error="Field cannot be blank")
+
+    id = fields.String(dump_only=True)  # table_id
+    workbook_id = fields.Integer(allow_none=True)  # if you link to a workbook
+    source_block_id = fields.String(allow_none=True)
+
+    outline_version = fields.Integer(allow_none=True)
+    # prefer dicts; switch to fields.String if you store JSON-serialized strings
+    outline_json = fields.Raw(required=True)
+    original_table_json = fields.Raw(required=True)
+
+    # read-only expansion of cells
+    cells = fields.Nested(
+        SmartDefGridCellResourceSchema(exclude=["smart_def_grid_id"]),
+        many=True,
+        dump_only=True,
+        # if you strictly want to hide 'table_id' inside each cell in this view:
+        # exclude=("table_id",),
+    )
+
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)
+
+
+class SmartDefGridDetailResourceSchema(Schema):
+    id = fields.String(dump_only=True)
+    workbook_id = fields.String(allow_none=True)
+    source_block_id = fields.String(allow_none=True)
+    outline_version = fields.Integer(allow_none=True)
+    outline_json = fields.Raw(required=True)
+    original_table_json = fields.Raw(required=True)
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)
+
+    cells = fields.Nested(
+        SmartDefGridCellResourceSchema(),
+        many=True,
+        dump_only=True,
+        # include answers inlined under latest_question if you like:
+        only=("table_id","cell_id","row","col","is_header","formatting_spec",
+              "latest_question","applied_value"),
+    )

cs_models/resources/SmartDefGridCell/models.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, JSON, Boolean, Index, UniqueConstraint
+from sqlalchemy.orm import relationship
+from ...database import Base
+
+
+class SmartDefGridCellModel(Base):
+    """
+    One logical 'master' cell from the outline; the cell_id is stable.
+    Header cells exist too (is_header), in case you later want header questions.
+    """
+    __tablename__ = "smart_def_grid_cells"
+
+    # Composite natural key (table_id, cell_id)
+    smart_def_grid_id = Column(Integer, ForeignKey("smart_def_grids.id", ondelete="CASCADE"), primary_key=True)
+    cell_id = Column(String(36), primary_key=True)  # stable UUID you generated
+
+    # Positional metadata + spans help future reflow/debug, not needed at runtime for writeback
+    row = Column(Integer, nullable=False)
+    col = Column(Integer, nullable=False)
+    row_span = Column(Integer, nullable=False, default=1)
+    col_span = Column(Integer, nullable=False, default=1)
+    is_header = Column(Boolean, nullable=False, default=False)
+
+    header_path_row = Column(JSON, nullable=False, default=list)  # ["Efficacy (vs PBO)", "Clinical Remission"]
+    header_path_col = Column(JSON, nullable=False, default=list)  # ["Humira"] etc.
+
+    # Formatting guidance to apply when writing display strings
+    formatting_spec = Column(JSON, nullable=True)
+
+    # Optional: cache of the latest generated question id
+    latest_question_id = Column(Integer, ForeignKey("smart_def_grid_cell_questions.id"), nullable=True)
+
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    table = relationship("SmartDefGridModel", back_populates="cells")
+    latest_question = relationship("SmartDefGridCellQuestionModel", foreign_keys=[latest_question_id], uselist=False)
+
+    # Canonical applied cell value (write-back)
+    applied_value = relationship(
+        "SmartDefGridCellValueModel",
+        back_populates="cell",
+        uselist=False,
+        cascade="all, delete-orphan",
+    )
+
+    __table_args__ = (
+        UniqueConstraint("smart_def_grid_id", "row", "col", name="uq_sdg_cell_pos"),
+        Index("ix_smart_def_grid_cells_header", "smart_def_grid_id", "is_header"),
+    )

cs_models/resources/SmartDefGridCell/schemas.py

@@ -0,0 +1,39 @@
+from marshmallow import Schema, fields, validate
+from ..SmartDefGridCellQuestion.schemas import SmartDefGridCellQuestionResourceSchema
+from ..SmartDefGridCellValue.schemas import SmartDefGridCellValueResourceSchema
+
+
+class SmartDefGridCellResourceSchema(Schema):
+    """
+    One logical (master) cell from the user-defined table.
+    """
+    not_blank = validate.Length(min=1, error="Field cannot be blank")
+
+    smart_def_grid_id = fields.Integer(required=True)
+    cell_id = fields.String(required=True)
+
+    row = fields.Integer(required=True)
+    col = fields.Integer(required=True)
+    row_span = fields.Integer(required=True, data_key="rowSpan")
+    col_span = fields.Integer(required=True, data_key="colSpan")
+    is_header = fields.Boolean(required=True)
+
+    header_path_row = fields.List(fields.String(), required=True, data_key="headerPathRow")
+    header_path_col = fields.List(fields.String(), required=True, data_key="headerPathCol")
+
+    formatting_spec = fields.Raw(allow_none=True, data_key="formattingSpec")
+
+    latest_question_id = fields.String(allow_none=True)
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)
+
+    # optional, read-only projections
+    latest_question = fields.Nested(
+        SmartDefGridCellQuestionResourceSchema(),
+        dump_only=True,
+        exclude=("answers",),
+    )
+    applied_value = fields.Nested(
+        SmartDefGridCellValueResourceSchema(),
+        dump_only=True,
+    )

cs_models/resources/SmartDefGridCellAnswer/models.py

@@ -0,0 +1,45 @@
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Float, String, JSON, Integer, Index, Text, BigInteger, ForeignKeyConstraint
+from sqlalchemy.orm import relationship
+from ...database import Base
+
+
+class SmartDefGridCellAnswerModel(Base):
+    """
+    Answers emitted by workers. Keep multiple rows per question (retries, models).
+    """
+    __tablename__ = "smart_def_grid_cell_answers"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    question_id = Column(Integer, ForeignKey("smart_def_grid_cell_questions.id", ondelete="CASCADE"), nullable=False)
+
+    smart_def_grid_id = Column(Integer, ForeignKey("smart_def_grids.id", ondelete="CASCADE"), nullable=False)
+    run_id = Column(Integer, ForeignKey("smart_def_grid_runs.id", ondelete="SET NULL"), nullable=True)
+    cell_id = Column(String(36), nullable=False)
+
+    # canonical payload
+    raw_value = Column(Float, nullable=True)        # numeric scalar (if any)
+    text_value = Column(Text, nullable=True)        # string/summary
+    display_text = Column(Text, nullable=True)      # preformatted; writeback may still reformat
+    citations = Column(JSON, nullable=True)         # list of {url|doi|title|snippet|...}
+    extra_payload = Column(JSON, nullable=True)     # any provider-specific structure
+
+    # provenance
+    provider = Column(String(64), nullable=True)    # e.g., "gpt-4.1"
+    provider_meta = Column(JSON, nullable=True)     # tokens, latency, etc.
+
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+    # convenience index to quickly get latest by created_at
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["smart_def_grid_id", "cell_id"],
+            ["smart_def_grid_cells.smart_def_grid_id", "smart_def_grid_cells.cell_id"],
+            ondelete="CASCADE",
+        ),
+        Index("ix_smart_def_grid_cell_answers_cell", "smart_def_grid_id", "cell_id", "created_at"),
+        Index("ix_sdgca_run_cell", "run_id", "smart_def_grid_id", "cell_id", "created_at"),
+    )
+
+    question = relationship("SmartDefGridCellQuestionModel", back_populates="answers")
+    run = relationship("SmartDefGridRunModel")

cs_models/resources/SmartDefGridCellAnswer/schemas.py

@@ -0,0 +1,23 @@
+from marshmallow import Schema, fields
+
+
+class SmartDefGridCellAnswerResourceSchema(Schema):
+    id = fields.String(dump_only=True)
+    question_id = fields.Integer(required=True)
+    smart_def_grid_id = fields.Integer(required=True)
+    cell_id = fields.String(required=True)
+
+    raw_value = fields.Float(allow_none=True)
+    text_value = fields.String(allow_none=True)
+    display_text = fields.String(allow_none=True)
+
+    citations = fields.Raw(allow_none=True)              # list/dict (or keep normalized rows separately)
+    extra_payload = fields.Raw(allow_none=True)          # provider-specific data
+
+    provider = fields.String(allow_none=True)
+    provider_meta = fields.Raw(allow_none=True)
+
+    created_at = fields.DateTime(dump_only=True)
+
+    # if you materialize normalized citations, expose them here:
+    # citations_rel = fields.Nested(AnswerCitationResourceSchema, many=True, dump_only=True)

cs_models/resources/SmartDefGridCellAnswerCitation/models.py

@@ -0,0 +1,21 @@
+from sqlalchemy import Column, DateTime, ForeignKey, String, JSON, Integer, Index, Text, BigInteger
+from ...database import Base
+
+
+class SmartDefGridCellAnswerCitationModel(Base):
+    __tablename__ = "smart_def_grid_cell_answer_citations"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    answer_id = Column(Integer, ForeignKey("smart_def_grid_cell_answers.id", ondelete="CASCADE"), nullable=False)
+
+    source_type = Column(String(16), nullable=True)  # 'url','doi','patent','pubmed'
+    source_id = Column(String(256), nullable=True)   # doi, pubmed id, etc.
+    url = Column(Text, nullable=True)
+    title = Column(Text, nullable=True)
+    snippet = Column(Text, nullable=True)
+    published_at = Column(DateTime, nullable=True)
+    extra = Column(JSON, nullable=True)
+
+    __table_args__ = (
+        Index("ix_smart_def_grid_cell_answer_citations_source", "source_type", "source_id"),
+    )

cs_models/resources/SmartDefGridCellAnswerCitation/schemas.py

@@ -0,0 +1,14 @@
+from marshmallow import Schema, fields, validate
+
+
+class SmartDefGridCellAnswerCitationResourceSchema(Schema):
+    id = fields.Integer(dump_only=True)
+    answer_id = fields.Integer(required=True)
+
+    source_type = fields.String(allow_none=True)
+    source_id = fields.String(allow_none=True)
+    url = fields.String(allow_none=True)
+    title = fields.String(allow_none=True)
+    snippet = fields.String(allow_none=True)
+    published_at = fields.DateTime(allow_none=True)
+    extra = fields.Raw(allow_none=True)                  # any additional normalized payload

cs_models/resources/SmartDefGridCellQuestion/models.py

@@ -0,0 +1,76 @@
+import enum
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, JSON, Boolean, Index, Text, Enum, ForeignKeyConstraint
+from sqlalchemy.orm import relationship
+from ...database import Base
+
+
+class QuestionStatus(str, enum.Enum):
+    pending = "pending"     # created, not enqueued yet
+    queued = "queued"      # sent to your queue
+    running = "running"     # worker picked it up
+    succeeded = "succeeded"   # at least one answer persisted
+    failed = "failed"      # irrecoverable error (manual retry/override)
+    cancelled = "cancelled"  # cancelled
+
+
+class ExpectedType(str, enum.Enum):
+    number = "number"
+    text = "text"
+
+
+class SmartDefGridCellQuestionModel(Base):
+    """
+    One question per cell (you may create new ones on re-ask/revision).
+    """
+    __tablename__ = "smart_def_grid_cell_questions"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)  # question_id (uuid)
+    smart_def_grid_id = Column(Integer, ForeignKey("smart_def_grids.id", ondelete="CASCADE"), nullable=False)
+    run_id = Column(Integer, ForeignKey("smart_def_grid_runs.id", ondelete="SET NULL"), nullable=True)
+    cell_id = Column(String(36), nullable=False)
+
+    question_text = Column(Text, nullable=False)
+    expected_type = Column(Enum(ExpectedType), nullable=False)
+    must_cite = Column(Boolean, nullable=False, default=True)
+
+    topic_key = Column(JSON, nullable=True)
+    retrieval_hints = Column(JSON, nullable=True)
+
+    # Answer
+    answer_text = Column(Text, nullable=True)
+    answer_info = Column(JSON, nullable=True)
+
+    # Queue & lifecycle
+    status = Column(Enum(QuestionStatus), nullable=False, default=QuestionStatus.pending)
+    priority = Column(Integer, nullable=False, default=5)     # lower = higher priority
+    attempts = Column(Integer, nullable=False, default=0)
+    last_error = Column(Text, nullable=True)
+
+    idempotency_key = Column(String(64), nullable=True)       # to avoid dup work
+    dedupe_hash = Column(String(64), nullable=True)           # e.g., hash(table_id, cell_id, question_text)
+
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+    started_at = Column(DateTime, nullable=True)
+    finished_at = Column(DateTime, nullable=True)
+
+    # relationships
+    answers = relationship("SmartDefGridCellAnswerModel", back_populates="question", cascade="all, delete-orphan")
+    run = relationship("SmartDefGridRunModel")
+
+    __table_args__ = (
+        # Useful to grab next jobs: status+priority+created
+        Index("ix_smart_def_grid_cell_questions_queue", "status", "priority", "created_at"),
+        # Quick lookup for this cell's active question(s)
+        Index("ix_smart_def_grid_cell_questions_cell", "smart_def_grid_id", "cell_id"),
+        Index("ix_sdgcq_run_status", "run_id", "status", "priority", "created_at"),
+        Index("ix_sdgcq_run_cell", "run_id", "smart_def_grid_id", "cell_id"),
+        ForeignKeyConstraint(
+            ["smart_def_grid_id", "cell_id"],
+            ["smart_def_grid_cells.smart_def_grid_id", "smart_def_grid_cells.cell_id"],
+            ondelete="CASCADE",
+        ),
+        # strong uniqueness if you want only one ACTIVE per cell; or enforce app-side
+        # UniqueConstraint("table_id", "cell_id", "status", name="uq_cell_question_cell_status"),
+    )

cs_models/resources/SmartDefGridCellQuestion/schemas.py

@@ -0,0 +1,41 @@
+from marshmallow import Schema, fields, validate
+from ..SmartDefGridCellAnswer.schemas import SmartDefGridCellAnswerResourceSchema
+
+
+QUESTION_STATUS = ["pending", "queued", "running", "succeeded", "failed", "cancelled"]
+EXPECTED_TYPE = ["number", "text", "citationList", "json"]
+
+
+class SmartDefGridCellQuestionResourceSchema(Schema):
+    not_blank = validate.Length(min=1, error="Field cannot be blank")
+
+    id = fields.String(dump_only=True)
+    smart_def_grid_id = fields.Integer(required=True)
+    run_id = fields.Integer(allow_none=True)
+    cell_id = fields.String(required=True)
+
+    question_text = fields.String(required=True, validate=not_blank)
+    expected_type = fields.String(required=True, validate=validate.OneOf(EXPECTED_TYPE))
+    must_cite = fields.Boolean(required=True)
+
+    topic_key = fields.Raw(allow_none=True)              # e.g., {"row":[...], "col":[...]}
+    retrieval_hints = fields.Raw(allow_none=True)
+
+    answer_text = fields.String(allow_none=True)
+    answer_info = fields.Raw(allow_none=True)
+
+    status = fields.String(required=True, validate=validate.OneOf(QUESTION_STATUS))
+    priority = fields.Integer(required=True)
+    attempts = fields.Integer(required=True)
+    last_error = fields.String(allow_none=True)
+
+    idempotency_key = fields.String(allow_none=True)
+    dedupe_hash = fields.String(allow_none=True)
+
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)
+    started_at = fields.DateTime(dump_only=True)
+    finished_at = fields.DateTime(dump_only=True)
+
+    # light nesting of answers on read
+    answers = fields.Nested(SmartDefGridCellAnswerResourceSchema(), many=True, dump_only=True)

cs_models/resources/SmartDefGridCellValue/models.py

@@ -0,0 +1,54 @@
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Float, String, JSON, Boolean, Integer, Text, ForeignKeyConstraint, and_
+from sqlalchemy.orm import relationship
+from ...database import Base
+from ..SmartDefGridCell.models import SmartDefGridCellModel
+
+
+class SmartDefGridCellValueModel(Base):
+    """
+    The canonical, last-applied value for a cell in the user table (what's rendered back).
+    This is what your UI reads to show the latest state (without opening BlockNote).
+    """
+    __tablename__ = "smart_def_grid_cell_values"
+
+    smart_def_grid_id = Column(Integer, ForeignKey("smart_def_grids.id", ondelete="CASCADE"), primary_key=True)
+    applied_run_id = Column(Integer, ForeignKey("smart_def_grid_runs.id", ondelete="SET NULL"), nullable=True)
+    cell_id = Column(String(36), primary_key=True)
+
+    # applied value derived from a specific answer_id (or manual override)
+    answer_id = Column(Integer, ForeignKey("smart_def_grid_cell_answers.id", ondelete="SET NULL"), nullable=True)
+    raw_value = Column(Float, nullable=True)
+    display_text = Column(Text, nullable=True)
+    citations = Column(JSON, nullable=True)
+    formatting_used = Column(JSON, nullable=True)  # snapshot of FormattingSpec used to render
+
+    # flags
+    manual_override = Column(Boolean, nullable=False, default=False)
+    note = Column(Text, nullable=True)
+
+    applied_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["smart_def_grid_id", "cell_id"],
+            ["smart_def_grid_cells.smart_def_grid_id", "smart_def_grid_cells.cell_id"],
+            ondelete="CASCADE",
+        ),
+    )
+
+    # relationships
+    cell = relationship(
+        "SmartDefGridCellModel",
+        back_populates="applied_value",
+        uselist=False,
+        primaryjoin=lambda: and_(
+            SmartDefGridCellValueModel.smart_def_grid_id == SmartDefGridCellModel.smart_def_grid_id,
+            SmartDefGridCellValueModel.cell_id == SmartDefGridCellModel.cell_id,
+        ),
+        foreign_keys=lambda: [SmartDefGridCellValueModel.smart_def_grid_id, SmartDefGridCellValueModel.cell_id],
+    )
+
+    answer = relationship("SmartDefGridCellAnswerModel", foreign_keys=[answer_id])
+    applied_run = relationship("SmartDefGridRunModel")

cs_models/resources/SmartDefGridCellValue/schemas.py

@@ -0,0 +1,19 @@
+from marshmallow import Schema, fields
+
+
+class SmartDefGridCellValueResourceSchema(Schema):
+    smart_def_grid_id = fields.Integer(required=True)
+    applied_run_id = fields.Integer(allow_none=True)
+    cell_id = fields.String(required=True)
+
+    answer_id = fields.Integer(allow_none=True)
+    raw_value = fields.Float(allow_none=True)
+    display_text = fields.String(allow_none=True)
+    citations = fields.Raw(allow_none=True)
+    formatting_used = fields.Raw(allow_none=True)
+
+    manual_override = fields.Boolean(required=True, default=False)
+    note = fields.String(allow_none=True)
+
+    applied_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)

cs_models/resources/SmartDefGridRun/models.py

@@ -0,0 +1,60 @@
+from enum import Enum
+from datetime import datetime
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, JSON, Text, Index
+from sqlalchemy.orm import relationship
+from ...database import Base
+
+
+class SmartDefGridRunStatus(str, Enum):
+    created = "created"
+    dispatched = "dispatched"
+    running = "running"
+    succeeded = "succeeded"
+    failed = "failed"
+    cancelled = "cancelled"
+    partial = "partial"   # finished with some failed cells
+
+
+class SmartDefGridRunScope(str, Enum):
+    all = "all"
+    empty_only = "empty_only"
+
+
+class SmartDefGridRunModel(Base):
+    __tablename__ = "smart_def_grid_runs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)  # run_id
+    smart_def_grid_id = Column(Integer, ForeignKey("smart_def_grids.id", ondelete="CASCADE"), nullable=False)
+
+    scope_mode = Column(SAEnum(SmartDefGridRunScope), nullable=False, default=SmartDefGridRunScope.all)
+
+    # optional snapshotting to make runs reproducible/debuggable
+    outline_json = Column(JSON, nullable=False)  # new outline created for this run
+    original_table_json = Column(JSON, nullable=False)    # stamped block at run start
+    targets_json = Column(JSON, nullable=True)
+
+    # execution metadata
+    status = Column(
+        SAEnum(
+            SmartDefGridRunStatus,
+            validate_strings=True,  # allow assigning "created" etc. as strings too
+        ),
+        nullable=False,
+        default=SmartDefGridRunStatus.created,
+    )
+
+    started_by_user_id = Column(String(64), nullable=False)
+    notes = Column(Text, nullable=True)
+    # optional idempotency token if you want “re-run latest”
+    client_token = Column(String(128), nullable=True, index=True)
+
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    started_at = Column(DateTime, nullable=True)
+    finished_at = Column(DateTime, nullable=True)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    grid = relationship("SmartDefGridModel", backref="runs")
+    __table_args__ = (
+        Index("ix_sdgr_runs_grid_created", "smart_def_grid_id", "created_at"),
+    )

cs_models/resources/SmartDefGridRun/schemas.py

@@ -0,0 +1,31 @@
+from marshmallow import Schema, fields, validate
+
+
+class SmartDefGridRunResourceSchema(Schema):
+    """
+        The user-defined table artifact (aka 'SmartDefGrid' resource).
+        - id is your table_id (UUID string or int—your choice).
+        - outline_json/original_table_json can be dicts (preferred) or JSON strings if you’d rather store serialized blobs.
+        """
+    not_blank = validate.Length(min=1, error="Field cannot be blank")
+
+    id = fields.String(dump_only=True)  # table_id
+    smart_def_grid_id = fields.Integer(allow_none=True)  # if you link to a workbook
+
+    scope_mode = fields.String(required=True)
+
+    # prefer dicts; switch to fields.String if you store JSON-serialized strings
+    outline_json = fields.Raw(required=True)
+    original_table_json = fields.Raw(required=True)
+    targets_json = fields.Raw(allow_none=True)
+
+    status = fields.String(required=True)
+    started_by_user_id = fields.String(required=True)
+
+    notes = fields.String(allow_none=True)
+    client_token = fields.String(allow_none=True)
+
+    created_at = fields.DateTime(dump_only=True)
+    started_at = fields.DateTime(allow_none=True)
+    finished_at = fields.DateTime(allow_none=True)
+    updated_at = fields.DateTime(dump_only=True)