zylon-ai/private-gpt · error · ValueError

Tabular data analysis tool requires an ingested artifact con

Error message

Tabular data analysis tool requires an ingested artifact context.

What it means

Raised by the TabularDataProcessor when the tabular data analysis tool (TABULAR_DATA_ANALYSIS) is present in a request but its tool context holds no IngestedArtifact. The tool is built from an ingested corpus's context_filter, so without one it cannot be resolved.

Source

Thrown at private_gpt/components/tools/processors/tabular_data_processor.py:47

    @inject
    def __init__(self, tabular_data_tool_builder: TabularDataToolBuilder) -> None:
        self._builder = tabular_data_tool_builder

    async def intercept(self, request: ResolvedChatRequest) -> bool:
        for tool in request.tool_config.tools:
            if not _tool_matches(
                tool, TABULAR_DATA_ANALYSIS
            ) or not _is_unresolved_tool(tool):
                continue

            tool_context = _get_tool_context(request, tool)
            ingested_artifacts = (
                [a for a in tool_context if isinstance(a, IngestedArtifact)]
                if tool_context
                else None
            )
            if not ingested_artifacts:
                raise ValueError(
                    "Tabular data analysis tool requires an ingested artifact context.",
                )
            if len(ingested_artifacts) > 1:
                raise ValueError("Only one ingested context is supported.")

            try:
                resolved = await self._builder.build_tool(
                    model_id=request.system.model,
                    name=tool.name or TABULAR_DATA_ANALYSIS,
                    type=tool.type or TABULAR_DATA_ANALYSIS + "_v1",
                    context_filter=ingested_artifacts[0].context_filter,
                    validate=request.tool_config.validation_mode,
                    blob_visibility=request.system.blob_visibility,
                )
            except ImportError as e:
                logger.warning("Tabular tool unavailable: %s", e)
                raise RuntimeError(_PANDASAI_NOT_INSTALLED_MSG) from e

View on GitHub (pinned to 4a030776a3)

Solutions

Attach exactly one IngestedArtifact (the ingested tabular corpus) to the tabular tool's context
Or remove the tabular data analysis tool when no ingested data is in scope
Verify the data was ingested successfully and its context_filter is available

Example fix

# before
tools=[ToolConfig(name=TABULAR_DATA_ANALYSIS)]
# after
tools=[
    ToolConfig(
        name=TABULAR_DATA_ANALYSIS,
        context=[IngestedArtifact(context_filter=ContextFilter(filters=...))],
    )
]

Defensive patterns

Strategy: validation

Validate before calling

ingested = [a for a in (tool_context or []) if isinstance(a, IngestedArtifact)]
if not ingested:
    # exclude TABULAR_DATA_ANALYSIS from the request or attach an IngestedArtifact

Type guard

def is_ingested_artifact(ctx: object) -> bool:
    return isinstance(ctx, IngestedArtifact)

Try / catch

try:
    resp = await client.chat(request)
except ValueError as e:
    if "requires an ingested artifact context" in str(e):
        # attach the ingested tabular corpus and resend
        raise

Prevention

Offer the tabular tool only after a dataset has been selected/ingested
Validate tool-to-artifact requirements before submitting multi-tool requests
Check the PandasAI extra is installed wherever the tabular tool is enabled

When it happens

Trigger: Enabling the tabular data analysis tool while tool_context is None/empty or only contains non-ingested artifact types.

Common situations: Tool catalogs enabling every tool by default; ingesting CSV/spreadsheet data but not passing the corresponding IngestedArtifact; artifact attached to a different tool entry in a multi-tool request.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/87b9db30983dbf9f. Report an issue: GitHub.