Skip to content

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

7.6 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
from typing import Annotated, Literal
from urllib.parse import urlsplit

from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator

ProtocolName = Literal["anthropic", "chat", "responses"]
KEY_PLACEHOLDER = "{api_key}"
# Largest integer JSON readers, Studio included, hold exactly.
JSON_INT_MAX = 2**53

# OpenViking MCP tools that change data; new profiles offer only the read-only ones.
WRITE_TOOLS = (
    "remember",
    "write",
    "edit",
    "add_resource",
    "add_skill",
    "forget",
    "set_acl",
    "cancel_watch",
)


def validation_detail(error: ValidationError) -> str:
    """Each problem with the field it concerns, without echoing submitted values."""
    return "; ".join(
        ".".join(map(str, item["loc"])) + ": " + item["msg"] if item["loc"] else item["msg"]
        for item in error.errors(include_input=False, include_context=False)
    )


class CaptureReset(BaseModel):
    session: str = Field(min_length=1, max_length=128)
    protocol: ProtocolName


class Policy(BaseModel):
    # Session roots keep a copy as JSON, so numbers must be finite and integers exact there.
    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
    name: str = "Default"
    recall: bool = True
    profile: bool = True
    profile_max_tokens: int = Field(default=4000, ge=0, le=32000)
    capture: bool = True
    context_types: list[str] = Field(default_factory=lambda: ["memory", "resource", "skill"])
    quotas: dict[str, Annotated[int, Field(ge=0, le=JSON_INT_MAX)]] = Field(default_factory=dict)
    max_tokens: int = Field(default=1600, ge=64, le=32000)
    session_max_tokens: int = Field(default=30000, ge=0, le=JSON_INT_MAX)
    score_threshold: float = Field(default=0.35, ge=0, le=1)
    recall_timeout: float = Field(default=2, gt=0, le=30)
    query_max_chars: int = Field(default=8000, ge=3, le=32000)
    # Start each turn's reply with a summary of what OpenViking injected; the model never sees it.
    show_recall: bool = False
    commit_tokens: int = Field(default=20000, ge=1, le=JSON_INT_MAX)
    keep_recent_messages: int = Field(default=10, ge=0, le=1000)
    idle_seconds: float = Field(default=600, ge=1)
    compaction: bool = True
    compaction_threshold: float = Field(default=0.9, ge=0.5, le=0.98)
    summary_max_tokens: int = Field(default=8000, ge=1000, le=32000)
    # Fallback when the upstream lists no window for the model; 1M is assumed when unset.
    context_window: int | None = Field(default=None, ge=1024, le=JSON_INT_MAX)
    gateway_tools: bool = True
    # MCP tool names; tools the server adds later stay enabled.
    disabled_tools: list[str] = Field(default_factory=lambda: list(WRITE_TOOLS))
    # None means no limit, as in an agent harness's own tool loop.
    tool_max_rounds: int | None = Field(default=None, ge=1, le=JSON_INT_MAX)
    tool_timeout_seconds: float = Field(default=30, gt=0, le=120)
    tool_result_bytes: int = Field(default=65536, ge=1024, le=1048576)
    tool_total_seconds: float | None = Field(default=None, gt=0)
    tool_total_tokens: int | None = Field(default=None, ge=1024, le=JSON_INT_MAX)
    show_tool_calls: bool = True
    # Experimental: the model starts fresh context windows itself (needs gateway tools).
    agent_windows: bool = False
    window_soft_ratio: float = Field(default=0.7, ge=0.3, le=0.95)
    window_hard_ratio: float = Field(default=0.85, ge=0.4, le=0.97)
    # Clients may override the other fields per conversation with X-OpenViking-Context.
    client_overrides: bool = True

    @model_validator(mode="before")
    @classmethod
    def drop_storage_metadata(cls, value):
        """Accept a policy as the management store returns it.

        ``id`` and ``revision`` are storage metadata, not settings; saved
        policies and the copies frozen into session roots carry them.
        """
        if isinstance(value, dict):
            return {key: item for key, item in value.items() if key not in {"id", "revision"}}
        return value

    @model_validator(mode="after")
    def check_window_ratios(self):
        if self.window_soft_ratio >= self.window_hard_ratio:
            raise ValueError("window_soft_ratio must be below window_hard_ratio")
        return self


class Upstream(BaseModel):
    model_config = ConfigDict(extra="forbid")
    name: str
    protocol: ProtocolName
    base_url: str
    append_endpoint_path: bool = True
    api_key: str = ""
    key_header: Literal["authorization", "api-key", "x-api-key"] = "authorization"
    auth_mode: Literal["managed", "passthrough"] = "managed"
    headers: dict[str, str] = Field(default_factory=dict)
    models: list[str] = Field(default_factory=list)
    aliases: dict[str, str] = Field(default_factory=dict)
    priority: int = 0
    enabled: bool = True
    vendor: Literal["generic", "anthropic", "openai", "deepseek", "ark", "byteplus"] = "generic"
    allow_gateway_tools: bool = True
    # Send back the reasoning a client dropped from replies the gateway relayed.
    # None follows the vendor: on for DeepSeek, Ark and BytePlus, off otherwise.
    replay_reasoning: bool | None = None
    coding_plan: bool = False
    allow_coding_plan: bool = False
    cache_min_tokens: int = Field(default=1024, ge=0)
    context_windows: dict[str, int] = Field(default_factory=dict)

    @field_validator("context_windows")
    @classmethod
    def validate_windows(cls, value: dict[str, int]) -> dict[str, int]:
        if any(size < 1024 for size in value.values()):
            raise ValueError("model context windows must be at least 1024 tokens")
        return value

    @field_validator("base_url")
    @classmethod
    def validate_url(cls, value: str) -> str:
        parsed = urlsplit(value)
        if (
            parsed.scheme not in {"http", "https"}
            or not parsed.hostname
            or parsed.username
            or parsed.password
            or "#" in value
        ):
            raise ValueError("expected an HTTP(S) upstream URL without credentials or fragment")
        rest = value.replace(KEY_PLACEHOLDER, "")
        if "{" in rest or "}" in rest or "{" in parsed.netloc:
            raise ValueError("base_url may only use the {api_key} placeholder, outside the host")
        base, mark, query = value.partition("?")
        return base.rstrip("/") + mark + query

    @model_validator(mode="after")
    def validate_protocol_base(self):
        if (
            self.append_endpoint_path
            and self.protocol == "anthropic"
            and urlsplit(self.base_url).path.endswith("/v1")
        ):
            raise ValueError(
                "Anthropic base_url must not end in /v1; the gateway appends /v1/messages"
            )
        return self

    @field_validator("headers")
    @classmethod
    def validate_headers(cls, value: dict[str, str]) -> dict[str, str]:
        for key, item in value.items():
            if (
                "\r" in key + item
                or "\n" in key + item
                or key.lower() in {"host", "content-length", "transfer-encoding", "connection"}
            ):
                raise ValueError("invalid upstream header")
        return value


class UpstreamTestRequest(BaseModel):
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
    model: str | None = Field(default=None, min_length=1, max_length=256)


class KeyRequest(BaseModel):
    model_config = ConfigDict(extra="forbid")
    name: str
    openviking_key: str = ""
    user_id: str | None = None
    policy_id: str
    upstream_ids: list[str] = Field(min_length=1)
    models: list[str] = Field(default_factory=list)