From 5735f40a755c690c637156cb31656d1103c9833d Mon Sep 17 00:00:00 2001 From: Aleksandra Makszewska Date: Sat, 26 Sep 2026 12:09:55 +0200 Subject: [PATCH 1/5] feat(schema): close relationship vocabulary and add category-item label pairs --- graph_config.yaml | 49 ++++-- src/config/config_models.py | 22 ++- src/config/relationship_qualifiers.py | 44 ++++++ src/data_pipeline/label_vocabulary.py | 19 +-- src/data_pipeline/relationship_vocabulary.py | 143 ++++++++++++++++++ .../knowledge_graph/question_analysis.py | 21 +-- src/mcp_server/tools/knowledge_graph/rag.py | 12 +- .../test_label_canonicalization.py | 2 +- tests/data_pipeline/test_label_vocabulary.py | 11 +- .../test_relationship_vocabulary.py | 83 ++++++++++ tests/test_graph_schema_config.py | 94 +++++++----- tests/test_llm_determinism_config.py | 28 ++-- 12 files changed, 434 insertions(+), 94 deletions(-) create mode 100644 src/config/relationship_qualifiers.py create mode 100644 src/data_pipeline/relationship_vocabulary.py create mode 100644 tests/data_pipeline/test_relationship_vocabulary.py diff --git a/graph_config.yaml b/graph_config.yaml index e075fc6..a63dd28 100644 --- a/graph_config.yaml +++ b/graph_config.yaml @@ -214,8 +214,6 @@ graph_schema: - invented: "Article" canonical: "Document" - # Preferred relationship types. Unlike labels these are not rewritten, because a wrong - # relationship type is visible in the traversal while a wrong label silently hides the node. relationship_types: - "PART_OF" - "BELONGS_TO" @@ -249,6 +247,41 @@ graph_schema: - "CONSIDERS" - "ASSESSES" - "DEFINED_IN" + - "RELATED_TO" + + relationship_aliases: + - invented: "WORKS_IN" + canonical: "EMPLOYED_BY" + - invented: "WORKS_AT" + canonical: "EMPLOYED_BY" + - invented: "IS_PART_OF" + canonical: "PART_OF" + - invented: "SUGGESTS" + canonical: "RECOMMENDS" + - invented: "NEEDS" + canonical: "REQUIRES" + + fallback_relationship_type: "RELATED_TO" + + category_item_labels: + - category: "CompetencyCategory" + item: "Competency" + - category: "CriterionCategory" + item: "Criterion" + + relationship_qualifier_rules: + - relationship_type: "RECOMMENDS" + token_stems: + - "pozadan" + words: + - "pozadane" + - relationship_type: "REQUIRES" + token_stems: + - "wymagan" + - "niezbedn" + words: + - "wymagane" + - "niezbedne" database: name: "neo4j" @@ -319,7 +352,7 @@ prompts: ALLOWED NODE LABELS - use these and nothing else: {node_labels} - PREFERRED RELATIONSHIP TYPES - reuse one of these whenever it fits: + ALLOWED RELATIONSHIP TYPES - use only these names: {relationship_types} 1. COMPLETENESS - this is the most important rule: @@ -374,7 +407,7 @@ prompts: 5. FOR RELATIONSHIPS: - MERGE between existing node variables - - Use UPPER_SNAKE_CASE; prefer a type from PREFERRED RELATIONSHIP TYPES + - Use UPPER_SNAKE_CASE and choose only from ALLOWED RELATIONSHIP TYPES - Direction matters (A->B is not B->A) EXAMPLE OUTPUT: @@ -400,7 +433,7 @@ prompts: ALLOWED NODE LABELS - use these and nothing else: {node_labels} - PREFERRED RELATIONSHIP TYPES - reuse one of these whenever it fits: + ALLOWED RELATIONSHIP TYPES - use only these names: {relationship_types} RULES: @@ -489,10 +522,8 @@ prompts: WRONG, matches nothing: WHERE toLower(g.title) CONTAINS toLower('jakie sa kryteria doboru kandydatki lub kandydata') - "Jakie są kompetencje pożądane dla naukowca R2?" names the entity by its code "R2", so - filter on the code, not on the words around it, and collect the items under it. The - question also says which items it wants: "pożądane" is the RECOMMENDS relationship and - "niezbędne"/"wymagane" is REQUIRES, so traverse only that type, never a union of types, - which mixes the two lists into one: + filter on the code, not on the words around it, and collect the items under it. + {relationship_qualifier_guidance} MATCH (c:CompetencyCategory)-[r:RECOMMENDS]->(i) WHERE toLower(c.title) CONTAINS toLower('r2') RETURN c.title, type(r), collect(i.title) AS items diff --git a/src/config/config_models.py b/src/config/config_models.py index ccec1cf..8ec9c68 100644 --- a/src/config/config_models.py +++ b/src/config/config_models.py @@ -1,6 +1,6 @@ # generated by datamodel-codegen: # filename: graph_config.yaml -# timestamp: 2026-09-16T09:54:18+00:00 +# timestamp: 2026-09-26T09:41:51+00:00 from __future__ import annotations @@ -86,11 +86,31 @@ class LabelAliase(BaseModel): canonical: str +class RelationshipAliase(BaseModel): + invented: str + canonical: str + + +class CategoryItemLabel(BaseModel): + category: str + item: str + + +class RelationshipQualifierRule(BaseModel): + relationship_type: str + token_stems: list[str] + words: list[str] + + class GraphSchema(BaseModel): fallback_label: str node_labels: list[str] label_aliases: list[LabelAliase] relationship_types: list[str] + relationship_aliases: list[RelationshipAliase] + fallback_relationship_type: str + category_item_labels: list[CategoryItemLabel] + relationship_qualifier_rules: list[RelationshipQualifierRule] class Database(BaseModel): diff --git a/src/config/relationship_qualifiers.py b/src/config/relationship_qualifiers.py new file mode 100644 index 0000000..1d743e4 --- /dev/null +++ b/src/config/relationship_qualifiers.py @@ -0,0 +1,44 @@ +from src.config.config_models import GraphSchema +from src.text_normalization import normalize_search_text + + +def get_relationship_qualifier_rules( + schema: GraphSchema, +) -> tuple[tuple[str, tuple[str, ...]], ...]: + """Return qualifier->relationship mapping from config. + + Args: + schema: ``graph_schema`` section of loaded config + + Returns: + Tuple of ``(relationship_type, token_stems)`` + """ + rules: list[tuple[str, tuple[str, ...]]] = [] + for rule in schema.relationship_qualifier_rules: + rules.append( + ( + rule.relationship_type, + tuple(normalize_search_text(stem).strip() for stem in rule.token_stems), + ) + ) + return tuple(rules) + + +def render_relationship_qualifier_guidance(schema: GraphSchema) -> str: + """Render one prompt sentence describing qualifier->relationship mapping. + + Args: + schema: ``graph_schema`` section of loaded config + + Returns: + One sentence suitable for ``prompts.cypher_search`` + """ + mappings: list[str] = [] + for rule in schema.relationship_qualifier_rules: + words = ", ".join(f'"{word}"' for word in rule.words) + mappings.append(f"{words} -> {rule.relationship_type}") + return ( + "The question also says which items it wants: qualifiers map as " + f"{'; '.join(mappings)}; traverse only that type, never a union of types, " + "which mixes the two lists into one:" + ) diff --git a/src/data_pipeline/label_vocabulary.py b/src/data_pipeline/label_vocabulary.py index 8f87744..a853a41 100644 --- a/src/data_pipeline/label_vocabulary.py +++ b/src/data_pipeline/label_vocabulary.py @@ -10,10 +10,9 @@ """ import re -from collections.abc import Callable from src.config.config_models import GraphSchema -from src.text_normalization import CYPHER_STRING_LITERAL_RE, normalize_search_text +from src.text_normalization import apply_outside_string_literals, normalize_search_text # A node pattern: an optional variable followed by one or more :Label parts, inside parentheses. # Relationship types live in square brackets and are deliberately not matched. @@ -48,20 +47,6 @@ def render_allowed_labels(schema: GraphSchema) -> str: return "\n".join(lines) -def _apply_outside_string_literals(cypher: str, transform: Callable[[str], str]) -> str: - """Run a rewrite over Cypher syntax only, leaving quoted values untouched.""" - pieces: list[str] = [] - cursor = 0 - - for literal in CYPHER_STRING_LITERAL_RE.finditer(cypher): - pieces.append(transform(cypher[cursor : literal.start()])) - pieces.append(literal.group(0)) - cursor = literal.end() - - pieces.append(transform(cypher[cursor:])) - return "".join(pieces) - - class LabelVocabulary: """Resolves any label the extraction model produced to a configured canonical label.""" @@ -124,7 +109,7 @@ def replace_node(match: re.Match[str]) -> str: rewritten_labels = SINGLE_LABEL_RE.sub(replace_label, match.group("labels")) return match.group(0).replace(match.group("labels"), rewritten_labels, 1) - rewritten = _apply_outside_string_literals( + rewritten = apply_outside_string_literals( cypher, lambda segment: NODE_LABELS_RE.sub(replace_node, segment) ) return rewritten, rewrites diff --git a/src/data_pipeline/relationship_vocabulary.py b/src/data_pipeline/relationship_vocabulary.py new file mode 100644 index 0000000..a230c68 --- /dev/null +++ b/src/data_pipeline/relationship_vocabulary.py @@ -0,0 +1,143 @@ +import re + +from src.config.config_models import GraphSchema +from src.text_normalization import apply_outside_string_literals, normalize_search_text + +RELATIONSHIP_TYPES_PREFIX_RE = re.compile( + r"\[\s*(?P[A-Za-z_]\w*\s*)?:\s*" + r"(?P(?:`[^`]+`|[A-Za-z_]\w*)(?:\s*\|\s*(?:`[^`]+`|[A-Za-z_]\w*))*)" +) +SINGLE_RELATIONSHIP_TYPE_RE = re.compile(r"`[^`]+`|[A-Za-z_]\w*") + + +def normalize_relationship_name(name: str) -> str: + """Normalize relationship names for vocabulary matching. + + Args: + name: Relationship name as written in generated Cypher + + Returns: + Case- and diacritic-insensitive form without separators (`_`, `-`, whitespace) + """ + return normalize_search_text(name).replace("_", "").replace("-", "").replace(" ", "") + + +def render_allowed_relationship_types(schema: GraphSchema) -> str: + """Render allowed relationship types for extraction prompts. + + Args: + schema: Graph schema section of the loaded configuration + + Returns: + Prompt-ready text listing canonical relationship types (excluding fallback) + and known alias redirects + """ + allowed = [ + relationship_type + for relationship_type in schema.relationship_types + if relationship_type != schema.fallback_relationship_type + ] + lines = [", ".join(allowed)] + + if schema.relationship_aliases: + redirects = ", ".join( + f"{alias.invented} -> {alias.canonical}" for alias in schema.relationship_aliases + ) + lines.append("") + lines.append(f"Never use these; write the canonical relationship type instead: {redirects}") + + return "\n".join(lines) + + +class RelationshipVocabulary: + """Resolves generated relationship types to configured canonical names.""" + + def __init__(self, schema: GraphSchema) -> None: + """Build relationship-type lookup from canonical names and aliases. + + Args: + schema: Graph schema section of the loaded configuration + """ + self.fallback_relationship_type = schema.fallback_relationship_type + self.relationship_types = tuple(schema.relationship_types) + + self._by_normalized_form = { + normalize_relationship_name(relationship_type): relationship_type + for relationship_type in self.relationship_types + } + for alias in schema.relationship_aliases: + self._by_normalized_form.setdefault( + normalize_relationship_name(alias.invented), + alias.canonical, + ) + + def resolve_relationship_type(self, relationship_type: str) -> tuple[str, bool]: + """Resolve a relationship type and report whether fallback was used. + + Args: + relationship_type: Relationship type as written by the extraction model + + Returns: + Tuple of (canonical_relationship_type, used_fallback) + """ + stripped = relationship_type.strip().strip("`") + if not stripped: + return self.fallback_relationship_type, True + + normalized = normalize_relationship_name(stripped) + canonical = self._by_normalized_form.get(normalized) + if canonical is None: + return self.fallback_relationship_type, True + return canonical, False + + def canonical_relationship_type(self, relationship_type: str) -> str: + """Resolve one relationship type to canonical name or fallback. + + Args: + relationship_type: Relationship type as written by the extraction model + + Returns: + Canonical relationship type from configuration + """ + canonical, _ = self.resolve_relationship_type(relationship_type) + return canonical + + def canonicalize_statement(self, cypher: str) -> tuple[str, dict[str, str], set[str]]: + """Rewrite relationship types in one Cypher statement. + + Args: + cypher: One generated MERGE statement + + Returns: + Tuple of: + - rewritten statement, + - map of rewritten types (original -> canonical), + - set of original types that were downgraded to fallback + """ + rewrites: dict[str, str] = {} + fallback_rewrites: set[str] = set() + + def replace_relationship(match: re.Match[str]) -> str: + original_types = match.group("types") + + rewritten_types: list[str] = [] + seen: set[str] = set() + for relationship_type_match in SINGLE_RELATIONSHIP_TYPE_RE.finditer(original_types): + original_type = relationship_type_match.group(0).strip().strip("`") + canonical_type, used_fallback = self.resolve_relationship_type(original_type) + if canonical_type != original_type: + rewrites[original_type] = canonical_type + if used_fallback and original_type != canonical_type: + fallback_rewrites.add(original_type) + if canonical_type not in seen: + seen.add(canonical_type) + rewritten_types.append(canonical_type) + + variable = (match.group("variable") or "").strip() + return f"[{variable}:{'|'.join(rewritten_types)}" + + rewritten = apply_outside_string_literals( + cypher, + lambda segment: RELATIONSHIP_TYPES_PREFIX_RE.sub(replace_relationship, segment), + ) + return rewritten, rewrites, fallback_rewrites diff --git a/src/mcp_server/tools/knowledge_graph/question_analysis.py b/src/mcp_server/tools/knowledge_graph/question_analysis.py index 4f048b1..fb1933e 100644 --- a/src/mcp_server/tools/knowledge_graph/question_analysis.py +++ b/src/mcp_server/tools/knowledge_graph/question_analysis.py @@ -18,6 +18,7 @@ CYPHER_STRING_LITERAL_RE, FUZZY_STRING_COMPARISON_RE, POLISH_FUNCTION_WORDS, + is_code_token, normalize_search_text, ) @@ -100,26 +101,6 @@ MAX_SEARCH_PHRASES = 24 -def is_code_token(token: str) -> bool: - """ - Report whether a search token is a code like "r2", "w4" or a course code. - - A code mixes letters and digits. It is a name however short it is, and one character away - from a different entity: "r2" and "r3" are two researcher levels (issue #106). Pure numbers - are left out on purpose. They are mostly years and dates, which a page writes in too many - ways ("2026", "2026/27", "26") for the question's spelling to be required of a node. - - Args: - token: A single lowercase ASCII search token - - Returns: - True when the token holds both a letter and a digit - """ - return any(character.isdigit() for character in token) and any( - character.isalpha() for character in token - ) - - def tokenize_search_text(text: str) -> list[str]: """ Split text into case- and diacritic-folded ASCII search tokens. diff --git a/src/mcp_server/tools/knowledge_graph/rag.py b/src/mcp_server/tools/knowledge_graph/rag.py index c14861d..fc09d9d 100644 --- a/src/mcp_server/tools/knowledge_graph/rag.py +++ b/src/mcp_server/tools/knowledge_graph/rag.py @@ -35,6 +35,7 @@ NO_GRAPH_DATA_MESSAGE, OFF_TOPIC_MESSAGE, ) +from ....config.relationship_qualifiers import render_relationship_qualifier_guidance from ....config.system_labels import SYSTEM_LABELS from ....config.timeouts import ( get_graph_timeout_seconds, @@ -1046,7 +1047,12 @@ def _initialize_prompt_templates(self): config = get_config() self.generate_cypher_template = PromptTemplate( - input_variables=["user_question", "normalized_question", "schema"], + input_variables=[ + "user_question", + "normalized_question", + "schema", + "relationship_qualifier_guidance", + ], template=config.prompts.cypher_search, ) @@ -1389,10 +1395,14 @@ def _build_processing_graph(self): @staticmethod def _build_cypher_prompt_payload(user_question: str, schema: str) -> dict[str, str]: """Provide both natural-language and canonical search forms to the LLM.""" + config = get_config() return { "user_question": user_question, "normalized_question": normalize_search_text(user_question), "schema": schema, + "relationship_qualifier_guidance": render_relationship_qualifier_guidance( + config.graph_schema + ), } def generate_cypher(self, state: State): diff --git a/tests/data_pipeline/test_label_canonicalization.py b/tests/data_pipeline/test_label_canonicalization.py index 2e9720a..4e0fa87 100644 --- a/tests/data_pipeline/test_label_canonicalization.py +++ b/tests/data_pipeline/test_label_canonicalization.py @@ -75,7 +75,7 @@ def test_canonical_statement_is_left_untouched(vocabulary) -> None: def test_relationship_types_are_not_rewritten(vocabulary) -> None: - """Only node labels are a closed set; a relationship type must survive verbatim.""" + """LabelVocabulary rewrites node labels only; relationship rewrites are a separate pass.""" statement = "MERGE (node1)-[:HAS_DAY_OFF]->(node2)" rewritten, rewrites = vocabulary.canonicalize_statement(statement) diff --git a/tests/data_pipeline/test_label_vocabulary.py b/tests/data_pipeline/test_label_vocabulary.py index 684e2bb..bfba629 100644 --- a/tests/data_pipeline/test_label_vocabulary.py +++ b/tests/data_pipeline/test_label_vocabulary.py @@ -4,6 +4,7 @@ from src.config.config import get_config from src.data_pipeline.label_vocabulary import render_allowed_labels +from src.data_pipeline.relationship_vocabulary import render_allowed_relationship_types CALENDAR_PAGE = ( "Dni wolne od zajec w semestrze zimowym 2026/2027:\n" @@ -25,7 +26,7 @@ def _render_prompt() -> str: context=CALENDAR_PAGE, schema_context="(empty)", node_labels=render_allowed_labels(config.graph_schema), - relationship_types=", ".join(config.graph_schema.relationship_types), + relationship_types=render_allowed_relationship_types(config.graph_schema), ) @@ -52,6 +53,14 @@ def test_prompt_template_renders_with_the_pipeline_payload() -> None: assert CALENDAR_PAGE in prompt assert "StudyProgram" in prompt assert "HAS_DAY_OFF" in prompt + assert "RELATED_TO" not in prompt + + +def test_prompt_uses_allowed_relationship_vocabulary_language() -> None: + prompt = _render_prompt() + + assert "ALLOWED RELATIONSHIP TYPES" in prompt + assert "PREFERRED RELATIONSHIP TYPES" not in prompt def test_prompt_states_the_completeness_rule() -> None: diff --git a/tests/data_pipeline/test_relationship_vocabulary.py b/tests/data_pipeline/test_relationship_vocabulary.py new file mode 100644 index 0000000..b29581c --- /dev/null +++ b/tests/data_pipeline/test_relationship_vocabulary.py @@ -0,0 +1,83 @@ +import pytest + +from src.config.config import get_config +from src.data_pipeline.relationship_vocabulary import ( + RelationshipVocabulary, + render_allowed_relationship_types, +) + + +def _vocabulary() -> RelationshipVocabulary: + return RelationshipVocabulary(get_config().graph_schema) + + +@pytest.mark.parametrize( + ("input_type", "expected"), + [ + ("WORKS_IN", "EMPLOYED_BY"), + ("works-at", "EMPLOYED_BY"), + ("is_part_of", "PART_OF"), + ("TOTALLY_UNKNOWN_REL", "RELATED_TO"), + ], +) +def test_relationship_types_resolve_to_canonical_or_fallback( + input_type: str, expected: str +) -> None: + assert _vocabulary().canonical_relationship_type(input_type) == expected + + +@pytest.mark.parametrize( + ("statement", "rewritten", "rewrites", "fallbacks"), + [ + ( + "MERGE (a)-[:WORKS_IN]->(b)", + "MERGE (a)-[:EMPLOYED_BY]->(b)", + {"WORKS_IN": "EMPLOYED_BY"}, + set(), + ), + ( + "MERGE (a)-[:`WORKS-IN`]->(b)", + "MERGE (a)-[:EMPLOYED_BY]->(b)", + {"WORKS-IN": "EMPLOYED_BY"}, + set(), + ), + ( + "MERGE (a)-[:Requires]->(b)", + "MERGE (a)-[:REQUIRES]->(b)", + {"Requires": "REQUIRES"}, + set(), + ), + ( + "MERGE (a)-[:HAS_COMPETENCY]->(b)", + "MERGE (a)-[:RELATED_TO]->(b)", + {"HAS_COMPETENCY": "RELATED_TO"}, + {"HAS_COMPETENCY"}, + ), + ], +) +def test_statement_relationship_types_are_rewritten_and_tracked( + statement: str, + rewritten: str, + rewrites: dict[str, str], + fallbacks: set[str], +) -> None: + result = _vocabulary().canonicalize_statement(statement) + assert result == (rewritten, rewrites, fallbacks) + + +def test_relationship_names_inside_string_values_are_not_rewritten() -> None: + statement = "MERGE (n:Document {title: 'WORKS_IN relation', context: '[:NEEDS]'})" + rewritten, rewrites, fallback_rewrites = _vocabulary().canonicalize_statement(statement) + + assert rewritten == statement + assert rewrites == {} + assert fallback_rewrites == set() + + +def test_prompt_relationship_types_exclude_fallback_and_list_aliases() -> None: + schema = get_config().graph_schema + + rendered = render_allowed_relationship_types(schema) + + assert "RELATED_TO" not in rendered + assert "WORKS_IN -> EMPLOYED_BY" in rendered diff --git a/tests/test_graph_schema_config.py b/tests/test_graph_schema_config.py index 6467cb1..9bc9299 100644 --- a/tests/test_graph_schema_config.py +++ b/tests/test_graph_schema_config.py @@ -1,12 +1,6 @@ -"""The ingestion label set is a closed vocabulary; these tests keep it internally consistent. - -Issue #53: the extraction model invented a label per page, so one concept landed as several -nodes (StudyProgram and Program for the same programme). The fix only holds if the configured -vocabulary itself is coherent — an alias pointing at a label that does not exist would silently -reintroduce an off-list label. -""" - from src.config.config import get_config +from src.data_pipeline.relationship_vocabulary import normalize_relationship_name +from src.text_normalization import normalize_search_text EXPECTED_NODE_LABEL_COUNT = 27 @@ -15,54 +9,86 @@ def _schema(): return get_config().graph_schema -def test_node_labels_are_unique() -> None: +def test_node_labels_are_unique_and_stable_in_size() -> None: + """Growing the vocabulary is a deliberate decision, not a side effect of a page.""" labels = _schema().node_labels assert len(labels) == len(set(labels)) + assert len(labels) == EXPECTED_NODE_LABEL_COUNT -def test_node_label_set_stays_at_the_documented_size() -> None: - """Growing the vocabulary is a deliberate decision, not a side effect of a page.""" - assert len(_schema().node_labels) == EXPECTED_NODE_LABEL_COUNT - +def test_label_aliases_are_well_formed() -> None: + """An alias must be unique, resolve to a configured label, and never rewrite a valid one.""" + aliases = _schema().label_aliases + labels = set(_schema().node_labels) + sources = [alias.invented for alias in aliases] -def test_every_alias_resolves_to_a_configured_label() -> None: - schema = _schema() - labels = set(schema.node_labels) + assert len(sources) == len(set(sources)) + assert [alias.invented for alias in aliases if alias.canonical not in labels] == [] + assert [alias.invented for alias in aliases if alias.invented in labels] == [] - unresolved = [alias.invented for alias in schema.label_aliases if alias.canonical not in labels] - assert unresolved == [] +def test_relationship_types_are_unique_upper_snake_case() -> None: + relationship_types = _schema().relationship_types + assert len(relationship_types) == len(set(relationship_types)) + assert all(name == name.upper() for name in relationship_types) + assert all(name.replace("_", "").isalpha() for name in relationship_types) -def test_no_alias_shadows_a_configured_label() -> None: - """An alias for a label that is already canonical would rewrite valid output.""" - schema = _schema() - labels = set(schema.node_labels) - shadowing = [alias.invented for alias in schema.label_aliases if alias.invented in labels] +def test_relationship_aliases_are_well_formed() -> None: + """Same rules as labels, plus no alias may collide with a type once both are normalized.""" + aliases = _schema().relationship_aliases + types = set(_schema().relationship_types) + normalized_types = {normalize_relationship_name(name) for name in types} + sources = [alias.invented for alias in aliases] - assert shadowing == [] + assert len(sources) == len(set(sources)) + assert [alias.invented for alias in aliases if alias.canonical not in types] == [] + assert [alias.invented for alias in aliases if alias.invented in types] == [] + assert [ + alias.invented + for alias in aliases + if normalize_relationship_name(alias.invented) in normalized_types + ] == [] -def test_alias_sources_are_unique() -> None: - sources = [alias.invented for alias in _schema().label_aliases] +def test_fallbacks_are_configured_entries() -> None: + schema = _schema() - assert len(sources) == len(set(sources)) + assert schema.fallback_label in schema.node_labels + assert schema.fallback_relationship_type in schema.relationship_types -def test_fallback_label_is_a_configured_label() -> None: +def test_relationship_qualifier_rules_point_to_configured_relationship_types() -> None: schema = _schema() + relationship_types = set(schema.relationship_types) - assert schema.fallback_label in schema.node_labels + assert schema.relationship_qualifier_rules + for rule in schema.relationship_qualifier_rules: + assert rule.relationship_type in relationship_types + assert rule.token_stems + assert rule.words + assert all(stem == stem.lower() for stem in rule.token_stems) -def test_relationship_types_are_unique_upper_snake_case() -> None: - relationship_types = _schema().relationship_types +def test_every_qualifier_word_is_matched_by_its_own_stems() -> None: + for rule in _schema().relationship_qualifier_rules: + stems = [normalize_search_text(stem) for stem in rule.token_stems] + for word in rule.words: + normalized_word = normalize_search_text(word) + assert any(normalized_word.startswith(stem) for stem in stems), word - assert len(relationship_types) == len(set(relationship_types)) - assert all(name == name.upper() for name in relationship_types) - assert all(name.replace("_", "").isalpha() for name in relationship_types) + +def test_category_item_pairs_point_to_configured_labels() -> None: + schema = _schema() + labels = set(schema.node_labels) + + assert schema.category_item_labels + for pair in schema.category_item_labels: + assert pair.category in labels + assert pair.item in labels + assert pair.category.endswith("Category") def test_label_drift_reported_in_the_issue_is_covered() -> None: diff --git a/tests/test_llm_determinism_config.py b/tests/test_llm_determinism_config.py index 1a05750..00323b5 100644 --- a/tests/test_llm_determinism_config.py +++ b/tests/test_llm_determinism_config.py @@ -1,11 +1,3 @@ -"""The routing and Cypher models must be deterministic. - -Issue #52 measured the cost of sampling: the same question was routed to `end` on some runs and -to `generate_cypher` on others (~40% false rejects), and the generated Cypher differed run to -run. Both models are therefore pinned to temperature 0 in graph_config.yaml, and this test keeps -a future config edit from quietly reintroducing the sampling. -""" - import re from types import SimpleNamespace from unittest.mock import patch @@ -13,12 +5,12 @@ import pytest from src.config.config import get_config +from src.config.relationship_qualifiers import render_relationship_qualifier_guidance from src.mcp_server.tools.knowledge_graph.rag import RAG, LLMProvider def test_configured_models_do_not_sample() -> None: config = get_config() - assert config.llm.fast_model.temperature == 0 assert config.llm.accurate_model.temperature == 0 @@ -54,7 +46,6 @@ def test_the_cypher_prompt_asks_for_the_limit_the_code_enforces() -> None: rows an answer is built from. """ config = get_config() - limit_lines = [ line for line in config.prompts.cypher_search.splitlines() if "LIMIT" in line.upper() ] @@ -62,3 +53,20 @@ def test_the_cypher_prompt_asks_for_the_limit_the_code_enforces() -> None: asked_for = [int(number) for line in limit_lines for number in re.findall(r"\d+", line)] assert asked_for == [config.rag.max_results] * len(asked_for) + + +def test_the_cypher_prompt_uses_relationship_qualifier_rules_from_config() -> None: + config = get_config() + guidance = render_relationship_qualifier_guidance(config.graph_schema) + + payload = RAG._build_cypher_prompt_payload( + "Jakie sa kompetencje pozadane dla naukowca R2?", "(:X)" + ) + + assert "{relationship_qualifier_guidance}" in config.prompts.cypher_search + assert payload["relationship_qualifier_guidance"] == guidance + assert '"pozadane" -> RECOMMENDS' in guidance + assert '"wymagane", "niezbedne" -> REQUIRES' in guidance + + rendered = config.prompts.cypher_search.format(**payload) + assert guidance in rendered From e3ac52671d91149ba6a3172fc44076d44c7cba58 Mon Sep 17 00:00:00 2001 From: Aleksandra Makszewska Date: Sat, 26 Sep 2026 12:11:07 +0200 Subject: [PATCH 2/5] feat(topology): resolve Topic ends and attach missing category-item edges deterministically --- src/data_pipeline/deterministic_topology.py | 368 ++++++++++++++++++ .../flows/llm_cypher_generation.py | 76 +++- src/text_normalization.py | 29 ++ tests/data_pipeline/test_completeness.py | 32 +- .../test_deterministic_topology.py | 215 ++++++++++ .../test_llm_cypher_generation.py | 63 +++ tests/test_rag_retrieval_normalization.py | 5 + 7 files changed, 759 insertions(+), 29 deletions(-) create mode 100644 src/data_pipeline/deterministic_topology.py create mode 100644 tests/data_pipeline/test_deterministic_topology.py diff --git a/src/data_pipeline/deterministic_topology.py b/src/data_pipeline/deterministic_topology.py new file mode 100644 index 0000000..9722403 --- /dev/null +++ b/src/data_pipeline/deterministic_topology.py @@ -0,0 +1,368 @@ +import re +from dataclasses import dataclass + +from src.config.config import get_config +from src.config.relationship_qualifiers import get_relationship_qualifier_rules +from src.data_pipeline.completeness import ( + NODE_PROPERTY_MAP_RE, + PROPERTY_ENTRY_RE, + SET_ASSIGNMENT_RE, + TITLE_PROPERTY, +) +from src.text_normalization import CYPHER_STRING_LITERAL_RE, normalize_search_text + +CONTROLLED_RELATIONSHIP_TYPES = frozenset({"HAS_CRITERION", "REQUIRES", "RECOMMENDS", "RELATED_TO"}) +CRITERION_CATEGORY_LABEL = "CriterionCategory" +CRITERION_RELATIONSHIP_TYPE = "HAS_CRITERION" +NEGATION = "nie" + +TOKEN_RE = re.compile(r"[0-9a-z]+") +NODE_LABEL_RE = re.compile(r"\(\s*(?P[A-Za-z_]\w*)\s*:\s*`?(?P