signalsafe-learning-core 0.5.0__tar.gz

signalsafe_learning_core-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

signalsafe_learning_core-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include docs *.md
+prune tests

signalsafe_learning_core-0.5.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: signalsafe-learning-core
+Version: 0.5.0
+Summary: Shared learning-core services and persistence
+License-Expression: MIT
+Requires-Python: <4,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: servicephilosophy<0.2,>=0.1.2
+Requires-Dist: sqlphilosophy<0.4,>=0.3.4
+Requires-Dist: sqlalchemy<3,>=2
+Dynamic: license-file
+
+# learning-core Python
+
+See [Python models and services](docs/README.md). Python 0.5.0 is the Company-free release approved on 2026-10-21; TypeScript remains 0.1.0. Existing hosts stay on their prior compatible artifacts until tenant-bound session adoption.
+
+Coordinated candidate dependencies: servicePhilosophy >=0.1.2,<0.2 and SQLPhilosophy >=0.3.4,<0.4. Build tooling requires patched setuptools >=84.2.1,<85. These unpublished minima are tested with exact local wheels before approval; fresh registry-only frozen checks remain required after upstream publication.

signalsafe_learning_core-0.5.0/README.md

@@ -0,0 +1,5 @@
+# learning-core Python
+
+See [Python models and services](docs/README.md). Python 0.5.0 is the Company-free release approved on 2026-10-21; TypeScript remains 0.1.0. Existing hosts stay on their prior compatible artifacts until tenant-bound session adoption.
+
+Coordinated candidate dependencies: servicePhilosophy >=0.1.2,<0.2 and SQLPhilosophy >=0.3.4,<0.4. Build tooling requires patched setuptools >=84.2.1,<85. These unpublished minima are tested with exact local wheels before approval; fresh registry-only frozen checks remain required after upstream publication.

signalsafe_learning_core-0.5.0/docs/README.md

@@ -0,0 +1,41 @@
+# Learning models and services
+
+Python 0.5.0 is an unpublished breaking Company-free candidate. Twelve learning defaults,
+field contracts, repositories and services have no Company columns, FKs or scoping arguments.
+TypeScript remains 0.1.0. Learning still has no platform-core dependency. Hosts add genuine
+local identity/simulation/scenario-version FKs when composing contracts on their own registry.
+
+```python
+from learning_core.models.defaults import Lesson
+from learning_core.repositories.lessons import LessonRepository
+from learning_core.services.lessons import LessonService
+
+service = LessonService(LessonRepository(Lesson, session))
+lesson = service.create_lesson({"key": "intro", "title": "Introduction"})
+```
+
+The host supplies a tenant-bound database session, authorization, effective grants and concrete
+versioned content. This package never chooses databases, parses hostnames or verifies JWTs.
+Existing shared-database hosts must remain on 0.4.0 until session/authentication isolation is
+implemented. These defaults do not authorize changes to existing databases.
+
+Course lifecycle methods use local course IDs. Publication still requires an explicit,
+host-authorized recipient_profile_ids list; omitting it fails before writes. Profile predicates
+remain on learner run, enrollment, certificate and progress reads. State guards, ordered steps,
+snapshot hashes, run-specific activity completion and caller-owned transactions remain intact.
+Multiple attempts remain historical records; enrollment/progress/certificate uniqueness is
+local to (profile_id, course_id). Batch keys, metrics and run-step progress retain local keys.
+
+Lesson creation defaults to editable local content. Administration/import orchestration may
+explicitly set is_master=True; user fields cannot override provenance. Master/imported lessons
+remain visible when active, but default update and delete paths reject them. Authorized central
+catalog editing may explicitly use update_lesson(..., allow_master=True); never expose this flag
+as a customer permission bypass. Content timestamps and writable-field filtering remain.
+
+`CourseProgressService` activity callbacks receive (profile_id, step, run_id). Preserve the
+run ID when reading assessment/simulation completion so another course run cannot satisfy it.
+Hosts own published scenario-version validation, assessment launch, provider integration and
+HTTP contracts. Services return domain models/results and never commit or serialize HTTP views.
+
+Run Ruff, strict mypy and all tests against disposable PostgreSQL, build clean wheel/sdist
+artifacts and run scripts/check_python_artifact.py. Verify installed bytes before adoption.

signalsafe_learning_core-0.5.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=84.2.1,<85", "wheel>=0.46,<1"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "signalsafe-learning-core"
+version = "0.5.0"
+description = "Shared learning-core services and persistence"
+readme = "README.md"
+requires-python = ">=3.12,<4"
+license = "MIT"
+dependencies = ["servicephilosophy>=0.1.2,<0.2", "sqlphilosophy>=0.3.4,<0.4", "sqlalchemy>=2,<3"]
+[dependency-groups]
+dev = ["build>=1.6.1,<2", "mypy>=1.17,<2", "pytest>=8.3,<10", "psycopg2-binary>=2.9,<3", "ruff>=0.12,<1"]
+[tool.setuptools.packages.find]
+where = ["src"]
+[tool.setuptools.package-data]
+learning_core = ["py.typed"]
+[tool.mypy]
+strict = true
+python_version = "3.12"
+files = ["src", "tests"]
+[tool.ruff]
+target-version = "py312"
+line-length = 90
+[tool.ruff.lint]
+select = ["E", "F", "I", "ANN", "ARG", "B", "C4", "PIE", "RET", "RUF", "SIM", "UP"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]

signalsafe_learning_core-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

signalsafe_learning_core-0.5.0/src/learning_core/__init__.py

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

signalsafe_learning_core-0.5.0/src/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"

signalsafe_learning_core-0.5.0/src/learning_core/models/__init__.py

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

signalsafe_learning_core-0.5.0/src/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"
+        }
+    )

signalsafe_learning_core-0.5.0/src/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
+    )