feat(api): configurable entity_types (global + per-KB) via the config API

entity_types (the entity-extraction vocabulary) is now surfaced through the
config read/write API, layering global.yaml -> KB config.yaml like the other
scalars: a KB list overrides the global list wholesale, an explicit null
inherits, and unset falls back to DEFAULT_ENTITY_TYPES. The compiler already
consumed config["entity_types"] via resolve_entity_types; this just exposes it.

- GLOBAL_SCALAR_KEYS gains "entity_types" (layering + per-key `sources` tracking;
  the value-not-None-wins rule is type-agnostic, so it works for a list).
- _KbConfigWritable / GlobalConfigValues / KbConfigResponse / GlobalConfigResponse
  carry entity_types; read_kb_config/read_global_config report the cleaned
  EFFECTIVE list (resolve_entity_types) plus the raw global value for the badge.
- PATCH /api/v1/kb/config and PATCH /api/v1/config accept entity_types.

Tests: KB override (cleaned + source 'kb') + null revert, global patch, global
inheritance; updated the global-defaults shape assertion. Frontend UI follows.

Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG

Author: KylinMountain

openkb/api_config.py

@@ -34,6 +34,7 @@
     load_global_config,
     resolve_credential_bundle,
     resolve_effective_config,
+    resolve_entity_types,
     save_config,
 )
 from openkb.locks import atomic_write_text
@@ -150,13 +151,17 @@ def read_kb_config(kb_dir: Path) -> KbConfigResponse:
         model=effective["model"],
         language=effective["language"],
         pageindex_threshold=effective["pageindex_threshold"],
+        # Cleaned effective list (what the compiler will use), not the raw stored
+        # value — resolve_entity_types defaults + dedupes + ensures "other".
+        entity_types=resolve_entity_types(effective),
         openai_api_base=bundle.base_url,
         has_api_key=bundle.api_key is not None,
         sources=sources,
         global_values=GlobalConfigValues(
             model=global_config.get("model"),
             language=global_config.get("language"),
             pageindex_threshold=global_config.get("pageindex_threshold"),
+            entity_types=global_config.get("entity_types"),
         ),
     )
 
@@ -262,6 +267,8 @@ def read_global_config() -> GlobalConfigResponse:
         model=gc.get("model", DEFAULT_CONFIG["model"]),
         language=gc.get("language", DEFAULT_CONFIG["language"]),
         pageindex_threshold=gc.get("pageindex_threshold", DEFAULT_CONFIG["pageindex_threshold"]),
+        # Effective global vocabulary (cleaned; defaults to DEFAULT_ENTITY_TYPES).
+        entity_types=resolve_entity_types(gc),
         # Report the EFFECTIVE root (env > global.yaml kb_root > default) via the
         # module object so a test-monkeypatched GLOBAL_CONFIG_DIR is honored.
         kb_root=str(_config_module.kb_root_dir()),

openkb/api_models.py

@@ -401,6 +401,10 @@ class _KbConfigWritable(BaseModel):
     model: str | None = None
     language: str | None = None
     pageindex_threshold: int | None = None
+    # Entity-type vocabulary for extraction. A list REPLACES the layer below; an
+    # explicit null reverts to inherited. Values are cleaned/deduped and "other"
+    # is always ensured at read time (config.resolve_entity_types).
+    entity_types: list[str] | None = None
 
 
 # Single source of truth for the writable config keys (derived from the model
@@ -409,17 +413,20 @@ class _KbConfigWritable(BaseModel):
 
 
 class GlobalConfigValues(BaseModel):
-    """Raw global-layer scalar values (null where global.yaml is silent)."""
+    """Raw global-layer values (null where global.yaml is silent)."""
 
     model: str | None = None
     language: str | None = None
     pageindex_threshold: int | None = None
+    entity_types: list[str] | None = None
 
 
 class GlobalConfigResponse(BaseModel):
     model: str
     language: str
     pageindex_threshold: int
+    # Effective global entity-type vocabulary (cleaned; always includes "other").
+    entity_types: list[str]
     # Effective KB root that kb_root_dir() would return (env OPENKB_KB_ROOT >
     # global.yaml kb_root > default <config>/kbs). kb_root_env_pinned is True
     # when OPENKB_KB_ROOT is set — a global.yaml kb_root is then ineffective, so
@@ -453,6 +460,8 @@ class KbConfigResponse(BaseModel):
     model: str
     language: str
     pageindex_threshold: int
+    # Effective entity-type vocabulary (cleaned; always includes "other").
+    entity_types: list[str]
     openai_api_base: str | None
     has_api_key: bool
     # Additive (non-breaking): which layer supplied each scalar's effective

openkb/config.py

@@ -483,7 +483,16 @@ def load_global_config() -> dict[str, Any]:
 # Whitelisted scalar keys that global.yaml may provide as shared defaults for
 # every KB. Non-scalar global keys (known_kbs, kb_aliases, default_kb) are NOT
 # config and must never leak into a KB's effective runtime config.
-GLOBAL_SCALAR_KEYS: tuple[str, ...] = ("model", "language", "pageindex_threshold")
+# Config keys that layer global.yaml -> KB config.yaml with per-key `sources`
+# tracking (a KB explicit null = inherit). Mostly scalars; `entity_types` is the
+# one list-valued member — the layering rule (a non-null value wins over the
+# layer below) is type-agnostic, so a KB list overrides the global list wholesale.
+GLOBAL_SCALAR_KEYS: tuple[str, ...] = (
+    "model",
+    "language",
+    "pageindex_threshold",
+    "entity_types",
+)
 
 
 def resolve_effective_config(kb_dir: Path) -> tuple[dict[str, Any], dict[str, str]]:

tests/test_api.py

@@ -2204,6 +2204,60 @@ def test_kb_config_patch_updates_model_only(monkeypatch, kb_dir):
     assert saved["model"] == "claude-opus"
 
 
+def test_kb_config_patch_sets_and_reverts_entity_types(monkeypatch, kb_dir):
+    client = _client(monkeypatch)
+    kb = _use_named_kb(monkeypatch, kb_dir)
+
+    # Set a custom vocabulary: stored raw, read back cleaned (lowercased, unsafe
+    # chars stripped, deduped, "other" ensured) with source 'kb'.
+    r = client.patch(
+        "/api/v1/kb/config",
+        json={"kb": kb, "config": {"entity_types": ["Person", "Team!"]}},
+        headers=_auth(),
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["entity_types"] == ["person", "team", "other"]
+    assert body["sources"]["entity_types"] == "kb"
+    saved = yaml.safe_load((kb_dir / ".openkb" / "config.yaml").read_text())
+    assert saved["entity_types"] == ["Person", "Team!"]  # raw value persisted
+
+    # Revert (explicit null) -> inherit; with no global set, falls to default.
+    r = client.patch(
+        "/api/v1/kb/config", json={"kb": kb, "config": {"entity_types": None}}, headers=_auth()
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["sources"]["entity_types"] == "default"
+    assert body["entity_types"][-1] == "other"
+
+
+def test_global_config_patch_entity_types(monkeypatch, tmp_path):
+    monkeypatch.setattr("openkb.config.GLOBAL_CONFIG_PATH", tmp_path / "global.yaml")
+    monkeypatch.setattr("openkb.config.GLOBAL_CONFIG_DIR", tmp_path)
+    monkeypatch.delenv("OPENKB_KB_ROOT", raising=False)
+    client = _client(monkeypatch)
+    r = client.patch(
+        "/api/v1/config", json={"config": {"entity_types": ["Org", "Law!"]}}, headers=_auth()
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["entity_types"] == ["org", "law", "other"]  # cleaned effective list
+
+
+def test_kb_config_get_reports_global_source_for_entity_types(monkeypatch, kb_dir, tmp_path):
+    monkeypatch.setattr("openkb.config.GLOBAL_CONFIG_PATH", tmp_path / "global.yaml")
+    monkeypatch.setattr("openkb.config.GLOBAL_CONFIG_DIR", tmp_path)
+    from openkb.config import save_global_config
+
+    save_global_config({"entity_types": ["team", "org"]})
+    client = _client(monkeypatch)
+    kb = _use_named_kb(monkeypatch, kb_dir)
+    body = client.get("/api/v1/kb/config", params={"kb": kb}, headers=_auth()).json()
+    assert body["sources"]["entity_types"] == "global"  # inherited from global.yaml
+    assert body["entity_types"] == ["team", "org", "other"]
+    assert body["global_values"]["entity_types"] == ["team", "org"]  # raw global for the badge
+
+
 def test_kb_config_patch_unknown_field_is_400(monkeypatch, kb_dir):
     client = _client(monkeypatch)
     kb = _use_named_kb(monkeypatch, kb_dir)
@@ -2477,6 +2531,8 @@ def test_global_config_get_defaults_when_absent(monkeypatch, tmp_path):
         "model": "gpt-5.4",
         "language": "en",
         "pageindex_threshold": 20,
+        # Default entity-type vocabulary when global.yaml sets none.
+        "entity_types": ["person", "organization", "place", "product", "work", "event", "other"],
         # kb_root reports the EFFECTIVE root; with no env/global override it is
         # the default <GLOBAL_CONFIG_DIR>/kbs, and env_pinned is False.
         "kb_root": str((tmp_path / "kbs").resolve()),