iatoolkit 2.42.0__tar.gz → 2.42.2__tar.gz

{iatoolkit-2.42.0/src/iatoolkit.egg-info → iatoolkit-2.42.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.42.0
+Version: 2.42.2
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/__init__.py

@@ -3,7 +3,7 @@
 #
 # IAToolkit is open source software.
 
-__version__ = "2.42.0"
+__version__ = "2.42.2"
 
 # Expose main classes and functions at the top level of the package
 

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/common/model_registry.py

@@ -60,6 +60,10 @@ class RouteParam:
     is_env_name: bool = False
     #: A regular expression the value must match, or None for "any non-empty".
     pattern: str | None = None
+    #: How to finish "'base_url' does not look like ___" when the pattern refuses a
+    #: value. Declared here so a new parameter cannot inherit another one's wording:
+    #: the message for `model_name` read "does not look like a URL".
+    looks_like: str = "a valid value"
 
 
 #: What each provider needs in order to be reached, keyed by provider.
@@ -81,14 +85,23 @@ class RouteParam:
 #: `openrouter` allows both and requires neither: there is one OpenRouter for
 #: everyone and its base URL has a working default, so an entry only overrides
 #: when it has a reason to.
+#: `model_name` is optional and exists because a catalogue key is lowercased: it
+#: identifies the model across entitlements, rate cards and usage rows, so it cannot
+#: also be the name on the wire. A vLLM endpoint serving
+#: `meta-llama/Llama-3.1-8B-Instruct` answers 404 to the lowercased key. When set,
+#: it is the exact name that endpoint answers to, and only the wire value changes.
 PROVIDER_ROUTE_PARAMS: dict[str, tuple[RouteParam, ...]] = {
     "openai_compatible": (
-        RouteParam("base_url", required=True, pattern=r"^https?://\S+$"),
-        RouteParam("api_key_env", required=True, is_env_name=True, pattern=r"^[A-Z][A-Z0-9_]*$"),
+        RouteParam("base_url", required=True, pattern=r"^https?://\S+$", looks_like="a URL"),
+        RouteParam("api_key_env", required=True, is_env_name=True, pattern=r"^[A-Z][A-Z0-9_]*$",
+                   looks_like="an environment variable name"),
+        RouteParam("model_name", required=False, pattern=r"^[A-Za-z0-9._:\-/]+$",
+                   looks_like="a model name"),
     ),
     "openrouter": (
-        RouteParam("base_url", required=False, pattern=r"^https?://\S+$"),
-        RouteParam("api_key_env", required=False, is_env_name=True, pattern=r"^[A-Z][A-Z0-9_]*$"),
+        RouteParam("base_url", required=False, pattern=r"^https?://\S+$", looks_like="a URL"),
+        RouteParam("api_key_env", required=False, is_env_name=True, pattern=r"^[A-Z][A-Z0-9_]*$",
+                   looks_like="an environment variable name"),
     ),
 }
 
@@ -163,12 +176,16 @@ class ModelRegistry:
 
     def get_capabilities(self, model: str, provider: str | None = None) -> dict:
         normalized_provider = self.normalize_provider(provider=provider, model=model)
+        # `openai_compatible` is absent on purpose. Its adapter targets any server
+        # that speaks chat.completions — llama.cpp, vLLM, a private gateway — and
+        # forwards no reasoning field, because one the server does not know earns a
+        # 400. Claiming the capability here made the tenant's Models page offer a
+        # reasoning control whose value went nowhere.
         supports_reasoning_effort = normalized_provider in {
             "openai",
             "xai",
             "openrouter",
             "deepseek",
-            "openai_compatible",
         }
         supports_text_verbosity = normalized_provider in {"openai", "xai", "openrouter"}
         supports_store = normalized_provider in {"openai", "xai"}

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/infra/llm_providers/openai_compatible_chat_adapter.py

@@ -22,7 +22,21 @@ class OpenAICompatibleChatAdapter:
     """
 
     supports_multimodal = False
-    supports_reasoning = True
+    #: `reasoning` is a **Responses API** parameter. This class calls
+    #: `chat.completions.create`, whose signature has no such argument, so the
+    #: OpenAI SDK raises a TypeError before any request leaves the process:
+    #: "Completions.create() got an unexpected keyword argument 'reasoning'".
+    #:
+    #: It was True here, and both subclasses overrode it to False — DeepSeek and
+    #: OpenRouter each had to correct the base. Nothing was served by this class
+    #: directly until a model with provider `openai_compatible` was added from the
+    #: catalogue, and that first request crashed.
+    supports_reasoning = False
+    #: The Chat Completions equivalent is the plain string `reasoning_effort`, and
+    #: it stays off *here*: this class targets any OpenAI-compatible server —
+    #: llama.cpp, vLLM, a private gateway — and a server that does not know the
+    #: field answers 400. A provider whose API does accept it opts in, which is
+    #: what DeepseekAdapter does.
     supports_reasoning_effort = False
     supports_reasoning_content_messages = False
     supports_metadata = False

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/infra/llm_proxy.py

@@ -142,7 +142,11 @@ class LLMProxy:
             request_kwargs["telemetry_execution"] = telemetry_execution
 
         # Delegate to the adapter (OpenAI, Gemini, DeepSeek, xAI, Anthropic, etc.)
-        return adapter.create_response(model=model, input=input, **request_kwargs)
+        return adapter.create_response(
+            model=self._wire_model(model, model_config),
+            input=input,
+            **request_kwargs,
+        )
 
     def describe_transport(self, company_short_name: str, model: str) -> str:
         provider = self._resolve_provider_for_company_model(
@@ -349,7 +353,6 @@ class LLMProxy:
                 self.PROVIDER_OPENAI,
                 self.PROVIDER_XAI,
                 self.PROVIDER_DEEPSEEK,
-                self.PROVIDER_OPENAI_COMPATIBLE,
                 self.PROVIDER_OPENROUTER,
             })
         )
@@ -746,6 +749,23 @@ class LLMProxy:
         route = (model_config or {}).get("route_config") if isinstance(model_config, dict) else None
         return dict(route) if isinstance(route, dict) else {}
 
+    @staticmethod
+    def _wire_model(model: str, model_config: Dict[str, Any] | None) -> str:
+        """The name the endpoint itself answers to, which is not always our key.
+
+        Catalogue keys are lowercased on write, because one key identifies a model
+        across entitlements, rate cards and usage rows. A server is free to be
+        case-sensitive: a vLLM endpoint serving `meta-llama/Llama-3.1-8B-Instruct`
+        answers `404 - The model does not exist` to the lowercased key.
+
+        So an entry may carry the exact served name in its route, and only the value
+        on the wire changes. Everything metered stays keyed by the catalogue key,
+        which is what keeps one model from splitting into two usage lines.
+        """
+        route = LLMProxy._model_route(model_config)
+        served_name = str(route.get("model_name") or "").strip()
+        return served_name or model
+
     @staticmethod
     def _model_credential_ref(model_config: Dict[str, Any] | None) -> str | None:
         """The secret this model is entitled to run on, when the company owns it.

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/locales/en.yaml

@@ -1806,6 +1806,17 @@ ui:
     new_modal_title: "Create New Prompt"
     name_label: "Name (Slug)"
     name_help: "Use lowercase, numbers, and underscores only."
+    create_name_label: "Name"
+    create_name_placeholder: "Customer Support"
+    create_name_help: "Used to suggest the technical identifier."
+    create_key_label: "Technical ID"
+    create_key_placeholder: "customer_support"
+    create_key_help: "Stable snake_case identifier used internally."
+    create_name_required: "Name is required."
+    create_key_required: "Technical ID is required."
+    create_creating: "Creating agent..."
+    create_success: "Agent \"{name}\" created."
+    create_failed: "Failed to create the agent."
     category_label: "Category"
     versions_btn: "Versions"
     versions_modal_title: "Previous versions"
@@ -1848,8 +1859,9 @@ ui:
     type_label: "Tool Type"
     method_label: "Execution Method"
     method_help: "Python method name in your company class implementation, or inference tool name."
-    desc_label: "Description (Prompt)"
-    desc_placeholder: "Describe to the LLM when and how to use this tool..."
+    desc_label: "Description for the agent"
+    desc_placeholder: "Describe for the agent when and how to use this tool..."
+    desc_help: "This description guides the agent in deciding when to use this tool."
     active_label: "Active"
 
     # Schema Section
@@ -1877,6 +1889,14 @@ ui:
     modal_title: "Create New Tool"
     modal_name_label: "Tool Name (LLM Function)"
     modal_name_help: "Use snake_case. Must be unique."
+    modal_display_name_label: "Name"
+    modal_display_name_placeholder: "Tax Calculator"
+    modal_display_name_help: "Used to suggest the technical identifier."
+    modal_display_name_required: "Name is required."
+    modal_key_label: "Technical ID"
+    modal_key_placeholder: "calculate_tax"
+    modal_key_help: "Stable snake_case identifier used by prompts and routing."
+    modal_key_required: "Technical ID is required."
     modal_type_label: "Type"
     modal_output_preset_label: "Output preset"
     modal_output_preset_none: "No preset"
@@ -2172,6 +2192,7 @@ ui:
     col_cost: "Cost"
     col_key: "API key"
     col_enabled: "Enabled"
+    col_default: "Default"
     col_reasoning: "Reasoning"
     cost_metered: "Metered"
     cost_not_billable: "No charge"
@@ -2206,6 +2227,8 @@ ui:
     form_route_base_url_hint: "The full URL requests go to, e.g. https://your-host/v1"
     form_route_api_key_env: "Credential variable"
     form_route_api_key_env_hint: "The NAME of an environment variable in this deployment, e.g. OSS_LLM_API_KEY. Never the key itself."
+    form_route_model_name: "Name served by the endpoint"
+    form_route_model_name_hint: "Optional. The exact name this endpoint answers to, e.g. meta-llama/Llama-3.1-8B-Instruct. Leave empty to send the identifier above, which is stored in lowercase."
     route_required: "This provider needs an endpoint and the name of its credential variable."
   secrets:
     title: "Secrets"

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/locales/es.yaml

@@ -1811,6 +1811,17 @@ ui:
     new_modal_title: "Crear Nuevo Prompt"
     name_label: "Nombre (Slug)"
     name_help: "Solo minúsculas, números y guiones bajos."
+    create_name_label: "Nombre"
+    create_name_placeholder: "Soporte al cliente"
+    create_name_help: "Se usa para sugerir el identificador técnico."
+    create_key_label: "ID técnico"
+    create_key_placeholder: "soporte_cliente"
+    create_key_help: "Identificador estable en snake_case usado internamente."
+    create_name_required: "El nombre es obligatorio."
+    create_key_required: "El ID técnico es obligatorio."
+    create_creating: "Creando agente..."
+    create_success: "Agente \"{name}\" creado."
+    create_failed: "No se pudo crear el agente."
     category_label: "Categoría"
     versions_btn: "Versiones"
     versions_modal_title: "Versiones antiguas"
@@ -1854,8 +1865,9 @@ ui:
     type_label: "Tipo de Herramienta"
     method_label: "Método a ejecutar"
     method_help: "Nombre del método Python en la implementación de la clase de su empresa, o nombre de tool en inference"
-    desc_label: "Descripción (Prompt)"
-    desc_placeholder: "Describe al LLM cuándo y cómo usar esta herramienta..."
+    desc_label: "Descripción para el agente"
+    desc_placeholder: "Describe al agente cuándo y cómo usar esta tool..."
+    desc_help: "Esta descripción guía al agente para decidir cuándo usar esta tool."
     active_label: "Activo"
 
     # Schema Section
@@ -1883,6 +1895,14 @@ ui:
     modal_title: "Crear Nueva Herramienta"
     modal_name_label: "Nombre (Función LLM)"
     modal_name_help: "Usar snake_case. Debe ser único."
+    modal_display_name_label: "Nombre"
+    modal_display_name_placeholder: "Calculadora tributaria"
+    modal_display_name_help: "Se usa para sugerir el identificador técnico."
+    modal_display_name_required: "El nombre es obligatorio."
+    modal_key_label: "ID técnico"
+    modal_key_placeholder: "calcular_impuestos"
+    modal_key_help: "Identificador estable en snake_case usado por prompts y routing."
+    modal_key_required: "El ID técnico es obligatorio."
     modal_type_label: "Tipo"
     modal_output_preset_label: "Preset de output"
     modal_output_preset_none: "Sin preset"
@@ -2178,6 +2198,7 @@ ui:
     col_cost: "Costo"
     col_key: "API key"
     col_enabled: "Habilitado"
+    col_default: "Por defecto"
     col_reasoning: "Razonamiento"
     cost_metered: "Con medición"
     cost_not_billable: "Sin costo"
@@ -2212,6 +2233,8 @@ ui:
     form_route_base_url_hint: "La URL completa a la que van las requests, ej. https://tu-host/v1"
     form_route_api_key_env: "Variable de la credencial"
     form_route_api_key_env_hint: "El NOMBRE de una variable de entorno de este deployment, ej. OSS_LLM_API_KEY. Nunca la key."
+    form_route_model_name: "Nombre que sirve el endpoint"
+    form_route_model_name_hint: "Opcional. El nombre exacto al que responde el endpoint, ej. meta-llama/Llama-3.1-8B-Instruct. Vacío envía el identificador de arriba, que se guarda en minúsculas."
     route_required: "Este proveedor necesita un endpoint y el nombre de la variable con su credencial."
   secrets:
     title: "Secrets"

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/repositories/llm_query_repo.py

@@ -66,6 +66,12 @@ class LLMQueryRepo:
             is_active=True
         ).first()
 
+    def get_tool_by_name(self, company: Company, tool_name: str) -> Tool | None:
+        return self.session.query(Tool).filter_by(
+            company_id=company.id,
+            name=tool_name,
+        ).first()
+
     def get_system_tool(self, tool_name: str) -> Tool | None:
         return self.session.query(Tool).filter_by(
             tool_type=Tool.TYPE_SYSTEM,

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/services/prompt_service.py

@@ -22,8 +22,11 @@ from iatoolkit.common.exceptions import IAToolkitException
 from iatoolkit.services.system_prompt_catalog import build_system_prompt_payload
 from iatoolkit.services.structured_output_service import StructuredOutputService
 import logging
+import re
+import unicodedata
 
 class PromptService:
+    PROMPT_NAME_MAX_LENGTH = 255
     OUTPUT_SCHEMA_MODE_BEST_EFFORT = "best_effort"
     OUTPUT_SCHEMA_MODE_STRICT = "strict"
     OUTPUT_RESPONSE_MODE_CHAT = "chat_compatible"
@@ -76,6 +79,34 @@ class PromptService:
         self.sql_service = sql_service
         self.configuration_service = configuration_service
 
+    @classmethod
+    def normalize_prompt_name(cls, prompt_name: str | None) -> str:
+        candidate = str(prompt_name or "").strip()
+        if not candidate:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.MISSING_PARAMETER,
+                "Prompt name is required",
+            )
+
+        normalized = unicodedata.normalize("NFKD", candidate).encode("ascii", "ignore").decode("ascii")
+        normalized = normalized.lower()
+        normalized = re.sub(r"[^a-z0-9]+", "_", normalized)
+        normalized = re.sub(r"_+", "_", normalized).strip("_")
+
+        if not normalized:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                "Prompt name must contain letters or numbers",
+            )
+
+        if len(normalized) > cls.PROMPT_NAME_MAX_LENGTH:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                f"Prompt name must be {cls.PROMPT_NAME_MAX_LENGTH} characters or fewer",
+            )
+
+        return normalized
+
     def _normalize_execution_mode(
         self,
         execution_mode: str | None,

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/services/query_service.py

@@ -612,7 +612,6 @@ class QueryService:
                 "xai",
                 "openrouter",
                 "deepseek",
-                "openai_compatible",
             ))
         )
         text_verbosity_provider_supported = bool(

{iatoolkit-2.42.0 → iatoolkit-2.42.2}/src/iatoolkit/services/tenant_wiki_service.py

@@ -56,6 +56,10 @@ class TenantWikiService:
     ACCESS_MODE_ENFORCE = "enforce"
     ACCESS_MODES = (ACCESS_MODE_OFF, ACCESS_MODE_DRY_RUN, ACCESS_MODE_ENFORCE)
 
+    # What a withheld page answers with, instead of "not found".
+    ACCESS_STATUS_FORBIDDEN = "forbidden"
+    ACCESS_STATUS_UNAVAILABLE = "unavailable"
+
     # Resolves the visibility labels one user holds. Registered by the edition
     # that knows where they come from -- the core has no business calling a
     # tenant's access control service -- and left unset in the community edition,
@@ -138,6 +142,42 @@ class TenantWikiService:
     def clear_access_label_resolver(cls) -> None:
         cls._access_label_resolver = None
 
+    @classmethod
+    def denial_event_metadata(cls, payload: Any) -> dict | None:
+        """
+        Turns a withheld-page answer into what is worth recording about it, or
+        None when the payload is not one.
+
+        Lives next to the payload it reads, so whoever changes the shape of a
+        denial changes this in the same edit. Callers decide how to store it: the
+        point of recording denials is to find pages classified more strictly than
+        they should be, without waiting for someone to complain.
+        """
+        if not isinstance(payload, dict):
+            return None
+        status = str(payload.get("status") or "").strip().lower()
+        if status not in {cls.ACCESS_STATUS_FORBIDDEN, cls.ACCESS_STATUS_UNAVAILABLE}:
+            return None
+        if not payload.get("path") or "blocked_by" not in payload:
+            # Some other subsystem's 'forbidden', not a wiki page decision.
+            return None
+
+        return {
+            "reason": str(payload.get("reason") or "").strip() or None,
+            "metadata": {
+                "access_denial": {
+                    "status": status,
+                    "blocked_by": payload.get("blocked_by"),
+                    "wiki_key": payload.get("wiki_key"),
+                    "path": payload.get("path"),
+                    "required_labels": list(payload.get("required_labels") or []),
+                    "held_labels": list(payload.get("held_labels") or []),
+                    "not_registered": bool(payload.get("not_registered")),
+                    "unlabelled_page": bool(payload.get("unlabelled_page")),
+                }
+            },
+        }
+
     @classmethod
     def page_is_visible(cls, access_tags: Any, user_labels: Any) -> bool:
         """
@@ -548,6 +588,15 @@ class TenantWikiService:
         if page is None or page.status == KnowledgeWikiPageStatus.ARCHIVED:
             return {"status": "error", "error_message": "page not found"}
         if visibility_filter is not None and not visibility_filter(page.path):
+            # A page that exists but is withheld says so, naming the label it
+            # needs. Answering "not found" would protect the content and bury the
+            # mistake: an over-restricted page is never reported by anyone,
+            # because nobody can tell there is anything to report.
+            if isinstance(visibility_filter, AccessGate):
+                return {
+                    **visibility_filter.denial_payload(page.path),
+                    "wiki": self.serialize_wiki(wiki),
+                }
             return {"status": "error", "error_message": "page not found"}
 
         markdown = self.markdown_wiki_service.read_markdown(company_short_name, page.source_storage_key)
@@ -945,54 +994,24 @@ class TenantWikiService:
         wiki that never opted in behaves exactly as it did before. In dry_run the
         decision is computed and logged but not applied, which is how a corpus of
         this size gets switched on without a blackout. In enforce it is applied.
+
+        Returns a gate that is callable like any other filter, and that can also
+        explain a single denial — see `AccessGate.denial_payload`.
         """
         access_control = self.wiki_access_control(wiki)
         mode = access_control["mode"]
         if mode == self.ACCESS_MODE_OFF:
             return base_filter
 
-        user_labels = self._resolve_access_labels(company_short_name, user_identifier)
-        access_tags_index: dict[str, list[str]] = {}
-        index_loaded = False
-        # One line per call, not per page: a 1.268-page index would otherwise
-        # bury the log. The full picture is the `wiki-access-check` report.
-        already_logged = False
-
-        def access_tags_for(path: str):
-            nonlocal index_loaded
-            if not index_loaded:
-                access_tags_index.update({
-                    page.path: (page.access_tags or [])
-                    for page in self.knowledge_wiki_repo.list_pages(
-                        wiki.id,
-                        include_archived=False,
-                        limit=self.MAX_PAGES,
-                    )
-                })
-                index_loaded = True
-            # A path with no row is unknown, and unknown denies.
-            return access_tags_index.get(path)
-
-        def is_visible(path: str) -> bool:
-            nonlocal already_logged
-            if base_filter is not None and not base_filter(path):
-                return False
-            if self.page_is_visible(access_tags_for(path), user_labels):
-                return True
-            if not already_logged:
-                already_logged = True
-                logging.info(
-                    "Knowledge wiki access %s: company=%s wiki=%s user=%s labels=%s first_denied_path=%s",
-                    "would deny (dry_run)" if mode == self.ACCESS_MODE_DRY_RUN else "denied",
-                    company_short_name,
-                    wiki.wiki_key,
-                    user_identifier or "(none)",
-                    "unresolved" if user_labels is None else sorted(user_labels),
-                    path,
-                )
-            return mode == self.ACCESS_MODE_DRY_RUN
-
-        return is_visible
+        return AccessGate(
+            service=self,
+            company_short_name=company_short_name,
+            wiki=wiki,
+            user_identifier=user_identifier,
+            base_filter=base_filter,
+            mode=mode,
+            user_labels=self._resolve_access_labels(company_short_name, user_identifier),
+        )
 
     def _resolve_access_labels(self, company_short_name: str, user_identifier: str | None):
         if not str(user_identifier or "").strip():
@@ -2122,3 +2141,156 @@ class TenantWikiService:
             "started_at": run.started_at.isoformat() if run.started_at else None,
             "finished_at": run.finished_at.isoformat() if run.finished_at else None,
         }
+
+
+class AccessGate:
+    """
+    Decides whether one reader may see a page of one wiki, and says why not.
+
+    It is callable, so it serves as the visibility filter for bulk work (the
+    index, search) where only a yes or no is needed. For a single page,
+    `denial_payload` turns the same decision into an answer the caller can hand
+    to a model: which label the page needs, which ones the reader holds, and
+    whether the reader is registered at all.
+
+    Saying "forbidden" instead of "not found" makes a page's existence visible,
+    which is deliberate. A denial that looks like a 404 protects the content but
+    hides the mistake: a page classified more strictly than it should be is never
+    reported, because nobody can tell there is anything to report.
+    """
+
+    BLOCKED_BY_LABELS = "labels"
+    BLOCKED_BY_POLICY = "policy"
+
+    def __init__(
+        self,
+        *,
+        service: TenantWikiService,
+        company_short_name: str,
+        wiki: KnowledgeWiki,
+        user_identifier: str | None,
+        base_filter: Callable[[str], bool] | None,
+        mode: str,
+        user_labels: Any,
+    ):
+        self.service = service
+        self.company_short_name = company_short_name
+        self.wiki = wiki
+        self.user_identifier = user_identifier
+        self.base_filter = base_filter
+        self.mode = mode
+        self.user_labels = user_labels
+        self._access_tags_index: dict[str, list[str]] | None = None
+        # One log line per call, not per page: a 1.268-page index would bury the
+        # log. The full picture is the `wiki-access-check` report.
+        self._logged = False
+
+    def __call__(self, path: str) -> bool:
+        if self.base_filter is not None and not self.base_filter(path):
+            return False
+        if self.service.page_is_visible(self._access_tags_for(path), self.user_labels):
+            return True
+        self._log_once(path)
+        # dry_run computes the decision and reports it without applying it.
+        return self.mode == TenantWikiService.ACCESS_MODE_DRY_RUN
+
+    def denial_payload(self, path: str) -> dict:
+        """
+        Why this page was withheld, in a shape a model can act on.
+
+        Never carries the title, the summary or the body: the caller already knew
+        the path it asked for, and nothing else about the page needs to leak for
+        the reader to know what to request.
+        """
+        payload = {
+            "wiki_key": self.wiki.wiki_key,
+            "path": path,
+            "held_labels": sorted(self._comparable(self.user_labels)) if self.user_labels is not None else [],
+        }
+
+        if self.base_filter is not None and not self.base_filter(path):
+            # A policy rule, not a label. Naming a label here would send the
+            # reader to ask for a grant that would not change the outcome.
+            return {
+                **payload,
+                "status": TenantWikiService.ACCESS_STATUS_FORBIDDEN,
+                "blocked_by": self.BLOCKED_BY_POLICY,
+                "reason": "an access policy blocks this path",
+                "required_labels": [],
+            }
+
+        if self.user_labels is None:
+            # Not "you lack permission": nobody knows yet. Telling the reader to
+            # request a label during an outage of the access control service
+            # sends them to ask for something they may already hold.
+            return {
+                **payload,
+                "status": TenantWikiService.ACCESS_STATUS_UNAVAILABLE,
+                "blocked_by": self.BLOCKED_BY_LABELS,
+                "reason": "your access could not be verified right now; retry shortly",
+                "required_labels": [],
+            }
+
+        required = sorted(self._comparable(self._access_tags_for(path)))
+        if not required:
+            # The page carries no labels at all, so it is unreadable for everyone.
+            # That is a classification defect, not a permission decision, and it
+            # is worth saying so plainly to whoever runs into it.
+            return {
+                **payload,
+                "status": TenantWikiService.ACCESS_STATUS_FORBIDDEN,
+                "blocked_by": self.BLOCKED_BY_LABELS,
+                "reason": "this page carries no access labels, so no one can read it",
+                "required_labels": [],
+                "unlabelled_page": True,
+            }
+
+        if not self.user_labels:
+            return {
+                **payload,
+                "status": TenantWikiService.ACCESS_STATUS_FORBIDDEN,
+                "blocked_by": self.BLOCKED_BY_LABELS,
+                "reason": "you hold no access labels for this knowledge base",
+                "required_labels": required,
+                "not_registered": True,
+            }
+
+        return {
+            **payload,
+            "status": TenantWikiService.ACCESS_STATUS_FORBIDDEN,
+            "blocked_by": self.BLOCKED_BY_LABELS,
+            "reason": "this page requires an access label you do not hold",
+            "required_labels": required,
+            "not_registered": False,
+        }
+
+    def _access_tags_for(self, path: str):
+        if self._access_tags_index is None:
+            self._access_tags_index = {
+                page.path: (page.access_tags or [])
+                for page in self.service.knowledge_wiki_repo.list_pages(
+                    self.wiki.id,
+                    include_archived=False,
+                    limit=TenantWikiService.MAX_PAGES,
+                )
+            }
+        # A path with no row is unknown, and unknown denies.
+        return self._access_tags_index.get(path)
+
+    @staticmethod
+    def _comparable(value: Any) -> set[str]:
+        return TenantWikiService._comparable_labels(value)
+
+    def _log_once(self, path: str) -> None:
+        if self._logged:
+            return
+        self._logged = True
+        logging.info(
+            "Knowledge wiki access %s: company=%s wiki=%s user=%s labels=%s first_denied_path=%s",
+            "would deny (dry_run)" if self.mode == TenantWikiService.ACCESS_MODE_DRY_RUN else "denied",
+            self.company_short_name,
+            self.wiki.wiki_key,
+            self.user_identifier or "(none)",
+            "unresolved" if self.user_labels is None else sorted(self._comparable(self.user_labels)),
+            path,
+        )