{"record":{"id":"5f2d821fed75facb","repo":"datawhalechina/hello-agents","slug":"unsupported-document-ingestion-mode-mode","errorCode":null,"errorMessage":"Unsupported document_ingestion_mode: {mode}","messagePattern":"Unsupported document_ingestion_mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/document_ingestion.py","lineNumber":301,"sourceCode":"\ndef ingest_input_document(\n    data_path: str | Path,\n    *,\n    run_dir: str | Path,\n    data_dir: str | Path,\n    logs_dir: str | Path,\n    mode: str = \"auto\",\n    max_pdf_pages: int = 20,\n    max_candidate_tables: int = 5,\n    selected_table_id: str | None = None,\n) -> IngestionResult:\n    started_at = time.perf_counter()\n    source_path = Path(data_path).resolve()\n    data_dir = Path(data_dir)\n    logs_dir = Path(logs_dir)\n    normalized_mode = str(mode or \"auto\").strip().lower()\n    if normalized_mode not in {\"auto\", \"text_only\", \"vision_fallback\"}:\n        raise ValueError(f\"Unsupported document_ingestion_mode: {mode}\")\n\n    log_path = logs_dir / \"document_ingestion.json\"\n    if source_path.suffix.lower() in SUPPORTED_TABULAR_SUFFIXES:\n        result = IngestionResult(\n            input_kind=\"tabular\",\n            status=\"not_needed\",\n            summary=\"输入文件已经是结构化表格，跳过文档解析阶段。\",\n            normalized_data_path=source_path,\n            duration_ms=_elapsed_ms(started_at),\n            log_path=log_path,\n            candidate_table_count=0,\n            pdf_multi_table_mode=False,\n        )\n        payload = {\n            \"input_kind\": result.input_kind,\n            \"status\": result.status,\n            \"summary\": result.summary,\n            \"normalized_data_path\": result.normalized_data_path.as_posix(),","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/document_ingestion.py#L283-L319","documentation":"`ingest_document` validates the `mode` argument (default 'auto') after strip+lowercase against {'auto', 'text_only', 'vision_fallback'} and raises ValueError on anything else. mode selects how the PDF is parsed: automatic text extraction, text-only, or vision-LLM fallback.","triggerScenarios":"Calling ingest_document with mode='text', 'vision', 'ocr', or similar partial names; passing None is coerced to 'auto' safely (`str(mode or 'auto')`), but wrong strings fail; mode names taken from an older/newer version of the API.","commonSituations":"Client code guessing mode names, config files copied from other projects, or docs drift after the mode set changed.","solutions":["Use exactly 'auto', 'text_only', or 'vision_fallback' (case-insensitive, whitespace trimmed).","Note 'vision_fallback' itself is accepted here but rejected later at document_ingestion.py:333 — prefer 'auto' or 'text_only'.","Omit mode entirely to get 'auto' behavior.","Check SUPPORTED_DOCUMENT_SUFFIXES / SUPPORTED_TABULAR_SUFFIXES handling before calling so the mode check is reached with a document file."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"INGESTION_MODES = {\"auto\", \"text_only\", \"vision_fallback\"}\n\ndef validate_ingestion_mode(mode: str | None) -> str:\n    normalized = str(mode or \"auto\").strip().lower()\n    if normalized not in INGESTION_MODES:\n        raise ValueError(f\"mode must be one of {sorted(INGESTION_MODES)}, got {mode!r}\")\n    return normalized","typeGuard":"from typing import Literal, TypeGuard\n\nIngestionMode = Literal[\"auto\", \"text_only\", \"vision_fallback\"]\n\ndef is_ingestion_mode(value: object) -> TypeGuard[IngestionMode]:\n    return isinstance(value, str) and value.strip().lower() in {\"auto\", \"text_only\", \"vision_fallback\"}","tryCatchPattern":"try:\n    result = ingest_document(path, data_dir, logs_dir, mode=mode)\nexcept ValueError as e:\n    if \"document_ingestion_mode\" in str(e):\n        result = ingest_document(path, data_dir, logs_dir, mode=\"auto\")\n    else:\n        raise","preventionTips":["Use the exact mode tokens; partial names like 'text' or 'vision' are rejected.","Remember 'vision_fallback' parses validation but is unimplemented (raises later) — stick to 'auto'/'text_only'.","Omit mode to accept the 'auto' default."],"tags":["validation","enum","valueerror","configuration","python"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}