flowtask 5.12.2__tar.gz → 5.12.4__tar.gz

{flowtask-5.12.2 → flowtask-5.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtask
-Version: 5.12.2
+Version: 5.12.4
 Summary: Framework for Task orchestration
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: Apache-2.0
@@ -37,7 +37,7 @@ Requires-Dist: selenium>=4.35.0
 Requires-Dist: snapshot-selenium==0.0.2
 Requires-Dist: httpx[http2,socks]>=0.26.0
 Requires-Dist: urllib3[socks]>=2.3.0
-Requires-Dist: requests==2.32.4
+Requires-Dist: requests<2.34,>=2.33.0
 Requires-Dist: h2>=4.2.0
 Requires-Dist: blinker>=1.9.0
 Requires-Dist: webdriver-manager==4.0.2
@@ -127,10 +127,12 @@ Requires-Dist: kr8s>=0.16.0; extra == "k8s"
 Provides-Extra: git
 Requires-Dist: gitpython>=3.1.50; extra == "git"
 Provides-Extra: ai
-Requires-Dist: ai-parrot[agents,images,integrations,llms,scheduler]>=0.20.4; extra == "ai"
+Requires-Dist: ai-parrot[agents,graphindex,images,llms,retrieval]>=0.20.4; extra == "ai"
 Requires-Dist: ai-parrot-loaders[audio,document,ebook,ml,pdf,scraping,video,web,youtube]>=0.1.0; extra == "ai"
 Requires-Dist: ai-parrot-tools[analysis,arxiv,aws,codeinterpreter,db,docker,excel,finance,flowtask,git,google,jira,messaging,pdf,pulumi,sandbox,scraping,sitesearch,slack,weather,wikipedia]>=0.1.0; extra == "ai"
 Requires-Dist: ai-parrot-pipelines>=0.1.0; extra == "ai"
+Requires-Dist: ai-parrot-server[all]>=0.1.0; extra == "ai"
+Requires-Dist: ai-parrot-integrations[all]>=0.0.17; extra == "ai"
 Provides-Extra: dev
 Requires-Dist: pytest>=5.4.0; extra == "dev"
 Requires-Dist: coverage; extra == "dev"

{flowtask-5.12.2 → flowtask-5.12.4}/flowtask/components/CallAnalysis.py

@@ -2,7 +2,7 @@ from collections.abc import Callable
 import asyncio
 import pandas as pd
 import orjson
-from ..exceptions import DataNotFound
+from ..exceptions import DataNotFound, ComponentError
 from ..interfaces.ParrotBot import ParrotBot
 from ..interfaces.flow import FlowComponent
 
@@ -236,6 +236,49 @@ class CallAnalysis(ParrotBot, FlowComponent):
         self.skip_existing: bool = kwargs.get('skip_existing', True)
         self.lookup_schema_column: str = kwargs.get('schema_column', 'program_slug')
 
+        # Credentials/auth abort state (set per bot_evaluation run).
+        # When a non-retryable credentials error is detected, _auth_error holds
+        # the offending exception and _abort_event signals every in-flight/queued
+        # task to bail out so no further API calls are attempted.
+        self._auth_error: Exception | None = None
+        self._abort_event: asyncio.Event | None = None
+
+    # Substrings that flag a non-retryable credentials/permission failure.
+    # Retrying these only wastes API quota — the key/permissions must be fixed.
+    _CREDENTIALS_ERROR_MARKERS = (
+        "PERMISSION_DENIED",
+        "API_KEY_SERVICE_BLOCKED",
+        "API_KEY_INVALID",
+        "API key not valid",
+        "API_KEY_HTTP_REFERRER_BLOCKED",
+        "UNAUTHENTICATED",
+        "CONSUMER_INVALID",
+    )
+
+    def _is_credentials_error(self, exc: Exception) -> bool:
+        """Return True if ``exc`` is a non-retryable credentials/auth failure.
+
+        Detects the Google GenAI ``403 PERMISSION_DENIED`` /
+        ``API_KEY_SERVICE_BLOCKED`` family (and equivalent auth errors) so the
+        batch can fail fast instead of retrying a blocked API key.
+
+        Args:
+            exc: The exception raised by the LLM provider call.
+
+        Returns:
+            bool: True when the error indicates blocked/invalid credentials.
+        """
+        # HTTP status carried on the exception (google-genai / aiohttp styles).
+        status = (
+            getattr(exc, 'status_code', None)
+            or getattr(exc, 'code', None)
+            or getattr(exc, 'status', None)
+        )
+        if status in (401, 403):
+            return True
+        message = str(exc)
+        return any(marker in message for marker in self._CREDENTIALS_ERROR_MARKERS)
+
     def load_from_file(
         self,
         df: pd.DataFrame,
@@ -651,6 +694,13 @@ class CallAnalysis(ParrotBot, FlowComponent):
         """
         call_key = call_key or call_identifier
         async with semaphore:
+            # A fatal credentials error already aborted the batch — bail out
+            # without making another doomed API call.
+            if self._abort_event is not None and self._abort_event.is_set():
+                self._logger.debug(
+                    f"Skipping {call_identifier} - batch aborted due to credentials error"
+                )
+                return (call_key, None)
             for attempt in range(self.retry_attempts):
                 try:
                     # Wait minimum interval before request to respect RPM limit
@@ -673,6 +723,23 @@ class CallAnalysis(ParrotBot, FlowComponent):
 
 
                 except Exception as e:
+                    # Credentials / permission errors are NOT retryable: retrying
+                    # only burns API quota against a blocked key. Flag the batch
+                    # for abort so no further calls are attempted and surface it
+                    # clearly (distinct from DataNotFound) in bot_evaluation.
+                    if self._is_credentials_error(e):
+                        if self._auth_error is None:
+                            self._auth_error = e
+                            self._logger.error(
+                                f"🔑 Credentials/permission error from LLM provider while "
+                                f"analyzing {call_identifier}: {e}. Aborting batch — the API "
+                                f"key is blocked/invalid or lacks permission. No further "
+                                f"calls will be attempted."
+                            )
+                        if self._abort_event is not None:
+                            self._abort_event.set()
+                        return (call_key, None)
+
                     if attempt < self.retry_attempts - 1:
                         # Calculate exponential backoff wait time
                         wait_time = self.retry_backoff_factor ** attempt
@@ -704,6 +771,10 @@ class CallAnalysis(ParrotBot, FlowComponent):
             A Pandas Dataframe with the Call Analysis results.
 
         """
+        # Reset credentials-abort state for this run.
+        self._auth_error = None
+        self._abort_event = asyncio.Event()
+
         # Determine if we should group the data or process row by row
         should_group = self.group_analysis
         schema_col_present = (
@@ -944,6 +1015,17 @@ class CallAnalysis(ParrotBot, FlowComponent):
             # Add the analysis results as a new column
             result_df[self.output_column] = analysis_results
 
+        # If a fatal credentials/permission error aborted the batch, surface it
+        # explicitly. Do NOT let it fall through to the DataNotFound below — that
+        # status (204, "nothing to analyze") would mask a blocked/invalid API key.
+        if self._auth_error is not None:
+            raise ComponentError(
+                f"{self._bot_name}: aborted analysis due to a credentials/permission "
+                f"error from the LLM provider ({self._auth_error}). The API key is "
+                f"blocked, invalid, or lacks permission to call the model. Fix the "
+                f"credentials and retry — no further API calls were attempted."
+            )
+
         # Clean up JSON formatting in the output column if present
         # Only clean strings, preserve dicts/lists that are already valid JSON objects
         if self.output_column in result_df.columns and not result_df[self.output_column].isna().all():

{flowtask-5.12.2 → flowtask-5.12.4}/flowtask/components/OpenWithBase.py

@@ -56,15 +56,13 @@ def detect_encoding(filename, encoding: str = "utf-8"):
         try:
             result = chardet.detect(raw)
             if result["encoding"] in ("ASCII", "ascii"):
-                # let me try to repair the file:
-                content = None
-                with open(filename, "rb") as fp:
-                    content = fp.read()
-                decoded = content.decode(encoding, "ignore")
-                output = StringIO()
-                output.write(decoded)
-                output.seek(0)
-                return [output, encoding]
+                # ASCII is a strict subset of UTF-8, so the declared encoding
+                # is safe to use as-is.  Do NOT slurp the whole file here: the
+                # only thing every caller consumes from this function is the
+                # encoding string (the buffer is always discarded), and reading
+                # a multi-GB file just to throw it away caused massive memory
+                # pressure / apparent hangs on large CSVs.
+                return [None, encoding]
             else:
                 enc = result["encoding"]
         except UnicodeDecodeError:

{flowtask-5.12.2 → flowtask-5.12.4}/flowtask/components/OpenWithPandas.py

@@ -539,11 +539,13 @@ class OpenWithPandas(OpenWithBase):
                     raise ComponentError(
                         f"Error Combining Resultset Dataframes: {err}"
                     ) from err
-        # When --debug is on, print the RAW DataFrame exactly as read, BEFORE
-        # any post-processing (drop_empty/trim/dropna). This is the place to
-        # validate which columns came in and which are all-empty (and would be
-        # dropped below by drop_empty).
-        if self._debug is True:
+        # When is_debug is on, log the RAW read shape/columns BEFORE any
+        # post-processing (drop_empty/trim/dropna) — useful to validate which
+        # columns came in and which are all-empty (and would be dropped below
+        # by drop_empty). Gated behind the explicit is_debug YAML flag (NOT the
+        # global --debug) so normal debug runs don't flood the logs with the
+        # per-column non-null dump on every OpenWithPandas step.
+        if getattr(self, 'is_debug', False) is True:
             try:
                 nonnull = df.notna().sum()
                 empty_cols = [c for c in df.columns if nonnull[c] == 0]
@@ -656,11 +658,15 @@ class OpenWithPandas(OpenWithBase):
         self.add_metric("NUMROWS", numrows)
         self.add_metric("OPENED_FILES", self._filenames)
         if getattr(self, 'is_debug', False) is True:
-            self._logger.debug("DataFrame result:\n%s", df.to_string())
+            # Do NOT render the full DataFrame (df.to_string() with no row limit
+            # materialises every row into one giant string — CPU-bound for
+            # minutes/hours on multi-GB frames, the apparent "hang"). Instead,
+            # show the shape and a single representative row: every column with
+            # its dtype and its first value.
+            self._logger.debug("DataFrame result: shape=%s", df.shape)
             self._logger.debug("::: Column Information ===")
             for column, t in df.dtypes.items():
-                self._logger.debug(
-                    "%s -> %s -> %s", column, t, df[column].iloc[0]
-                )
+                sample = df[column].iloc[0] if len(df.index) else "<empty>"
+                self._logger.debug("%s -> %s -> %s", column, t, sample)
             self._logger.debug("Opened File(s) with Pandas %s", self._filenames)
         return self._result

flowtask-5.12.4/flowtask/components/ParrotKnowledgeBuilder/__init__.py

@@ -0,0 +1,5 @@
+"""ParrotKnowledgeBuilder — builds GraphIndex/PageIndex knowledge structures from documents."""
+from .loader import ParrotKnowledgeBuilder
+from .payload import KnowledgeArtifact
+
+__all__ = ["KnowledgeArtifact", "ParrotKnowledgeBuilder"]

flowtask-5.12.4/flowtask/components/ParrotKnowledgeBuilder/loader.py

@@ -0,0 +1,439 @@
+"""ParrotKnowledgeBuilder — FlowComponent that builds GraphIndex/PageIndex structures."""
+import asyncio
+from collections.abc import Callable
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import Any, Optional
+
+from ...exceptions import ComponentError, ConfigError, DataNotFound
+from ...interfaces.flow import FlowComponent
+
+# Reuse module-level helpers and private methods from ParrotLoader without
+# modifying it.  In Python 3, accessing a method via the class returns the
+# underlying function whose __globals__ still live in ParrotLoader's module, so
+# every helper they depend on (_has_glob, pd, json, …) resolves correctly.
+from ..ParrotLoader.loader import (
+    ParrotLoader as _PL,
+    _has_glob,
+)
+from .payload import KnowledgeArtifact as KnowledgeArtifact  # re-exported
+
+_VALID_INDEX_TYPES = frozenset({"graphindex", "pageindex"})
+
+
+class ParrotKnowledgeBuilder(FlowComponent):
+    """Build a GraphIndex graph or PageIndex tree from documents; emit KnowledgeArtifact.
+
+    Config keys (YAML):
+        index_type:      graphindex | pageindex   (required)
+        path:            single file/dir/glob pattern
+        path_list:       inline list or path to .txt/.json/.csv file of sources
+        path_column:     column name when upstream component provides a DataFrame
+        loader:          ParrotLoader class name (graphindex only)
+        tenant_id:       ArangoDB tenant identifier (graphindex; default "default")
+        directory:       KB storage directory under the task storage. A relative
+                         path (e.g. "mi_agente/kb") resolves to
+                         programs/{program}/agents/{directory}; absolute is used
+                         as-is; if omitted, defaults to programs/{program}/agents.
+                         Each mode writes to its own leaf so they never intermix:
+                         pageindex → {directory}/pages, graphindex → {directory}/graph.
+                         (index JSON + per-node markdown; graphindex section nodes
+                         get a content_ref pointing at it.)
+        llm:             LLM provider name (e.g. "anthropic", "google", "groq").
+                         Required by pageindex; OPTIONAL for graphindex (enables
+                         hierarchical section extraction + disk persistence;
+                         omit for flat, in-memory extraction).
+        llm_model:       model id for the adapter. If omitted, the client's own
+                         default model is used (NOT the adapter's Google default).
+        llm_concurrency: max concurrent LLM calls (legacy; the PageIndexToolkit
+                         manages its own concurrency).
+        with_summaries:  generate section summaries via LLM (pageindex; default True)
+        fail_on_empty:   raise DataNotFound when no nodes/tree extracted (default True)
+    """
+
+    _version = "1.0.0"
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop = None,
+        job: Callable = None,
+        stat: Callable = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialise the component from YAML config kwargs.
+
+        Args:
+            loop: optional event loop (forwarded to super).
+            job: upstream job/component (forwarded to super).
+            stat: stats callback (forwarded to super).
+            **kwargs: YAML config keys consumed here; remainder forwarded to FlowComponent.
+        """
+        # Source resolution (mirror ParrotLoader attribute layout so rebound
+        # methods work without modification)
+        self.path: Optional[str] = kwargs.pop("path", None)
+        self._path_list: Optional[Any] = kwargs.pop("path_list", None)
+        self._path_list_format: str = str(
+            kwargs.pop("path_list_format", "auto") or "auto"
+        ).lower()
+        self._path_column: Optional[str] = kwargs.pop("path_column", None)
+        self.encoding: str = kwargs.get("encoding", "utf-8")
+
+        # Mode
+        self._index_type: Optional[str] = kwargs.pop("index_type", None)
+
+        # graphindex config
+        self._loader_name: Optional[str] = kwargs.pop("loader", None)
+        self._tenant_id: str = kwargs.pop("tenant_id", "default")
+
+        # KB storage directory (both modes persist the PageIndex tree here)
+        self._directory: Optional[str] = kwargs.pop("directory", None)
+
+        # pageindex config
+        self._llm: Optional[Any] = kwargs.pop("llm", None)
+        self._llm_model: Optional[str] = kwargs.pop("llm_model", None)
+        self._llm_concurrency: int = int(kwargs.pop("llm_concurrency", 8))
+        self._with_summaries: bool = bool(kwargs.pop("with_summaries", True))
+
+        # Behaviour
+        self._fail_on_empty: bool = bool(kwargs.pop("fail_on_empty", True))
+
+        super().__init__(loop=loop, job=job, stat=stat, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Reuse ParrotLoader source-resolution and LLM-building helpers.
+    # These functions' __globals__ live in ParrotLoader's module, so their
+    # module-level dependencies (_has_glob, pd, json, …) resolve correctly.
+    # ------------------------------------------------------------------
+    _build_llm_client = _PL._build_llm_client
+    _resolve_loader_class = _PL._resolve_loader_class
+    _resolve_sources = _PL._resolve_sources
+    _read_path_list_file = _PL._read_path_list_file
+    _extract_paths_from_dataframe = _PL._extract_paths_from_dataframe
+
+    def _resolve_model(self, client: Any) -> Optional[str]:
+        """Resolve the model name to hand to ``PageIndexLLMAdapter``.
+
+        Precedence: explicit ``llm_model`` config → the client's configured
+        ``model`` → the client's provider default (``_default_model``). This
+        avoids ``PageIndexLLMAdapter``'s hardcoded Google default
+        (``gemini-3.1-flash-lite-preview``) leaking onto a non-Google client
+        (e.g. Groq), which causes a 404 model_not_found.
+
+        Args:
+            client: the built ``AbstractClient`` (e.g. GroqClient).
+
+        Returns:
+            A provider-appropriate model name, or ``None`` to defer to the
+            adapter (only when nothing could be resolved).
+        """
+        return (
+            self._llm_model
+            or getattr(client, "model", None)
+            or getattr(client, "_default_model", None)
+        )
+
+    def _resolve_kb_directory(self, subdir: str) -> Path:
+        """Resolve the KB storage directory under the task storage.
+
+        Layout (per Jesús Lara): ``<task-storage-root>/{program}/agents/{directory}``,
+        with a per-mode ``subdir`` appended so the two builders never intermix in
+        the same folder:
+
+            programs/{program}/agents/{directory}/pages   (pageindex)
+            programs/{program}/agents/{directory}/graph   (graphindex)
+
+        - relative ``directory`` (e.g. "mi_agente/kb") → joined under
+          ``programs/{program}/agents``;
+        - absolute ``directory`` → used as-is;
+        - omitted → defaults to ``programs/{program}/agents``.
+
+        The PageIndex stores auto-create the directory (``mkdir parents=True``).
+
+        Args:
+            subdir: per-mode leaf folder ("pages" or "graph").
+
+        Returns:
+            Absolute :class:`~pathlib.Path` for the PageIndex ``storage_dir``.
+        """
+        base = Path(self._taskstore.get_path()).joinpath(self._program, "agents")
+        if self._directory:
+            directory = Path(self._directory)
+            base = directory if directory.is_absolute() else base.joinpath(directory)
+        return base.joinpath(subdir)
+
+    # ------------------------------------------------------------------
+    # FlowComponent lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self, **kwargs: Any) -> None:
+        """Validate config and resolve document sources.
+
+        Args:
+            **kwargs: forwarded to FlowComponent.start().
+
+        Raises:
+            ConfigError: missing/invalid index_type or no source provided.
+            ComponentError: resolved path does not exist.
+        """
+        await super().start(**kwargs)
+
+        # Validate index_type
+        if not self._index_type:
+            raise ConfigError(
+                "ParrotKnowledgeBuilder: 'index_type' is required. "
+                f"Supported values: {sorted(_VALID_INDEX_TYPES)}."
+            )
+        if self._index_type == "ontology":
+            raise ConfigError(
+                "ParrotKnowledgeBuilder: 'index_type: ontology' is not supported here. "
+                "Ontology is an ArangoDB persistence/schema layer — use the CopyToArango "
+                "spec for persistence instead."
+            )
+        if self._index_type not in _VALID_INDEX_TYPES:
+            raise ConfigError(
+                f"ParrotKnowledgeBuilder: unsupported index_type '{self._index_type}'. "
+                f"Supported values: {sorted(_VALID_INDEX_TYPES)}."
+            )
+
+        # Normalize path_list string through mask replacement
+        if isinstance(self._path_list, str):
+            self._path_list = self.mask_replacement_recursively(self._path_list)
+
+        # Resolve and validate single path
+        if self.path:
+            if isinstance(self.path, str):
+                self.path = self.mask_replacement_recursively(self.path)
+                if not self.path.startswith(("http://", "https://", "ftp://")):
+                    if _has_glob(self.path):
+                        pass  # glob expansion deferred to run()
+                    else:
+                        self.path = Path(self.path).resolve()
+                        if not self.path.exists():
+                            raise ComponentError(
+                                f"ParrotKnowledgeBuilder: {self.path} doesn't exist."
+                            )
+            elif isinstance(self.path, Path) and not self.path.exists():
+                raise ComponentError(
+                    f"ParrotKnowledgeBuilder: {self.path} doesn't exist."
+                )
+        elif self._path_list is None and not self._path_column:
+            raise ConfigError(
+                "ParrotKnowledgeBuilder: provide at least one of: 'path', "
+                "'path_list', or 'path_column' (with an upstream DataFrame)."
+            )
+
+    async def run(self) -> bool:
+        """Dispatch to the appropriate index-type branch and set self._result.
+
+        Returns:
+            True on success.
+        """
+        if self._index_type == "graphindex":
+            await self._run_graphindex()
+        else:
+            await self._run_pageindex()
+        return True
+
+    async def _run_graphindex(self) -> None:
+        """Build a merged tenant graph via LoaderExtractor + GraphAssembler.
+
+        For each resolved source, runs LoaderExtractor.extract() to get
+        (nodes, edges), feeds them into a single GraphAssembler, then emits one
+        KnowledgeArtifact(kind="graph") with model_dump() dicts. When `llm` is
+        set, a PageIndexToolkit(storage_dir) is supplied so section content is
+        persisted to disk and nodes carry a content_ref; otherwise extraction is
+        flat/in-memory. Embed and cross-domain resolve are intentionally skipped
+        (no vectors in v1).
+
+        Raises:
+            ConfigError: loader name not provided or loader class not found.
+            DataNotFound: extraction produced no nodes and fail_on_empty is True.
+        """
+        # defer heavy import so graphindex extra is only required at runtime
+        from parrot.knowledge.graphindex.assemble import GraphAssembler
+        from parrot.knowledge.graphindex.extractors.loader import LoaderExtractor
+
+        if not self._loader_name:
+            raise ConfigError(
+                "ParrotKnowledgeBuilder: 'loader' is required for graphindex mode."
+            )
+        loader_cls = self._resolve_loader_class(self._loader_name)
+        if loader_cls is None:
+            raise ConfigError(
+                f"ParrotKnowledgeBuilder: loader '{self._loader_name}' not found "
+                "in LOADER_REGISTRY, parrot_loaders, or parrot.loaders."
+            )
+
+        sources = self._resolve_sources()
+        if sources is None:
+            sources = [self.path]
+
+        # Deduplicate the payload to mirror the assembler's merged view: a
+        # node_id seen across multiple sources collapses to one entry (last
+        # wins, as GraphAssembler.add_node does), and parallel edges collapse
+        # on (source_id, target_id, kind). This keeps artifact.nodes/edges
+        # consistent with the node_count/edge_count metadata and avoids pushing
+        # duplicate upserts to a downstream CopyToArango.
+        assembler = GraphAssembler(self._tenant_id)
+        nodes_by_id: dict[str, Any] = {}
+        edges_by_key: dict[tuple, Any] = {}
+
+        # Optional LLM adapter + PageIndexToolkit: when `llm` is configured,
+        # LoaderExtractor routes hierarchical content through the toolkit, which
+        # persists each document's sections to disk (index JSON + per-node
+        # markdown under storage_dir) and gives every SECTION node a
+        # content_ref = "pageindex://<tree>/<node>". Without `llm` it degrades to
+        # flat, in-memory extraction (one DOCUMENT node, no content_ref).
+        # The AbstractClient MUST be entered as an async context manager
+        # (__aenter__ initializes the per-loop SDK client).
+        storage_dir = self._resolve_kb_directory("graph")
+        persisted = self._llm is not None
+        async with AsyncExitStack() as stack:
+            extractor_kwargs: dict = {"toolkit": None}
+            if persisted:
+                from parrot.knowledge.pageindex.llm_adapter import PageIndexLLMAdapter
+                from parrot.knowledge.pageindex.toolkit import PageIndexToolkit
+                client = await stack.enter_async_context(self._build_llm_client())
+                adapter = PageIndexLLMAdapter(
+                    client=client, model=self._resolve_model(client)
+                )
+                extractor_kwargs["llm_adapter"] = adapter
+                extractor_kwargs["toolkit"] = PageIndexToolkit(
+                    adapter=adapter, storage_dir=str(storage_dir)
+                )
+
+            extractor = LoaderExtractor(**extractor_kwargs)
+
+            for source in sources:
+                source_str = str(source)
+                try:
+                    loader = loader_cls(source=source_str)
+                    nodes, edges = await extractor.extract(loader, source_str)
+                except Exception as exc:  # noqa: BLE001
+                    self._logger.warning(
+                        "ParrotKnowledgeBuilder: source %s failed, skipping: %s",
+                        source_str, exc,
+                    )
+                    continue
+                assembler.add_nodes(nodes)
+                assembler.add_edges(edges)
+                for node in nodes:
+                    nodes_by_id[node.node_id] = node
+                for edge in edges:
+                    edges_by_key[(edge.source_id, edge.target_id, edge.kind)] = edge
+
+        if self._fail_on_empty and not nodes_by_id:
+            raise DataNotFound(
+                "ParrotKnowledgeBuilder: graphindex extraction produced no nodes "
+                f"across {len(sources)} source(s)."
+            )
+
+        self._result = KnowledgeArtifact(
+            kind="graph",
+            index_type="graphindex",
+            source="<merged>",
+            tenant_id=self._tenant_id,
+            nodes=[n.model_dump() for n in nodes_by_id.values()],
+            edges=[e.model_dump() for e in edges_by_key.values()],
+            metadata={
+                "source_count": len(sources),
+                "node_count": assembler.node_count,
+                "edge_count": assembler.edge_count,
+                # Where section markdown/index were persisted (content_ref base);
+                # None when running flat/in-memory (no `llm`).
+                "storage_dir": str(storage_dir) if persisted else None,
+            },
+        )
+        self.add_metric("NUM_NODES", assembler.node_count)
+        self.add_metric("NUM_EDGES", assembler.edge_count)
+
+    async def _run_pageindex(self) -> None:
+        """Build + persist one PageIndex tree per PDF via PageIndexToolkit.
+
+        For each PDF, ``toolkit.import_pdf`` builds the tree AND writes it to
+        disk under the resolved storage_dir:
+        ``<storage_dir>/<tree_name>.json`` (index) + ``<storage_dir>/<tree_name>/
+        <node_id>.md`` (per-node markdown). The emitted KnowledgeArtifact keeps
+        the lean tree/index in ``tree`` and points at the on-disk content via
+        ``metadata`` (storage_dir / tree_name / index_file / content_dir);
+        ``node_markdown`` stays empty since the bodies live on disk. A downstream
+        CopyTo* persister reads from those paths.
+
+        Raises:
+            ConfigError: source is not a PDF file.
+            DataNotFound: no trees produced and fail_on_empty is True.
+        """
+        # defer heavy import; requires dev parrot 0.25.7 + editable-source toggle
+        from parrot.knowledge.pageindex.llm_adapter import PageIndexLLMAdapter
+        from parrot.knowledge.pageindex.toolkit import PageIndexToolkit
+
+        sources = self._resolve_sources()
+        if sources is None:
+            sources = [self.path]
+
+        storage_dir = self._resolve_kb_directory("pages")
+        artifacts: list[KnowledgeArtifact] = []
+
+        # The AbstractClient MUST be entered as an async context manager so its
+        # per-loop SDK client is initialized; a bare instance leaves the SDK as
+        # None and the toolkit's LLM calls fail with 'NoneType .. chat'.
+        async with self._build_llm_client() as client:
+            adapter = PageIndexLLMAdapter(
+                client=client, model=self._resolve_model(client)
+            )
+            toolkit = PageIndexToolkit(adapter=adapter, storage_dir=str(storage_dir))
+
+            for source in sources:
+                source_str = str(source)
+                if not source_str.lower().endswith(".pdf"):
+                    raise ConfigError(
+                        f"ParrotKnowledgeBuilder: pageindex requires PDF sources, "
+                        f"got: {source_str!r}. Non-PDF formats are not supported by build_page_index."
+                    )
+                tree_name = Path(source_str).stem
+                try:
+                    # Idempotent: replace any prior tree for this document.
+                    if tree_name in await toolkit.list_trees():
+                        await toolkit.delete_tree(tree_name)
+                    await toolkit.create_tree(tree_name, doc_name=Path(source_str).name)
+                    await toolkit.import_pdf(
+                        tree_name=tree_name,
+                        pdf_path=source_str,
+                        with_summaries=self._with_summaries,
+                    )
+                    tree = await toolkit.get_tree(tree_name)
+                except Exception as exc:  # noqa: BLE001
+                    self._logger.warning(
+                        "ParrotKnowledgeBuilder: pageindex failed for %s, skipping: %s",
+                        source_str, exc,
+                    )
+                    continue
+
+                artifacts.append(
+                    KnowledgeArtifact(
+                        kind="tree",
+                        index_type="pageindex",
+                        source=source_str,
+                        tree=tree,            # lean index kept in the payload too
+                        node_markdown={},     # bodies live on disk, not embedded
+                        metadata={
+                            "storage_dir": str(storage_dir),
+                            "tree_name": tree_name,
+                            "index_file": str(storage_dir / f"{tree_name}.json"),
+                            "content_dir": str(storage_dir / tree_name),
+                        },
+                    )
+                )
+
+        if self._fail_on_empty and not artifacts:
+            raise DataNotFound(
+                "ParrotKnowledgeBuilder: pageindex extraction produced no trees "
+                f"across {len(sources)} source(s)."
+            )
+
+        self._result = artifacts
+        self.add_metric("NUM_TREES", len(artifacts))
+        self.add_metric("STORAGE_DIR", str(storage_dir))
+
+    async def close(self) -> None:
+        """Release resources (LLM client, etc.)."""