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
"""Shared helpers for config validation and error formatting."""
import difflib
import logging
from collections.abc import Mapping
from typing import Any, Optional, get_args, get_origin
from pydantic import BaseModel, ValidationError
DEFAULT_SERVICE_NAME = "openviking-server"
def suggest_closest_field(field_name: str, valid_fields: set[str]) -> Optional[str]:
"""Return the closest matching field name when it is similar enough."""
close_matches = difflib.get_close_matches(field_name, sorted(valid_fields), n=1, cutoff=0.6)
if close_matches:
return close_matches[0]
return None
def _unwrap_model_type(annotation: Any) -> Optional[type[BaseModel]]:
if isinstance(annotation, type) and issubclass(annotation, BaseModel):
return annotation
origin = get_origin(annotation)
if origin is None:
return None
for arg in get_args(annotation):
model_type = _unwrap_model_type(arg)
if model_type is not None:
return model_type
return None
def _get_model_at_path(
root_model: type[BaseModel], path: tuple[Any, ...]
) -> Optional[type[BaseModel]]:
current_model = root_model
for part in path:
field = current_model.model_fields.get(str(part))
if field is None:
return None
next_model = _unwrap_model_type(field.annotation)
if next_model is None:
return None
current_model = next_model
return current_model
def warn_unknown_fields(
*,
data: Mapping[str, Any],
valid_fields: set[str],
logger: logging.Logger,
path_prefix: str = "",
) -> None:
"""Warn about keys the owner of one config section does not declare.
Unknown fields stay ignored so legacy configuration keeps loading; the
warning keeps the mismatch visible to whoever wrote the file. Only field
names are logged, never values.
"""
messages = []
for key in data:
if key in valid_fields:
continue
field_path = f"{path_prefix}.{key}" if path_prefix else key
# Config files are JSON, but from_dict() is also called programmatically;
# a diagnostic must never be the reason loading fails.
messages.append(f"Ignoring unknown config field '{field_path!s}'")
if messages:
logger.warning("%s", "\n".join(messages))
def _child_model_type(annotation: Any) -> Optional[type[BaseModel]]:
"""Return the model nested values must validate against, when unambiguous."""
if isinstance(annotation, type) and issubclass(annotation, BaseModel):
return annotation
args = get_args(annotation)
if not args or any(get_origin(arg) in (dict, Mapping) for arg in args):
return None
models = {model for model in (_unwrap_model_type(arg) for arg in args) if model is not None}
if len(models) == 1:
return models.pop()
return None
def warn_unknown_config_fields(
*,
data: Mapping[str, Any],
model: type[BaseModel],
logger: logging.Logger,
path_prefix: str = "",
extra_valid_fields: Optional[set[str]] = None,
) -> None:
"""Warn about config keys the model does not declare, recursing into sub-models.
``extra_valid_fields`` lists keys consumed by another owner (for example the
``server`` section) so they are not reported as unknown.
"""
warn_unknown_fields(
data=data,
valid_fields=set(model.model_fields)
| {field.alias for field in model.model_fields.values() if isinstance(field.alias, str)}
| (extra_valid_fields or set()),
logger=logger,
path_prefix=path_prefix,
)
for key, value in data.items():
field = model.model_fields.get(key)
if field is None:
continue
child_model = _child_model_type(field.annotation)
if child_model is None:
continue
child_prefix = f"{path_prefix}.{key}" if path_prefix else key
is_sequence = isinstance(value, (list, tuple))
for index, item in enumerate(value if is_sequence else (value,)):
if not isinstance(item, Mapping):
continue
warn_unknown_config_fields(
data=item,
model=child_model,
logger=logger,
path_prefix=f"{child_prefix}[{index}]" if is_sequence else child_prefix,
)
def normalize_service_name(value: Any, field_name: str = "service_name") -> str:
"""Return a validated service name for cache namespaces and OTel defaults."""
if not isinstance(value, str):
raise ValueError(f"{field_name} must be a string")
normalized = value.strip()
if not normalized:
raise ValueError(f"{field_name} must not be empty")
if any(not (char.isascii() and (char.isalnum() or char in "._-")) for char in normalized):
raise ValueError(f"{field_name} must contain only ASCII letters, digits, '.', '_' or '-'")
return normalized
def format_validation_error(
*,
root_model: type[BaseModel],
error: ValidationError,
path_prefix: str = "",
) -> str:
"""Render a pydantic ValidationError as a concise config error message."""
formatted_errors = []
for item in error.errors():
loc = tuple(item.get("loc", ()))
path_parts = [path_prefix] if path_prefix else []
path_parts.extend(str(part) for part in loc)
path = ".".join(path_parts)
error_type = item.get("type", "")
if error_type == "extra_forbidden" and loc:
parent_model = _get_model_at_path(root_model, loc[:-1])
invalid_field = str(loc[-1])
message = f"Unknown config field '{path}'" if path else "Unknown config field"
if parent_model is not None:
suggestion = suggest_closest_field(
invalid_field,
set(parent_model.model_fields.keys()),
)
if suggestion:
suggested_parts = [path_prefix] if path_prefix else []
suggested_parts.extend(str(part) for part in loc[:-1])
suggested_parts.append(suggestion)
message += f" (did you mean '{'.'.join(suggested_parts)}'?)"
formatted_errors.append(message)
continue
if path:
formatted_errors.append(
f"Invalid value for '{path}': {item.get('msg', 'validation failed')}"
)
else:
formatted_errors.append(f"Invalid config value: {item.get('msg', 'validation failed')}")
return "\n".join(formatted_errors)