Seed all 24 syllabus trees and document Gemini model tiers

- Add seed_syllabi.py: AI-authored topic/lesson trees for every subject,
posted to /v1/admin/seed-structures (fixes empty topics and 0-of-0 lessons)
- Annotate the two valid Gemini model names (lite default, 3.5-flash heavy)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

main.py

@@ -59,6 +59,10 @@ except Exception as e:
     logger.error(f"FATAL GenAI init: {e}")
     raise SystemExit(1)
 
+# Gemini model tiers across the Marka ecosystem (only two valid chat names):
+#   gemini-3.1-flash-lite  — default, cheapest, highest availability
+#   gemini-3.5-flash       — stronger, for quality-critical generation
+# This service only embeds + (optionally) does light text, so it stays on lite.
 EMBED_MODEL = os.environ.get("GEMINI_EMBED_MODEL", "text-embedding-004")
 TEXT_MODEL  = os.environ.get("GEMINI_TEXT_MODEL", "gemini-3.1-flash-lite")
 

seed_syllabi.py

@@ -0,0 +1,605 @@
+"""
+Seed syllabus structure trees for every subject in the registry.
+
+Why this exists
+---------------
+The data API ships with a SUBJECT_REGISTRY (24 Cambridge/ZIMSEC subjects) but the
+syllabus trees in Firebase were never populated. With no tree, the app server has
+nothing to scaffold a learning path on, so every subject showed empty topic lists
+and "0 of 0 lessons". Lessons and quizzes are generated by AI at runtime per node,
+so a subject only needs a faithful tree of  topic -> [lessons]  to become usable.
+
+This script holds an AI-authored structure for each subject (real syllabus topics
+and the sub-lessons under them), turns it into the tree shape the app expects, and
+POSTs the whole batch to the data API's /v1/admin/seed-structures endpoint.
+
+Tree node shape consumed by the app:
+    { "id": "...", "title": "...", "type": "topic" | "lesson", "children": [...] }
+
+Usage
+-----
+    python seed_syllabi.py                 # seed the live data API
+    DATA_API_BASE_URL=http://localhost:7860/v1 python seed_syllabi.py
+    python seed_syllabi.py --dry-run       # print what would be sent, send nothing
+"""
+
+import os
+import sys
+import json
+import requests
+
+DATA_API_BASE_URL = os.environ.get(
+    "DATA_API_BASE_URL", "https://rairo-marka-data-api.hf.space/v1"
+)
+
+# -----------------------------------------------------------------------------
+# Authored syllabus content.
+#   remote_id -> { topic_title: [lesson_title, ...], ... }
+# Topic order is the intended teaching order; lessons sit under each topic.
+# -----------------------------------------------------------------------------
+
+SYLLABI = {
+    # ===================== A-LEVEL =====================
+    "A_9706": {  # Accounting
+        "The Accounting Cycle": [
+            "Double-entry bookkeeping", "Books of prime entry",
+            "The ledger and trial balance", "Accounting concepts and conventions",
+        ],
+        "Financial Statements": [
+            "Income statement", "Statement of financial position",
+            "Accruals and prepayments", "Depreciation of non-current assets",
+            "Irrecoverable and doubtful debts",
+        ],
+        "Partnership Accounts": [
+            "Appropriation of profit", "Capital and current accounts",
+            "Goodwill", "Admission and retirement of partners",
+        ],
+        "Company Accounts": [
+            "Share capital and reserves", "Issue of shares and debentures",
+            "Published financial statements", "Statement of cash flows",
+        ],
+        "Cost and Management Accounting": [
+            "Cost classification", "Marginal costing", "Absorption costing",
+            "Break-even analysis", "Budgeting and budgetary control",
+        ],
+        "Analysis and Communication": [
+            "Accounting ratios", "Interpretation of financial statements",
+        ],
+    },
+    "A_9700": {  # Biology
+        "Cell Structure": [
+            "Microscopy and magnification", "Prokaryotic and eukaryotic cells",
+            "Cell organelles", "Cell membranes and transport",
+        ],
+        "Biological Molecules": [
+            "Carbohydrates", "Lipids", "Proteins", "Water and inorganic ions", "Enzymes",
+        ],
+        "Genetic Information": [
+            "DNA structure and replication", "Protein synthesis",
+            "Mitosis and the cell cycle", "Meiosis and variation",
+        ],
+        "Transport Systems": [
+            "Transport in plants", "Transport in mammals",
+            "The mammalian heart", "Haemoglobin and gas transport",
+        ],
+        "Disease and Immunity": [
+            "Infectious diseases", "Antibiotics", "The immune system", "Vaccination",
+        ],
+        "Energy and Coordination": [
+            "Photosynthesis", "Respiration", "Homeostasis", "Nervous coordination",
+        ],
+    },
+    "A_9609": {  # Business
+        "Business and its Environment": [
+            "Enterprise and entrepreneurs", "Business structure",
+            "Size of business", "Business objectives", "Stakeholders in business",
+        ],
+        "Human Resource Management": [
+            "Motivation theories", "Leadership and management styles",
+            "Human resource planning", "Organisation structure",
+        ],
+        "Marketing": [
+            "Marketing planning", "Market research", "The marketing mix", "Marketing strategy",
+        ],
+        "Operations Management": [
+            "Operations planning", "Inventory management",
+            "Capacity utilisation", "Quality management", "Lean production",
+        ],
+        "Finance and Accounting": [
+            "Sources of finance", "Costs and break-even",
+            "Budgets and variances", "Investment appraisal",
+        ],
+        "Strategic Management": [
+            "Strategic analysis (SWOT and PEST)", "Strategic choice", "Managing change",
+        ],
+    },
+    "A_9701": {  # Chemistry
+        "Atomic Structure": [
+            "Atoms and isotopes", "Electronic configuration",
+            "Ionisation energies", "Mass spectrometry",
+        ],
+        "Chemical Bonding": [
+            "Ionic bonding", "Covalent bonding", "Shapes of molecules",
+            "Intermolecular forces", "Metallic bonding",
+        ],
+        "Chemical Energetics": [
+            "Enthalpy changes", "Hess's law", "Bond energies", "Born-Haber cycles",
+        ],
+        "Equilibria": [
+            "Reversible reactions", "Kc and Kp", "Le Chatelier's principle",
+            "Acids and bases", "pH and buffer calculations",
+        ],
+        "Reaction Kinetics": [
+            "Rates of reaction", "Rate equations", "Reaction mechanisms", "Catalysis",
+        ],
+        "Organic Chemistry": [
+            "Hydrocarbons", "Halogenoalkanes", "Alcohols and esters",
+            "Carbonyl compounds", "Organic analysis",
+        ],
+    },
+    "A_9618": {  # Computer Science
+        "Information Representation": [
+            "Number systems", "Binary and hexadecimal", "Data types",
+            "Character sets and image representation",
+        ],
+        "Communication and Networking": [
+            "Networks and topologies", "Internet technologies", "Protocols",
+        ],
+        "Hardware and Processors": [
+            "Logic gates", "Boolean algebra", "CPU architecture", "Assembly language",
+        ],
+        "System Software": [
+            "Operating systems", "Language translators", "Memory management",
+        ],
+        "Databases": [
+            "Relational databases", "Normalisation", "SQL", "Database management systems",
+        ],
+        "Algorithms and Programming": [
+            "Programming paradigms", "Data structures", "Searching and sorting",
+            "Recursion", "Abstract data types",
+        ],
+    },
+    "A_9708": {  # Economics
+        "Basic Economic Ideas": [
+            "Scarcity and choice", "Factors of production",
+            "Production possibility curves", "Specialisation and exchange",
+        ],
+        "The Price System": [
+            "Demand and supply", "Elasticities", "Market equilibrium",
+            "Consumer and producer surplus",
+        ],
+        "Market Failure": [
+            "Externalities", "Public goods", "Information failure",
+            "Government intervention",
+        ],
+        "The Macroeconomy": [
+            "Aggregate demand and supply", "National income", "Economic growth",
+            "Inflation and unemployment",
+        ],
+        "Government Macro Policy": [
+            "Fiscal policy", "Monetary policy", "Supply-side policy",
+            "Balance of payments",
+        ],
+        "International Economics": [
+            "Exchange rates", "Trade and protectionism", "Globalisation",
+        ],
+    },
+    "A_9231": {  # Further Mathematics
+        "Further Pure 1": [
+            "Roots of polynomial equations", "Rational functions and graphs",
+            "Summation of series", "Matrices", "Polar coordinates",
+        ],
+        "Further Pure 2": [
+            "Hyperbolic functions", "Further integration",
+            "Complex numbers", "Differential equations",
+        ],
+        "Further Mechanics": [
+            "Momentum and impulse", "Circular motion",
+            "Work, energy and power", "Simple harmonic motion",
+        ],
+        "Further Probability and Statistics": [
+            "Continuous random variables", "Poisson distribution",
+            "Hypothesis testing", "Chi-squared tests",
+        ],
+    },
+    "A_9489": {  # History
+        "Modern Europe 1750-1921": [
+            "The French Revolution", "The Industrial Revolution",
+            "Nationalism and unification", "The Russian Revolution",
+        ],
+        "International Relations 1871-1945": [
+            "Origins of the First World War", "The Treaty of Versailles",
+            "Rise of dictatorships", "Origins of the Second World War",
+        ],
+        "The Cold War": [
+            "Origins of the Cold War", "Berlin and Cuba crises",
+            "Détente", "The end of the Cold War",
+        ],
+        "African History": [
+            "Colonialism in Africa", "African nationalism",
+            "Decolonisation", "Post-independence Africa",
+        ],
+    },
+    "A_9695": {  # Literature in English
+        "Poetry": [
+            "Reading and responding to poetry", "Form and structure",
+            "Imagery and language", "Comparative analysis",
+        ],
+        "Prose": [
+            "The novel and narrative voice", "Characterisation",
+            "Themes and context", "Critical interpretation",
+        ],
+        "Drama": [
+            "Dramatic techniques", "Tragedy", "Comedy", "Staging and performance",
+        ],
+        "Shakespeare": [
+            "Shakespearean language", "Themes and ideas",
+            "Character study", "Critical perspectives",
+        ],
+        "Critical Skills": [
+            "Unseen criticism", "Contextual analysis", "Essay writing",
+        ],
+    },
+    "A_9709": {  # Mathematics
+        "Pure Mathematics 1": [
+            "Quadratics", "Functions", "Coordinate geometry", "Circular measure",
+            "Trigonometry", "Series", "Differentiation", "Integration",
+        ],
+        "Pure Mathematics 3": [
+            "Algebra", "Logarithmic and exponential functions",
+            "Trigonometry", "Differentiation and integration",
+            "Numerical solution of equations", "Vectors",
+            "Differential equations", "Complex numbers",
+        ],
+        "Mechanics": [
+            "Forces and equilibrium", "Kinematics of motion",
+            "Newton's laws of motion", "Energy, work and power", "Momentum",
+        ],
+        "Probability and Statistics": [
+            "Representation of data", "Permutations and combinations",
+            "Probability", "Discrete random variables", "The normal distribution",
+        ],
+    },
+    "A_9702": {  # Physics
+        "Mechanics": [
+            "Kinematics", "Dynamics", "Forces and equilibrium",
+            "Work, energy and power", "Momentum",
+        ],
+        "Matter and Materials": [
+            "Density and pressure", "Deformation of solids", "Phases of matter",
+        ],
+        "Oscillations and Waves": [
+            "Wave properties", "Superposition", "Stationary waves",
+            "Simple harmonic motion", "The Doppler effect",
+        ],
+        "Electricity and Magnetism": [
+            "Electric fields", "Current electricity", "D.C. circuits",
+            "Magnetic fields", "Electromagnetic induction",
+        ],
+        "Modern Physics": [
+            "Quantum physics", "The photoelectric effect",
+            "Atomic and nuclear physics", "Radioactivity",
+        ],
+        "Thermal Physics": [
+            "Temperature and thermal energy", "Ideal gases", "Thermodynamics",
+        ],
+    },
+    "A_9699": {  # Sociology
+        "Socialisation and Identity": [
+            "Culture and identity", "Socialisation",
+            "Social control", "Nature versus nurture",
+        ],
+        "Sociological Theory": [
+            "Functionalism", "Marxism", "Feminism", "Social action theory",
+        ],
+        "Family": [
+            "Family forms and diversity", "Changing family roles",
+            "Marriage and divorce", "Childhood",
+        ],
+        "Education": [
+            "The role of education", "Educational achievement",
+            "The hidden curriculum", "Education policy",
+        ],
+        "Research Methods": [
+            "Quantitative methods", "Qualitative methods",
+            "Sampling", "Reliability and validity",
+        ],
+        "Social Inequality": [
+            "Class inequality", "Gender inequality", "Ethnicity", "Poverty",
+        ],
+    },
+    "A_9395": {  # Travel & Tourism
+        "The Travel and Tourism Industry": [
+            "Structure of the industry", "Types of tourism",
+            "Travel organisations", "Sustainable tourism",
+        ],
+        "Features of Destinations": [
+            "Destination appeal", "Tourist motivations and typologies",
+            "Destination management",
+        ],
+        "Customer Service": [
+            "Customer needs", "Quality service", "Handling complaints", "Selling skills",
+        ],
+        "Marketing in Travel and Tourism": [
+            "The marketing mix", "Market research", "Promotion", "Branding",
+        ],
+        "Tourism Development": [
+            "Economic impacts", "Social and cultural impacts",
+            "Environmental impacts", "Managing tourism",
+        ],
+    },
+    # ===================== O-LEVEL / IGCSE =====================
+    "O_0452": {  # Accounting
+        "Introduction to Accounting": [
+            "The accounting equation", "Double entry bookkeeping",
+            "Books of prime entry", "The ledger and trial balance",
+        ],
+        "Financial Statements": [
+            "Income statement", "Statement of financial position",
+            "Accruals and prepayments", "Depreciation",
+        ],
+        "Accounting for Different Entities": [
+            "Sole traders", "Partnerships", "Limited companies",
+            "Non-profit organisations",
+        ],
+        "Verification and Control": [
+            "Bank reconciliation statements", "Control accounts",
+            "Correction of errors", "Suspense accounts",
+        ],
+        "Analysis and Interpretation": [
+            "Accounting ratios", "Interpreting accounts",
+        ],
+    },
+    "O_0610": {  # Biology
+        "Characteristics and Cells": [
+            "Characteristics of living organisms", "Cell structure",
+            "Movement in and out of cells", "Classification",
+        ],
+        "Molecules and Nutrition": [
+            "Biological molecules", "Enzymes",
+            "Nutrition in plants", "Nutrition in humans",
+        ],
+        "Transport and Respiration": [
+            "Transport in plants", "Transport in animals",
+            "Gas exchange", "Respiration",
+        ],
+        "Coordination and Homeostasis": [
+            "The nervous system", "Hormones", "Homeostasis", "Excretion",
+        ],
+        "Reproduction and Inheritance": [
+            "Reproduction in plants", "Reproduction in humans",
+            "Inheritance", "Variation and selection",
+        ],
+        "Ecology and Human Impact": [
+            "Organisms and their environment",
+            "Human influences on ecosystems", "Biotechnology",
+        ],
+    },
+    "O_0450": {  # Business Studies
+        "Business Activity": [
+            "Purpose and nature of business", "Classification of business",
+            "Enterprise and entrepreneurs", "Business growth",
+        ],
+        "People in Business": [
+            "Motivation", "Organisation and management",
+            "Recruitment and training", "Communication",
+        ],
+        "Marketing": [
+            "Market research", "The marketing mix", "Marketing strategy",
+        ],
+        "Operations Management": [
+            "Production methods", "Costs and break-even",
+            "Achieving quality", "Location decisions",
+        ],
+        "Finance": [
+            "Sources of finance", "Cash flow forecasting",
+            "Financial statements", "Ratio analysis",
+        ],
+    },
+    "O_0620": {  # Chemistry
+        "Matter and Atoms": [
+            "Particulate nature of matter", "Atomic structure",
+            "The periodic table", "Chemical bonding",
+        ],
+        "Stoichiometry": [
+            "Formulae and equations", "The mole concept", "Reacting masses",
+        ],
+        "Electrochemistry and Energetics": [
+            "Electrolysis", "Energy changes", "Rates of reaction",
+            "Reversible reactions",
+        ],
+        "Acids, Bases and Salts": [
+            "Acids and bases", "Preparation of salts", "Identification of ions",
+        ],
+        "Metals and Periodicity": [
+            "Properties of metals", "The reactivity series", "Extraction of metals",
+        ],
+        "Organic and Environmental Chemistry": [
+            "Fuels", "Alkanes and alkenes", "Alcohols", "Air and water",
+        ],
+    },
+    "O_0478": {  # Computer Science
+        "Data Representation": [
+            "Binary systems", "Hexadecimal", "Data storage and compression",
+        ],
+        "Communication and Networking": [
+            "Data transmission", "Networks", "The internet", "Security",
+        ],
+        "Hardware": [
+            "Logic gates", "Input and output devices", "Storage devices", "The CPU",
+        ],
+        "Software": [
+            "System software", "Application software", "Operating systems",
+        ],
+        "Programming and Databases": [
+            "Algorithm design", "Pseudocode and flowcharts",
+            "Programming concepts", "Databases",
+        ],
+    },
+    "O_0500": {  # English Language
+        "Reading Skills": [
+            "Comprehension", "Summary writing",
+            "Extended response to reading", "Analysing language",
+        ],
+        "Directed Writing": [
+            "Writing for purpose", "Audience and tone",
+            "Discursive writing", "Argumentative writing",
+        ],
+        "Composition": [
+            "Descriptive writing", "Narrative writing", "Planning and structure",
+        ],
+        "Language Techniques": [
+            "Vocabulary and style", "Grammar and accuracy", "Punctuation",
+        ],
+    },
+    "O_0475": {  # English Literature
+        "Poetry": [
+            "Reading poetry", "Imagery and figurative language",
+            "Form and structure", "Comparing poems",
+        ],
+        "Prose": [
+            "Studying the novel", "Character and theme",
+            "Setting and context", "Close reading",
+        ],
+        "Drama": [
+            "Studying plays", "Dramatic devices",
+            "Character and conflict", "Themes",
+        ],
+        "Critical Writing": [
+            "Essay structure", "Using quotations", "Personal response",
+        ],
+    },
+    "O_0680": {  # Environmental Management
+        "The Lithosphere": [
+            "Rocks and minerals", "Mining and extraction", "Soil and its management",
+        ],
+        "The Atmosphere": [
+            "Atmosphere and climate", "Air pollution", "Climate change",
+        ],
+        "The Hydrosphere": [
+            "Water resources", "Water pollution", "Managing water", "The oceans",
+        ],
+        "The Biosphere": [
+            "Ecosystems", "Biodiversity", "Human impact", "Conservation",
+        ],
+        "Population and Sustainability": [
+            "Population dynamics", "Resources and energy", "Sustainable development",
+        ],
+    },
+    "O_0460": {  # Geography
+        "Population and Settlement": [
+            "Population dynamics", "Migration", "Settlement patterns", "Urbanisation",
+        ],
+        "The Natural Environment": [
+            "Plate tectonics", "Rivers", "Coasts", "Weather and climate", "Ecosystems",
+        ],
+        "Economic Development": [
+            "Agriculture", "Industry", "Tourism", "Energy", "Development",
+        ],
+        "Geographical Skills": [
+            "Map skills", "Data collection", "Interpreting data",
+        ],
+    },
+    "O_0470": {  # History
+        "The Nineteenth Century": [
+            "International relations", "Nationalism", "Empire and colonialism",
+        ],
+        "The First World War": [
+            "Causes of the First World War", "The course of the war", "Peace treaties",
+        ],
+        "Between the Wars": [
+            "The League of Nations", "Rise of dictatorships",
+            "Causes of the Second World War",
+        ],
+        "The Cold War": [
+            "Origins of the Cold War", "Crises and conflicts", "End of the Cold War",
+        ],
+        "Depth Study": [
+            "Germany 1918-1945", "Russia and the USSR", "The United States",
+        ],
+    },
+    "O_0625": {  # Physics
+        "General Physics": [
+            "Measurements", "Motion", "Mass, weight and density",
+            "Forces", "Energy, work and power", "Pressure",
+        ],
+        "Thermal Physics": [
+            "Kinetic theory", "Thermal properties", "Transfer of thermal energy",
+        ],
+        "Waves": [
+            "General wave properties", "Light", "Sound",
+            "The electromagnetic spectrum",
+        ],
+        "Electricity and Magnetism": [
+            "Magnetism", "Static electricity", "Current electricity",
+            "Electrical circuits", "Electromagnetic effects",
+        ],
+        "Atomic Physics": [
+            "The nuclear atom", "Radioactivity",
+        ],
+    },
+}
+
+
+def _slug(text: str) -> str:
+    keep = [c.lower() if c.isalnum() else "_" for c in text]
+    out = "".join(keep)
+    while "__" in out:
+        out = out.replace("__", "_")
+    return out.strip("_")[:40]
+
+
+def build_tree(subject_content: dict) -> list:
+    """Convert {topic: [lessons]} into the app's tree node shape."""
+    tree = []
+    for t_index, (topic_title, lessons) in enumerate(subject_content.items(), start=1):
+        topic_id = f"t{t_index}_{_slug(topic_title)}"
+        children = []
+        for l_index, lesson_title in enumerate(lessons, start=1):
+            children.append({
+                "id":    f"{topic_id}_l{l_index}",
+                "title": lesson_title,
+                "type":  "lesson",
+            })
+        tree.append({
+            "id":       topic_id,
+            "title":    topic_title,
+            "type":     "topic",
+            "children": children,
+        })
+    return tree
+
+
+def main():
+    dry_run = "--dry-run" in sys.argv
+    structures = {rid: {"tree": build_tree(content)} for rid, content in SYLLABI.items()}
+
+    total_topics = sum(len(s["tree"]) for s in structures.values())
+    total_lessons = sum(
+        len(node["children"]) for s in structures.values() for node in s["tree"]
+    )
+    print(f"Prepared {len(structures)} subjects, "
+          f"{total_topics} topics, {total_lessons} lessons.")
+
+    if dry_run:
+        print(json.dumps(structures["A_9709"], indent=2))
+        print("\n[dry-run] Nothing sent.")
+        return
+
+    url = f"{DATA_API_BASE_URL}/admin/seed-structures"
+    print(f"POST {url}")
+    resp = requests.post(url, json={"structures": structures}, timeout=120)
+    print(f"HTTP {resp.status_code}")
+    try:
+        results = resp.json().get("results", {})
+        ok = sum(1 for r in results.values() if r.get("ok"))
+        print(f"Seeded OK: {ok}/{len(results)}")
+        failures = {k: v for k, v in results.items() if not v.get("ok")}
+        if failures:
+            print("Failures:", json.dumps(failures, indent=2))
+    except Exception:
+        print(resp.text[:1000])
+
+
+if __name__ == "__main__":
+    main()