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
"""Content endpoints for OpenViking HTTP Server."""
from typing import Literal, Optional
from urllib.parse import quote
from fastapi import APIRouter, Body, Depends, HTTPException, Query, Request
from fastapi.responses import Response as FastAPIResponse
from pydantic import BaseModel, ConfigDict, Field, model_validator
from openviking.core.namespace import (
is_hidden_by_actor_peer_view,
may_include_hidden_actor_peers,
resolve_uri,
)
from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.server.auth import (
get_download_request_context,
get_request_context,
require_role,
)
from openviking.server.dependencies import get_service
from openviking.server.error_mapping import map_exception
from openviking.server.identity import RequestContext, Role
from openviking.server.models import Response
from openviking.server.telemetry import run_operation
from openviking.storage.acl import AclSpec
from openviking.storage.vector_ids import is_vector_record_id
from openviking.telemetry import TelemetryRequest
from openviking_cli.exceptions import NotFoundError, PermissionDeniedError
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
class WriteContentRequest(BaseModel):
"""Request to write, append, or create text content to a file."""
model_config = ConfigDict(extra="forbid")
uri: str
content: str
mode: str = "replace"
wait: bool = False
timeout: float | None = Field(
default=None,
deprecated=True,
description="Deprecated compatibility parameter; accepted and ignored.",
)
telemetry: TelemetryRequest = False
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
tags: list[str] | None = None
tag_mode: Literal["replace", "append", "clear"] = "replace"
acl: AclSpec | None = None
# Who made the edit; versions of Compile outputs record it (console edit = manual).
edit_source: Literal["manual", "agent", "compile"] = "agent"
class BatchWriteOperation(BaseModel):
model_config = ConfigDict(extra="forbid")
uri: str
content: str | None = None
content_base64: str | None = None
mode: Literal["replace", "append", "create", "upsert"] = "replace"
# Optional byte revision, checked under the existing file locks before any writes.
expected_sha256: str | None = Field(default=None, pattern=r"^[a-f0-9]{64}$")
tags: list[str] | None = None
tag_mode: Literal["replace", "append", "clear"] = "replace"
acl: AclSpec | None = None
@model_validator(mode="after")
def validate_content_shape(self) -> "BatchWriteOperation":
if (self.content is None) == (self.content_base64 is None):
raise ValueError("exactly one of content or content_base64 is required")
return self
class BatchWriteRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
root_uri: str
operations: list[BatchWriteOperation]
wait: bool = True
timeout: float | None = Field(
default=None,
deprecated=True,
description="Deprecated compatibility parameter; accepted and ignored.",
)
telemetry: TelemetryRequest = False
# Preserve conflicting target files and return their URI/reason while writing other files.
skip_conflicts: bool = False
# Save content without semantic or vector work; the caller schedules processing.
defer_processing: bool = False
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
edit_source: Literal["manual", "agent", "compile"] = "agent"
class SetTagsRequest(BaseModel):
"""Request to set explicit k=v retrieval tags metadata for a file or directory."""
model_config = ConfigDict(extra="forbid")
uri: str
tags: list[str] | None = None
mode: str = "replace"
recursive: bool = False
telemetry: TelemetryRequest = False
class ReindexRequest(BaseModel):
uri: str
mode: str = "vectors_only"
force: bool = False
wait: bool = True
recursive: bool = True
tags: list[str] | None = None
tag_mode: str = "replace"
router = APIRouter(prefix="/api/v1/content", tags=["content"])
def _authorize_reindex_uri(uri: str, ctx: RequestContext) -> str:
"""Allow users to reindex only their own private namespace."""
if ctx.role != Role.USER:
return uri
target = resolve_uri(uri)
if (
target.scope != "user"
or target.owner_user_id != ctx.user.user_id
or is_hidden_by_actor_peer_view(uri, ctx)
or may_include_hidden_actor_peers(uri, ctx)
):
raise PermissionDeniedError(
"USER can only reindex their own user namespace.",
resource=uri,
)
return uri
@router.get("/read")
async def read(
uri: str = Query(..., description="Viking URI"),
offset: int = Query(0, description="Starting line number (0-indexed)"),
limit: int = Query(-1, description="Number of lines to read, -1 means read to end"),
raw: bool = Query(False, description="Return raw stored content without memory-field cleanup"),
_ctx: RequestContext = Depends(get_request_context),
):
"""Read file content (L2)."""
service = get_service()
# If the argument is a raw 32-hex vector record id, skip URI validation
# (id lookup + access check happens inside VikingFS.read_file).
if is_vector_record_id(uri):
resolved = uri
else:
resolved = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
if raw:
result = await service.fs.read(resolved, ctx=_ctx, offset=offset, limit=limit)
else:
result = await service.fs.read_visible(resolved, ctx=_ctx, offset=offset, limit=limit)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
except AGFSClientError as e:
mapped = map_exception(e, resource=uri, resource_type="file")
if mapped is not None:
raise mapped from e
raise
return Response(status="ok", result=result)
@router.get("/abstract")
async def abstract(
uri: str = Query(..., description="Viking URI"),
_ctx: RequestContext = Depends(get_request_context),
):
"""Read L0 abstract."""
service = get_service()
uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
result = await service.fs.abstract(uri, ctx=_ctx)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
except AGFSClientError as e:
mapped = map_exception(e, resource=uri, resource_type="file")
if mapped is not None:
raise mapped from e
raise
return Response(status="ok", result=result)
@router.get("/overview")
async def overview(
uri: str = Query(..., description="Viking URI"),
_ctx: RequestContext = Depends(get_request_context),
):
"""Read L1 overview."""
service = get_service()
uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
result = await service.fs.overview(uri, ctx=_ctx)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
except AGFSClientError as e:
mapped = map_exception(e, resource=uri, resource_type="file")
if mapped is not None:
raise mapped from e
raise
return Response(status="ok", result=result)
@router.get("/download")
async def download(
request: Request,
uri: Optional[str] = Query(None, description="Viking URI"),
_ctx: RequestContext = Depends(get_download_request_context),
):
"""Download file as raw bytes (for images, binaries, etc.).
A signed ``?token=`` from the MCP ``download`` tool serves only the URI bound to the
token; any ``uri`` query parameter is ignored on that path.
"""
signed_uri = getattr(request.state, "signed_download_uri", None)
if signed_uri is not None:
uri = signed_uri
if not uri:
raise HTTPException(status_code=400, detail="uri is required")
service = get_service()
uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
content = await service.fs.read_file_bytes(uri, ctx=_ctx)
except AGFSNotFoundError:
raise NotFoundError(uri, "file")
except AGFSClientError as e:
mapped = map_exception(e, resource=uri, resource_type="file")
if mapped is not None:
raise mapped from e
raise
# Try to get filename from stat
filename = "download"
try:
stat = await service.fs.stat(uri, ctx=_ctx, skip_count=True)
if stat and "name" in stat:
filename = stat["name"]
except Exception:
pass
filename = quote(filename)
return FastAPIResponse(
content=content,
media_type="application/octet-stream",
headers={"Content-Disposition": f"attachment; filename*=UTF-8''{filename}"},
)
@router.post("/write")
async def write(
request: WriteContentRequest = Body(...),
_ctx: RequestContext = Depends(get_request_context),
):
"""Write text content to a file (replace, append, or create) and refresh semantics/vectors."""
service = get_service()
uri = validate_request_viking_uri(resolve_path_variables(request.uri), _ctx)
execution = await run_operation(
operation="content.write",
telemetry=request.telemetry,
fn=lambda: service.fs.write(
uri=uri,
content=request.content,
ctx=_ctx,
mode=request.mode,
wait=request.wait,
processing_mode=request.processing_mode,
tags=request.tags,
tag_mode=request.tag_mode,
acl=request.acl,
edit_source=request.edit_source,
),
)
return Response(
status="ok",
result=execution.result,
telemetry=execution.telemetry,
).model_dump(exclude_none=True)
@router.post("/batch-write")
async def batch_write(
request: BatchWriteRequest = Body(...),
_ctx: RequestContext = Depends(get_request_context),
):
"""Apply file writes and refresh their indexes once after the batch is written."""
service = get_service()
root_uri = validate_request_viking_uri(resolve_path_variables(request.root_uri), _ctx)
operations = [operation.model_dump(exclude_none=True) for operation in request.operations]
for operation in operations:
operation["uri"] = validate_request_viking_uri(
resolve_path_variables(operation["uri"]), _ctx
)
execution = await run_operation(
operation="content.batch_write",
telemetry=request.telemetry,
fn=lambda: service.fs.batch_write(
root_uri=root_uri,
operations=operations,
ctx=_ctx,
wait=request.wait,
skip_conflicts=request.skip_conflicts,
defer_processing=request.defer_processing,
processing_mode=request.processing_mode,
edit_source=request.edit_source,
),
)
return Response(
status="ok",
result=execution.result,
telemetry=execution.telemetry,
).model_dump(exclude_none=True)
@router.post("/set_tags")
async def set_tags(
request: SetTagsRequest = Body(...),
_ctx: RequestContext = Depends(get_request_context),
):
"""Set explicit k=v retrieval tags metadata for a file or directory."""
service = get_service()
uri = validate_request_viking_uri(resolve_path_variables(request.uri), _ctx)
tags = [] if request.mode == "clear" else request.tags or []
execution = await run_operation(
operation="content.set_tags",
telemetry=request.telemetry,
fn=lambda: service.fs.set_tags(
uri=uri,
tags=tags,
mode=request.mode,
recursive=request.recursive,
ctx=_ctx,
),
)
return Response(
status="ok",
result=execution.result,
telemetry=execution.telemetry,
).model_dump(exclude_none=True)
@router.post("/reindex")
async def reindex(
body: ReindexRequest = Body(...),
ctx: RequestContext = require_role(Role.ROOT, Role.ADMIN, Role.USER),
):
"""Reindex semantic/vector artifacts for a URI-scoped maintenance target."""
uri = validate_request_viking_uri(resolve_path_variables(body.uri), ctx)
uri = _authorize_reindex_uri(uri, ctx)
service = get_service()
reindex_kwargs = {
"uri": uri,
"mode": body.mode,
"wait": body.wait,
"ctx": ctx,
}
if body.force:
reindex_kwargs["force"] = True
if not body.recursive:
reindex_kwargs["recursive"] = False
if body.tags is not None or body.tag_mode == "clear":
reindex_kwargs["tags"] = body.tags
reindex_kwargs["tag_mode"] = body.tag_mode
result = await service.reindex(
**reindex_kwargs,
)
return Response(status="ok", result=result)