seed courses

app/bot/handlers/admin.py

@@ -11,6 +11,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config import get_settings
 from app.core.catalog import KINDS, STREAMS
+from app.core.seed_courses import FRESHMAN_COURSES
 from app.db.models import User
 from app.db.repos import library as repo
 from app.db.repos import stats as stats_repo
@@ -32,6 +33,8 @@ HELP = (
     "<b>Admin tools</b>\n"
     "/addcourse &lt;natural|social|all&gt; &lt;year 0-5&gt; &lt;code&gt; &lt;name...&gt;\n"
     "  e.g. <code>/addcourse natural 1 Math1011 Calculus I</code>\n"
+    "  (use <code>-</code> as the code if a course has none)\n"
+    "/seedcourses : add the Year-1 course list (safe to run twice)\n"
     "/courses : list courses with ids\n"
     "/stats : numbers\n"
     "/ping : measure database and Telegram speed\n\n"
@@ -73,10 +76,23 @@ async def add_course(message: Message, command: CommandObject, session: AsyncSes
         return
     stream = None if parts[0] == "all" else parts[0]
     year = int(parts[1]) or None
-    course = await repo.add_course(session, name=parts[3].strip(), code=parts[2], stream=stream, year=year)
+    code = None if parts[2] == "-" else parts[2]
+    course = await repo.add_course(session, name=parts[3].strip(), code=code, stream=stream, year=year)
     await message.answer(f"✅ Course <b>#{course.id}</b> added: {course.code} · {course.name}")
 
 
+@router.message(Command("seedcourses"))
+async def seed_courses(message: Message, session: AsyncSession) -> None:
+    added = skipped = 0
+    for stream, year, semester, code, name in FRESHMAN_COURSES:
+        if await repo.find_course(session, name, stream, year):
+            skipped += 1
+            continue
+        await repo.add_course(session, name=name, code=code, stream=stream, year=year, semester=semester)
+        added += 1
+    await message.answer(f"✅ Added <b>{added}</b> courses, skipped {skipped} that already existed.\nSee /courses for ids.")
+
+
 @router.message(Command("courses"))
 async def list_courses(message: Message, session: AsyncSession) -> None:
     courses = await repo.all_courses(session)

app/core/seed_courses.py

@@ -0,0 +1,52 @@
+"""Year-1 (freshman) course catalog used by /seedcourses.
+
+Sources (checked 14 Oct 2026):
+  * NATURAL stream, courses WITH a code: official DBU course catalog (dbu.edu.et, College of
+    Engineering, Year I). Codes are DBU's own.
+  * NATURAL stream, General Biology / General Chemistry: common national natural-science
+    freshman list (Jimma / Debark University). DBU code not verified -> shown without a code.
+  * SOCIAL stream: national common social-science freshman list (University of Gondar listing).
+    No DBU-specific source found -> shown without codes. Please verify against your registrar list.
+
+Tuple: (stream, year, semester, code or None, name)
+"""
+
+FRESHMAN_COURSES: list[tuple[str, int, int, str | None, str]] = [
+    # ---- NATURAL, semester I (DBU catalog) ----
+    ("natural", 1, 1, "FLEn1001", "Communicative English Language Skills I"),
+    ("natural", 1, 1, "Math1003", "Mathematics for Natural Sciences"),
+    ("natural", 1, 1, "LoCT1005", "Critical Thinking"),
+    ("natural", 1, 1, "Psys1007", "General Psychology"),
+    ("natural", 1, 1, "Phys1009", "General Physics"),
+    ("natural", 1, 1, "SpSc1011", "Physical Fitness"),
+    ("natural", 1, 1, "GeES1013", "Geography of Ethiopia and the Horn"),
+    # ---- NATURAL, semester II (DBU catalog) ----
+    ("natural", 1, 2, "FLEn1002", "Communicative English Language Skills II"),
+    ("natural", 1, 2, "Math1004", "Applied Mathematics I"),
+    ("natural", 1, 2, "Anth1006", "Social Anthropology"),
+    ("natural", 1, 2, "MGMT1008", "Entrepreneurship"),
+    ("natural", 1, 2, "EmTe1010", "Introduction to Emerging Technologies"),
+    ("natural", 1, 2, "ECEg1012", "Computer Programming"),
+    ("natural", 1, 2, "MCiE1014", "Moral and Civic Education"),
+    ("natural", 1, 2, "Hist1016", "History of Ethiopia and the Horn"),
+    # ---- NATURAL science (non-engineering), semester II: code not verified for DBU ----
+    ("natural", 1, 2, None, "General Biology"),
+    ("natural", 1, 2, None, "General Chemistry"),
+    # ---- SOCIAL, semester I (national common list; codes not verified for DBU) ----
+    ("social", 1, 1, None, "Communicative English Language Skills I"),
+    ("social", 1, 1, None, "General Psychology"),
+    ("social", 1, 1, None, "Geography of Ethiopia and the Horn"),
+    ("social", 1, 1, None, "Introduction to Economics"),
+    ("social", 1, 1, None, "Logic and Critical Thinking"),
+    ("social", 1, 1, None, "Mathematics for Social Sciences"),
+    ("social", 1, 1, None, "Physical Fitness"),
+    # ---- SOCIAL, semester II ----
+    ("social", 1, 2, None, "Communicative English Language Skills II"),
+    ("social", 1, 2, None, "Entrepreneurship"),
+    ("social", 1, 2, None, "Global Affairs"),
+    ("social", 1, 2, None, "Introduction to Law and the Ethiopian Legal System"),
+    ("social", 1, 2, None, "Social Anthropology"),
+    ("social", 1, 2, None, "History of Ethiopia and the Horn"),
+    ("social", 1, 2, None, "Introduction to Emerging Technologies"),
+    ("social", 1, 2, None, "Moral and Civic Education"),
+]

app/db/repos/library.py

@@ -50,10 +50,25 @@ async def all_courses(session: AsyncSession) -> list[Course]:
     return list(res.scalars())
 
 
+async def find_course(
+    session: AsyncSession, name: str, stream: Optional[str], year: Optional[int]
+) -> Optional[Course]:
+    res = await session.execute(
+        select(Course).where(Course.name == name, Course.stream == stream, Course.year == year).limit(1)
+    )
+    return res.scalar_one_or_none()
+
+
 async def add_course(
-    session: AsyncSession, *, name: str, code: Optional[str], stream: Optional[str], year: Optional[int]
+    session: AsyncSession,
+    *,
+    name: str,
+    code: Optional[str],
+    stream: Optional[str],
+    year: Optional[int],
+    semester: Optional[int] = None,
 ) -> Course:
-    course = Course(name=name, code=code, stream=stream, year=year)
+    course = Course(name=name, code=code, stream=stream, year=year, semester=semester)
     session.add(course)
     await session.flush()
     return course