Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

8.2 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""
ParserRouter: Route parsing requests between ParserRegistry and UnderstandingAPI.

Routing is controlled by ov.conf (OpenVikingConfig.parser_api).
"""

from pathlib import Path
from typing import Union
from urllib.parse import urlparse

from openviking.parse.accessors.base import LocalResource, SourceType
from openviking.parse.backend import ParserBackend, normalize_parser_backend
from openviking.parse.base import ParseResult
from openviking.parse.registry import ParserRegistry
from openviking_cli.exceptions import InvalidArgumentError
from openviking_cli.utils.logger import get_logger

logger = get_logger(__name__)


class ParserRouter:
    """
    ParserRouter: Route parsing to internal ParserRegistry or third-party UnderstandingAPI.

    Routing logic:
    1. Check feature flag and extension whitelist
    2. Default: ParserRegistry
    3. Matched extensions: UnderstandingAPI
    """

    def __init__(self, parser_registry: ParserRegistry):
        self._parser_registry = parser_registry
        self._understanding_api = None

    def understanding_api_enabled(self) -> bool:
        """Return whether the external parser is enabled."""
        try:
            from openviking_cli.utils.config.open_viking_config import get_openviking_config

            parser_api = getattr(get_openviking_config(), "parser_api", None)
        except Exception:
            return False
        return bool(parser_api and getattr(parser_api, "enable", False))

    def should_use_understanding_api(
        self,
        source: Union[str, Path, LocalResource],
        resolved_extension: str = "",
    ) -> bool:
        """
        Decide whether to use UnderstandingAPI.
        """
        # FeishuAccessor has already normalized proprietary content to Markdown.
        if (
            isinstance(source, LocalResource)
            and source.source_type == SourceType.FEISHU
            and source.meta.get("feishu_content_kind") != "file"
        ):
            return False

        try:
            from openviking_cli.utils.config.open_viking_config import get_openviking_config

            ov_config = get_openviking_config()
        except Exception:
            return False

        parser_api = getattr(ov_config, "parser_api", None)
        if not parser_api or not getattr(parser_api, "enable", False):
            return False

        source_path = self._extract_source_path(source)
        try:
            from openviking.parse.accessors.feishu_accessor import FeishuAccessor

            if FeishuAccessor._is_feishu_url(str(source_path)):
                return bool(getattr(parser_api, "enable_feishu_url", False))
        except Exception:
            pass

        ext = self._normalize_extension(resolved_extension) or self._extract_extension(source_path)
        extensions = getattr(parser_api, "extensions", None) or []
        return ext in extensions

    def should_use_understanding_directly(self, source: str, **kwargs) -> bool:
        parser_backend = normalize_parser_backend(kwargs.get("parser_backend"))
        if parser_backend is ParserBackend.INTERNAL:
            return False
        forced = parser_backend is ParserBackend.UNDERSTANDING
        return bool(
            (forced or self.should_use_understanding_api(source))
            and self._get_understanding_api().can_submit_url_directly(source, **kwargs)
        )

    @staticmethod
    def _normalize_extension(extension: str) -> str:
        return str(extension or "").lower().lstrip(".")

    def _extract_extension(self, source_path: Union[str, Path]) -> str:
        source = str(source_path)
        parsed = urlparse(source)
        if parsed.scheme.lower() in {"http", "https"} and parsed.netloc:
            source = parsed.path
        return Path(source).suffix.lower().lstrip(".")

    async def parse(self, source: Union[str, Path, "LocalResource"], **kwargs) -> ParseResult:
        """
        Parse with ParserRegistry or UnderstandingAPI based on the routing decision.
        """
        source_path = self._extract_source_path(source)

        parser_backend = normalize_parser_backend(kwargs.pop("parser_backend", None))

        normalized_feishu = (
            isinstance(source, LocalResource)
            and source.source_type == SourceType.FEISHU
            and source.meta.get("feishu_content_kind") != "file"
        )
        use_understanding = not normalized_feishu and (
            parser_backend is ParserBackend.UNDERSTANDING
            or (
                parser_backend is None
                and self.should_use_understanding_api(
                    source,
                    resolved_extension=str(kwargs.get("resolved_extension") or ""),
                )
            )
        )

        if use_understanding and kwargs.get("split_content") is False:
            raise InvalidArgumentError(
                "parse_mode='no_split' is not supported by the configured Understanding parser."
            )

        if use_understanding:
            if isinstance(source, LocalResource):
                kwargs["source_name"] = source.meta.get("resolved_name") or Path(source_path).name
                kwargs["resolved_extension"] = (
                    kwargs.get("resolved_extension")
                    or source.meta.get("resolved_extension")
                    or Path(source_path).suffix
                )
            display = source_path
            if isinstance(source_path, str) and source_path.startswith(("http://", "https://")):
                display = "<url>"
            else:
                try:
                    display = Path(source_path).name
                except Exception:
                    display = "<path>"
            logger.info(f"[ParserRouter] Using UnderstandingAPI for {display}")
            return await self._get_understanding_api().parse(str(source_path), **kwargs)
        else:
            try:
                display = Path(source_path).name
            except Exception:
                display = "<path>"
            logger.info(f"[ParserRouter] Using internal ParserRegistry for {display}")
            return await self._parser_registry.parse(source_path, **kwargs)

    async def submit(self, source: Union[str, Path, LocalResource], **kwargs) -> str:
        source_path = self._extract_source_path(source)
        if Path(source_path).is_file():
            source_name = (
                source.meta["resolved_name"]
                if isinstance(source, LocalResource)
                else kwargs.get("source_name")
            )
            return await self._get_understanding_api().submit_file(
                source_path,
                source_name=source_name,
                resolved_extension=(
                    source.meta["resolved_extension"]
                    if isinstance(source, LocalResource)
                    else kwargs.get("resolved_extension", "")
                ),
            )
        if not self.should_use_understanding_api(str(source_path)):
            raise ValueError("source is not routed to UnderstandingAPI")
        return await self._get_understanding_api().submit_url(str(source_path), **kwargs)

    async def upload_file(self, source: Union[str, Path, LocalResource]) -> str:
        """Upload a local source file and return only the external Files API file_id."""
        source_path = self._extract_source_path(source)
        source_name = source.meta["resolved_name"] if isinstance(source, LocalResource) else None
        return await self._get_understanding_api().upload_file(
            source_path,
            source_name=source_name,
            resolved_extension=(
                source.meta["resolved_extension"] if isinstance(source, LocalResource) else ""
            ),
        )

    def _extract_source_path(self, source: Union[str, Path, LocalResource]) -> Union[str, Path]:
        """Extract a filesystem path from the source."""
        if hasattr(source, "path"):
            return source.path
        return source

    def _get_understanding_api(self):
        if self._understanding_api is None:
            from openviking.parse.understanding_api import UnderstandingAPI

            self._understanding_api = UnderstandingAPI()
        return self._understanding_api