fix(agent): gate entity name-length drop behind strict_entity_types, warn on drops

- Entity create-item name-length gate (_MAX_NAME_WORDS) now only applies when strict_entity_types=true, matching the type-mismatch drop's opt-in behavior. Previously it applied unconditionally regardless of the flag.
- Dropped entity items (both type-mismatch and name-length) are now logged at WARNING (visible without -v) with a sample of affected names, instead of INFO (effectively silent for normal runs).

Concepts are unaffected (no strict toggle exists for them; the cap still always applies there).

Author: Sebastian Braun

config.yaml.example

@@ -31,7 +31,10 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 # entity_types (above) instead of coercing it to "other". Off by default
 # (backward compatible); turn on for a narrow, domain-specific entity_types
 # list where an "other"-typed entity usually signals a bad/too-specific
-# candidate you'd rather drop than keep.
+# candidate you'd rather drop than keep. Also enables a name-length gate:
+# a brand-new entity name longer than 3 words is dropped too (concepts
+# always enforce this cap; entities only opt in together with this flag).
+# Drops are logged as warnings, never silent.
 # strict_entity_types: false
 
 # Optional: how concept/entity pages absorb new documents on `openkb add`.

examples/configuration/README.md

@@ -99,7 +99,10 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 # entity_types (above) instead of coercing it to "other". Off by default
 # (backward compatible); turn on for a narrow, domain-specific entity_types
 # list where an "other"-typed entity usually signals a bad/too-specific
-# candidate you'd rather drop than keep.
+# candidate you'd rather drop than keep. Also enables a name-length gate:
+# a brand-new entity name longer than 3 words is dropped too (concepts
+# always enforce this cap; entities only opt in together with this flag).
+# Drops are logged as warnings, never silent.
 # strict_entity_types: false
 
 # Optional: LLM / LiteLLM tuning. Keys are forwarded to LiteLLM; `timeout` and
@@ -121,7 +124,7 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 | `concurrency` | `null` | Caps concurrent LLM calls OpenKB makes during ingest — both PageIndex's indexing of a long document and OpenKB's own concept/entity compilation. The two never run at once for the same document, so one setting covers both. Lower it if you hit provider rate limits or "too many open files" on large PDFs. `null` lets each stage apply its own default. |
 | `parallel_tool_calls` | unset | Whether the LLM agents (query, chat, lint, skill) may call tools in parallel. Unset keeps OpenKB's per-agent defaults; `true`/`false` force allow/sequential for every agent; `null` omits the setting (provider default). **Amazon Bedrock needs `null`** (see below). |
 | `entity_types` | 7 defaults | Custom vocabulary for entity pages. `other` is always kept. |
-| `strict_entity_types` | `false` | When `true`, drops an entity whose type doesn't match `entity_types` instead of coercing it to `other`. |
+| `strict_entity_types` | `false` | When `true`, drops an entity whose type doesn't match `entity_types` instead of coercing it to `other`, and also drops a brand-new entity name longer than 3 words (concepts always enforce the name-length cap; entities only opt in together with this flag). Drops are logged as warnings, never silent. |
 | `litellm:` | – | A pass-through block for LiteLLM. See below. |
 
 ### The `litellm:` block

openkb/agent/compiler.py

@@ -92,7 +92,11 @@
 # the token-density constant used to compute the soft per-document "how many
 # brand-new items" guidance substituted into __DOC_TOKEN_GUIDANCE__. Both are
 # intentionally NOT config keys (see issue #247) — the only new config-driven
-# knob in this feature is strict_entity_types.
+# knob in this feature is strict_entity_types. Concepts always enforce this
+# cap; entities only enforce it when strict_entity_types=true (see
+# _filter_entity_items) — it opts into the same "reject, don't coerce" spirit
+# as the type check, so leaving strict_entity_types off keeps entity name
+# length unrestricted, matching pre-issue-#247 behavior exactly.
 _MAX_NAME_WORDS = 3
 _TOKENS_PER_NEW_ITEM = 1000
 
@@ -757,46 +761,52 @@ def _filter_entity_items(
 
     ``strict`` (see ``config.resolve_strict_entity_types``), when ``True``,
     drops an item whose type falls outside ``valid_types`` instead of coercing
-    it to ``"other"``. ``max_words`` (see :func:`_count_words`), when given,
-    drops names with more words than that. Both default to today's lenient
-    behavior (``False``/``None``); pass them only for "create" items — an
-    "update" targets an already-existing, already-vetted name/type.
+    it to ``"other"``, and additionally enables the ``max_words`` (see
+    :func:`_count_words`) name-length gate — both checks are opt-in together,
+    so leaving ``strict_entity_types`` at its default keeps today's lenient
+    behavior (no type drop, no length drop) exactly. Pass ``max_words`` only
+    for "create" items — an "update" targets an already-existing,
+    already-vetted name/type. Drops are logged at warning level (visible
+    without ``-v``) with a sample of the affected names, never silently.
     """
     if valid_types is None:
         valid_types = _ENTITY_TYPES
     out: list[dict] = []
     if not isinstance(items, list):
         return out
-    dropped_strict = 0
-    dropped_words = 0
+    dropped_strict: list[str] = []
+    dropped_words: list[str] = []
     for it in items:
         if not isinstance(it, dict):
             continue
         name = it.get("name")
         if not isinstance(name, str) or not name.strip():
             continue
-        if max_words is not None and _count_words(name) > max_words:
-            dropped_words += 1
+        if strict and max_words is not None and _count_words(name) > max_words:
+            dropped_words.append(name)
             continue
         title = it.get("title") if isinstance(it.get("title"), str) else name
         etype = it.get("type")
         if not isinstance(etype, str) or etype not in valid_types:
             if strict:
-                dropped_strict += 1
+                dropped_strict.append(name)
                 continue
             etype = "other"
         out.append({"name": name, "title": title, "type": etype})
     if dropped_strict:
-        logger.info(
+        logger.warning(
             "concepts plan: dropped %d entity item(s) with type outside the configured "
-            "entity_types (strict_entity_types=true)",
-            dropped_strict,
+            "entity_types (strict_entity_types=true): %s",
+            len(dropped_strict),
+            dropped_strict[:5],
         )
     if dropped_words:
-        logger.info(
-            "concepts plan: dropped %d entity item(s) with names over %d words",
-            dropped_words,
+        logger.warning(
+            "concepts plan: dropped %d entity item(s) with names over %d words "
+            "(strict_entity_types=true): %s",
+            len(dropped_words),
             max_words,
+            dropped_words[:5],
         )
     return out
 
@@ -813,7 +823,8 @@ def _parse_entities_plan(
     Returns ``{"create": [...], "update": [...], "related": [...]}``. A
     missing/malformed ``entities`` key yields empty lists, so older or
     partial LLM responses never raise. ``strict``/``max_words`` (see
-    :func:`_filter_entity_items`) are applied to "create" only — an "update"
+    :func:`_filter_entity_items` — the name-length gate only applies when
+    ``strict`` is ``True``) are applied to "create" only — an "update"
     targets an already-existing, already-vetted name/type.
     """
     empty = {"create": [], "update": [], "related": []}

tests/test_compiler.py

@@ -226,7 +226,9 @@ def test_strict_true_keeps_matching_type(self):
 class TestMaxWordsFilter:
     """Hard cap on brand-new concept/entity names to 3 words (see
     compiler._count_words / issue #247) — a lightweight proxy for "too
-    specific to be reusable knowledge"."""
+    specific to be reusable knowledge". Concepts always enforce this cap;
+    entities only enforce it when strict=True (opt-in together with
+    strict_entity_types, see issue #247 follow-up)."""
 
     def test_count_words_splits_on_hyphen_underscore_and_space(self):
         assert _count_words("attention") == 1
@@ -248,19 +250,48 @@ def test_concept_items_without_max_words_are_unaffected(self):
         out = _filter_concept_items(items, "update")
         assert len(out) == 1
 
-    def test_entity_items_over_limit_are_dropped(self):
+    def test_entity_items_over_limit_are_dropped_when_strict(self):
         items = [
             {"name": "nvidia", "title": "NVIDIA", "type": "organization"},
             {"name": "andreas-mueller-alwart-ssmpa-2573", "title": "Andreas", "type": "person"},
         ]
-        out = _filter_entity_items(items, max_words=3)
+        out = _filter_entity_items(items, max_words=3, strict=True)
         assert [e["name"] for e in out] == ["nvidia"]
 
+    def test_entity_items_over_limit_kept_when_not_strict(self):
+        # The word-length gate is opt-in together with strict_entity_types
+        # (see issue #247 follow-up) — passing max_words alone must not drop
+        # anything unless strict=True is also set.
+        items = [
+            {"name": "nvidia", "title": "NVIDIA", "type": "organization"},
+            {"name": "andreas-mueller-alwart-ssmpa-2573", "title": "Andreas", "type": "person"},
+        ]
+        out = _filter_entity_items(items, max_words=3, strict=False)
+        assert [e["name"] for e in out] == ["nvidia", "andreas-mueller-alwart-ssmpa-2573"]
+
     def test_entity_items_without_max_words_are_unaffected(self):
         items = [{"name": "andreas-mueller-alwart-ssmpa-2573", "title": "Andreas", "type": "other"}]
         out = _filter_entity_items(items)
         assert len(out) == 1
 
+    def test_dropped_entity_items_are_logged_at_warning_not_silently(self, caplog):
+        # Drops must be visible without -v/--verbose (root logger defaults to
+        # WARNING, see cli.py) — logging them at INFO would be effectively
+        # silent for a normal `openkb add` run.
+        import logging
+
+        valid = frozenset({"person", "other"})
+        items = [
+            {"name": "andreas-mueller-alwart-ssmpa-2573", "title": "A", "type": "person"},
+            {"name": "x", "title": "X", "type": "organization"},
+        ]
+        with caplog.at_level(logging.WARNING, logger="openkb.agent.compiler"):
+            out = _filter_entity_items(items, valid, strict=True, max_words=3)
+        assert out == []
+        messages = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+        assert any("over 3 words" in m for m in messages)
+        assert any("type outside the configured" in m for m in messages)
+
 
 class TestParseEntitiesPlanStrictAndMaxWords:
     """strict/max_words are threaded through _parse_entities_plan for
@@ -301,6 +332,22 @@ def test_update_is_never_word_or_strict_filtered(self):
         assert len(out["update"]) == 1
         assert out["update"][0]["type"] == "other"  # coerced, not strict-dropped
 
+    def test_create_max_words_ignored_without_strict(self):
+        # The name-length gate is opt-in together with strict_entity_types —
+        # passing max_words without strict=True must not drop long names.
+        valid = frozenset({"person", "other"})
+        parsed = {
+            "entities": {
+                "create": [
+                    {"name": "andreas-mueller-alwart-ssmpa-2573", "title": "A", "type": "person"},
+                ],
+                "update": [],
+                "related": [],
+            }
+        }
+        out = _parse_entities_plan(parsed, valid, strict=False, max_words=3)
+        assert [e["name"] for e in out["create"]] == ["andreas-mueller-alwart-ssmpa-2573"]
+
 
 class TestDocTokenGuidance:
     """Soft, textual __DOC_TOKEN_GUIDANCE__ substitution (see issue #247) —