GML-2323 Release GraphRAG 2.0.4

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [2.0.4]
+
+### Changed
+- **Agentic answers reuse what the conversation and the graph schema already hold.** The agentic engines searched again for questions the conversation had already answered, and answered questions about the knowledge base itself, such as "what data do we have", from a document search. They now answer from the conversation or the graph schema when it already holds the answer, search only for the parts it does not, and search again when an earlier answer found nothing, was incomplete, or the question asks for the current or latest state. Trace Logs show this review in the plan step.
+- **A question without an answer tells the user how to ask again.** When the retrieved information does not answer a question, or part of it, the answer says so and suggests asking again with more specific details. The fixed no-answer messages use the same wording.
+- **Failed answers show their error in Trace Logs.** When GraphRAG cannot answer, the trace ends with a step that states the error. The chat message stays generic and asks the user to rephrase the question.
+- **Trace Logs show the structured query that ran.** Each structured query step shows the query, any failed attempts with their errors, and the number of rows returned, also when the query returned no rows.
+- **Routine requests log less.** Loading conversations, opening traces and similar requests write one line to the service log instead of four, and the web server's access log is off. `LOGLEVEL=DEBUG` restores the detailed lines.
+
+### Fixed
+- **Regenerating embeddings no longer loses an embedding while reporting success.** With the OpenAI provider, a later Regenerate embeddings or Regenerate summaries run could fail to save an embedding and still count it as regenerated. The `openai` package is now held below version 3, and a vertex counts as regenerated only when its embedding is saved.
+- **Agentic plans no longer come back without steps.** A model, often Gemini, could return a plan with no steps, so nothing was retrieved. Every plan now either retrieves or answers from what the conversation and schema already hold.
+- **The agentic planner plans from the graph schema.** The planner did not know the graph's types, so it guessed from the question's wording whether a structured query would help. It now plans from the graph's schema and type descriptions, and picks up changes to them without a restart.
+- **Structured queries no longer start with a step that cannot succeed.** Each structured query first ran a step that always failed before the query was generated. That step is now skipped, saving a model call per structured query.
+- **The Trace Logs window keeps long content inside it.** A long line, such as a URL or a query, widened the window past the screen and hid the Close button. Long lines now wrap, and Download and Close stay visible.
+- **Generated graph queries succeed more often.** Questions that filter by date or ask about missing values could fail on every attempt or return wrong rows, and some queries that TigerGraph rejects were retried until all attempts were used. Each generated query is now checked by TigerGraph before it runs (TigerGraph 4.0 and later), failed checks are corrected and tried again up to `cypher_max_attempts` times, dates and missing values follow TigerGraph's rules, and queries that would change data are rejected.
+- **An empty structured query result no longer counts as data.** A query that returned no rows was treated as an answer, so the document search did not run. It now runs, in both the agentic and the classic engine.
+- **External MCP servers load again.** New images installed MCP SDK 2, and the agent then skipped every server configured on the MCP Servers page. The SDK is now held below version 2.
+- **The agentic planner and reactive agent see the most recent conversation turns.** They received the oldest turns, so a long earlier answer could hide the turns a follow-up refers to. They now receive the most recent turns.
+- **Gemini 3 planning no longer loops at temperature 0.** Gemini 3 models could repeat text in the plan instead of finishing it. Agentic planning now uses temperature 1.0 for Gemini 3 when a lower value is configured, as Google recommends; answers, knowledge-graph building and other models keep the configured temperature.
+- **Agentic planning no longer gets stuck writing its plan summary.** A model could repeat a phrase in the plan summary until it reached its output limit, which cost time and tokens and sometimes the plan. The summary is now kept short and the planner's output is capped.
+
+### Removed
+- **The `tg_run_query` and `tg_get_neighbors` agent tools.** Structured retrieval writes and runs graph queries for the agent. Custom planner or agent prompts that name these tools should drop them.
+
+### Added
+- **`cypher_max_attempts` setting.** How many times a structured graph query may be generated for one question (default `10`).
+- **`planner_max_output_tokens` setting.** The most output tokens the planner may use for one plan (default `4000`; reasoning models use at least `16000`).
+
 ## [2.0.3]
 
 ### Added

README.md

@@ -68,6 +68,7 @@
 ---
 
 ## Releases
+* **10/15/2026**: GraphRAG v2.0.4 released. Agentic answers reuse what the conversation and the graph schema already hold and plan from the graph's schema, Trace Logs show the structured queries that ran and the error of a failed answer, external MCP servers load again, and fixed planning and structured-query issues. See [Release Notes](https://github.com/tigergraph/graphrag/releases/tag/v2.0.4) for details.
 * **10/12/2026**: GraphRAG v2.0.3 released. Improved agentic answers to multi-part and follow-up questions, kept answers within the chat model's input limit, added deleting chat conversations individually, in groups, or all at once, made the Migration Assistant check a graph's schema before repairing it, and fixed document retrieval, ingestion, and contextual search issues. See [Release Notes](https://github.com/tigergraph/graphrag/releases/tag/v2.0.3) for details.
 * **8/28/2026**: GraphRAG v2.0.2 released. Added Migration Assistant data-integrity checks with targeted re-embedding of missing embeddings and re-summarization of incomplete community summaries, made agentic chat work with current and future tool-calling models automatically, and fixed rebuild, PDF extraction, and chat issues. See [Release Notes](https://github.com/tigergraph/graphrag/releases/tag/v2.0.2) for details.
 * **7/22/2026**: GraphRAG v2.0.1 released. Fixed a chat error with models that return structured content (such as Gemini 3), and hardened knowledge-graph rebuild so it no longer hangs when the language model is unreachable. Relicensed from Apache 2.0 to AGPL-3.0. See [Release Notes](https://github.com/tigergraph/graphrag/releases/tag/v2.0.1) for details.
@@ -198,8 +199,8 @@ This line can be changed to support different logging levels.
 | `CRITICAL` | A serious error. |
 | `ERROR` | Failing to perform functions. |
 | `WARNING` | Indication of unexpected problems, e.g. failure to map a user’s question to the graph schema. |
-| `INFO` | Confirming that the service is performing as expected. |
-| `DEBUG` | Detailed information, e.g. the functions retrieved during the `GenerateFunction` step, etc. |
+| `INFO` | Confirming that the service is performing as expected. Each request is recorded once, by its audit entry. |
+| `DEBUG` | Detailed information, e.g. the functions retrieved during the `GenerateFunction` step, each request's entry line, and the HTTP calls GraphRAG makes to other services. |
 | `DEBUG_PII` | Finer-grained information that could potentially include `PII`, such as a user’s question, the complete function call (with parameters), and the LLM’s natural language response. |
 | NOTSET | All messages are processed. |
 
@@ -389,12 +390,12 @@ GraphRAG offers two chat engines, chosen from the chat menu (or set as a per-gra
 
 ### Agentic
 
-The agent decides its **own** retrieval instead of following a fixed pipeline: it picks which methods to use (structural graph queries, vector search, community search), can call external [MCP tools](#mcp-servers-agentic-tools), answers greetings and questions about itself directly, and cites the chunks and queries it used. It comes in two styles:
+The agent decides its **own** retrieval instead of following a fixed pipeline: it picks which methods to use (structural graph queries, vector search, community search), can call external [MCP tools](#mcp-servers-agentic-tools), answers greetings and questions about itself directly, reuses what the conversation already answers and retrieves only what is missing, and cites the chunks and queries it used. It comes in two styles:
 
-- **Planned** *(default)* — analyzes the question up front and lays out the whole retrieval plan (which methods, how many, in what order) as a small DAG, executes it, then synthesizes one grounded answer. Predictable and efficient; a strong fit for most questions, including multi-part ones.
+- **Planned** *(default)* — analyzes the question against the graph's schema up front, answers directly when the conversation or the schema already holds the answer (for example "what data do we have?"), and otherwise lays out the whole retrieval plan (which methods, how many, in what order) as a small DAG, executes it, then synthesizes one grounded answer. Predictable and efficient; a strong fit for most questions, including multi-part ones.
 - **Reactive** — reasons and acts one step at a time, deciding each next retrieval from what the previous step returned, and keeps going until it can answer completely and accurately. More adaptive to what it finds, at the cost of more steps (and tokens) on complex questions.
 
-Both styles send trivial/conversational messages straight to a direct answer, and record their retrieval in the admin **Trace** — the plan/steps and reasoning, which chunks were retrieved, and which the agent selected for the answer.
+Both styles send trivial/conversational messages straight to a direct answer, and record their retrieval in the admin **Trace** — the plan/steps and reasoning, the structured queries that ran, which chunks were retrieved, which the agent selected for the answer, and the error when an answer fails.
 
 **Selecting an engine.** In the chat UI, use the engine/style picker (Classic, or Agentic → Planned / Reactive). To set a per-graph default, configure `agent_style` (`auto` follows the configured default; `planned` or `reactive` force a style) — see [GraphRAG configuration](#graphrag-configuration). Depth is bounded by `agent_max_iterations` (Reactive) and `agent_max_replans` / `agent_max_total_steps` (Planned).
 
@@ -546,6 +547,8 @@ Copy the below code into `configs/server_config.json`. You shouldn’t need to c
 | `agent_style` | string | `"planned"` | Default agentic engine style: `"planned"` (plan the whole retrieval up front) or `"reactive"` (decide each step from the last result). The chat menu can override per request. See [Chat Engines and Agents](#chat-engines-and-agents). |
 | `agent_max_iterations` | int | `30` | Reactive agent only: maximum reason-act-observe steps before it must answer. |
 | `agent_max_replans` | int | `3` | Planned agent only: how many times the planner may extend its plan when the gathered context is insufficient. |
+| `cypher_max_attempts` | int | `10` | How many times a structured graph query may be generated for one question before GraphRAG gives up on it. |
+| `planner_max_output_tokens` | int | `4000` | Planned agent only: the most output tokens the planner may use for one plan. Reasoning models use at least `16000`. |
 | `agent_max_total_steps` | int | `20` | Planned agent only: hard cap on executed retrieval steps across all replans. |
 | `chunk_only` | bool | `true` | If true, hybrid search only retrieves document chunks, excluding entity data. |
 | `doc_only` | bool | `false` | If true, hybrid search retrieves whole documents instead of chunks. Significantly increases context size. |
@@ -695,6 +698,8 @@ In the `llm_config` section of `configs/server_config.json` file, copy JSON conf
 | `base_url` | string | No | — | Custom API endpoint URL. |
 | `token_limit` | int | No | inherited from top-level | Hard cap on token count for a prompt carrying retrieved context, prompt included. Context beyond it is truncated. `0` or omitted uses the model's own input limit when known, otherwise no cap. |
 
+> **Gemini 3 models:** the agentic engine plans with temperature `1.0` when `model_kwargs` sets a lower one, as Google recommends for these models. Answers and knowledge graph building use the configured temperature.
+
 **`embedding_service` parameters:**
 
 | Parameter | Type | Required | Default | Description |

VERSION

@@ -1 +1 @@
-2.0.3
+2.0.4

common/db/schema_utils.py

@@ -1332,7 +1332,9 @@ def _collect_attrs(attr_list, skip_name: str) -> Tuple[dict, List[str]]:
     """Walk an ``Attributes`` array from ``getVertexType`` /
     ``getEdgeType`` and return ``({attr_name: tg_type}, ["name of type
     type", ...])``. ``skip_name`` is the primary-id attribute that
-    shouldn't appear in the user-facing schema rep.
+    shouldn't appear in the user-facing schema rep. A NULLABLE attribute
+    gets a " NULLABLE" suffix, so query generation knows which attributes
+    can hold NULL.
     """
     attrs_map: dict = {}
     lines: List[str] = []
@@ -1342,7 +1344,8 @@ def _collect_attrs(attr_list, skip_name: str) -> Tuple[dict, List[str]]:
         if not a_name or a_name == skip_name:
             continue
         attrs_map[a_name] = a_type
-        lines.append(f"{a_name} of type {a_type}")
+        nullable = " NULLABLE" if a.get("isNullable") else ""
+        lines.append(f"{a_name} of type {a_type}{nullable}")
     return attrs_map, lines