course.py

from __future__ import annotations

from datetime import datetime
from enum import Enum
from typing import Any

from pydantic import BaseModel, Field

from app.domain.ai import AIUsageSummary
from app.domain.registry import PackageType, StarterType
from app.domain.task_agent import AssignmentDesignSpec, DataSourceSpec
from app.domain.workflow import DraftKind, HILGate, MaterializedBundle, ReviewerFinding, WorkflowReviewSummary, WorkflowStage, WorkflowStatus


class CourseRunStage(str, Enum):
    drafting = "drafting"
    awaiting_course_review = "awaiting_course_review"
    ready_to_publish = "ready_to_publish"
    published = "published"
    blocked = "blocked"


class CourseRunStatus(str, Enum):
    active = "active"
    awaiting_human = "awaiting_human"
    published = "published"
    blocked = "blocked"


class CourseDeliverableDraft(BaseModel):
    deliverable_slug: str = Field(validation_alias="deliverable_slug")
    title: str
    summary: str
    learning_outcomes: list[str] = Field(default_factory=list)
    design_spec: AssignmentDesignSpec | None = None
    domain_pack: str | None = None
    overlays: list[str] = Field(default_factory=list)
    workflow_run_id: str | None = None
    workflow_stage: str | None = None
    workflow_status: str | None = None
    draft_kind: str | None = None
    recommendation_status: str | None = None
    notes: list[str] = Field(default_factory=list)

class CourseRun(BaseModel):
    id: str
    course_family_id: str
    title: str
    summary: str
    package_type: PackageType
    pattern_slug: str | None = None
    creator_choices: CreatorCourseSetupChoices | None = None
    shared_design_spec: AssignmentDesignSpec | None = None
    shared_workflow_run_id: str | None = None
    latest_publish_snapshot_id: str | None = None
    active_operation: CourseAsyncOperation | None = None
    created_at: datetime
    updated_at: datetime
    stage: CourseRunStage
    status: CourseRunStatus
    materialized_bundle: MaterializedBundle | None = None
    deliverables: list[CourseDeliverableDraft] = Field(default_factory=list, validation_alias="deliverables")
    notes: list[str] = Field(default_factory=list)
    goal: str | None = None
    requested_learning_outcomes: list[str] = Field(default_factory=list)
    lab_tutor_enabled: bool = False
    generated_plan: GeneratedCoursePlan | None = None
    generation_source: CourseGenerationSource | None = None
    generation_status: CourseGenerationStatus | None = None
    own_ai_usage: AIUsageSummary = Field(default_factory=AIUsageSummary)
    ai_usage: AIUsageSummary = Field(default_factory=AIUsageSummary)
    last_error: str | None = None
    # Free-form JSON blob keyed by feature name. Used by the
    # outcome-mode workflow to stash a serialized
    # ``OutcomeWorkflowState`` under ``payload_json["outcome_state"]``
    # so the run survives a reload / refresh / gate resume. Generic
    # enough that future features can stash their own state shapes
    # without a schema migration.
    payload_json: dict[str, Any] = Field(default_factory=dict)


class CourseRunSummary(BaseModel):
    id: str
    course_family_id: str
    title: str
    summary: str
    goal: str | None = None
    package_type: PackageType
    stage: CourseRunStage
    status: CourseRunStatus
    deliverable_count: int = Field(validation_alias="deliverable_count")
    shared_workflow_run_id: str | None = None
    latest_publish_snapshot_id: str | None = None
    active_operation: CourseAsyncOperation | None = None
    ai_usage: AIUsageSummary = Field(default_factory=AIUsageSummary)
    last_error: str | None = None
    created_at: datetime
    updated_at: datetime

    @classmethod
    def from_run(cls, run: CourseRun) -> "CourseRunSummary":
        return cls(
            id=run.id,
            course_family_id=run.course_family_id,
            title=run.title,
            summary=run.summary,
            goal=run.goal,
            package_type=run.package_type,
            stage=run.stage,
            status=run.status,
            deliverable_count=len(run.deliverables),
            shared_workflow_run_id=run.shared_workflow_run_id,
            latest_publish_snapshot_id=run.latest_publish_snapshot_id,
            active_operation=run.active_operation,
            ai_usage=run.ai_usage,
            last_error=run.last_error,
            created_at=run.created_at,
            updated_at=run.updated_at,
        )

class CourseEvent(BaseModel):
    course_run_id: str
    sequence_no: int
    event_type: str
    created_at: datetime
    payload: dict = Field(default_factory=dict)


class DraftTimelineSourceKind(str, Enum):
    course_event = "course_event"
    workflow_authoring = "workflow_authoring"
    workflow_event = "workflow_event"
    workflow_node = "workflow_node"


class DraftTimelineItem(BaseModel):
    id: str
    created_at: datetime
    source_kind: DraftTimelineSourceKind
    source_id: str
    source_title: str
    title: str
    detail: str | None = None
    event_type: str
    stage: str | None = None
    status: str | None = None
    sequence_no: int | None = None
    iteration: int | None = None
    attempt: int | None = None
    payload: dict = Field(default_factory=dict)


class DraftTimelineResponse(BaseModel):
    course_run: CourseRunSummary
    shared_workflow_run_id: str | None = None
    linked_workflow_run_ids: list[str] = Field(default_factory=list)
    items: list[DraftTimelineItem] = Field(default_factory=list)


class CourseRunList(BaseModel):
    runs: list[CourseRunSummary]


class LocalDraftResetResult(BaseModel):
    deleted_course_runs: int
    deleted_course_events: int
    deleted_workflow_runs: int
    deleted_workflow_events: int
    deleted_publish_snapshots: int = 0
    deleted_learner_enrollments: int = 0
    deleted_learner_submissions: int = 0
    deleted_learner_workspace_sessions: int = 0
    deleted_creator_feedback: int = 0
    deleted_learner_feedback: int = 0
    deleted_learner_eval_reports: int = 0
    deleted_creator_assets: int = 0
    cleared_directories: list[str] = Field(default_factory=list)


class CourseGenerationSource(str, Enum):
    openai_live = "openai_live"
    deterministic_fallback = "deterministic_fallback"


class CourseAsyncOperation(str, Enum):
    generation = "generation"
    revision = "revision"
    materialize = "materialize"
    publish = "publish"


class CourseGenerationStatus(BaseModel):
    provider: str
    available: bool
    source: CourseGenerationSource
    message: str
    sdk_installed: bool = False
    api_key_present: bool = False
    model_id: str | None = None
    env_file: str | None = None


class CourseLinkedBundleSummary(BaseModel):
    bundle_id: str
    root_dir: str
    public_dir: str
    manifest_path: str
    total_file_count: int
    public_files: list[str] = Field(default_factory=list)
    private_file_count: int = 0


class CourseLinkedWorkflowSummary(BaseModel):
    run_id: str
    title: str
    stage: WorkflowStage
    status: WorkflowStatus
    pending_gate: HILGate | None = None
    draft_kind: DraftKind
    bundle: CourseLinkedBundleSummary | None = None
    review_summary: WorkflowReviewSummary | None = None


class CourseDeliverableReview(BaseModel):
    position: int
    deliverable_slug: str = Field(validation_alias="deliverable_slug")
    title: str
    summary: str
    design_spec: AssignmentDesignSpec | None = None
    domain_pack: str | None = None
    overlays: list[str] = Field(default_factory=list)
    learning_outcomes: list[str] = Field(default_factory=list)
    workflow_run_id: str | None = None
    workflow_stage: str | None = None
    workflow_status: str | None = None
    recommendation_status: str | None = None
    ready_for_publish: bool = False
    bundle_available: bool = False
    blockers: list[str] = Field(default_factory=list)
    linked_workflow: CourseLinkedWorkflowSummary | None = None
    notes: list[str] = Field(default_factory=list)

class CourseReviewCounts(BaseModel):
    total_deliverables: int = Field(validation_alias="total_deliverables")
    ready_deliverables: int = Field(validation_alias="ready_deliverables")
    deliverables_with_blockers: int = Field(validation_alias="deliverables_with_blockers")
    deliverables_with_bundle: int = Field(validation_alias="deliverables_with_bundle")
    linked_workflow_runs: int
    published_workflow_runs: int
    workflow_runs_with_bundle: int

class OutcomeFindingsBundle(BaseModel):
    """Outcome-mode review findings surfaced from ``OutcomeWorkflowState``.

    Populated by ``_build_review_report`` when the course_run carries a
    persisted outcome state (``payload_json["outcome_state"]``). The
    legacy ``CourseReviewReport.blockers`` / ``next_actions`` fields
    continue to be populated for non-outcome consumers; this bundle
    exposes the same data with explicit per-stage attribution so the
    UI / repair LLM can tell which check produced each finding.
    """

    spec_review: list[ReviewerFinding] = Field(default_factory=list)
    starter_review: list[ReviewerFinding] = Field(default_factory=list)
    oracle_validation_failures: list[str] = Field(default_factory=list)
    curated_validation_failures: list[str] = Field(default_factory=list)
    blocking_reasons: list[str] = Field(default_factory=list)
    overall_status: str
    stage: str


class CourseReviewReport(BaseModel):
    course_run_id: str
    title: str
    package_type: PackageType
    stage: CourseRunStage
    status: CourseRunStatus
    shared_design_spec: AssignmentDesignSpec | None = None
    shared_workflow_run_id: str | None = None
    materialized_bundle: MaterializedBundle | None = None
    counts: CourseReviewCounts
    blockers: list[str] = Field(default_factory=list)
    next_actions: list[str] = Field(default_factory=list)
    linked_workflows: list[CourseLinkedWorkflowSummary] = Field(default_factory=list)
    deliverables: list[CourseDeliverableReview] = Field(default_factory=list, validation_alias="deliverables")
    # Populated only for outcome-mode runs (i.e. those carrying
    # ``payload_json["outcome_state"]``). ``None`` for legacy runs so the
    # existing review surface remains byte-identical for those callers.
    outcome_findings: OutcomeFindingsBundle | None = None


class CreateCourseDeliverableRequest(BaseModel):
    deliverable_slug: str | None = Field(default=None, validation_alias="deliverable_slug")
    title: str
    summary: str | None = None
    learning_outcomes: list[str] = Field(default_factory=list)
    design_spec: AssignmentDesignSpec | None = None
    domain_pack_hint: str | None = None
    overlays_hint: list[str] = Field(default_factory=list)

class GeneratedCoursePlan(BaseModel):
    title: str
    summary: str
    package_type: PackageType
    shared_design_spec: AssignmentDesignSpec | None = None
    deliverables: list[CreateCourseDeliverableRequest] = Field(default_factory=list, min_length=1, validation_alias="deliverables")
    notes: list[str] = Field(default_factory=list)


class CreateCourseRunRequest(BaseModel):
    pattern_slug: str | None = None
    title: str | None = None
    summary: str | None = None
    package_type: PackageType | None = None
    creator_choices: CreatorCourseSetupChoices | None = None
    shared_design_spec: AssignmentDesignSpec | None = None
    course_family_id: str | None = None
    deliverables: list[CreateCourseDeliverableRequest] = Field(default_factory=list, validation_alias="deliverables")


class CreatorCourseSetupInput(BaseModel):
    starter_type: StarterType | None = None
    implementation_language: str | None = None
    language_version: str | None = None
    application_framework: str | None = None
    framework_version: str | None = None
    package_manager: str | None = None
    primary_database: str | None = None
    primary_database_version: str | None = None
    cache_backend: str | None = None
    cache_backend_version: str | None = None
    tech_stack: list[str] = Field(default_factory=list)
    data_sources: list[DataSourceSpec] = Field(default_factory=list)


class CreatorCourseSetupChoices(BaseModel):
    starter_type: StarterType = StarterType.partial
    implementation_language: str | None = None
    language_version: str | None = None
    application_framework: str | None = None
    framework_version: str | None = None
    package_manager: str | None = None
    primary_database: str | None = None
    primary_database_version: str | None = None
    cache_backend: str | None = None
    cache_backend_version: str | None = None
    tech_stack: list[str] = Field(default_factory=list)
    data_sources: list[DataSourceSpec] = Field(default_factory=list)


class CreatorStackCatalogOption(BaseModel):
    value: str
    label: str
    source_url: str | None = None
    recommended: bool = False


class CreatorStackCatalog(BaseModel):
    languages: list[CreatorStackCatalogOption] = Field(default_factory=list)
    frameworks_by_language: dict[str, list[CreatorStackCatalogOption]] = Field(default_factory=dict)
    package_managers_by_language: dict[str, list[CreatorStackCatalogOption]] = Field(default_factory=dict)
    databases: list[CreatorStackCatalogOption] = Field(default_factory=list)
    caches: list[CreatorStackCatalogOption] = Field(default_factory=list)


class RecommendCreatorStackContractRequest(BaseModel):
    goal: str = Field(min_length=10)
    creator_setup: CreatorCourseSetupInput = Field(default_factory=CreatorCourseSetupInput)


class RecommendCreatorStackContractResponse(BaseModel):
    creator_choices: CreatorCourseSetupChoices
    catalog: CreatorStackCatalog
    language_versions: list[CreatorStackCatalogOption] = Field(default_factory=list)
    framework_versions: list[CreatorStackCatalogOption] = Field(default_factory=list)
    database_versions: list[CreatorStackCatalogOption] = Field(default_factory=list)
    cache_versions: list[CreatorStackCatalogOption] = Field(default_factory=list)
    notes: list[str] = Field(default_factory=list)


class GenerateCourseFromBriefRequest(BaseModel):
    goal: str = Field(min_length=10)
    learning_outcomes: list[str] = Field(default_factory=list, max_length=10)
    title: str | None = None
    package_type_hint: PackageType | None = None
    creator_setup: CreatorCourseSetupInput = Field(default_factory=CreatorCourseSetupInput)


class GenerateCourseFromBriefResponse(BaseModel):
    source: CourseGenerationSource
    status: CourseGenerationStatus
    plan: GeneratedCoursePlan
    course_run: CourseRun
    review: CourseReviewReport


class QueueCourseGenerationResponse(BaseModel):
    queued: bool = True
    status: CourseGenerationStatus
    course_run: CourseRun


class QueueCourseRevisionResponse(BaseModel):
    queued: bool = True
    course_run: CourseRun


class QueueCourseOperationResponse(BaseModel):
    queued: bool = True
    operation: CourseAsyncOperation
    course_run: CourseRun


class SuggestLearningOutcomesRequest(BaseModel):
    goal: str = Field(min_length=10)
    title: str | None = None


class SuggestLearningOutcomesResponse(BaseModel):
    source: CourseGenerationSource
    status: CourseGenerationStatus
    learning_outcomes: list[str] = Field(default_factory=list)


class CreatorCourseDeliverablePlan(BaseModel):
    deliverable_slug: str = Field(validation_alias="deliverable_slug")
    title: str
    summary: str
    learning_outcomes: list[str] = Field(default_factory=list)
    creator_notes: list[str] = Field(default_factory=list)
    design_spec: AssignmentDesignSpec | None = None

class CreatorCoursePlan(BaseModel):
    goal: str | None = None
    learning_outcomes: list[str] = Field(default_factory=list)
    title: str
    summary: str
    package_type: PackageType
    creator_choices: CreatorCourseSetupChoices
    shared_design_spec: AssignmentDesignSpec | None = None
    deliverables: list[CreatorCourseDeliverablePlan] = Field(default_factory=list, min_length=1, validation_alias="deliverables")
    creator_summary: str | None = None
    notes: list[str] = Field(default_factory=list)


class GenerateCreatorCoursePlanRequest(BaseModel):
    goal: str = Field(min_length=10)
    learning_outcomes: list[str] = Field(default_factory=list)
    title: str | None = None
    package_type_hint: PackageType | None = None
    creator_choices: CreatorCourseSetupInput = Field(default_factory=CreatorCourseSetupInput)


class GenerateCreatorCoursePlanResponse(BaseModel):
    source: CourseGenerationSource
    status: CourseGenerationStatus
    learning_outcomes: list[str] = Field(default_factory=list)
    plan: CreatorCoursePlan


class CreateCourseFromCreatorPlanRequest(BaseModel):
    plan: CreatorCoursePlan