iatoolkit 2.25.0__tar.gz → 2.26.0__tar.gz

{iatoolkit-2.25.0/src/iatoolkit.egg-info → iatoolkit-2.26.0}/PKG-INFO

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

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/__init__.py

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

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/config/system_tools_pack.yaml

@@ -276,6 +276,96 @@ tools:
           description: "Opcional en la práctica. Usa null cuando no necesites filtrar por metadata. No inventes filtros ni envíes [] por defecto. Ejemplo: [{'key':'doc.type','value':'invoice'},{'key':'chunk.source_type','value':'table'}]."
       required:
         - query
+  - function_name: iat_wiki_search
+    description: Busca páginas publicadas dentro de las wikis de conocimiento compartidas por la empresa. Úsala como acelerador cuando necesites encontrar rápidamente una página relevante, pero no como punto de entrada por defecto. Si no conoces un `path` válido, primero llama `iat_wiki_get_page` con `path="/"` para leer el índice raíz de la wiki y seguir sus links exactos. `wiki_key` es el identificador estable de una wiki publicada, por ejemplo `sales`, `ops` o `hr`; úsalo cuando ya sepas en qué wiki buscar y omítelo cuando quieras buscar en todas las wikis publicadas disponibles en esta conexión MCP. Esta tool devuelve candidatos; luego usa `iat_wiki_get_page` para leer la página completa antes de responder.
+    routing:
+      force_include_capability: has_knowledge_wikis
+    routing_profile:
+      tags:
+        - knowledge_wiki
+        - company_knowledge
+        - tenant_context
+        - playbook
+        - policy
+        - process
+        - runbook
+        - onboarding
+        - wiki
+      intents:
+        - Search curated company wiki pages when direct lookup is faster than browsing the root index.
+        - Find the relevant company wiki page after the user asks about internal procedures, policies, or runbooks.
+        - Narrow down which exact page to open with iat_wiki_get_page.
+      examples:
+        - iat_wiki_search(query="politica de descuentos enterprise", wiki_key="sales", limit=5)
+        - iat_wiki_search(query="como escalar incidentes sev1", wiki_key="ops", limit=3)
+        - iat_wiki_search(query="onboarding de nuevos ejecutivos", limit=5)
+      cost:
+        penalty: 0.09
+        latency_class: low
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        query:
+          type: string
+          description: Consulta en lenguaje natural sobre políticas, playbooks, procesos, runbooks o conocimiento curado publicado en las wikis del tenant.
+        wiki_key:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: Clave estable de la wiki publicada, por ejemplo `sales`, `ops` o `hr`. Debe coincidir con el `wiki_key` expuesto por el catálogo/resource. Usa null para buscar en todas las wikis publicadas disponibles.
+        limit:
+          type: integer
+          description: Cantidad máxima de páginas candidatas a recuperar antes de elegir una para leer completa.
+          minimum: 1
+          maximum: 25
+      required:
+        - query
+        - limit
+  - function_name: iat_wiki_get_page
+    description: |-
+      Wiki entrypoint: llama `iat_wiki_get_page` con `path="/"` para cargar el índice raíz de una wiki de conocimiento publicada del tenant.
+      Lee UNA página de wiki y devuelve su contenido en Markdown. La wiki documenta contexto de negocio, áreas, sistemas internos, arquitectura, procesos, políticas, runbooks, onboarding, operaciones y glosarios. Es una wiki navegable por links: la página raíz `path="/"` es el punto de entrada y lista las páginas disponibles con sus paths exactos; después abre solo las páginas relevantes siguiendo esos links o los paths devueltos por `iat_wiki_search`.
+      `wiki_key` identifica la wiki publicada, por ejemplo `sales`, `ops` o `hr`. Los `path` son sensibles a mayúsculas y deben coincidir EXACTAMENTE con el link o path publicado; no los inventes ni los reconstruyas de memoria. Si no conoces un path válido, vuelve a llamar con `path="/"`. Esta tool es de solo lectura y es segura de usar siempre que la documentación interna de la empresa ayude a responder. Prefiere abrir pocas páginas puntuales antes de recorrer el corpus completo. Cuando respondas usando material de la wiki, cita la página usada.
+    routing:
+      force_include_capability: has_knowledge_wikis
+    routing_profile:
+      tags:
+        - knowledge_wiki
+        - company_knowledge
+        - tenant_context
+        - page
+        - markdown
+        - wiki
+        - entrypoint
+        - index
+        - root
+        - internal_docs
+      intents:
+        - Load the root index of a tenant knowledge wiki with path="/".
+        - Open a published tenant wiki page by exact path or slug.
+        - Read the full markdown content of a company knowledge page before answering.
+        - Follow links from the root index or another wiki page to retrieve the exact page content.
+      examples:
+        - iat_wiki_get_page(wiki_key="sales", path="/")
+        - iat_wiki_get_page(wiki_key="sales", path="pricing.md")
+        - iat_wiki_get_page(wiki_key="ops", path="incident-response.md")
+      cost:
+        penalty: 0.01
+        latency_class: low
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        wiki_key:
+          type: string
+          description: Clave estable de la wiki publicada, por ejemplo `sales`, `ops` o `hr`.
+        path:
+          type: string
+          description: Usa `"/"` para leer el índice raíz de la wiki. En cualquier otro caso, envía el path o slug exacto de la página dentro de esa wiki, idealmente uno listado en el índice raíz o devuelto por `iat_wiki_search`.
+      required:
+        - wiki_key
+        - path
   - function_name: iat_memory_search
     description: Busca páginas relevantes dentro de la Memoria personal del usuario y retorna contexto compilado. Incluye la señal `has_native_files` cuando una memoria tiene archivos fuente que pueden adjuntarse nativamente al modelo. Debe usarse antes de responder preguntas sobre cosas guardadas, notas previas, memoria del usuario, continuidad entre sesiones o "lo que hablamos/guardé antes".
     routing:

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/infra/connectors/file_connector.py

@@ -9,7 +9,7 @@ from typing import List, Optional
 
 class FileConnector(ABC):
     @abstractmethod
-    def list_files(self) -> List[str]:
+    def list_files(self, prefix: str | None = None) -> List[str]:
         pass
 
     @abstractmethod
@@ -25,4 +25,4 @@ class FileConnector(ABC):
         pass
 
     def generate_presigned_url(self, file_path: str, expiration: int = 3600) -> Optional[str]:
-        return None
+        return None

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/infra/connectors/google_cloud_storage_connector.py

@@ -36,11 +36,12 @@ class GoogleCloudStorageConnector(FileConnector):
             client = storage.Client.from_service_account_json(self.service_account_path)
         return client
 
-    def list_files(self) -> List[dict]:
+    def list_files(self, prefix: str | None = None) -> List[dict]:
         """
         Lista todos los archivos en el bucket de GCS como diccionarios con claves 'path', 'name' y 'metadata'.
         """
-        blobs = self.bucket.list_blobs()
+        normalized_prefix = str(prefix or "").strip().strip("/") or None
+        blobs = self.bucket.list_blobs(prefix=normalized_prefix)
 
         return [
             {

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/infra/connectors/google_drive_connector.py

@@ -52,7 +52,7 @@ class GoogleDriveConnector(FileConnector):
         )
         return service
 
-    def list_files(self) -> List[dict]:
+    def list_files(self, prefix: str | None = None) -> List[dict]:
         """
         Estándar: Lista todos los archivos como diccionarios con claves 'path', 'name' y 'metadata'.
         """

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/infra/connectors/local_file_connector.py

@@ -14,7 +14,7 @@ class LocalFileConnector(FileConnector):
         local_root = os.getenv("ROOT_DIR_LOCAL_FILES", '')
         self.directory = os.path.join(local_root, directory)
 
-    def list_files(self) -> List[dict]:
+    def list_files(self, prefix: str | None = None) -> List[dict]:
         """
         Estándar: Lista todos los archivos como diccionarios con claves 'path', 'name' y 'metadata'.
         """

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/infra/connectors/s3_connector.py

@@ -15,21 +15,32 @@ class S3Connector(FileConnector):
         self.folder = folder
         self.s3 = boto3.client('s3', **auth)
 
-    def list_files(self) -> List[dict]:
+    def list_files(self, prefix: str | None = None) -> List[dict]:
         # List only real S3 objects representing files, excluding folder placeholders.
-        # Construimos el prefijo evitando dobles barras si folder está vacío
-        parts = [p.strip('/') for p in [self.prefix, self.folder] if p]
-        prefix = "/".join(parts)
-
-        # Agregamos slash final solo si hay prefijo, para listar "contenido de carpeta"
-        if prefix:
-            prefix += "/"
-
-        response = self.s3.list_objects_v2(Bucket=self.bucket, Prefix=prefix)
-        files = [
-            obj for obj in response.get('Contents', [])
-            if self._is_file_key(obj.get('Key'))
-        ]
+        list_prefix = self._resolve_list_prefix(prefix)
+        files = []
+        continuation_token = None
+
+        while True:
+            params = {
+                "Bucket": self.bucket,
+                "Prefix": list_prefix,
+            }
+            if continuation_token:
+                params["ContinuationToken"] = continuation_token
+
+            response = self.s3.list_objects_v2(**params)
+            files.extend(
+                obj for obj in response.get('Contents', [])
+                if self._is_file_key(obj.get('Key'))
+            )
+
+            if not response.get("IsTruncated"):
+                break
+
+            continuation_token = response.get("NextContinuationToken")
+            if not continuation_token:
+                break
 
         return [
             {
@@ -44,6 +55,27 @@ class S3Connector(FileConnector):
             for obj in files
         ]
 
+    def _resolve_list_prefix(self, requested_prefix: str | None) -> str:
+        base_prefix = "/".join(p.strip("/") for p in [self.prefix, self.folder] if p)
+        normalized_requested = str(requested_prefix or "").strip().strip("/")
+
+        if normalized_requested:
+            if base_prefix and (
+                normalized_requested == base_prefix
+                or normalized_requested.startswith(f"{base_prefix}/")
+            ):
+                effective_prefix = normalized_requested
+            elif base_prefix:
+                effective_prefix = "/".join([base_prefix, normalized_requested])
+            else:
+                effective_prefix = normalized_requested
+        else:
+            effective_prefix = base_prefix
+
+        if effective_prefix:
+            return f"{effective_prefix.rstrip('/')}/"
+        return ""
+
     def _is_file_key(self, key: str | None) -> bool:
         return isinstance(key, str) and key != "" and not key.endswith("/")
 

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/locales/en.yaml

@@ -621,6 +621,90 @@ ui:
     description: "Description"
     skills: "Skills"
 
+  knowledge_wikis:
+    menu_label: "Wikis"
+    title: "Knowledge wikis"
+    wikis: "Wikis"
+    new_wiki: "New wiki"
+    create_wiki: "Create wiki"
+    select_wiki: "Select a wiki"
+    workspace_placeholder: "Choose a wiki from the list or create a new one."
+    configure: "Configuration"
+    key: "Key"
+    name: "Name"
+    root: "Storage root"
+    edit_root: "Edit storage root"
+    lock_root: "Lock storage root editing"
+    status: "Status"
+    status_published: "Published"
+    status_draft: "Draft"
+    status_archived: "Archived"
+    description: "Description"
+    pages: "Pages"
+    index: "Index"
+    mcp: "MCP"
+    mcp_status: "MCP publication"
+    mcp_status_published: "Published"
+    mcp_status_unpublished: "Not published"
+    mcp_status_published_help: "This wiki index is already exposed as a resource in the tenant MCP catalog."
+    mcp_status_unpublished_help: "This wiki does not yet expose its index as an MCP resource."
+    mcp_wiki_key: "MCP wiki_key"
+    lint: "Validate"
+    validate: "Validate"
+    validation_results: "Validation results"
+    sync: "Sync"
+    issues: "issues"
+    index_resource: "Resource URI"
+    mcp_publish_help: "This action publishes only this wiki's markdown index resource into MCP."
+    mcp_tools_help: "The tools iat_wiki_search and iat_wiki_get_page are enabled separately from the MCP manager."
+    mcp_step_publish_title: "1. Publish resource"
+    mcp_step_publish_text: "The Publish to MCP button adds or updates `iat://knowledge-wikis/{wiki_key}/index` in the tenant MCP resources."
+    mcp_step_tools_title: "2. Enable tools"
+    mcp_step_tools_text: "If you want tool-based search or page reads, enable `iat_wiki_search` and `iat_wiki_get_page` from the MCP manager."
+    mcp_step_usage_title: "3. Use wiki_key and path"
+    mcp_step_usage_text: "MCP clients can read this index first to discover pages, then use `wiki_key` and `path` with the tools."
+    copy_uri: "Copy URI"
+    publish_mcp: "Publish to MCP"
+    republish_mcp: "Update publication"
+    open_mcp: "Open MCP manager"
+    filter_pages: "Filter pages"
+    loading: "Loading..."
+    empty: "No wikis configured."
+    no_pages: "No pages."
+    no_issues: "No issues found."
+    lint_summary_clean: "Checked {count} indexed pages. No issues found."
+    lint_summary_issues: "Checked {count} indexed pages. Found {issues} issues."
+    missing_key: "Wiki key is required."
+    save_ok: "Wiki saved."
+    save_error: "Could not save wiki."
+    delete_confirmation: "Delete wiki"
+    delete_message: "This removes the wiki configuration, generated index, and indexed pages. Source markdown files in storage are not deleted."
+    delete_ok: "Wiki deleted."
+    delete_error: "Could not delete wiki."
+    sync_ok: "Sync completed."
+    sync_partial_ok: "Sync completed with errors."
+    sync_error: "Could not sync wiki."
+    sync_running: "Syncing..."
+    sync_results: "Sync result"
+    sync_status_idle: "Not run"
+    sync_status_success: "Completed"
+    sync_status_partial: "Completed with errors"
+    sync_status_error: "Failed"
+    sync_seen: "Files seen"
+    sync_indexed: "Pages indexed"
+    sync_failed: "Failed"
+    sync_finished_at: "Finished"
+    sync_first_error: "First error"
+    sync_summary_success: "Reviewed {seen} markdown files and indexed {indexed} pages."
+    sync_summary_partial: "Reviewed {seen} markdown files, indexed {indexed} pages, and found {failed} failures."
+    sync_summary_error: "Sync failed after reviewing {seen} markdown files. {failed} files could not be indexed."
+    sync_summary_empty: "No markdown files were found under this storage root."
+    lint_ok: "Validation completed."
+    lint_error: "Could not validate wiki."
+    mcp_ok: "Wiki published to MCP."
+    mcp_error: "Could not publish to MCP."
+    copy_ok: "URI copied."
+
   skills:
     title: "Skills"
     search_placeholder: "Search skills"

{iatoolkit-2.25.0 → iatoolkit-2.26.0}/src/iatoolkit/locales/es.yaml

@@ -621,6 +621,90 @@ ui:
     description: "Descripción"
     skills: "Skills"
 
+  knowledge_wikis:
+    menu_label: "Wikis"
+    title: "Wikis de conocimiento"
+    wikis: "Wikis"
+    new_wiki: "Nueva wiki"
+    create_wiki: "Crear wiki"
+    select_wiki: "Selecciona una wiki"
+    workspace_placeholder: "Elige una wiki del listado o crea una nueva."
+    configure: "Configuración"
+    key: "Clave"
+    name: "Nombre"
+    root: "Raíz storage"
+    edit_root: "Editar raíz storage"
+    lock_root: "Bloquear edición de raíz storage"
+    status: "Estado"
+    status_published: "Publicada"
+    status_draft: "Borrador"
+    status_archived: "Archivada"
+    description: "Descripción"
+    pages: "Páginas"
+    index: "Índice"
+    mcp: "MCP"
+    mcp_status: "Publicación MCP"
+    mcp_status_published: "Publicado"
+    mcp_status_unpublished: "No publicado"
+    mcp_status_published_help: "El índice de esta wiki ya está expuesto como resource en el catálogo MCP del tenant."
+    mcp_status_unpublished_help: "Esta wiki todavía no expone su índice como resource MCP."
+    mcp_wiki_key: "wiki_key MCP"
+    lint: "Validar"
+    validate: "Validar"
+    validation_results: "Resultados de validación"
+    sync: "Sincronizar"
+    issues: "hallazgos"
+    index_resource: "URI del resource"
+    mcp_publish_help: "Esta acción publica en MCP solo el resource del índice markdown de esta wiki."
+    mcp_tools_help: "Las tools iat_wiki_search e iat_wiki_get_page se habilitan por separado desde el gestor MCP."
+    mcp_step_publish_title: "1. Publicar resource"
+    mcp_step_publish_text: "El botón Publicar en MCP agrega o actualiza `iat://knowledge-wikis/{wiki_key}/index` dentro de los resources MCP del tenant."
+    mcp_step_tools_title: "2. Habilitar tools"
+    mcp_step_tools_text: "Si quieres búsqueda o lectura por tool, habilita `iat_wiki_search` e `iat_wiki_get_page` desde el gestor MCP."
+    mcp_step_usage_title: "3. Usar wiki_key y path"
+    mcp_step_usage_text: "Los clientes MCP pueden leer primero este índice para descubrir páginas y luego usar `wiki_key` y `path` en las tools."
+    copy_uri: "Copiar URI"
+    publish_mcp: "Publicar en MCP"
+    republish_mcp: "Actualizar publicación"
+    open_mcp: "Abrir gestor MCP"
+    filter_pages: "Filtrar páginas"
+    loading: "Cargando..."
+    empty: "No hay wikis configuradas."
+    no_pages: "No hay páginas."
+    no_issues: "Sin hallazgos."
+    lint_summary_clean: "Se revisaron {count} páginas indexadas. No se encontraron hallazgos."
+    lint_summary_issues: "Se revisaron {count} páginas indexadas. Se encontraron {issues} hallazgos."
+    missing_key: "Debes ingresar una key de wiki."
+    save_ok: "Wiki guardada."
+    save_error: "No se pudo guardar la wiki."
+    delete_confirmation: "Eliminar wiki"
+    delete_message: "Se borrará la configuración de la wiki, el índice generado y las páginas indexadas. Los archivos markdown fuente del storage no se borran."
+    delete_ok: "Wiki eliminada."
+    delete_error: "No se pudo eliminar la wiki."
+    sync_ok: "Sincronización completada."
+    sync_partial_ok: "Sincronización completada con errores."
+    sync_error: "No se pudo sincronizar la wiki."
+    sync_running: "Sincronizando..."
+    sync_results: "Resultado de sincronización"
+    sync_status_idle: "Sin ejecutar"
+    sync_status_success: "Completada"
+    sync_status_partial: "Con errores"
+    sync_status_error: "Falló"
+    sync_seen: "Archivos vistos"
+    sync_indexed: "Páginas indexadas"
+    sync_failed: "Fallidas"
+    sync_finished_at: "Finalizó"
+    sync_first_error: "Primer error"
+    sync_summary_success: "Se revisaron {seen} archivos markdown y se indexaron {indexed} páginas."
+    sync_summary_partial: "Se revisaron {seen} archivos markdown, se indexaron {indexed} páginas y {failed} fallaron."
+    sync_summary_error: "La sincronización falló después de revisar {seen} archivos markdown. {failed} archivos no pudieron indexarse."
+    sync_summary_empty: "No se encontraron archivos markdown bajo esta raíz de storage."
+    lint_ok: "Validación completada."
+    lint_error: "No se pudo validar la wiki."
+    mcp_ok: "Wiki publicada en MCP."
+    mcp_error: "No se pudo publicar en MCP."
+    copy_ok: "URI copiada."
+
   skills:
     title: "Skills"
     search_placeholder: "Buscar skills"

iatoolkit-2.26.0/src/iatoolkit/repositories/knowledge_wiki_repo.py

@@ -0,0 +1,226 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from injector import inject
+
+from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.repositories.models import (
+    KnowledgeWiki,
+    KnowledgeWikiPage,
+    KnowledgeWikiPageStatus,
+    KnowledgeWikiStatus,
+    KnowledgeWikiSyncRun,
+    KnowledgeWikiSyncStatus,
+)
+
+
+class KnowledgeWikiRepo:
+    @inject
+    def __init__(self, db_manager: DatabaseManager):
+        self.session = db_manager.get_session()
+
+    def commit(self):
+        self.session.commit()
+
+    def rollback(self):
+        self.session.rollback()
+
+    def get_wiki_by_key(self, company_id: int, wiki_key: str) -> KnowledgeWiki | None:
+        if not company_id or not wiki_key:
+            return None
+        return (
+            self.session.query(KnowledgeWiki)
+            .filter_by(company_id=company_id, wiki_key=wiki_key)
+            .first()
+        )
+
+    def get_wiki(self, company_id: int, wiki_id: int) -> KnowledgeWiki | None:
+        if not company_id or not wiki_id:
+            return None
+        return (
+            self.session.query(KnowledgeWiki)
+            .filter_by(company_id=company_id, id=wiki_id)
+            .first()
+        )
+
+    def list_wikis(self, company_id: int, *, include_archived: bool = False) -> list[KnowledgeWiki]:
+        if not company_id:
+            return []
+        query = self.session.query(KnowledgeWiki).filter_by(company_id=company_id)
+        if not include_archived:
+            query = query.filter(KnowledgeWiki.status != KnowledgeWikiStatus.ARCHIVED)
+        return query.order_by(KnowledgeWiki.name.asc(), KnowledgeWiki.id.asc()).all()
+
+    def create_or_update_wiki(
+        self,
+        *,
+        company_id: int,
+        wiki_key: str,
+        name: str,
+        root_storage_key: str,
+        description: str | None = None,
+        status: KnowledgeWikiStatus = KnowledgeWikiStatus.PUBLISHED,
+        settings: dict | None = None,
+    ) -> KnowledgeWiki:
+        wiki = self.get_wiki_by_key(company_id, wiki_key)
+        if wiki:
+            wiki.name = name
+            wiki.description = description
+            wiki.root_storage_key = root_storage_key
+            wiki.status = status
+            wiki.settings = settings or {}
+        else:
+            wiki = KnowledgeWiki(
+                company_id=company_id,
+                wiki_key=wiki_key,
+                name=name,
+                description=description,
+                root_storage_key=root_storage_key,
+                status=status,
+                settings=settings or {},
+            )
+            self.session.add(wiki)
+        self.session.commit()
+        return wiki
+
+    def delete_wiki(self, company_id: int, wiki_key: str) -> KnowledgeWiki | None:
+        wiki = self.get_wiki_by_key(company_id, wiki_key)
+        if wiki is None:
+            return None
+        self.session.delete(wiki)
+        self.session.commit()
+        return wiki
+
+    def get_page_by_path(self, wiki_id: int, path: str) -> KnowledgeWikiPage | None:
+        if not wiki_id or not path:
+            return None
+        return (
+            self.session.query(KnowledgeWikiPage)
+            .filter_by(wiki_id=wiki_id, path=path)
+            .first()
+        )
+
+    def get_page_by_slug(self, wiki_id: int, slug: str) -> KnowledgeWikiPage | None:
+        if not wiki_id or not slug:
+            return None
+        return (
+            self.session.query(KnowledgeWikiPage)
+            .filter_by(wiki_id=wiki_id, slug=slug)
+            .first()
+        )
+
+    def list_pages(
+        self,
+        wiki_id: int,
+        *,
+        include_archived: bool = False,
+        limit: int = 500,
+    ) -> list[KnowledgeWikiPage]:
+        if not wiki_id:
+            return []
+        query = self.session.query(KnowledgeWikiPage).filter_by(wiki_id=wiki_id)
+        if not include_archived:
+            query = query.filter(KnowledgeWikiPage.status != KnowledgeWikiPageStatus.ARCHIVED)
+        return (
+            query
+            .order_by(KnowledgeWikiPage.path.asc(), KnowledgeWikiPage.id.asc())
+            .limit(limit)
+            .all()
+        )
+
+    def create_or_update_page(
+        self,
+        *,
+        company_id: int,
+        wiki_id: int,
+        path: str,
+        slug: str,
+        title: str,
+        source_storage_key: str,
+        summary: str | None = None,
+        body_text: str | None = None,
+        status: KnowledgeWikiPageStatus = KnowledgeWikiPageStatus.PUBLISHED,
+        tags: list[str] | None = None,
+        owner: str | None = None,
+        source_meta: dict | None = None,
+        last_synced_at: datetime | None = None,
+    ) -> KnowledgeWikiPage:
+        page = self.get_page_by_path(wiki_id, path)
+        if page is None:
+            page = self.get_page_by_slug(wiki_id, slug)
+
+        if page:
+            page.path = path
+            page.slug = slug
+            page.title = title
+            page.summary = summary
+            page.body_text = body_text
+            page.source_storage_key = source_storage_key
+            page.status = status
+            page.tags = tags or []
+            page.owner = owner
+            page.source_meta = source_meta or {}
+            page.last_synced_at = last_synced_at
+        else:
+            page = KnowledgeWikiPage(
+                company_id=company_id,
+                wiki_id=wiki_id,
+                path=path,
+                slug=slug,
+                title=title,
+                summary=summary,
+                body_text=body_text,
+                source_storage_key=source_storage_key,
+                status=status,
+                tags=tags or [],
+                owner=owner,
+                source_meta=source_meta or {},
+                last_synced_at=last_synced_at,
+            )
+            self.session.add(page)
+        self.session.commit()
+        return page
+
+    def archive_pages_not_in_paths(self, wiki_id: int, paths: set[str]) -> int:
+        if not wiki_id:
+            return 0
+        query = self.session.query(KnowledgeWikiPage).filter_by(wiki_id=wiki_id)
+        if paths:
+            query = query.filter(~KnowledgeWikiPage.path.in_(paths))
+        rows = query.all()
+        changed = 0
+        for page in rows:
+            if page.status != KnowledgeWikiPageStatus.ARCHIVED:
+                page.status = KnowledgeWikiPageStatus.ARCHIVED
+                changed += 1
+        if changed:
+            self.session.commit()
+        return changed
+
+    def create_sync_run(
+        self,
+        *,
+        company_id: int,
+        wiki_id: int,
+        metadata_json: dict | None = None,
+    ) -> KnowledgeWikiSyncRun:
+        run = KnowledgeWikiSyncRun(
+            company_id=company_id,
+            wiki_id=wiki_id,
+            status=KnowledgeWikiSyncStatus.RUNNING,
+            metadata_json=metadata_json or {},
+        )
+        self.session.add(run)
+        self.session.commit()
+        return run
+
+    def save_sync_run(self, run: KnowledgeWikiSyncRun) -> KnowledgeWikiSyncRun:
+        self.session.add(run)
+        self.session.commit()
+        return run