Functions
SPlannerState	s_planner_node (SPlannerState state, RunnableConfig config)
APlannerState	a_planner_node (APlannerState state, RunnableConfig config)
	db_node (DatabaseHelperState state, RunnableConfig config)
	web_node (WebSearchHelperState state, RunnableConfig config)
InsertionHelperState	insertion_node (InsertionHelperState state, RunnableConfig config)

Variables
	PARENT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
	ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
	CONFIG_PATH = os.path.join(ROOT_DIR, "config.json")
	CONFIG = json.load(f)
	CONTEXT_CONFIG = CONFIG["context_config"]
	LOOP_CONFIG = CONFIG["loop_limits"]

Detailed Description

Copyright 2026 Luca Silver

Core planning and helper nodes for both student and advisor chat agents.

Planning Nodes:
- `s_planner_node`: Student planner that decides which sources (database, web, insertion) are needed and what info to gather from them (or what info to insert) for the current user input.
- `a_planner_node`: Advisor planner that decides what sources (database, web) are needed and what info to gather from them for the current user input.

Helper Nodes:
- `db_node`: Database helper that formulates and executes database queries using available tools.
- `web_node`: Web search helper that formulates and executes web searches using available tools.
- `insertion_node`: Insertion helper that processes student profile updates (interests, tracked sections).

These nodes are integrated into LangGraph agents to provide multi-turn planning and tool execution workflows.
System prompts and loop limits for each node are defined in config.json and can be adjusted to control agent behavior and prevent infinite loops.

Function Documentation

◆ a_planner_node()

APlannerState a_planner_node	(	APlannerState	state,
		RunnableConfig	config )

Builds the next plan for the advisor-facing agent.

This node is the advisor counterpart to the student planner. It gathers the
current conversation, prior database and web results, and loop context, then
asks the planning model to decide whether more tool use is needed before a final
answer can be produced.

Args:
    state (APlannerState): Current advisor-agent state containing messages,
        loop counter, prior tool results, and user metadata.

Returns:
    APlannerState: Updated state with a new "plan" value from the planning model.

Side Effects:
    - Increments the loop counter.
    - May initialize empty db_info and web_info lists.

◆ db_node()

db_node	(	DatabaseHelperState	state,
		RunnableConfig	config )

Executes the database helper model with the appropriate tool set.

The node chooses between student and advisor database tools based on the user's 
account type, seeds the message list with system guidance when this is the first turn, 
preserves prior tool messages, and sends the curated conversation to the database LLM. 
The LLM may decide to call one or more database tools before producing its response.

Args:
    state (DatabaseHelperState): Helper state containing the requested information,
        message history, loop counter, user ID, and account type.

Returns:
    dict: A partial state update containing a single AI response message under
        the "messages" key.

Side Effects:
    - Increments the loop counter.
    - May append an initial system prompt and task description to state messages.

◆ insertion_node()

InsertionHelperState insertion_node	(	InsertionHelperState	state,
		RunnableConfig	config )

Executes the insertion helper model to persist new student information.

This node prepares a tool-enabled conversation for the insertion LLM, which is
used to decide whether any new student information should be written into the
database. On the first pass it seeds the conversation with instructions that
describe what should be inserted.

Args:
    state (InsertionHelperState): Helper state containing the information to
        insert, message history, loop counter, and user ID.

Returns:
    dict: A partial state update containing a single AI response message under
        the "messages" key.

Side Effects:
    - Increments the loop counter.
    - May append an initial system prompt and insertion request to state messages.

◆ s_planner_node()

SPlannerState s_planner_node	(	SPlannerState	state,
		RunnableConfig	config )

Builds the next plan for the student-facing agent.

This node collects the current conversation plus any database, web, or insertion
results that have already been gathered, then asks the planning model to decide
whether more tool use is required. The returned plan is stored in state and used
by the graph router to decide the next branch.

Args:
    state (SPlannerState): Current student-agent state containing messages,
        loop counter, prior tool results, and user metadata.

Returns:
    SPlannerState: Updated state with a new "plan" value from the planning model.

Side Effects:
    - Increments the loop counter.
    - May initialize empty db_info and web_info lists.

◆ web_node()

web_node	(	WebSearchHelperState	state,
		RunnableConfig	config )

Executes the web search helper model with the search tool set.

The node prepares the message history for the web LLM, including an initial
system prompt and search goal on the first pass. It preserves prior tool records
and sends the curated conversation to the model so it can search the web or
summarize the gathered results.

Args:
    state (WebSearchHelperState): Helper state containing the requested web
        information, message history, and loop counter.

Returns:
    dict: A partial state update containing a single AI response message under
        the "messages" key.

Side Effects:
    - Increments the loop counter.
    - May append an initial system prompt and task description to state messages.

Variable Documentation

◆ CONFIG

lg_agent.utilities.nodes.CONFIG = json.load(f)

◆ CONFIG_PATH

lg_agent.utilities.nodes.CONFIG_PATH = os.path.join(ROOT_DIR, "config.json")

◆ CONTEXT_CONFIG

lg_agent.utilities.nodes.CONTEXT_CONFIG = CONFIG["context_config"]

◆ LOOP_CONFIG

lg_agent.utilities.nodes.LOOP_CONFIG = CONFIG["loop_limits"]

◆ PARENT_DIR

lg_agent.utilities.nodes.PARENT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))

◆ ROOT_DIR

lg_agent.utilities.nodes.ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))

Functions

Variables