Skip to content

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

11.5 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Execute a single-file :class:`ContextUpdatePlan` outside the parser pipeline.

``add_resources`` already builds and executes a :class:`ContextUpdatePlan`
inside :class:`ResourceProcessor`. Content write does not have parsed artifact
files or the directory-level vector sources that executor consumes, so this
module adapts the same plan contract to an inline file body. Keeping this
adapter separate avoids making the resource-ingest executor depend on
single-file write state.

The helper deliberately does not own the resource lock or the request wait
tracker: those lifecycles differ per caller (write releases the lock between
enqueue and wait; ingest hands the lock off to the queue). Callers keep that
control and only ask this module to perform the plan's own work.
"""

from __future__ import annotations

from collections import Counter
from dataclasses import dataclass
from typing import Any, Optional

from openviking.core.context import ContextLevel
from openviking.core.namespace import context_type_for_uri
from openviking.server.identity import RequestContext
from openviking.storage.acl import AclUpdate
from openviking.storage.context_update_plan import ContextUpdatePlan, execute_content_tree_actions
from openviking.storage.index_action import FieldPatch, IndexAction
from openviking.utils.ingest_options import IngestOptions
from openviking.utils.log_correlation import log_correlation
from openviking_cli.utils import VikingURI, get_logger

logger = get_logger(__name__)


@dataclass(frozen=True)
class PlanWork:
    """Which downstream work a plan actually requested.

    The caller finalizes ``semantic_status`` / ``vector_status`` after it waits,
    because only the caller knows the queue status once its lock is released.
    ``semantic_action`` carries the parent-refresh freshness decision so a
    single-file caller can surface a ``deferred``/``skipped`` status.
    """

    semantic_requested: bool = False
    vector_requested: bool = False
    semantic_action: Optional[str] = None


async def enqueue_direct_index_actions(
    actions: Any,
    *,
    ctx: RequestContext,
    acl_update: AclUpdate | None = None,
) -> bool:
    """Enqueue plan-level direct index actions (delete / upsert / field update).

    This is the inline-file counterpart of ``ResourceProcessor``'s richer
    artifact executor. Deletes are coalesced into one message, file L2 upserts
    reuse :func:`vectorize_file`, and scalar-only mutations enqueue an
    ``update_fields`` message. Returns whether any embedding work was enqueued.
    """
    if not actions:
        return False

    from openviking.storage.queuefs import get_queue_manager
    from openviking.storage.queuefs.embedding_msg import EmbeddingMsg
    from openviking.telemetry import get_current_telemetry
    from openviking.utils.embedding_utils import _enqueue_embedding_message

    queue_manager = get_queue_manager()
    embedding_queue = queue_manager.get_queue(queue_manager.EMBEDDING, allow_create=True)
    telemetry_id = get_current_telemetry().telemetry_id
    action_counts = Counter(action.action.value for action in actions)
    enqueued_any = False

    delete_ids = [action.record_id for action in actions if action.action == IndexAction.DELETE]
    if delete_ids:
        message = EmbeddingMsg.for_delete(
            record_ids=delete_ids,
            context_data={
                "uri": actions[0].uri,
                "account_id": ctx.account_id,
                "owner_user_id": ctx.user.user_id,
            },
            telemetry_id=telemetry_id,
        )
        enqueued_any = (
            await _enqueue_embedding_message(
                embedding_queue,
                message,
                failure_message="Failed to enqueue planned vector deletes",
            )
            or enqueued_any
        )
    for action in actions:
        if action.action in {IndexAction.UPSERT, IndexAction.MERGE}:
            if action.level != int(ContextLevel.DETAIL):
                raise ValueError("Direct index upsert only supports file detail records")
            vector_enqueued = await vectorize_resource_file(
                action.uri,
                ctx=ctx,
                acl_update=acl_update,
                file_md5=action.md5,
                scalar_override={
                    **dict(action.upsert_fields),
                    "_record_id": action.record_id,
                },
                summary=action.summary,
                action=action.action.value,
                field_patch=action.field_patch,
            )
            if vector_enqueued:
                enqueued_any = True
            else:
                # An empty/unsupported replacement cannot produce a new
                # embedding. Delete the planned record ID so an older vector
                # cannot keep representing content that is no longer present.
                delete_message = EmbeddingMsg.for_delete(
                    record_ids=[action.record_id],
                    context_data={
                        "uri": action.uri,
                        "account_id": ctx.account_id,
                        "owner_user_id": ctx.user.user_id,
                    },
                    telemetry_id=telemetry_id,
                )
                enqueued_any = (
                    await _enqueue_embedding_message(
                        embedding_queue,
                        delete_message,
                        failure_message=f"Failed to enqueue stale vector delete for {action.uri}",
                    )
                    or enqueued_any
                )
            continue
        if action.action != IndexAction.UPDATE_FIELDS:
            continue
        assert action.field_patch is not None
        message = EmbeddingMsg.for_update_fields(
            record_id=action.record_id,
            field_patch=action.field_patch,
            context_data={
                "uri": action.uri,
                "level": action.level,
                "account_id": ctx.account_id,
                "owner_user_id": ctx.user.user_id,
            },
            telemetry_id=telemetry_id,
        )
        enqueued_any = (
            await _enqueue_embedding_message(
                embedding_queue,
                message,
                failure_message=f"Failed to enqueue scalar update for {action.uri}",
            )
            or enqueued_any
        )
    logger.debug(
        "[DirectIndexActions] %s root=%s action_counts=%s action_count=%d",
        log_correlation(),
        actions[0].uri if actions else "",
        dict(action_counts),
        len(actions),
    )
    return enqueued_any


async def vectorize_resource_file(
    file_uri: str,
    *,
    ctx: RequestContext,
    acl_update: AclUpdate | None = None,
    file_md5: str | None = None,
    scalar_override: Optional[dict[str, Any]] = None,
    field_patch: FieldPatch | None = None,
    summary: str = "",
    action: str = "merge",
) -> bool:
    """Enqueue a single file's L2 vector using the standard file text policy.

    In ``vectors_only`` mode no semantic node regenerates a summary, but the RNFV
    V snapshot already carries the existing L2 ``abstract`` (it is projected into
    the inventory and travels through the direct index action's scalar fields).
    Seed ``summary_dict`` with that abstract so ``vectorize_file`` can honor the
    configured ``text_source``: ``summary_first`` embeds the existing abstract
    when present, ``content_only`` still embeds the file body. When no abstract is
    available (new file / empty record) the summary stays empty and the body is
    used regardless of ``text_source``.
    """
    from openviking.utils.embedding_utils import vectorize_file

    parent = VikingURI(file_uri).parent
    if parent is None:
        return False
    name = file_uri.rsplit("/", 1)[-1]
    existing_abstract = str(summary or (scalar_override or {}).get("abstract") or "")
    return await vectorize_file(
        file_path=file_uri,
        summary_dict={"name": name, "summary": existing_abstract},
        parent_uri=parent.uri,
        context_type=context_type_for_uri(file_uri),
        ctx=ctx,
        # Direct actions carry planner-resolved tag fields in
        # ``scalar_override`` / ``field_patch``. Forward only ACL intent here so
        # the first asynchronous upsert can materialize it without applying tag
        # modes a second time.
        ingest_options=IngestOptions(acl_update=acl_update),
        file_md5=file_md5,
        scalar_override=scalar_override,
        field_patch=field_patch,
        action=action,
    )


async def commit_and_enqueue_plan(
    plan: ContextUpdatePlan,
    *,
    ctx: RequestContext,
    semantic_lock_handoff: dict[str, Any] | None = None,
    inline_store: Any = None,
    inline_ref: Any = None,
    target: Any = None,
    ingest_options: IngestOptions | None = None,
    file_created: bool = False,
    force_refresh: bool | None = None,
    generation_trigger: str = "content_write",
    summarizer: Any = None,
) -> PlanWork:
    """Commit content synchronously, then enqueue index + file-refresh work.

    Content-tree actions run under the caller's lease before any queue handoff.
    Direct index actions and the flat-file ``file_refresh`` are enqueued next.
    The caller owns the lock lifecycle and the request wait tracker (register
    before calling, wait/finalize after); this helper only performs the plan's
    own work and reports which downstream work it requested.

    ``force_refresh`` selects the parent-aggregation policy for ``file_refresh``:
    ``None`` always aggregates (resource ingest), while a boolean opts into the
    freshness gate so an asynchronous single-file write can defer parent L0/L1
    aggregation without dropping the changed file's own vector maintenance.
    """
    if plan.content_tree_actions:
        if target is None:
            raise ValueError("content-tree actions require a resource target")
        await execute_content_tree_actions(
            plan.content_tree_actions,
            store=inline_store,
            artifact_ref=inline_ref,
            target=target,
        )

    vector_requested = False
    if plan.direct_index_actions:
        options = IngestOptions.from_value(ingest_options)
        vector_requested = await enqueue_direct_index_actions(
            plan.direct_index_actions,
            ctx=ctx,
            acl_update=options.acl_update,
        )

    semantic_requested = False
    semantic_action: Optional[str] = None
    if plan.file_refresh is not None:
        if summarizer is None:
            from openviking.utils.summarizer import Summarizer

            summarizer = Summarizer(vlm_processor=None)
        refresh_result = await summarizer.refresh_file_parent(
            file_uri=plan.file_refresh.file_uri,
            ctx=ctx,
            lock_handoff=semantic_lock_handoff,
            ingest_options=IngestOptions.from_value(ingest_options),
            created=file_created,
            file_md5=plan.file_refresh.md5,
            file_abstract="",
            file_vector_action="upsert" if file_created else "",
            generation_trigger=generation_trigger,
            force_refresh=force_refresh,
        )
        semantic_requested = refresh_result.get("enqueued_count", 0) > 0
        semantic_action = refresh_result.get("semantic_action")
        vector_requested = True

    return PlanWork(
        semantic_requested=semantic_requested,
        vector_requested=vector_requested,
        semantic_action=semantic_action,
    )


__all__ = [
    "PlanWork",
    "commit_and_enqueue_plan",
    "enqueue_direct_index_actions",
    "vectorize_resource_file",
]