Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
import ast
import re
from typing import Any, Iterator
import httpx
from openviking.pyagfs.exceptions import (
AGFSAlreadyExistsError,
AGFSClientError,
AGFSConfigError,
AGFSConnectionError,
AGFSDirectoryNotEmptyError,
AGFSHTTPError,
AGFSInternalError,
AGFSInvalidOperationError,
AGFSInvalidPathError,
AGFSIoError,
AGFSIsADirectoryError,
AGFSMountPointNotFoundError,
AGFSNetworkError,
AGFSNotADirectoryError,
AGFSNotFoundError,
AGFSNotSupportedError,
AGFSPermissionDeniedError,
AGFSPluginError,
AGFSResourceExhaustedError,
AGFSSerializationError,
AGFSTimeoutError,
GitConcurrentCommitError,
)
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
from openviking.utils.exceptions import (
HTTP_STATUS_TO_ERROR_CODE,
AllCredentialsFailedError,
error_code_from_http_status,
)
from openviking_cli.exceptions import (
ConflictError,
FailedPreconditionError,
InternalError,
InvalidArgumentError,
InvalidURIError,
NotFoundError,
OpenVikingError,
PermissionDeniedError,
ResourceExhaustedError,
UnavailableError,
UnimplementedError,
)
_KNOWN_HTTP_STATUS_CODES = frozenset(HTTP_STATUS_TO_ERROR_CODE)
_UPSTREAM_ERROR_MARKERS = (
"api error",
"apierror",
"badrequesterror",
"authenticationerror",
"permissiondeniederror",
"ratelimiterror",
"httpstatuserror",
"openai",
"litellm",
"volcengine",
"ark",
"gemini",
"jina",
"voyage",
"cohere",
"dashscope",
"minimax",
"embedding",
"embedder",
"vlm",
"model",
"upstream",
"invalid api key",
"unauthorized",
"forbidden",
"too many requests",
"rate limit",
"quota",
"accountoverdue",
)
_API_KEY_CONFIG_MARKERS = (
"vlm configuration",
"embedding",
"embedder",
"provider",
"openai",
"azure",
"volcengine",
"jina",
"gemini",
"voyage",
"dashscope",
"minimax",
"cohere",
)
_HTTP_STATUS_PATTERNS = (
re.compile(r"\bHTTP\s*(\d{3})\b", re.IGNORECASE),
re.compile(r"\bstatus(?:\s+code)?\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
re.compile(r"\berror\s+code\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
)
def _iter_exception_chain(exc: Exception) -> Iterator[BaseException]:
seen: set[int] = set()
pending: list[BaseException] = [exc]
while pending:
current = pending.pop(0)
ident = id(current)
if ident in seen:
continue
seen.add(ident)
yield current
for nested in (getattr(current, "__cause__", None), getattr(current, "__context__", None)):
if isinstance(nested, BaseException) and id(nested) not in seen:
pending.append(nested)
def _coerce_http_status(value: Any) -> int | None:
if isinstance(value, bool) or value is None:
return None
try:
status = int(value)
except (TypeError, ValueError):
return None
if 100 <= status <= 599:
return status
return None
def _normalize_message(message: str) -> str:
return " ".join(str(message).split())
def _dedupe_messages(messages: list[str]) -> list[str]:
result: list[str] = []
for message in messages:
normalized = _normalize_message(message)
if not normalized:
continue
if any(normalized == existing or normalized in existing for existing in result):
continue
result = [existing for existing in result if existing not in normalized]
result.append(normalized)
return result
def _exception_chain_text(exc: Exception) -> str:
return "\n".join(_dedupe_messages([str(item) for item in _iter_exception_chain(exc)]))
def _trim_message(message: str, limit: int = 500) -> str:
normalized = _normalize_message(message)
if len(normalized) <= limit:
return normalized
return normalized[: limit - 3] + "..."
def _iter_braced_segments(text: str) -> Iterator[str]:
start: int | None = None
depth = 0
quote: str | None = None
escaped = False
for index, char in enumerate(text):
if quote is not None:
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == quote:
quote = None
continue
if char in {'"', "'"}:
quote = char
elif char == "{":
if depth == 0:
start = index
depth += 1
elif char == "}" and depth:
depth -= 1
if depth == 0 and start is not None:
yield text[start : index + 1]
start = None
def _extract_payload_message(payload: Any) -> str | None:
if not isinstance(payload, dict):
return None
error = payload.get("error")
if isinstance(error, dict):
message = error.get("message")
if isinstance(message, str) and message.strip():
return message.strip()
message = payload.get("message")
if isinstance(message, str) and message.strip():
return message.strip()
return None
def _extract_provider_error_message(text: str) -> str | None:
for segment in _iter_braced_segments(text):
try:
payload = ast.literal_eval(segment)
except (SyntaxError, ValueError):
continue
message = _extract_payload_message(payload)
if message:
return message
return None
def _upstream_detail_message(exc: Exception) -> str:
text = _exception_chain_text(exc)
return _extract_provider_error_message(text) or text
def _looks_like_upstream_model_error(exc: Exception) -> bool:
text = _exception_chain_text(exc).lower()
return any(marker in text for marker in _UPSTREAM_ERROR_MARKERS)
def _is_model_api_key_configuration_error(exc: Exception) -> bool:
text = _exception_chain_text(exc).lower()
if "api_key" not in text and "api key" not in text:
return False
if "invalid api key" in text or "unauthorized" in text:
return False
missing_key_phrases = (
"requires 'api_key'",
"requires api_key",
"api_key is required",
"api key is required",
"requires 'api key'",
)
if not any(phrase in text for phrase in missing_key_phrases):
return False
if any(marker in text for marker in _API_KEY_CONFIG_MARKERS):
return True
return text.strip() in (
"api_key is required",
"api key is required",
)
def _extract_structured_http_status(
exc: Exception,
) -> tuple[int, BaseException] | tuple[None, None]:
for item in _iter_exception_chain(exc):
for attr in ("status_code", "http_status", "status"):
status = _coerce_http_status(getattr(item, attr, None))
if status is not None:
return status, item
code = getattr(item, "code", None)
if not isinstance(code, str):
status = _coerce_http_status(code)
if status is not None:
return status, item
response = getattr(item, "response", None)
if response is not None:
for attr in ("status_code", "status"):
status = _coerce_http_status(getattr(response, attr, None))
if status is not None:
return status, item
return None, None
def _extract_text_http_status(exc: Exception) -> int | None:
if not _looks_like_upstream_model_error(exc):
return None
text = _exception_chain_text(exc)
for pattern in _HTTP_STATUS_PATTERNS:
match = pattern.search(text)
if match:
status = _coerce_http_status(match.group(1))
if status is not None:
return status
for status in _KNOWN_HTTP_STATUS_CODES:
if re.search(rf"\b{status}\b", text):
return status
return None
def _extract_vlm_info(exc: Exception | None) -> tuple[str | None, str | None]:
"""Extract model name and api_base from the exception chain, if annotated."""
if exc is None:
return None, None
for item in _iter_exception_chain(exc):
model = getattr(item, "_vlm_model", None)
api_base = getattr(item, "_vlm_api_base", None)
if model or api_base:
return model, api_base
return None, None
def _build_upstream_error(
*,
code: str,
message: str,
status: int | None = None,
source: BaseException | None = None,
vlm_context: BaseException | None = None,
) -> OpenVikingError:
labels = {
"INVALID_ARGUMENT": "Upstream model request was rejected",
"UNAUTHENTICATED": "Upstream model authentication failed",
"PERMISSION_DENIED": "Upstream model permission denied",
"NOT_FOUND": "Upstream model resource not found",
"CONFLICT": "Upstream model request conflicted",
"RESOURCE_EXHAUSTED": "Upstream model quota or rate limit exceeded",
"DEADLINE_EXCEEDED": "Upstream model request timed out",
"UNAVAILABLE": "Upstream model service unavailable",
}
detail_message = _trim_message(message)
display = labels.get(code, "Upstream model error")
if status is not None:
display = f"{display} (HTTP {status})"
if detail_message:
display = f"{display}: {detail_message}"
details: dict[str, Any] = {"upstream_message": detail_message}
if status is not None:
details["upstream_status_code"] = status
if source is not None:
details["upstream_error_type"] = type(source).__name__
# Search for VLM model/api_base annotations. vlm_context is the outermost
# exception (where failover wrappers attach the annotation); source may be
# an inner exception from the chain.
vlm_model, vlm_api_base = _extract_vlm_info(vlm_context)
if not vlm_model and not vlm_api_base:
vlm_model, vlm_api_base = _extract_vlm_info(source)
if vlm_model:
details["vlm_model"] = vlm_model
display = f"{display}\n Model: {vlm_model}"
if vlm_api_base:
details["vlm_api_base"] = vlm_api_base
display = f"{display}\n API base: {vlm_api_base}"
return OpenVikingError(display, code=code, details=details)
def _map_upstream_api_error(exc: Exception) -> OpenVikingError | None:
for item in _iter_exception_chain(exc):
if isinstance(item, AllCredentialsFailedError):
failures = [_map_upstream_api_error(error) for _, _, error, _ in item.errors]
codes = {failure.code if failure is not None else "INTERNAL" for failure in failures}
# A mixed failure has no single accurate status. Do not infer one
# from whichever credential happens to appear first in the message.
if len(codes) != 1 or "INTERNAL" in codes:
return InternalError(str(exc))
return _build_upstream_error(
code=codes.pop(),
message=_upstream_detail_message(exc),
source=item,
vlm_context=exc,
)
if _is_model_api_key_configuration_error(exc):
return FailedPreconditionError(
"Model provider API key is not configured",
details={"reason": _trim_message(_exception_chain_text(exc))},
)
status, source = _extract_structured_http_status(exc)
if status is None:
for item in _iter_exception_chain(exc):
if isinstance(item, httpx.TimeoutException):
code = "DEADLINE_EXCEEDED"
elif isinstance(item, (httpx.NetworkError, httpx.RemoteProtocolError)):
code = "UNAVAILABLE"
else:
continue
return _build_upstream_error(
code=code,
message=_upstream_detail_message(exc),
source=item,
vlm_context=exc,
)
status = _extract_text_http_status(exc)
if status is not None:
code = error_code_from_http_status(status, default="UNKNOWN")
if code == "UNKNOWN":
return None
return _build_upstream_error(
code=code,
status=status,
source=source,
message=_upstream_detail_message(exc),
vlm_context=exc,
)
if not _looks_like_upstream_model_error(exc):
return None
text = _exception_chain_text(exc)
lowered = text.lower()
if "invalid api key" in lowered or "unauthorized" in lowered:
return _build_upstream_error(
code="UNAUTHENTICATED",
message=_upstream_detail_message(exc),
source=exc,
vlm_context=exc,
)
if "forbidden" in lowered:
return _build_upstream_error(
code="PERMISSION_DENIED",
message=_upstream_detail_message(exc),
source=exc,
vlm_context=exc,
)
if any(
marker in lowered
for marker in (
"too many requests",
"rate limit",
"ratelimit",
"quota",
"accountoverdue",
"resource exhausted",
)
):
return _build_upstream_error(
code="RESOURCE_EXHAUSTED",
message=_upstream_detail_message(exc),
source=exc,
vlm_context=exc,
)
return None
def is_not_found_error(exc: Exception) -> bool:
if isinstance(exc, FileNotFoundError):
return True
if isinstance(exc, AGFSNotFoundError):
return True
if isinstance(exc, AGFSHTTPError) and exc.status_code == 404:
return True
message = str(exc).lower()
return any(
marker in message
for marker in (
"not found",
"no such file",
"does not exist",
)
)
def is_invalid_uri_error(exc: Exception) -> bool:
message = str(exc).lower()
return any(
marker in message
for marker in (
"invalid uri",
"invalid viking uri",
"invalid viking://",
)
)
def _not_found_error(resource: str | None, resource_type: str) -> NotFoundError:
return NotFoundError(resource or "", resource_type)
def _resource_details(resource: str | None) -> dict[str, str] | None:
return {"resource": resource} if resource else None
def _file_directory_details(resource: str | None) -> dict[str, str]:
details = {"expected": "file", "actual": "directory"}
if resource:
details["resource"] = resource
return details
def map_exception(
exc: Exception,
*,
resource: str | None = None,
resource_type: str = "resource",
) -> OpenVikingError | None:
if isinstance(exc, OpenVikingError):
return exc
if isinstance(exc, ResourceBusyError):
details: dict[str, Any] = {
"resource": exc.uri or resource,
"uri": exc.uri or resource,
"conflict_type": exc.conflict_type,
"retryable": exc.retryable,
}
return OpenVikingError(str(exc), code="CONFLICT", details=details)
if isinstance(exc, LockAcquisitionError):
details = {
"resource": resource,
"uri": resource,
"conflict_type": "path_busy",
"retryable": True,
}
return OpenVikingError(str(exc), code="CONFLICT", details=details)
if isinstance(exc, GitConcurrentCommitError):
details = {
"conflict_type": "git_ref_cas",
"retryable": True,
}
return OpenVikingError(
str(exc) or "concurrent git commit", code="CONFLICT", details=details
)
if isinstance(exc, PermissionError):
return PermissionDeniedError(str(exc), resource=resource)
if isinstance(exc, FileNotFoundError):
return _not_found_error(resource, resource_type)
if isinstance(exc, ValueError):
if _is_model_api_key_configuration_error(exc):
return _map_upstream_api_error(exc)
message = str(exc)
if is_invalid_uri_error(exc):
return InvalidURIError(resource or message, message)
return InvalidArgumentError(message, details={"resource": resource} if resource else None)
if isinstance(exc, (AGFSConnectionError, AGFSTimeoutError)):
return UnavailableError("storage backend", reason=str(exc))
if isinstance(exc, AGFSHTTPError):
if exc.status_code == 404 or is_not_found_error(exc):
return _not_found_error(resource, resource_type)
if exc.status_code == 403:
return PermissionDeniedError(str(exc), resource=resource)
if exc.status_code == 409:
return ConflictError(str(exc), resource=resource)
if exc.status_code == 400:
return InvalidArgumentError(
str(exc), details={"resource": resource} if resource else None
)
if exc.status_code in {500, 502, 503, 504}:
return UnavailableError("storage backend", reason=str(exc))
if isinstance(exc, AGFSPermissionDeniedError):
return PermissionDeniedError(str(exc), resource=resource)
if isinstance(exc, AGFSAlreadyExistsError):
return ConflictError(str(exc), resource=resource)
if isinstance(exc, AGFSNotSupportedError):
return UnimplementedError(str(exc), details=_resource_details(resource))
if isinstance(exc, AGFSInvalidPathError):
message = str(exc)
return InvalidURIError(resource or message, message)
if isinstance(exc, (AGFSNotADirectoryError, NotADirectoryError)):
return InvalidArgumentError(str(exc), details=_resource_details(resource))
if isinstance(exc, (AGFSIsADirectoryError, IsADirectoryError)):
return InvalidArgumentError(str(exc), details=_file_directory_details(resource))
if isinstance(exc, AGFSDirectoryNotEmptyError):
return InvalidArgumentError(str(exc), details=_resource_details(resource))
if isinstance(exc, AGFSResourceExhaustedError):
return ResourceExhaustedError(str(exc), details=_resource_details(resource))
if isinstance(exc, AGFSInvalidOperationError):
return InvalidArgumentError(str(exc), details=_resource_details(resource))
if isinstance(exc, AGFSInternalError):
return InternalError(str(exc))
if isinstance(
exc,
(
AGFSConfigError,
AGFSIoError,
AGFSMountPointNotFoundError,
AGFSNetworkError,
AGFSSerializationError,
),
):
return UnavailableError("storage backend", reason=str(exc))
if isinstance(exc, AGFSClientError):
message = str(exc)
if is_not_found_error(exc):
return _not_found_error(resource, resource_type)
if is_invalid_uri_error(exc):
return InvalidURIError(resource or message, message)
lowered = message.lower()
if "not a directory" in lowered:
return InvalidArgumentError(message, details=_resource_details(resource))
if "is a directory" in lowered:
return InvalidArgumentError(message, details=_resource_details(resource))
if "directory not empty" in lowered:
return InvalidArgumentError(message, details=_resource_details(resource))
if "permission denied" in lowered:
return PermissionDeniedError(message, resource=resource)
if "already exists" in lowered:
return ConflictError(message, resource=resource)
if (
"invalid operation" in lowered
or "regex parse error" in lowered
or "invalid regular expression" in lowered
):
return InvalidArgumentError(message, details=_resource_details(resource))
if (
isinstance(exc, AGFSPluginError)
or "timeout" in lowered
or "connection refused" in lowered
):
return UnavailableError("storage backend", reason=message)
upstream_mapped = _map_upstream_api_error(exc)
if upstream_mapped is not None:
return upstream_mapped
message = str(exc)
lowered = message.lower()
if is_not_found_error(exc):
return _not_found_error(resource, resource_type)
if is_invalid_uri_error(exc):
return InvalidURIError(resource or message, message)
if "permission denied" in lowered or "access denied" in lowered:
return PermissionDeniedError(message, resource=resource)
if "timeout" in lowered or "connection refused" in lowered:
return UnavailableError("storage backend", reason=message)
return None