Skip to content

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

7.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Client for the external Connector service (knowledge-base doc/add pipeline)."""

from __future__ import annotations

from typing import Any, Dict, Optional

import httpx

from openviking_cli.exceptions import InternalError
from openviking_cli.utils import get_logger

logger = get_logger(__name__)


def _unwrap_connector_response(payload: Any) -> Dict[str, Any]:
    """Validate the Connector business envelope and return its data object.

    The inner APIs return HTTP 200 for both success and business errors, so
    ``raise_for_status`` alone is insufficient. Flat dictionaries remain
    accepted for compatibility with Connector deployments that do not wrap
    responses in ``code/data``.
    """
    if not isinstance(payload, dict):
        raise InternalError("Connector returned a non-object JSON response")

    if "code" not in payload and "data" not in payload:
        return payload

    code = payload.get("code")
    if code not in (0, "0"):
        message = payload.get("message") or "unknown Connector error"
        raise InternalError(f"Connector request failed (code={code}): {message}")

    data = payload.get("data")
    if not isinstance(data, dict):
        raise InternalError("Connector success response contains no data object")
    return data


class ConnectorClient:
    """Wraps the Connector service's doc/add and task/info APIs."""

    def __init__(self, doc_add_url: str, task_info_url: str, account_id: str = "") -> None:
        self._doc_add_url = doc_add_url
        self._task_info_url = task_info_url
        self._headers = {"V-Account-Id": account_id} if account_id else {}

    def _request_headers(self, api_key: str) -> Dict[str, str]:
        """Build the headers required by the inner Connector endpoints."""
        headers = dict(self._headers)
        token = api_key if api_key.lower().startswith("bearer ") else f"Bearer {api_key}"
        headers["Authorization"] = token
        return headers

    def get_oauth_access_token(
        self, auth_url: str, api_key: str, reference: Dict[str, str]
    ) -> Dict[str, Any]:
        """Read a centrally managed token from synchronous Feishu worker threads."""
        try:
            with httpx.Client(timeout=10.0) as client:
                rsp = client.post(auth_url, json=reference, headers={"X-API-Key": api_key})
            rsp.raise_for_status()
            return _unwrap_connector_response(rsp.json())
        except (httpx.HTTPError, ValueError, InternalError):
            # Neither remote business messages nor response bodies may expose credentials.
            raise InternalError("External OAuth access token request failed.") from None

    def resolve_connector_credential(
        self, resolve_url: str, api_key: str, reference: Dict[str, Any]
    ) -> Dict[str, Any]:
        """Resolve centrally managed Connector credentials for a credential reference.

        Shares the synchronous access-token transport: the unified resolver is
        reached from both async imports and synchronous watch replays, returns
        the freshly assembled ``auth_config`` for this call only, and never
        exposes remote business messages or response bodies that may carry
        credentials.
        """
        try:
            with httpx.Client(timeout=10.0) as client:
                rsp = client.post(resolve_url, json=reference, headers={"X-API-Key": api_key})
            rsp.raise_for_status()
            return _unwrap_connector_response(rsp.json())
        except (httpx.HTTPError, ValueError, InternalError):
            raise InternalError("External connector credential resolution failed.") from None

    async def submit_doc_add(
        self,
        add_type: str,
        api_key: str,
        *,
        tos_path: Optional[str] = None,
        to: Optional[str] = None,
        include_child: bool = True,
        param_config: Optional[Dict[str, Any]] = None,
        auth_config: Optional[Dict[str, Any]] = None,
        stream_states: Optional[Dict[str, Any]] = None,
        extra_params: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Submit a document import job via the configured doc/add endpoint.

        ``to`` is the exact OpenViking file or directory target. Source-specific
        settings stay inside ``param_config``; source credentials stay inside
        ``auth_config``, which Connector and plugin request logs redact, and
        must never be merged into ``param_config``. The incoming OpenViking
        HTTP body may still be captured when unsafe body dumping is enabled.

        Returns the Connector response dict (contains task key / id on success).
        """
        payload: Dict[str, Any] = {
            "add_type": add_type,
            "backend": "ov",
            "include_child": include_child,
        }
        if tos_path is not None:
            payload["tos_path"] = tos_path
        if to is not None:
            payload["to"] = to
        if param_config:
            payload["param_config"] = param_config
        if auth_config:
            payload["auth_config"] = auth_config
        if stream_states is not None:
            payload["stream_states"] = stream_states
        if extra_params:
            # Authentication belongs exclusively in the Authorization header.
            payload.update({key: value for key, value in extra_params.items() if key != "api_key"})

        # Log shape only: param_config values and auth_config may carry source credentials.
        logger.info(
            "[ConnectorClient] doc/add: add_type=%s to=%s include_child=%s param_config_keys=%s "
            "has_auth_config=%s has_stream_states=%s",
            add_type,
            to,
            include_child,
            sorted(param_config or {}),
            bool(auth_config),
            stream_states is not None,
        )
        async with httpx.AsyncClient(timeout=30.0) as client:
            rsp = await client.post(
                self._doc_add_url,
                json=payload,
                headers=self._request_headers(api_key),
            )
        rsp.raise_for_status()
        return _unwrap_connector_response(rsp.json())

    async def get_task_info(self, task_key: str, api_key: str) -> Dict[str, Any]:
        """Query task status via the configured task/info endpoint.

        Connector task statuses: pending / running / succeeded / failed / cancelled.
        """
        async with httpx.AsyncClient(timeout=10.0) as client:
            rsp = await client.post(
                self._task_info_url,
                json={"TaskKey": task_key},
                headers=self._request_headers(api_key),
            )
        rsp.raise_for_status()
        data = _unwrap_connector_response(rsp.json())
        task = data.get("Task") or data.get("task")
        if task is None:
            return data
        if not isinstance(task, dict):
            raise InternalError("Connector task response contains an invalid Task object")
        task = dict(task)
        for key in ("StreamStates", "stream_states"):
            if key in data:
                task[key] = data[key]
        return task