standardgraph 1.2.4__tar.gz → 1.4.0__tar.gz

{standardgraph-1.2.4 → standardgraph-1.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: standardgraph
-Version: 1.2.4
-Summary: 158,000+ education standards (math, science, ELA, social studies, CS, arts) across 300 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server
+Version: 1.4.0
+Summary: 172,000+ education standards (math, science, ELA, social studies, CS, arts) across 310 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server
 Author: StandardGraph
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/swoopeagle/standardgraph
@@ -24,7 +24,7 @@ Requires-Dist: numpy>=1.26.0
 
 <!-- mcp-name: io.github.swoopeagle/standardgraph -->
 
-**158,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
+**154,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
 
 Covers seven subjects — Mathematics, Science, ELA, Social Studies, Computer Science, Arts, and World Languages — across the US (CCSS + all 50 states), Canada, Australia, UK, Singapore, Japan, New Zealand, Ireland, Hong Kong, India, Ghana, South Africa, Rwanda, Cambridge International, IB MYP/DP, AP, and more. Standards are cross-referenced to subject hubs (CCSS for math, NGSS for science, etc.) via semantic similarity, with LLM quality scores on the strongest mappings.
 

{standardgraph-1.2.4 → standardgraph-1.4.0}/README.md

@@ -2,7 +2,7 @@
 
 <!-- mcp-name: io.github.swoopeagle/standardgraph -->
 
-**158,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
+**154,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
 
 Covers seven subjects — Mathematics, Science, ELA, Social Studies, Computer Science, Arts, and World Languages — across the US (CCSS + all 50 states), Canada, Australia, UK, Singapore, Japan, New Zealand, Ireland, Hong Kong, India, Ghana, South Africa, Rwanda, Cambridge International, IB MYP/DP, AP, and more. Standards are cross-referenced to subject hubs (CCSS for math, NGSS for science, etc.) via semantic similarity, with LLM quality scores on the strongest mappings.
 

{standardgraph-1.2.4 → standardgraph-1.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "standardgraph"
-version = "1.2.4"
-description = "158,000+ education standards (math, science, ELA, social studies, CS, arts) across 300 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server"
+version = "1.4.0"
+description = "172,000+ education standards (math, science, ELA, social studies, CS, arts) across 310 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"

{standardgraph-1.2.4 → standardgraph-1.4.0}/src/common_core/server.py

@@ -1,4 +1,5 @@
 """StandardGraph MCP server — education standards across 7 subjects."""
+import functools
 import json
 import re
 import sqlite3
@@ -181,6 +182,42 @@ mcp = FastMCP(
 )
 
 
+# ── Static viz route ──────────────────────────────────────────────────────────
+
+def _viz_dir() -> "os.PathLike | None":
+    """Directory holding the pre-built viz HTML.
+
+    Uses SG_VIZ_DIR when set; otherwise falls back to ``<repo>/docs/viz`` derived
+    from DB_PATH (which, in the hosted deployment, lives in ``<repo>/data``).
+    """
+    import os
+    from pathlib import Path
+
+    override = os.getenv("SG_VIZ_DIR")
+    if override:
+        return Path(override)
+    candidate = Path(DB_PATH).resolve().parent.parent / "docs" / "viz"
+    return candidate if candidate.is_dir() else None
+
+
+@mcp.custom_route("/concept-map", methods=["GET"])
+async def _concept_map(request):  # noqa: ANN001 — Starlette Request
+    """Serve the self-contained interactive concept map (offline single file)."""
+    from pathlib import Path
+
+    from starlette.responses import HTMLResponse, PlainTextResponse
+
+    viz = _viz_dir()
+    if viz is not None:
+        f = Path(viz) / "concept_map.html"
+        if f.is_file():
+            return HTMLResponse(
+                f.read_text(encoding="utf-8"),
+                headers={"Cache-Control": "public, max-age=300"},
+            )
+    return PlainTextResponse("Concept map not available on this deployment.", status_code=404)
+
+
 # ── DB helpers ────────────────────────────────────────────────────────────────
 
 def _db() -> sqlite3.Connection:
@@ -215,6 +252,50 @@ def _grade_key(g: str) -> int:
         return 99
 
 
+# Separator between the two ends of a grade range ('3-6', '3–6', '6 to 8').
+_RANGE_SEP = re.compile(r"\s*(?:-|–|—|\.\.|to|through)\s*", re.I)
+
+
+def _coerce_grade(v) -> str | None:
+    """Map an int/str grade to a canonical GRADE_ORDER code, else None.
+
+    Accepts ints, numeric strings ('5', '5.0'), grade codes ('K', 'HS',
+    case-insensitive) and high-school year numbers (9–12 → 'HS').
+    """
+    if v is None:
+        return None
+    s = str(v).strip().upper()
+    s = re.sub(r"^(?:GRADES?|GR)\.?\s*", "", s)  # 'Grade 3' / 'Gr. 3' → '3'
+    if s in GRADE_ORDER:
+        return s
+    if s in ("K", "KG", "KINDERGARTEN"):
+        return "K"
+    if s in ("HS", "HIGH SCHOOL"):
+        return "HS"
+    try:
+        n = int(float(s))
+    except (ValueError, TypeError):
+        return None
+    if str(n) in GRADE_ORDER:
+        return str(n)
+    return "HS" if n >= 9 else "K" if n < 0 else None
+
+
+def _norm_grade_bounds(grade_start, grade_end) -> tuple[str | None, str | None]:
+    """Coerce loose grade_start/grade_end args into canonical grade-code bounds.
+
+    Tolerates a range string passed in either slot — LLM callers frequently send
+    grade_start='3-6' despite the integer signature, which previously slipped past
+    _grade_key as 99 and silently filtered out every grade. Split it into two ends.
+    """
+    for val in (grade_start, grade_end):
+        if isinstance(val, str) and _RANGE_SEP.search(val.strip()):
+            parts = _RANGE_SEP.split(val.strip(), maxsplit=1)
+            if len(parts) == 2 and parts[0] and parts[1]:
+                return _coerce_grade(parts[0]), _coerce_grade(parts[1])
+    return _coerce_grade(grade_start), _coerce_grade(grade_end)
+
+
 # A single-letter CCSS cluster segment sitting directly before the final numeric
 # ordinal (e.g. the 'A' in '6.RP.A.3'). The DB is inconsistent about retaining it
 # — most IDs keep it ('5.NF.A.2') but some dropped it on ingest ('6.RP.3') — so
@@ -223,7 +304,48 @@ _CLUSTER_LETTER = re.compile(r"\.[A-Z](?=\.\d)")
 
 
 def _loose_id(sid: str) -> str:
-    return _CLUSTER_LETTER.sub("", sid)
+    # Upper-case so the compare is case-insensitive and lowercase cluster
+    # letters ('6.rp.a.3') still match the [A-Z] cluster pattern.
+    return _CLUSTER_LETTER.sub("", sid.upper())
+
+
+def _resolve_id(conn: sqlite3.Connection, sid: str, system: str) -> str | None:
+    """Return the canonical stored ID matching sid, or None.
+
+    Tries, in order: exact match, case-insensitive exact match, then a
+    cluster-letter-tolerant loose match (so '6.RP.A.3' finds a stored
+    '6.RP.3' and vice versa, regardless of case). Each tier is retried with
+    trailing punctuation stripped ('6.RP.A.3.' pasted from prose) — but the
+    raw ID is always tried first, so IDs that legitimately end in punctuation
+    (e.g. Alberta 'CA-AB.MATH.K.MAT.5.1.3.a.') still match exactly. Shared by
+    lookup_standard and map_standard so both tolerate the same ID drift.
+    """
+    candidates = [sid]
+    stripped = sid.rstrip(" .,;:")
+    if stripped and stripped != sid:
+        candidates.append(stripped)
+
+    for cand in candidates:
+        row = conn.execute("SELECT id FROM standards WHERE id = ?", (cand,)).fetchone()
+        if row:
+            return row[0]
+        row = conn.execute(
+            "SELECT id FROM standards WHERE id = ? COLLATE NOCASE", (cand,)
+        ).fetchone()
+        if row:
+            return row[0]
+
+    for cand in candidates:
+        target = _loose_id(cand)
+        match = next(
+            (cid for (cid,) in conn.execute(
+                "SELECT id FROM standards WHERE system = ?", (system,))
+             if _loose_id(cid) == target),
+            None,
+        )
+        if match:
+            return match
+    return None
 
 
 # ── Embedding ─────────────────────────────────────────────────────────────────
@@ -239,10 +361,24 @@ def _embed_query(text: str) -> np.ndarray:
     return np.array(resp.json()["embeddings"][0], dtype=np.float32)
 
 
+# Canonical crosswalk-hub system per subject. A bare search (no system/subject)
+# ranks across all hubs so it is not silently limited to math.
+SUBJECT_HUB = {
+    "mathematics":    "ccss",
+    "science":        "ngss",
+    "ela":            "ccss-ela",
+    "social-studies": "c3",
+    "cs":             "csta",
+}
+HUB_SYSTEMS = list(SUBJECT_HUB.values())
+
+
 def _cosine_scores(
     query_vec: np.ndarray,
     conn: sqlite3.Connection,
     system: str | None = None,
+    systems: list[str] | None = None,
+    subject: str | None = None,
 ) -> list[tuple[float, str]]:
     if system:
         rows = conn.execute(
@@ -250,6 +386,19 @@ def _cosine_scores(
             "JOIN standards s ON s.id = e.standard_id WHERE s.system = ?",
             (system,),
         ).fetchall()
+    elif systems:
+        ph = ",".join("?" * len(systems))
+        rows = conn.execute(
+            "SELECT e.standard_id, e.vector, e.dimensions FROM embeddings e "
+            f"JOIN standards s ON s.id = e.standard_id WHERE s.system IN ({ph})",
+            list(systems),
+        ).fetchall()
+    elif subject:
+        rows = conn.execute(
+            "SELECT e.standard_id, e.vector, e.dimensions FROM embeddings e "
+            "JOIN standards s ON s.id = e.standard_id WHERE s.subject = ?",
+            (subject,),
+        ).fetchall()
     else:
         rows = conn.execute("SELECT standard_id, vector, dimensions FROM embeddings").fetchall()
     if not rows:
@@ -303,12 +452,14 @@ def _ensure_fts(conn: sqlite3.Connection) -> bool:
 def _fts_search(
     query: str,
     conn: sqlite3.Connection,
-    system: str,
+    system: str | None = None,
+    systems: list[str] | None = None,
+    subject: str | None = None,
     grade_filter: set[str] | None = None,
     domain_filter: str | None = None,
     limit: int = 5,
 ) -> list[dict]:
-    """BM25-ranked FTS5 keyword search, filtered to a single curriculum system."""
+    """BM25-ranked FTS5 keyword search, scoped to a system, set of systems, or subject."""
     if not _ensure_fts(conn):
         return []
     fts_q = _fts_query(query)
@@ -331,13 +482,22 @@ def _fts_search(
 
     rowids = [r[0] for r in ranked]
     placeholders = ",".join("?" * len(rowids))
+    if system:
+        scope_sql, scope_args = "AND system = ?", [system]
+    elif systems:
+        ph = ",".join("?" * len(systems))
+        scope_sql, scope_args = f"AND system IN ({ph})", list(systems)
+    elif subject:
+        scope_sql, scope_args = "AND subject = ?", [subject]
+    else:
+        scope_sql, scope_args = "", []
     try:
         rows_by_id = {
             r["rowid"]: r
             for r in conn.execute(
                 f"SELECT rowid, id, grade, domain, standard_text"
-                f" FROM standards WHERE rowid IN ({placeholders}) AND system = ?",
-                rowids + [system],
+                f" FROM standards WHERE rowid IN ({placeholders}) {scope_sql}",
+                rowids + scope_args,
             ).fetchall()
         }
     except Exception:
@@ -363,6 +523,51 @@ def _fts_search(
     return results
 
 
+# ── Relationship helpers (shared by lookup_standard + get_learning_path) ──────
+
+# Minimum confidence_score for an LLM-validated edge to count as a HARD (default)
+# prerequisite. SOFT edges are stored at 0.5 and only surfaced with include_soft.
+_HARD_CONF = 0.9
+_SOFT_CONF = 0.5
+
+
+def _related(conn, sid: str, relationship: str, prefer_validated: bool):
+    """Return (ids, source) for a standard's prerequisite/successor edges.
+
+    When prefer_validated is True and any method='llm_validated' edges exist for
+    this standard, return those (source='llm_validated'); otherwise fall back to
+    the grade-heuristic edges (source='grade_heuristic'). Falling back preserves
+    non-empty prerequisite lists for standards the pilot never re-validated.
+    """
+    if prefer_validated:
+        val = [r[0] for r in conn.execute(
+            "SELECT target_id FROM standard_relationships "
+            "WHERE source_id=? AND relationship=? AND method='llm_validated' "
+            "ORDER BY confidence_score DESC, target_id",
+            (sid, relationship)).fetchall()]
+        if val:
+            return val, "llm_validated"
+    allrows = [r[0] for r in conn.execute(
+        "SELECT target_id FROM standard_relationships "
+        "WHERE source_id=? AND relationship=? ORDER BY target_id",
+        (sid, relationship)).fetchall()]
+    return allrows, "grade_heuristic"
+
+
+def _parse_prereq_note(notes: str | None) -> tuple[str | None, str | None]:
+    """Split a validated-edge note into (strength, rationale).
+
+    Stored form: 'llm_prereq cosine=0.83 hard: <why>' — surfaced so callers can
+    show *why* a prerequisite was included (the provenance/trust story).
+    """
+    if not notes:
+        return None, None
+    m = re.search(r"\b(hard|soft):\s*(.*)$", notes, re.S)
+    if m:
+        return m.group(1), m.group(2).strip() or None
+    return None, notes.strip() or None
+
+
 # ── Tool 1: lookup_standard ───────────────────────────────────────────────────
 
 @mcp.tool()
@@ -370,6 +575,7 @@ def lookup_standard(
     standard_id: str,
     system: str = "ccss",
     include_elaborations: bool = False,
+    prefer_validated: bool = True,
 ) -> str:
     """Fetch the full text, domain, cluster, prerequisites, and successors for a single standard.
 
@@ -378,6 +584,10 @@ def lookup_standard(
     standard_id: full ID like 'CCSS.MATH.6.RP.A.3' or shortform '6.RP.A.3' (for CCSS).
                  For other systems use the full ID, e.g. 'TX.MATH.5.3.K' or 'CA_BC.MATH.3.a'.
     system: curriculum system code (default 'ccss'). See server instructions for all codes.
+    prefer_validated: when True (default), return the LLM-validated prerequisite/successor
+                 edges if any exist for this standard (higher precision, may be cross-domain);
+                 otherwise fall back to the grade-heuristic edges. The response reports which
+                 source was used via `prerequisites_method`.
 
     Returns the standard text, grade, domain, cluster, sub-standards (if any),
     prerequisite standard IDs from the prior grade, and successor IDs for the next grade.
@@ -385,19 +595,17 @@ def lookup_standard(
     sid = _expand_id(standard_id, system)
     conn = _db()
 
-    row = conn.execute("SELECT * FROM standards WHERE id = ?", (sid,)).fetchone()
-    if not row:
-        # Tolerate cluster-letter drift: match ignoring the single-letter cluster
-        # segment, so '6.RP.A.3' finds a stored '6.RP.3' (and vice versa).
-        target = _loose_id(sid)
-        match_id = next(
-            (cid for (cid,) in conn.execute(
-                "SELECT id FROM standards WHERE system=?", (system,))
-             if _loose_id(cid) == target),
-            None,
-        )
-        if match_id:
-            row = conn.execute("SELECT * FROM standards WHERE id = ?", (match_id,)).fetchone()
+    # Resolve to the canonical stored ID (tolerating cluster-letter/case drift),
+    # then use it for every downstream lookup so sub-standards, prerequisites and
+    # successors are keyed off the real ID rather than the drifted input.
+    canonical = _resolve_id(conn, sid, system)
+    row = (
+        conn.execute("SELECT * FROM standards WHERE id = ?", (canonical,)).fetchone()
+        if canonical
+        else None
+    )
+    if row:
+        sid = canonical
     if not row:
         # Suggest nearby IDs
         suggestions = [
@@ -416,18 +624,23 @@ def lookup_standard(
         (sid,),
     ).fetchall()
 
-    prerequisites = [
-        r[0] for r in conn.execute(
-            "SELECT target_id FROM standard_relationships WHERE source_id=? AND relationship='prerequisite'",
-            (sid,),
-        ).fetchall()
-    ]
-    successors = [
-        r[0] for r in conn.execute(
-            "SELECT target_id FROM standard_relationships WHERE source_id=? AND relationship='successor'",
-            (sid,),
-        ).fetchall()
-    ]
+    prerequisites, prereq_method = _related(conn, sid, "prerequisite", prefer_validated)
+    successors, _ = _related(conn, sid, "successor", prefer_validated)
+
+    # Provenance: when the prerequisites are LLM-validated, surface *why* each was
+    # included (rationale + hard/soft strength) so callers can show/trust the edge.
+    prereq_rationales = None
+    if prereq_method == "llm_validated":
+        prereq_rationales = {}
+        for r in conn.execute(
+            "SELECT target_id, confidence_score, notes FROM standard_relationships "
+            "WHERE source_id=? AND relationship='prerequisite' AND method='llm_validated'",
+            (sid,)).fetchall():
+            strength, why = _parse_prereq_note(r[2])
+            prereq_rationales[r[0]] = {
+                "strength": strength or ("hard" if (r[1] or 0) >= _HARD_CONF else "soft"),
+                "why": why,
+            }
     conn.close()
 
     return json.dumps({
@@ -439,6 +652,8 @@ def lookup_standard(
         "standard_text": std["standard_text"],
         "sub_standards": [f"{r['id']} — {r['text']}" for r in sub_stds],
         "prerequisites": prerequisites,
+        "prerequisites_method": prereq_method,
+        "prerequisite_rationales": prereq_rationales,
         "successors":    successors,
         "source_url":   std["source_url"],
         "elaborations":  None,
@@ -450,7 +665,8 @@ def lookup_standard(
 @mcp.tool()
 def search_standards(
     query: str,
-    system: str = "ccss",
+    system: str | None = None,
+    subject: str | None = None,
     grade: str | None = None,
     domain: str | None = None,
     limit: int = 5,
@@ -461,8 +677,15 @@ def search_standards(
     Works across all subjects: mathematics, science, ELA, social studies, CS, arts, world-languages.
     Examples: "adding fractions with unlike denominators", "photosynthesis", "argumentative writing grade 8".
 
+    Search scope is resolved in this order:
+      • system given  → search that one curriculum (e.g. 'ngss', 'sg-moe', 'de' = Delaware).
+      • subject given → search that subject's canonical hub ('mathematics'→ccss, 'science'→ngss,
+        'ela'→ccss-ela, 'social-studies'→c3, 'cs'→csta; 'arts'/'world-languages' search subject-wide).
+      • neither       → rank across all five subject hubs, so a bare query is never limited to math.
+
     query: plain English description of the concept or skill.
-    system: which curriculum to search (default 'ccss'). Call multiple times to compare systems.
+    system: optional — a single curriculum code. Call multiple times to compare systems.
+    subject: optional — 'mathematics', 'science', 'ela', 'social-studies', 'cs', 'arts', 'world-languages'.
     grade: optional filter — single grade '5', range '6-8', or 'HS'. Grade codes: K 1 2 3 4 5 6 7 8 HS.
     domain: optional keyword to restrict by domain name (e.g. 'geometry', 'algebra').
     limit: number of results (default 5, max sensible ~10).
@@ -470,12 +693,28 @@ def search_standards(
     Uses semantic similarity (requires Ollama) with automatic keyword FTS fallback when Ollama is unavailable.
     Returns standards ranked by relevance with scores (0–1).
     """
+    # Resolve scope: explicit system > subject (→ its hub, or subject-wide if hubless) > all hubs.
+    scope_system: str | None = None
+    scope_systems: list[str] | None = None
+    scope_subject: str | None = None
+    if system:
+        scope_system = system
+    elif subject:
+        hub = SUBJECT_HUB.get(subject.lower())
+        if hub:
+            scope_system = hub
+        else:
+            scope_subject = subject.lower()  # arts / world-languages: no hub, search the subject
+    else:
+        scope_systems = HUB_SYSTEMS
+
     try:
         query_vec = _embed_query(query)
     except Exception:
         conn = _db()
         results = _fts_search(
-            query, conn, system,
+            query, conn,
+            system=scope_system, systems=scope_systems, subject=scope_subject,
             grade_filter=_parse_grade_filter(grade) if grade else None,
             domain_filter=domain,
             limit=limit,
@@ -487,7 +726,7 @@ def search_standards(
             "results": results,
         }, indent=2)
     conn = _db()
-    scored = _cosine_scores(query_vec, conn, system=system)
+    scored = _cosine_scores(query_vec, conn, system=scope_system, systems=scope_systems, subject=scope_subject)
 
     results = []
     for score, sid in scored:
@@ -541,8 +780,8 @@ def _parse_grade_filter(grade: str | list) -> set[str]:
 def get_progression(
     concept: str,
     system: str = "ccss",
-    grade_start: int | None = None,
-    grade_end: int | None = None,
+    grade_start: int | str | None = None,
+    grade_end: int | str | None = None,
 ) -> str:
     """Show how a math concept is introduced and built upon across grade levels.
 
@@ -552,11 +791,13 @@ def get_progression(
     concept: plain English name of the math concept (e.g. 'fractions', 'linear equations',
              'place value', 'geometric transformations').
     system: curriculum to trace (default 'ccss'). Try 'cambridge' or 'ib-myp' for comparison.
-    grade_start / grade_end: optional integer bounds to narrow the range (e.g. 3 and 8).
+    grade_start / grade_end: optional bounds to narrow the range (e.g. 3 and 8). Accepts
+             ints, grade codes ('K', 'HS'), or a single range string like '3-6' / '6 to 8'.
 
     Returns the top matching standards per grade, ordered K through HS, showing how the
     concept deepens over time.
     """
+    g_start, g_end = _norm_grade_bounds(grade_start, grade_end)
     try:
         query_vec = _embed_query(concept)
     except Exception:
@@ -573,8 +814,8 @@ def get_progression(
                 continue
             by_grade.setdefault(g, []).append({"id": r["id"], "text": r["standard_text"]})
 
-        gr_start = str(grade_start) if grade_start is not None else "K"
-        gr_end   = str(grade_end)   if grade_end   is not None else "HS"
+        gr_start = g_start or "K"
+        gr_end   = g_end   or "HS"
 
         return json.dumps({
             "concept":       concept,
@@ -603,9 +844,9 @@ def get_progression(
         std = dict(row)
         g = std["grade"]
 
-        if grade_start is not None and _grade_key(g) < _grade_key(str(grade_start)):
+        if g_start is not None and _grade_key(g) < _grade_key(g_start):
             continue
-        if grade_end is not None and _grade_key(g) > _grade_key(str(grade_end)):
+        if g_end is not None and _grade_key(g) > _grade_key(g_end):
             continue
 
         by_grade.setdefault(g, []).append({
@@ -616,8 +857,8 @@ def get_progression(
 
     conn.close()
 
-    gr_start = str(grade_start) if grade_start is not None else "K"
-    gr_end   = str(grade_end)   if grade_end   is not None else "HS"
+    gr_start = g_start or "K"
+    gr_end   = g_end   or "HS"
 
     stages = []
     for g in sorted(by_grade.keys(), key=_grade_key):
@@ -635,7 +876,165 @@ def get_progression(
     }, indent=2)
 
 
-# ── Tool 4: map_standard ──────────────────────────────────────────────────────
+# ── Tool 4: get_learning_path ─────────────────────────────────────────────────
+
+@mcp.tool()
+def get_learning_path(
+    target: str,
+    system: str = "ccss",
+    from_standard: str | None = None,
+    max_depth: int = 20,
+    include_soft: bool = False,
+) -> str:
+    """Build an ordered, grade-increasing sequence of standards to learn to reach a target.
+
+    Walks the LLM-validated prerequisite graph backward from the target standard and
+    returns every prerequisite (transitively) as a topologically ordered study plan —
+    the substrate for self-paced acceleration ("what do I need before calculus?").
+    Only method='llm_validated' edges are traversed, so the path is far cleaner than the
+    raw grade-adjacency graph and includes genuine cross-domain dependencies.
+
+    target: the standard to work toward — full ID 'CCSS.MATH.HSF.LE.A.1.b' or shortform.
+    system: curriculum system code (default 'ccss'; validated edges currently exist for CCSS math).
+    from_standard: optional — the standard the learner has already mastered. When given, the
+                   path is pruned to the sub-sequence between that standard and the target.
+    max_depth: max prerequisite levels to walk back (default 20; guards pathological depth).
+    include_soft: when False (default) only HARD prerequisites (direct building blocks) are
+                  followed; when True, SOFT (helpful-background) edges are included too.
+
+    Returns the resolved target, an ordered `path` (each node with id/grade/domain/text and its
+    immediate in-path prerequisites), plus counts. If the target has no validated prerequisites
+    the path is just the target with an explanatory note.
+    """
+    conn = _db()
+    tgt = _resolve_id(conn, _expand_id(target, system), system)
+    if not tgt:
+        conn.close()
+        return json.dumps({"error": "standard_not_found", "queried_id": _expand_id(target, system)})
+
+    min_conf = _SOFT_CONF if include_soft else _HARD_CONF
+    # (learner, prereq) -> {strength, why, confidence} for provenance in the output.
+    edge_meta: dict[tuple[str, str], dict] = {}
+
+    def prereqs_of(node: str) -> list[str]:
+        rows = conn.execute(
+            "SELECT target_id, confidence_score, notes FROM standard_relationships "
+            "WHERE source_id=? AND relationship='prerequisite' "
+            "AND method='llm_validated' AND confidence_score >= ?",
+            (node, min_conf)).fetchall()
+        out = []
+        for p, conf, notes in rows:
+            strength, why = _parse_prereq_note(notes)
+            edge_meta[(node, p)] = {
+                "strength": strength or ("hard" if (conf or 0) >= _HARD_CONF else "soft"),
+                "why": why,
+                "confidence": conf,
+            }
+            out.append(p)
+        return out
+
+    # Reverse-BFS the prerequisite closure of the target, bounded by max_depth.
+    seen = {tgt}
+    edges: dict[str, list[str]] = {}
+    frontier = [tgt]
+    depth = 0
+    while frontier and depth < max_depth:
+        nxt: list[str] = []
+        for n in frontier:
+            ps = prereqs_of(n)
+            edges[n] = ps
+            for p in ps:
+                if p not in seen:
+                    seen.add(p)
+                    nxt.append(p)
+        frontier = nxt
+        depth += 1
+
+    # Optional from_standard pruning: keep only nodes on a chain from_standard → target.
+    from_resolved = None
+    from_reachable = None
+    if from_standard:
+        src = _resolve_id(conn, _expand_id(from_standard, system), system)
+        from_resolved = src
+        from_reachable = bool(src and src in seen)
+        if from_reachable:
+            # Forward reachability from src via validated successor edges, within the closure.
+            fwd = {src}
+            fr = [src]
+            while fr:
+                nx: list[str] = []
+                for n in fr:
+                    for r in conn.execute(
+                        "SELECT target_id FROM standard_relationships "
+                        "WHERE source_id=? AND relationship='successor' "
+                        "AND method='llm_validated' AND confidence_score >= ?",
+                        (n, min_conf)).fetchall():
+                        s = r[0]
+                        if s in seen and s not in fwd:
+                            fwd.add(s)
+                            nx.append(s)
+                fr = nx
+            keep = (fwd & seen) | {tgt}
+            seen = {n for n in seen if n in keep}
+
+    # Materialise node rows and order by grade (every validated edge increases grade,
+    # so grade order is a valid topological order; ties broken by id for determinism).
+    nodes = []
+    for n in seen:
+        row = conn.execute(
+            "SELECT id, grade, domain, standard_text FROM standards WHERE id=?", (n,)
+        ).fetchone()
+        if row:
+            nodes.append(dict(row))
+    conn.close()
+    nodes.sort(key=lambda d: (_grade_key(d["grade"]), d["id"]))
+
+    setids = {d["id"] for d in nodes}
+
+    def _prereq_entries(learner: str):
+        entries = []
+        for p in edges.get(learner, []):
+            if p not in setids:
+                continue
+            meta = edge_meta.get((learner, p), {})
+            entries.append({
+                "id":       p,
+                "strength": meta.get("strength"),
+                "why":      meta.get("why"),
+            })
+        return entries
+
+    path = [{
+        "id":            d["id"],
+        "grade":         d["grade"],
+        "domain":        d["domain"],
+        "standard_text": d["standard_text"],
+        "prerequisites_in_path": _prereq_entries(d["id"]),
+    } for d in nodes]
+
+    result = {
+        "target":       tgt,
+        "system":       system,
+        "edge_strength": "hard+soft" if include_soft else "hard_only",
+        "path_length":  len(path),
+        "path":         path,
+    }
+    if from_standard:
+        result["from_standard"] = from_resolved or _expand_id(from_standard, system)
+        result["from_standard_reachable"] = from_reachable
+    # Notes, most-specific first.
+    if from_standard and from_reachable and len(path) == 1:
+        # from_standard prunes everything else away → learner is already at/past the target.
+        result["note"] = "from_standard already reaches the target — no intermediate steps needed"
+    elif len(path) == 1 and path[0]["id"] == tgt:
+        result["note"] = ("no validated prerequisites found for this target"
+                          + (" at hard strength — retry with include_soft=True" if not include_soft else ""))
+    elif from_standard and from_resolved and not from_reachable:
+        result["note"] = "from_standard is not a validated prerequisite of the target; returning the full prerequisite path"
+    return json.dumps(result, indent=2)
+
+
+# ── Tool 5: map_standard ──────────────────────────────────────────────────────
 
 @mcp.tool()
 def map_standard(
@@ -670,11 +1069,19 @@ def map_standard(
     sid = _expand_id(standard_id, from_system)
     conn = _db()
 
-    src = conn.execute("SELECT * FROM standards WHERE id=?", (sid,)).fetchone()
+    # Same cluster-letter/case tolerance as lookup_standard, then pin sid to the
+    # canonical ID so the crosswalk/embedding queries below hit the stored rows.
+    canonical = _resolve_id(conn, sid, from_system)
+    src = (
+        conn.execute("SELECT * FROM standards WHERE id=?", (canonical,)).fetchone()
+        if canonical
+        else None
+    )
     if not src:
         conn.close()
         return json.dumps({"error": "standard_not_found", "queried_id": sid})
 
+    sid = canonical
     src_dict = dict(src)
 
     # ── 1. Precomputed crosswalk above threshold ───────────────────────────────
@@ -881,7 +1288,49 @@ def map_standard(
     return json.dumps(response, indent=2)
 
 
-# ── Tool 5: list_systems ──────────────────────────────────────────────────────
+# ── Tool 6: list_systems ──────────────────────────────────────────────────────
+
+@functools.lru_cache(maxsize=1)
+def _systems_snapshot():
+    """Per-process cache of system-level aggregates + corpus totals.
+
+    These come from full-table scans (GROUP BY over ~157k standards, a JOIN+GROUP
+    over ~103k crosswalks, a COUNT over ~3.2M relationships) that are *static* for a
+    server's lifetime — the DB is read-only while serving and the hosted process
+    restarts on any DB refresh. Caching turns list_systems from ~250ms into ~0.1ms
+    on repeat calls and removes it as a GIL bottleneck under concurrent load.
+    Returns (rows, totals); rows carry a private `subject_set` for the subject filter.
+    """
+    conn = _db()
+    systems = conn.execute(
+        "SELECT system, GROUP_CONCAT(DISTINCT subject) AS subjects, COUNT(id) AS standards "
+        "FROM standards GROUP BY system ORDER BY system").fetchall()
+    xwalk_counts = dict(conn.execute(
+        "SELECT s.system, COUNT(*) FROM crosswalk_mappings cm "
+        "INNER JOIN standards s ON s.id = cm.source_id GROUP BY s.system").fetchall())
+    totals = {
+        "systems":            len(systems),
+        "standards":          conn.execute("SELECT COUNT(*) FROM standards").fetchone()[0],
+        "embeddings":         conn.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0],
+        "crosswalk_mappings": conn.execute("SELECT COUNT(*) FROM crosswalk_mappings").fetchone()[0],
+        "relationships":      conn.execute("SELECT COUNT(*) FROM standard_relationships").fetchone()[0],
+    }
+    conn.close()
+
+    rows = []
+    for r in systems:
+        m = _meta(r["system"])
+        rows.append({
+            "system":      r["system"],
+            "subjects":    r["subjects"],
+            "subject_set": set((r["subjects"] or "").split(",")),
+            "standards":   r["standards"],
+            "crosswalked": xwalk_counts.get(r["system"], 0),
+            "country":     m.get("country"),
+            "region":      m.get("region", "") or None,
+        })
+    return rows, totals
+
 
 @mcp.tool()
 def list_systems(
@@ -899,63 +1348,19 @@ def list_systems(
 
     Returns: system code, subjects covered, standard count, crosswalk coverage, country, region.
     """
-    conn = _db()
-
-    # Build subject-filtered system list from the standards table
-    if subject:
-        subject_systems = {
-            r[0] for r in conn.execute(
-                "SELECT DISTINCT system FROM standards WHERE subject = ?", (subject,)
-            ).fetchall()
-        }
-    else:
-        subject_systems = None
-
-    # Counts split into separate fast queries to avoid expensive 3-way JOIN.
-    systems = conn.execute(
-        """SELECT system,
-                  GROUP_CONCAT(DISTINCT subject) AS subjects,
-                  COUNT(id) AS standards
-           FROM standards
-           GROUP BY system
-           ORDER BY system"""
-    ).fetchall()
-    xwalk_counts = dict(conn.execute(
-        "SELECT s.system, COUNT(*) FROM crosswalk_mappings cm "
-        "INNER JOIN standards s ON s.id = cm.source_id GROUP BY s.system"
-    ).fetchall())
-
-    total_std = conn.execute("SELECT COUNT(*) FROM standards").fetchone()[0]
-    total_emb = conn.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0]
-    total_xwalk = conn.execute("SELECT COUNT(*) FROM crosswalk_mappings").fetchone()[0]
-    total_rel = conn.execute("SELECT COUNT(*) FROM standard_relationships").fetchone()[0]
-    conn.close()
+    all_rows, totals = _systems_snapshot()
 
     system_rows = []
-    for r in systems:
-        if subject_systems is not None and r["system"] not in subject_systems:
+    for r in all_rows:
+        if subject and subject not in r["subject_set"]:
             continue
-        m = _meta(r["system"])
-        sys_region = m.get("region", "")
-        if region and region.lower() not in sys_region.lower():
+        if region and region.lower() not in (r["region"] or "").lower():
             continue
-        system_rows.append({
-            "system":      r["system"],
-            "subjects":    r["subjects"],
-            "standards":   r["standards"],
-            "crosswalked": xwalk_counts.get(r["system"], 0),
-            "country":     m.get("country"),
-            "region":      sys_region or None,
-        })
+        system_rows.append({k: r[k] for k in
+                            ("system", "subjects", "standards", "crosswalked", "country", "region")})
 
     return json.dumps({
-        "totals": {
-            "systems":            len(systems),
-            "standards":          total_std,
-            "embeddings":         total_emb,
-            "crosswalk_mappings": total_xwalk,
-            "relationships":      total_rel,
-        },
+        "totals": totals,
         "filters_applied": {k: v for k, v in {"subject": subject, "region": region}.items() if v},
         "matched_systems":  len(system_rows),
         "systems": system_rows,

{standardgraph-1.2.4 → standardgraph-1.4.0}/src/standardgraph.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: standardgraph
-Version: 1.2.4
-Summary: 158,000+ education standards (math, science, ELA, social studies, CS, arts) across 300 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server
+Version: 1.4.0
+Summary: 172,000+ education standards (math, science, ELA, social studies, CS, arts) across 310 curriculum systems, cross-referenced via NLP — accessible as a Claude MCP server
 Author: StandardGraph
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/swoopeagle/standardgraph
@@ -24,7 +24,7 @@ Requires-Dist: numpy>=1.26.0
 
 <!-- mcp-name: io.github.swoopeagle/standardgraph -->
 
-**158,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
+**154,000+ education standards across 300 curriculum systems, accessible as a Claude MCP server.**
 
 Covers seven subjects — Mathematics, Science, ELA, Social Studies, Computer Science, Arts, and World Languages — across the US (CCSS + all 50 states), Canada, Australia, UK, Singapore, Japan, New Zealand, Ireland, Hong Kong, India, Ghana, South Africa, Rwanda, Cambridge International, IB MYP/DP, AP, and more. Standards are cross-referenced to subject hubs (CCSS for math, NGSS for science, etc.) via semantic similarity, with LLM quality scores on the strongest mappings.