tdfs4ds.agent.query_optimizer_graph¶

tdfs4ds.agent.query_optimizer_graph ¶

LangGraph-based orchestration for the tdfs4ds query optimizer agent.

Flow::

START -> node_classify -> [conditional on intent] -> node_skill_* -> node_synthesize -> END

_QO_INTENT_NODE_MAP `module-attribute` ¶

_QO_INTENT_NODE_MAP = {'EXPLAIN': node_skill_explain, 'SIMPLIFY': node_skill_simplify, 'OPTIMIZE': node_skill_optimize}

_qo_graph_instance `module-attribute` ¶

_qo_graph_instance = None

QOState ¶

Bases: TypedDict

question `instance-attribute` ¶

question: str

sql_query `instance-attribute` ¶

sql_query: Optional[str]

process_id `instance-attribute` ¶

process_id: Optional[str]

intent `instance-attribute` ¶

intent: Optional[str]

skill_result `instance-attribute` ¶

skill_result: Optional[dict]

answer `instance-attribute` ¶

answer: Optional[str]

messages `instance-attribute` ¶

messages: Annotated[list, add_messages]

resolved_sql `instance-attribute` ¶

resolved_sql: Optional[str]

resolved_process_id `instance-attribute` ¶

resolved_process_id: Optional[str]

_effective_sql ¶

_effective_sql(state: QOState) -> Optional[str]

_effective_process_id ¶

_effective_process_id(state: QOState) -> Optional[str]

_persist_inputs ¶

_persist_inputs(state: QOState) -> dict

Build state update that remembers sql_query and process_id for next turns.

query_optimizer_report_root ¶

query_optimizer_report_root() -> str

Directory under which OPTIMIZE reports are written (QUERY_OPTIMIZER_REPORT_DIR).

_save_optimization_report ¶

_save_optimization_report(result: dict, process_id: Optional[str]) -> Optional[str]

Write the full Markdown report to disk and return its path relative to :func:query_optimizer_report_root ({domain}/{file}.md), or None on failure / when there is nothing to save.

Mirrors the file-naming convention used by upload_features in tdfs4ds/execution.py so reports from both paths land together.

node_skill_explain ¶

node_skill_explain(state: QOState) -> dict

Execute the EXPLAIN analysis skill.

node_skill_simplify ¶

node_skill_simplify(state: QOState) -> dict

Execute the SQL simplification skill.

node_skill_optimize ¶

node_skill_optimize(state: QOState) -> dict

Execute the full optimization pipeline skill.

_render_optimize_summary ¶

_render_optimize_summary(result: dict) -> str

Compact OPTIMIZE answer: score delta + best SQL + a link to the report.

The full Markdown report is written to disk by node_skill_optimize and referenced here by report_path (relative to the report root). The serve layer rewrites that path into a clickable download URL; in-process callers still get the full report under skill_result['report_full'].

node_synthesize ¶

node_synthesize(state: QOState) -> dict

Format the skill result as a human-readable answer.

build_qo_graph ¶

build_qo_graph()

Build and compile the LangGraph StateGraph for the query optimizer agent.

The skill set is loaded from the qo-skill-* SKILL.md files bundled with the package (via :func:tdfs4ds.query_optimizer_skill_catalog). Only skills whose intent is in _QO_INTENT_NODE_MAP are registered as graph nodes.

Returns:

Type	Description
	A compiled LangGraph with MemorySaver checkpointer for multi-turn support.

Raises:

Type	Description
`ValueError`	When no query-optimizer skills are found in the package.

_get_qo_graph ¶

_get_qo_graph()

Return the shared compiled query optimizer graph, building it once.

reset_query_optimizer_agent ¶

reset_query_optimizer_agent()

Clear the graph singleton cache.

Call this after adding or removing qo-skill-* SKILL.md files so that the next :func:query_optimizer_agent call picks up the new skill set.

query_optimizer_agent ¶

query_optimizer_agent(question: str, sql_query: Optional[str] = None, process_id: Optional[str] = None, thread_id: str = 'default', return_trace: bool = False) -> Union[str, tuple]

Run the LangGraph query optimizer agent for a single conversational turn.

The agent classifies the question into one of three intents (EXPLAIN / SIMPLIFY / OPTIMIZE) and routes to the corresponding skill. Multi-turn context (sql_query, process_id) is persisted across calls that share the same thread_id.

Parameters:

Name	Type	Description	Default
`question`	`str`	Natural language description of the desired action, e.g. 'Analyze this query for performance issues' or 'Optimize this SQL'.	required
`sql_query`	`Optional[str]`	Optional SQL string. When provided it is remembered for follow-up turns on the same `thread_id`.	`None`
`process_id`	`Optional[str]`	Optional process UUID (looked up in the process catalog to retrieve the SQL automatically). Remembered across turns.	`None`
`thread_id`	`str`	Conversation thread ID for multi-turn memory.	`'default'`
`return_trace`	`bool`	When True, returns `(answer, skill_result)` instead of just the answer string.	`False`

Returns:

Type	Description
`Union[str, tuple]`	Answer string, or `(answer, skill_result)` tuple when
`Union[str, tuple]`	`return_trace=True`.

tdfs4ds.agent.query_optimizer_graph¶