Skip to content

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

12.9 KB
Raw Blame
# 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)