Skip to content

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

9.2 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""FastAPI route handlers, one per OpenWebUI tool."""

from __future__ import annotations

import re
from typing import Any, Dict, List, Literal, Optional

from fastapi import APIRouter, Depends, HTTPException, Request
from pydantic import BaseModel, Field

from .client import OVClient, OVError
from .config import Settings


def get_client(request: Request) -> OVClient:
    """Resolve the shared OVClient placed on the FastAPI app state."""
    return request.app.state.ov_client


def get_settings(request: Request) -> Settings:
    return request.app.state.ov_settings


router = APIRouter(tags=["openviking"])


def _forward(exc: OVError) -> HTTPException:
    """Surface the OV server's error status + body verbatim."""
    return HTTPException(status_code=exc.status, detail=exc.payload)


# --- Schemas -----------------------------------------------------------------


class SearchRequest(BaseModel):
    query: str = Field(..., description="Natural-language query")
    limit: int = Field(10, ge=1, le=100)
    target_uri: Optional[str] = Field(
        None,
        description="Optional viking:// prefix to scope the search",
    )
    score_threshold: Optional[float] = Field(None, ge=0.0, le=1.0)


class SearchHit(BaseModel):
    uri: str
    score: float
    snippet: Optional[str] = None


class SearchResponse(BaseModel):
    hits: List[SearchHit]
    raw: Dict[str, Any] = Field(default_factory=dict)


class RecallRequest(BaseModel):
    query: str
    limit: int = Field(6, ge=1, le=50)


class AddMemoryRequest(BaseModel):
    name: str = Field(..., description="Filename under viking://~/memories/, e.g. 'profile.md'")
    content: str = Field(..., description="Memory body, plain text or Markdown")
    mode: Literal["replace", "append", "create"] = "replace"
    wait: bool = Field(False, description="Block until semantic indexing completes")


class AddMemoryResponse(BaseModel):
    uri: str
    raw: Dict[str, Any] = Field(default_factory=dict)


class ListMemoriesRequest(BaseModel):
    recursive: bool = False
    limit: int = Field(200, ge=1, le=1000)


class ReadResourceRequest(BaseModel):
    uri: str = Field(..., description="Full viking:// URI")
    offset: int = 0
    limit: int = -1


class AddResourceRequest(BaseModel):
    path: str = Field(..., description="Remote URL or local path the OV server can reach")
    to: Optional[str] = None
    parent: Optional[str] = None
    reason: str = ""
    instruction: str = ""
    wait: bool = False


class SessionStatusRequest(BaseModel):
    session_id: str


# --- Helpers -----------------------------------------------------------------


def _hits_from_find(payload: Dict[str, Any]) -> List[SearchHit]:
    """Flatten an OpenViking /search/find response into typed hits."""
    result = payload.get("result") if isinstance(payload, dict) else None
    if not isinstance(result, dict):
        return []
    bucket_keys = ("memories", "resources", "skills", "results")
    seen: List[SearchHit] = []
    for key in bucket_keys:
        bucket = result.get(key)
        if not isinstance(bucket, list):
            continue
        for item in bucket:
            if not isinstance(item, dict):
                continue
            uri = item.get("uri") or item.get("target_uri")
            if not isinstance(uri, str):
                continue
            score = float(item.get("score") or 0.0)
            snippet = item.get("snippet") or item.get("abstract") or item.get("preview")
            seen.append(
                SearchHit(
                    uri=uri,
                    score=score,
                    snippet=snippet if isinstance(snippet, str) else None,
                )
            )
    return seen


def _memory_uri(settings: Settings, name: str) -> str:
    name = name.strip().lstrip("/")
    if not name:
        raise HTTPException(status_code=400, detail="name must not be empty")
    return settings.memories_uri + name


# --- Routes ------------------------------------------------------------------


@router.post(
    "/tools/ov_search",
    response_model=SearchResponse,
    operation_id="ov_search",
    summary="Semantic search across OpenViking memories, resources, and skills.",
)
async def ov_search(
    body: SearchRequest,
    client: OVClient = Depends(get_client),
) -> SearchResponse:
    """Run a semantic find over OpenViking and return the top hits."""
    payload: Dict[str, Any] = {"query": body.query, "limit": body.limit}
    if body.target_uri:
        payload["target_uri"] = body.target_uri
    if body.score_threshold is not None:
        payload["score_threshold"] = body.score_threshold
    try:
        raw = await client.post("/api/v1/search/find", json=payload)
    except OVError as exc:
        raise _forward(exc) from exc
    return SearchResponse(hits=_hits_from_find(raw), raw=raw if isinstance(raw, dict) else {})


@router.post(
    "/tools/ov_recall_memories",
    response_model=SearchResponse,
    operation_id="ov_recall_memories",
    summary="Recall personal memories relevant to a query.",
)
async def ov_recall_memories(
    body: RecallRequest,
    client: OVClient = Depends(get_client),
    settings: Settings = Depends(get_settings),
) -> SearchResponse:
    """Search scoped to viking://~/memories/ for personal memory recall."""
    payload = {
        "query": body.query,
        "limit": body.limit,
        "target_uri": settings.memories_uri,
    }
    try:
        raw = await client.post("/api/v1/search/find", json=payload)
    except OVError as exc:
        raise _forward(exc) from exc
    return SearchResponse(hits=_hits_from_find(raw), raw=raw if isinstance(raw, dict) else {})


@router.post(
    "/tools/ov_add_memory",
    response_model=AddMemoryResponse,
    operation_id="ov_add_memory",
    summary="Persist a new memory under viking://~/memories/.",
)
async def ov_add_memory(
    body: AddMemoryRequest,
    client: OVClient = Depends(get_client),
    settings: Settings = Depends(get_settings),
) -> AddMemoryResponse:
    """Write a memory file via /api/v1/content/write."""
    uri = _memory_uri(settings, body.name)
    payload = {
        "uri": uri,
        "content": body.content,
        "mode": body.mode,
        "wait": body.wait,
    }
    try:
        raw = await client.post("/api/v1/content/write", json=payload)
    except OVError as exc:
        raise _forward(exc) from exc
    return AddMemoryResponse(uri=uri, raw=raw if isinstance(raw, dict) else {})


@router.post(
    "/tools/ov_list_memories",
    operation_id="ov_list_memories",
    summary="List entries under viking://~/memories/.",
)
async def ov_list_memories(
    body: ListMemoriesRequest,
    client: OVClient = Depends(get_client),
    settings: Settings = Depends(get_settings),
) -> Dict[str, Any]:
    """Browse the memories directory via /api/v1/fs/ls."""
    params = {
        "uri": settings.memories_uri,
        "recursive": str(body.recursive).lower(),
        "node_limit": body.limit,
    }
    try:
        return await client.get("/api/v1/fs/ls", params=params)
    except OVError as exc:
        raise _forward(exc) from exc


@router.post(
    "/tools/ov_read_resource",
    operation_id="ov_read_resource",
    summary="Read text content of any viking:// URI.",
)
async def ov_read_resource(
    body: ReadResourceRequest,
    client: OVClient = Depends(get_client),
) -> Dict[str, Any]:
    """Read full text content via /api/v1/content/read."""
    params: Dict[str, Any] = {
        "uri": body.uri,
        "offset": body.offset,
        "limit": body.limit,
    }
    try:
        return await client.get("/api/v1/content/read", params=params)
    except OVError as exc:
        raise _forward(exc) from exc


@router.post(
    "/tools/ov_add_resource",
    operation_id="ov_add_resource",
    summary="Ingest a remote URL or path-reachable file as an OpenViking resource.",
)
async def ov_add_resource(
    body: AddResourceRequest,
    client: OVClient = Depends(get_client),
) -> Dict[str, Any]:
    """POST /api/v1/resources to start ingestion."""
    payload = {
        "path": body.path,
        "reason": body.reason,
        "instruction": body.instruction,
        "wait": body.wait,
    }
    if body.to:
        payload["to"] = body.to
    if body.parent:
        payload["parent"] = body.parent
    try:
        return await client.post("/api/v1/resources", json=payload)
    except OVError as exc:
        raise _forward(exc) from exc


@router.post(
    "/tools/ov_session_status",
    operation_id="ov_session_status",
    summary="Get OpenViking session metadata (counts, archive state, pending tokens).",
)
async def ov_session_status(
    body: SessionStatusRequest,
    client: OVClient = Depends(get_client),
) -> Dict[str, Any]:
    """GET /api/v1/sessions/{session_id}."""
    session_id = body.session_id
    # Reject percent escapes as well: upstream routers may decode the path.
    if session_id in {".", ".."} or not re.fullmatch(r"[^/\\?#%\x00-\x1f\x7f]+", session_id):
        raise HTTPException(
            status_code=422,
            detail="session_id must be a single path segment without URL syntax or control characters",
        )
    try:
        return await client.get(f"/api/v1/sessions/{session_id}")
    except OVError as exc:
        raise _forward(exc) from exc