rag-backend / src /graph /reasoning.py
Harshilforworks's picture
Upload 99 files
4244db2 verified
Raw History Blame Contribute Delete
20.5 kB
"""
Graph reasoning layer β€” all prerequisite logic lives here.
Operates on the singleton DiGraph from graph.store.
"""
import re
import networkx as nx
from src.graph.store import get_graph
from src.core.logger import get_logger
log = get_logger(__name__)
_FINANCIAL_AID_SCOPE_RE = re.compile(
r"""
\b(?:
federal\s*student\s*(?:financial|nancial)\s*assistance|
(?:financial|nancial)\s*aid|
federal\s*aid|
federal\s*regulations|
satisfactory\s*academic\s*progress|
(?:financial|nancial)\s*aid\s*(?:warning|probation)|
67\s*%|
150\s*%|
\bpace\b
)\b
""",
re.IGNORECASE | re.VERBOSE,
)
# ─────────────────────────────────────────────────────────────────────────────
# Internal helpers
# ─────────────────────────────────────────────────────────────────────────────
def _normalize(code: str) -> str:
"""Uppercase and strip whitespace so lookups are consistent."""
return code.strip().upper()
def _predecessors_of(G: nx.DiGraph, course: str) -> list[tuple[str, dict]]:
"""Return (prereq_code, edge_attrs) for all direct prerequisites."""
return [(u, G[u][course]) for u in G.predecessors(course)]
def _grade_ok(grade_received: str, min_grade: str) -> bool:
"""
Simple letter-grade comparison.
Order: A > B > C > D > F
Returns True when grade_received meets or exceeds min_grade.
"""
order = {"A": 5, "B": 4, "C": 3, "D": 2, "F": 1, "": 0}
received = grade_received.strip().upper()[:1]
minimum = min_grade.strip().upper()[:1]
return order.get(received, 0) >= order.get(minimum, 0)
def _coerce_gpa_value(value: object) -> float | None:
"""Convert numeric/string GPA to float when possible."""
if value is None:
return None
if isinstance(value, (int, float)):
return float(value)
if isinstance(value, str):
match = re.search(r"\d(?:\.\d+)?", value)
if match:
try:
return float(match.group(0))
except ValueError:
return None
return None
def _format_gpa(value: float) -> str:
"""Format GPA values consistently for messages."""
return f"{value:.1f}"
def _normalize_student_level(value: object) -> str:
"""Normalize audience level labels used by policy rules."""
if value is None:
return ""
lowered = str(value).strip().lower()
if lowered.startswith("under"):
return "undergraduate"
if lowered.startswith("grad"):
return "graduate"
return ""
def _normalize_policy_scope(value: object) -> str:
"""Normalize policy scope labels used to decide applicability."""
if value is None:
return ""
lowered = str(value).strip().lower().replace("-", "_").replace(" ", "_")
if lowered in {"financial_aid", "aid", "federal_aid"}:
return "financial_aid"
if lowered in {"general", "enrollment", "academic", "all"}:
return "general"
return ""
def _infer_policy_scope(rule: dict) -> str:
"""
Infer policy scope for backward compatibility with previously ingested data.
Old graph metadata may not include a scope field, so we infer from evidence
text and treat policies as general unless they explicitly mention aid.
"""
explicit = _normalize_policy_scope(rule.get("scope"))
if explicit:
return explicit
evidence_blob = " ".join(
[
str(rule.get("evidence_text", "") or ""),
str(rule.get("document_name", "") or ""),
]
)
if _FINANCIAL_AID_SCOPE_RE.search(evidence_blob):
return "financial_aid"
return "general"
def _filter_policy_requirements(
policy_requirements: list[dict],
include_financial_aid_policies: bool,
) -> list[dict]:
"""Return only policies relevant to the current eligibility context."""
filtered: list[dict] = []
for rule in policy_requirements:
scope = _infer_policy_scope(rule)
if scope == "financial_aid" and not include_financial_aid_policies:
continue
normalized_rule = dict(rule)
normalized_rule["scope"] = scope
filtered.append(normalized_rule)
return filtered
def _evaluate_global_gpa_requirements(
policy_requirements: list[dict],
student_gpa: float | None,
student_level: str,
) -> tuple[list[str], bool, bool, bool]:
"""
Returns (issues, missing_gpa_info, has_hard_violation, missing_level_info).
"""
issues: list[str] = []
missing_gpa_info = False
has_hard_violation = False
missing_level_info = False
seen_rules: set[tuple[str, float, float | None]] = set()
missing_level_audiences: set[str] = set()
for rule in policy_requirements:
if str(rule.get("type", "")).lower() != "gpa":
continue
audience = _normalize_student_level(rule.get("audience", "all"))
if not audience:
audience = "all"
if audience != "all" and not student_level:
missing_level_audiences.add(audience)
continue
if audience != "all" and audience != student_level:
continue
threshold = _coerce_gpa_value(rule.get("threshold"))
if threshold is None:
continue
operator = str(rule.get("operator", ">=") or ">=")
scale_max = _coerce_gpa_value(rule.get("scale_max"))
dedupe_key = (operator, threshold, scale_max)
if dedupe_key in seen_rules:
continue
seen_rules.add(dedupe_key)
rule_text = f"cumulative GPA {operator} {_format_gpa(threshold)}"
if scale_max is not None:
rule_text += f" on {_format_gpa(scale_max)} scale"
if student_gpa is None:
issues.append(f"Requires {rule_text} - GPA not provided")
missing_gpa_info = True
continue
if operator == ">":
ok = student_gpa > threshold
else:
ok = student_gpa >= threshold
if not ok:
issues.append(f"Requires {rule_text}, got {_format_gpa(student_gpa)}")
has_hard_violation = True
if missing_level_audiences:
ordered = ", ".join(sorted(missing_level_audiences))
issues.append(
f"GPA policy depends on student level ({ordered}) - student level not provided"
)
missing_level_info = True
return issues, missing_gpa_info, has_hard_violation, missing_level_info
# ─────────────────────────────────────────────────────────────────────────────
# Public API
# ─────────────────────────────────────────────────────────────────────────────
def check_eligibility(
course_code: str,
completed: list[str],
grades: dict[str, str] | None = None,
student_gpa: float | str | None = None,
student_level: str | None = None,
enforce_gpa_policies: bool = True,
include_financial_aid_policies: bool = False,
) -> dict:
"""
Check whether a student is eligible to enrol in course_code.
By default, GPA policies classified as financial-aid rules are excluded so
non-aid prerequisite checks are not over-constrained.
Returns
-------
{
"eligible": bool,
"decision": "Eligible" | "Not eligible" | "Need more info",
"missing_prereqs": list[str],
"missing_coreqs": list[str],
"grade_issues": list[str],
"gpa_issues": list[str],
"policy_requirements": list[dict],
"prereq_path": list[str], # full ordered chain
"either_or_options": list[list[str]]
}
"""
G = get_graph()
course = _normalize(course_code)
normalized_grades = grades or {}
gpa_value = _coerce_gpa_value(student_gpa)
level_value = _normalize_student_level(student_level)
completed_set = {_normalize(c) for c in completed}
raw_policy_requirements = (
list(G.graph.get("global_policy_requirements", [])) if enforce_gpa_policies else []
)
policy_requirements = _filter_policy_requirements(
raw_policy_requirements,
include_financial_aid_policies,
)
result = {
"eligible": False,
"decision": "Need more info",
"missing_prereqs": [],
"missing_coreqs": [],
"grade_issues": [],
"gpa_issues": [],
"prereq_path": [],
"either_or_options": [],
"policy_requirements": policy_requirements,
}
if course not in G:
log.warning(f"Course {course} not found in graph.")
result["decision"] = "Need more info"
return result
missing_prereqs: list[str] = []
missing_coreqs: list[str] = []
grade_issues: list[str] = []
gpa_issues, missing_gpa_info, gpa_hard_violation, missing_level_info = _evaluate_global_gpa_requirements(
policy_requirements,
gpa_value,
level_value,
)
either_or_options: list[list[str]] = []
# Group predecessors by requirement_type
required_edges: list[tuple[str, dict]] = []
either_or_groups: dict[str, dict[str, list[str]]] = {}
coreq_edges: list[tuple[str, dict]] = []
for prereq, attrs in _predecessors_of(G, course):
req_type = attrs.get("requirement_type", "required")
group = attrs.get("either_or_group", None)
if req_type == "corequisite":
coreq_edges.append((prereq, attrs))
elif req_type == "either_or" and group:
branch_ids = attrs.get("either_or_branches", []) or []
if not branch_ids:
single_branch = attrs.get("either_or_branch")
if single_branch:
branch_ids = [single_branch]
if not branch_ids:
# Backward compatibility for previously-ingested edges with no branch metadata.
branch_ids = [prereq]
group_branches = either_or_groups.setdefault(group, {})
for branch_id in branch_ids:
branch_key = str(branch_id)
group_branches.setdefault(branch_key, []).append(prereq)
else:
required_edges.append((prereq, attrs))
# ── Check hard required prereqs ──────────────────────────────────────────
for prereq, attrs in required_edges:
min_grade = attrs.get("min_grade", "")
if prereq not in completed_set:
missing_prereqs.append(prereq)
elif min_grade:
received = normalized_grades.get(prereq, "")
if received and not _grade_ok(received, min_grade):
grade_issues.append(
f"{prereq} requires grade {min_grade}, got {received}"
)
elif not received:
# Grade unknown β€” flag but don't block
grade_issues.append(
f"{prereq} requires grade {min_grade} β€” grade not provided"
)
has_hard_missing_prereqs = bool(missing_prereqs)
# ── Check either/or groups ───────────────────────────────────────────────
for group_key, branch_map in either_or_groups.items():
if has_hard_missing_prereqs:
# Defer alternative-group guidance until hard required prerequisites are met.
continue
branch_options: list[list[str]] = []
for courses in branch_map.values():
unique_courses: list[str] = []
for code in courses:
if code not in unique_courses:
unique_courses.append(code)
if unique_courses:
branch_options.append(unique_courses)
if not branch_options:
continue
common_courses = set(branch_options[0])
for branch in branch_options[1:]:
common_courses &= set(branch)
ordered_common = [code for code in branch_options[0] if code in common_courses]
for code in ordered_common:
if code not in completed_set and code not in missing_prereqs:
missing_prereqs.append(code)
common_satisfied = all(code in completed_set for code in ordered_common)
if not common_satisfied:
# Shared prerequisites are still missing; alternatives are not actionable yet.
continue
reduced_options: list[list[str]] = []
for branch in branch_options:
reduced = [code for code in branch if code not in common_courses]
if reduced and reduced not in reduced_options:
reduced_options.append(reduced)
# No residual options means the group effectively reduced to shared required courses.
if not reduced_options:
continue
satisfied = any(all(course in completed_set for course in branch) for branch in reduced_options)
if not satisfied:
option_labels: list[str] = []
for branch in reduced_options:
if len(branch) == 1:
option_labels.append(branch[0])
else:
option_labels.append(" and ".join(branch))
if option_labels:
either_or_options.append(option_labels)
# ── Check coreqs ─────────────────────────────────────────────────────────
for coreq, attrs in coreq_edges:
if coreq not in completed_set:
# Coreqs can be taken concurrently β€” flag but handle separately
missing_coreqs.append(coreq)
# ── Build prereq path ────────────────────────────────────────────────────
try:
prereq_path = get_full_prereq_chain(course)
except Exception:
prereq_path = []
result["prereq_path"] = prereq_path
result["missing_prereqs"] = missing_prereqs
result["missing_coreqs"] = missing_coreqs
result["grade_issues"] = grade_issues
result["gpa_issues"] = gpa_issues
result["either_or_options"] = either_or_options
# ── Final decision ───────────────────────────────────────────────────────
has_missing_either_or = bool(either_or_options)
if not missing_prereqs and not has_missing_either_or and not grade_issues and not gpa_issues:
result["eligible"] = True
result["decision"] = "Eligible"
elif (
(missing_gpa_info or missing_level_info)
and not missing_prereqs
and not has_missing_either_or
and not grade_issues
and not gpa_hard_violation
):
result["eligible"] = False
result["decision"] = "Need more info"
elif missing_prereqs or has_missing_either_or:
result["eligible"] = False
result["decision"] = "Not eligible"
else:
# Grade and/or GPA policy issues remain
result["eligible"] = False
result["decision"] = "Not eligible"
return result
def get_full_prereq_chain(course_code: str) -> list[str]:
"""
Return a topologically sorted list of ALL courses that must be
completed before enrolling in course_code (transitive closure).
"""
G = get_graph()
course = _normalize(course_code)
if course not in G:
return []
# Collect all ancestors
ancestors = nx.ancestors(G, course)
if not ancestors:
return []
# Build subgraph of just ancestors + target, then topo sort
sub = G.subgraph(ancestors | {course}).copy()
self_loops = list(nx.selfloop_edges(sub))
if self_loops:
sub.remove_edges_from(self_loops)
log.warning(
f"Ignored {len(self_loops)} self-loop edge(s) while computing prereq chain for {course}"
)
try:
ordered = list(nx.topological_sort(sub))
# Remove the target course itself from the chain
return [n for n in ordered if n != course]
except nx.NetworkXUnfeasible:
log.warning(f"Cycle detected in graph while computing prereq chain for {course}")
return sorted(ancestors)
def get_available_next_courses(completed: list[str]) -> list[str]:
"""
Return all courses a student can now enrol in, given their
completed course list (ignoring grade requirements for simplicity).
"""
G = get_graph()
completed_set = {_normalize(c) for c in completed}
available: list[str] = []
for node in G.nodes():
if node in completed_set:
continue
preds = list(G.predecessors(node))
if not preds:
# No prereqs β€” always available
available.append(node)
continue
# Check if all required prereqs are met (simple version, ignores grades)
result = check_eligibility(node, completed, {}, enforce_gpa_policies=False)
if result["eligible"]:
available.append(node)
return sorted(available)
def find_path_to_course(target_course: str, completed: list[str]) -> dict:
"""
Build a DAG-ready payload for the frontend path visualiser.
Returns
-------
{
"nodes": [{"id", "label", "credits", "completed": bool}],
"edges": [{"from", "to", "type", "min_grade"}],
"paths": list[list[str]],
"shortest_path": list[str],
"student_completed": list[str]
}
"""
G = get_graph()
target = _normalize(target_course)
comp_set = {_normalize(c) for c in completed}
if target not in G:
return {
"nodes": [], "edges": [], "paths": [],
"shortest_path": [], "student_completed": list(comp_set),
}
ancestors = nx.ancestors(G, target) | {target}
sub = G.subgraph(ancestors)
# Build nodes
nodes = []
for n in sub.nodes():
attrs = G.nodes[n]
nodes.append({
"id": n,
"label": attrs.get("course_name", n),
"credits": attrs.get("credits", 0),
"completed": n in comp_set,
})
# Build edges
edges = []
for u, v, attrs in sub.edges(data=True):
edges.append({
"from": u,
"to": v,
"type": attrs.get("requirement_type", "required"),
"min_grade": attrs.get("min_grade", ""),
})
# Find all simple paths from any root (no prereqs) to target
roots = [n for n in sub.nodes() if sub.in_degree(n) == 0]
all_paths: list[list[str]] = []
for root in roots:
try:
for path in nx.all_simple_paths(G, root, target):
all_paths.append(path)
except nx.NetworkXNoPath:
pass
# Shortest path: fewest hops from any completed course or root
shortest: list[str] = []
if all_paths:
shortest = min(all_paths, key=len)
return {
"nodes": nodes,
"edges": edges,
"paths": all_paths,
"shortest_path": shortest,
"student_completed": list(comp_set),
}