signalsafe-learning-core 0.5.0__py3-none-any.whl

learning_core/__init__.py

@@ -0,0 +1 @@
+"""Shared learning-core APIs; import from explicit defining modules."""

learning_core/enums.py

@@ -0,0 +1,70 @@
+"""Owned persisted domain values; wire values remain stable."""
+
+from enum import Enum, StrEnum
+
+
+class StringEnum(StrEnum):
+    """Preserve established display formatting independently of identity packages."""
+
+    def __str__(self) -> str:
+        return Enum.__str__(self)
+
+    def __format__(self, format_spec: str) -> str:
+        return Enum.__format__(self, format_spec)
+
+
+class CourseState(StringEnum):
+    DRAFT = "draft"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    ARCHIVED = "archived"
+
+
+class CourseStepType(StringEnum):
+    BASELINE = "baseline_sim"
+    LESSON = "lesson"
+    FINAL_TEST = "final_test"
+    POST = "post_sim"
+
+    @classmethod
+    def ordered(cls) -> tuple[str, ...]:
+        return (
+            cls.BASELINE.value,
+            cls.LESSON.value,
+            cls.FINAL_TEST.value,
+            cls.POST.value,
+        )
+
+
+class EnrollmentStatus(StringEnum):
+    ENROLLED = "enrolled"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+class CourseRunStatus(StringEnum):
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+class StepProgressStatus(StringEnum):
+    COMPLETED = "completed"
+
+
+class CourseAssignmentType(StringEnum):
+    COURSE = "course"  # compatibility value for course-linked assignments
+
+
+class CourseAssignmentStatus(StringEnum):
+    ASSIGNED = "assigned"
+    COMPLETED = "completed"
+
+
+class CourseStepAvailability(StringEnum):
+    LOCKED = "locked"
+    READY = "ready"
+    COMPLETED = "completed"
+
+
+DEFAULT_COURSE_COMPLETION_MODE = "manual"

learning_core/models/__init__.py

@@ -0,0 +1 @@
+"""Owned domain fields and default mapped models."""

learning_core/models/base.py

@@ -0,0 +1,18 @@
+"""Independent learning model contracts and default persistence registry."""
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+
+class LearnerContract(DeclarativeBase):
+    """Unmapped fields; hosts choose their own concrete registry and relationships."""
+
+
+class LearnerBase(DeclarativeBase):
+    """Default learning registry; no organization or identity tables are registered."""
+
+    metadata = MetaData(
+        naming_convention={
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s"
+        }
+    )

learning_core/models/contracts.py

@@ -0,0 +1,347 @@
+"""Package-owned scalar model definitions; hosts add integration relationships."""
+
+from datetime import date, datetime
+from uuid import UUID
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    Date,
+    DateTime,
+    Float,
+    ForeignKey,
+    Integer,
+    SmallInteger,
+    String,
+    Text,
+    UniqueConstraint,
+    Uuid,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, declared_attr, mapped_column
+from sqlphilosophy.audit.model import (
+    TimestampModel,
+)
+from sqlphilosophy.types import JSONObject
+
+from learning_core.models.base import LearnerContract
+
+
+class CourseModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    is_master: Mapped[bool] = mapped_column(Boolean)
+
+    name: Mapped[str] = mapped_column(String(200))
+
+    state: Mapped[str] = mapped_column(String(16))
+
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    snapshot_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+
+class CourseAttemptModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    profile_id: Mapped[int] = mapped_column(BigInteger)
+
+    status: Mapped[str] = mapped_column(String(16))
+
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+
+class CourseBatchModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("key"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    name: Mapped[str] = mapped_column(String(200))
+
+    key: Mapped[str] = mapped_column(String(64))
+
+    assigned_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+
+    assigned_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    starts_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    due_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    ends_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    state: Mapped[str] = mapped_column(String(16))
+
+    selection_type: Mapped[str | None] = mapped_column(String(24), nullable=True)
+
+    selection_definition_json: Mapped[JSONObject | None] = mapped_column(
+        JSONB, nullable=True
+    )
+
+    notes: Mapped[str] = mapped_column(Text)
+
+
+class CourseCertificateModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("profile_id", "course_id"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    profile_id: Mapped[int] = mapped_column(BigInteger)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    issued_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    score: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+
+class CourseEnrollmentModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("profile_id", "course_id"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    profile_id: Mapped[int] = mapped_column(BigInteger)
+
+    attempt_id: Mapped[int | None] = mapped_column(
+        BigInteger, ForeignKey("content_courseattempt.id"), nullable=True
+    )
+
+    batch_id: Mapped[int | None] = mapped_column(
+        BigInteger, ForeignKey("content_coursebatch.id"), nullable=True
+    )
+
+    enrolled_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    due_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    assigned_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+
+    status: Mapped[str] = mapped_column(String(16))
+
+
+class CourseMetricsModel(LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("course_id"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    baseline_fail_rate: Mapped[float] = mapped_column(Float)
+
+    post_fail_rate: Mapped[float] = mapped_column(Float)
+
+    improvement_delta: Mapped[float] = mapped_column(Float)
+
+    last_calculated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+
+class CourseProgressModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("profile_id", "course_id"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    profile_id: Mapped[int] = mapped_column(BigInteger)
+
+    current_step: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
+
+    completed_steps_count: Mapped[int] = mapped_column(SmallInteger)
+
+    total_steps: Mapped[int] = mapped_column(SmallInteger)
+
+    percent_complete: Mapped[float] = mapped_column(Float)
+
+
+class CourseStepModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    order: Mapped[int] = mapped_column(SmallInteger)
+
+    step_type: Mapped[str] = mapped_column(String(24))
+
+    required: Mapped[bool] = mapped_column(Boolean)
+
+    completion_mode: Mapped[str] = mapped_column(String(16))
+
+    name: Mapped[str] = mapped_column(String(200))
+
+    description: Mapped[str] = mapped_column(Text)
+
+    simulation_run_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+
+    lesson_id: Mapped[UUID | None] = mapped_column(
+        Uuid(as_uuid=True), ForeignKey("content_lesson.id"), nullable=True
+    )
+
+    scenario_version_id: Mapped[UUID | None] = mapped_column(
+        Uuid(as_uuid=True), nullable=True
+    )
+
+    template_key: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+
+class CourseStepRunModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_step_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("content_coursestep.id")
+    )
+
+    profile_id: Mapped[int] = mapped_column(BigInteger)
+
+    simulation_run_id: Mapped[int] = mapped_column(BigInteger)
+
+    status: Mapped[str] = mapped_column(String(16))
+
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    clicked_link: Mapped[bool] = mapped_column(Boolean)
+
+    reported: Mapped[bool] = mapped_column(Boolean)
+
+    verified: Mapped[bool] = mapped_column(Boolean)
+
+    entered_credentials: Mapped[bool] = mapped_column(Boolean)
+
+    time_to_action: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+
+class DailyCourseMetricsModel(LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("course_id", "date"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("content_course.id"))
+
+    date_: Mapped[date] = mapped_column("date", Date)
+
+    enrolled_count: Mapped[int] = mapped_column(Integer)
+
+    completed_count: Mapped[int] = mapped_column(Integer)
+
+    avg_completion_time: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+
+class LessonModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    id: Mapped[UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True)
+
+    key: Mapped[str] = mapped_column(String(50))
+
+    title: Mapped[str] = mapped_column(String(200))
+
+    short_takeaway: Mapped[str] = mapped_column(String(200))
+
+    description: Mapped[str] = mapped_column(Text)
+
+    category: Mapped[str] = mapped_column(String(64))
+
+    is_active: Mapped[bool] = mapped_column(Boolean)
+
+    is_master: Mapped[bool] = mapped_column(Boolean)
+
+    summary: Mapped[str] = mapped_column(Text)
+
+    content_markdown: Mapped[str] = mapped_column(Text)
+
+    estimated_minutes: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
+
+    content_updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+
+class CourseRunStepProgressModel(TimestampModel, LearnerContract):
+    __abstract__ = True
+
+    @declared_attr.directive
+    def __table_args__(cls) -> tuple[UniqueConstraint, ...]:
+        return (UniqueConstraint("course_run_id", "course_step_id"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    course_run_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("content_courseattempt.id")
+    )
+
+    course_step_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("content_coursestep.id")
+    )
+
+    status: Mapped[str] = mapped_column(String(16))
+
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )

learning_core/models/defaults.py

@@ -0,0 +1,212 @@
+"""Ready-to-use domain models on the default package registry."""
+
+from sqlalchemy.orm import Mapped, relationship
+
+from learning_core.models.base import LearnerBase
+from learning_core.models.contracts import (
+    CourseAttemptModel,
+    CourseBatchModel,
+    CourseCertificateModel,
+    CourseEnrollmentModel,
+    CourseMetricsModel,
+    CourseModel,
+    CourseProgressModel,
+    CourseRunStepProgressModel,
+    CourseStepModel,
+    CourseStepRunModel,
+    DailyCourseMetricsModel,
+    LessonModel,
+)
+
+
+class Course(LearnerBase, CourseModel):
+    __tablename__ = "content_course"
+
+    steps: Mapped[list["CourseStep"]] = relationship(
+        "CourseStep",
+        back_populates="course",
+        foreign_keys="[CourseStep.course_id]",
+        order_by="CourseStep.order",
+    )
+
+    attempts: Mapped[list["CourseAttempt"]] = relationship(
+        "CourseAttempt", back_populates="course", foreign_keys="[CourseAttempt.course_id]"
+    )
+
+    batches: Mapped[list["CourseBatch"]] = relationship(
+        "CourseBatch", back_populates="course", foreign_keys="[CourseBatch.course_id]"
+    )
+
+    certificates: Mapped[list["CourseCertificate"]] = relationship(
+        "CourseCertificate",
+        back_populates="course",
+        foreign_keys="[CourseCertificate.course_id]",
+    )
+
+    enrollments: Mapped[list["CourseEnrollment"]] = relationship(
+        "CourseEnrollment",
+        back_populates="course",
+        foreign_keys="[CourseEnrollment.course_id]",
+    )
+
+    metrics: Mapped[list["CourseMetrics"]] = relationship(
+        "CourseMetrics", back_populates="course", foreign_keys="[CourseMetrics.course_id]"
+    )
+
+    progress_records: Mapped[list["CourseProgress"]] = relationship(
+        "CourseProgress",
+        back_populates="course",
+        foreign_keys="[CourseProgress.course_id]",
+    )
+
+    daily_metrics: Mapped[list["DailyCourseMetrics"]] = relationship(
+        "DailyCourseMetrics",
+        back_populates="course",
+        foreign_keys="[DailyCourseMetrics.course_id]",
+    )
+
+
+class CourseAttempt(LearnerBase, CourseAttemptModel):
+    __tablename__ = "content_courseattempt"
+
+    enrollments: Mapped[list["CourseEnrollment"]] = relationship(
+        "CourseEnrollment",
+        back_populates="attempt",
+        foreign_keys="[CourseEnrollment.attempt_id]",
+    )
+
+    run_step_progress: Mapped[list["CourseRunStepProgress"]] = relationship(
+        "CourseRunStepProgress",
+        back_populates="course_run",
+        foreign_keys="[CourseRunStepProgress.course_run_id]",
+    )
+
+    course: Mapped["Course"] = relationship(
+        "Course", back_populates="attempts", foreign_keys="[CourseAttempt.course_id]"
+    )
+
+
+class CourseBatch(LearnerBase, CourseBatchModel):
+    __tablename__ = "content_coursebatch"
+
+    enrollments: Mapped[list["CourseEnrollment"]] = relationship(
+        "CourseEnrollment",
+        back_populates="batch",
+        foreign_keys="[CourseEnrollment.batch_id]",
+    )
+
+    course: Mapped["Course"] = relationship(
+        "Course", back_populates="batches", foreign_keys="[CourseBatch.course_id]"
+    )
+
+
+class CourseCertificate(LearnerBase, CourseCertificateModel):
+    __tablename__ = "content_coursecertificate"
+
+    course: Mapped["Course"] = relationship(
+        "Course",
+        back_populates="certificates",
+        foreign_keys="[CourseCertificate.course_id]",
+    )
+
+
+class CourseEnrollment(LearnerBase, CourseEnrollmentModel):
+    __tablename__ = "content_courseenrollment"
+
+    course: Mapped["Course"] = relationship(
+        "Course",
+        back_populates="enrollments",
+        foreign_keys="[CourseEnrollment.course_id]",
+    )
+
+    batch: Mapped["CourseBatch | None"] = relationship(
+        "CourseBatch",
+        back_populates="enrollments",
+        foreign_keys="[CourseEnrollment.batch_id]",
+    )
+
+    attempt: Mapped["CourseAttempt | None"] = relationship(
+        "CourseAttempt",
+        back_populates="enrollments",
+        foreign_keys="[CourseEnrollment.attempt_id]",
+    )
+
+
+class CourseMetrics(LearnerBase, CourseMetricsModel):
+    __tablename__ = "content_coursemetrics"
+
+    course: Mapped["Course"] = relationship(
+        "Course", back_populates="metrics", foreign_keys="[CourseMetrics.course_id]"
+    )
+
+
+class CourseProgress(LearnerBase, CourseProgressModel):
+    __tablename__ = "content_courseprogress"
+
+    course: Mapped["Course"] = relationship(
+        "Course",
+        back_populates="progress_records",
+        foreign_keys="[CourseProgress.course_id]",
+    )
+
+
+class CourseStep(LearnerBase, CourseStepModel):
+    __tablename__ = "content_coursestep"
+
+    runs: Mapped[list["CourseStepRun"]] = relationship(
+        "CourseStepRun",
+        back_populates="step",
+        foreign_keys="[CourseStepRun.course_step_id]",
+    )
+
+    run_step_progress: Mapped[list["CourseRunStepProgress"]] = relationship(
+        "CourseRunStepProgress",
+        back_populates="step",
+        foreign_keys="[CourseRunStepProgress.course_step_id]",
+    )
+
+    lesson: Mapped["Lesson | None"] = relationship(
+        "Lesson", foreign_keys="[CourseStep.lesson_id]"
+    )
+
+    course: Mapped["Course"] = relationship(
+        "Course", back_populates="steps", foreign_keys="[CourseStep.course_id]"
+    )
+
+
+class CourseStepRun(LearnerBase, CourseStepRunModel):
+    __tablename__ = "content_coursesteprun"
+
+    step: Mapped["CourseStep"] = relationship(
+        "CourseStep", back_populates="runs", foreign_keys="[CourseStepRun.course_step_id]"
+    )
+
+
+class DailyCourseMetrics(LearnerBase, DailyCourseMetricsModel):
+    __tablename__ = "content_dailycoursemetrics"
+
+    course: Mapped["Course"] = relationship(
+        "Course",
+        back_populates="daily_metrics",
+        foreign_keys="[DailyCourseMetrics.course_id]",
+    )
+
+
+class Lesson(LearnerBase, LessonModel):
+    __tablename__ = "content_lesson"
+
+
+class CourseRunStepProgress(LearnerBase, CourseRunStepProgressModel):
+    __tablename__ = "content_courserunstepprogress"
+
+    course_run: Mapped["CourseAttempt"] = relationship(
+        "CourseAttempt",
+        back_populates="run_step_progress",
+        foreign_keys="[CourseRunStepProgress.course_run_id]",
+    )
+
+    step: Mapped["CourseStep"] = relationship(
+        "CourseStep",
+        back_populates="run_step_progress",
+        foreign_keys="[CourseRunStepProgress.course_step_id]",
+    )

learning_core/repositories/__init__.py

@@ -0,0 +1 @@
+"""Domain persistence; import explicit model-bound repositories."""