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
#!/usr/bin/env python3
"""Minimal Agent Memory Leaderboard bridge for OpenViking."""
from __future__ import annotations
import argparse
import asyncio
import base64
import binascii
import hmac
import math
import os
import time
from contextlib import asynccontextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Annotated, Any, AsyncIterator, Awaitable, Callable, Literal, TypeVar
import httpx
import uvicorn
from fastapi import Depends, FastAPI, HTTPException, Request, status
from openviking_sdk import AsyncHTTPClient, OpenVikingError
from pydantic import BaseModel, ConfigDict, Field, field_validator
DEFAULT_HOST = "127.0.0.1"
DEFAULT_PORT = 8088
DEFAULT_OPENVIKING_URL = "http://127.0.0.1:1933"
MEMORY_ROOT_URI = "viking://~/memories"
MAX_IMAGE_BYTES = 10 * 1024 * 1024
MAX_ADD_IMAGE_BYTES = 30 * 1024 * 1024
MAX_QUERY_IMAGE_BYTES = 30 * 1024 * 1024
RETRYABLE_OPENVIKING_CODES = {
"ABORTED",
"DEADLINE_EXCEEDED",
"INTERNAL",
"RESOURCE_EXHAUSTED",
"UNAVAILABLE",
"UNKNOWN",
}
T = TypeVar("T")
def _positive_int_env(name: str, default: int) -> int:
value = int(os.getenv(name, str(default)))
if value < 1:
raise ValueError(f"{name} must be at least 1")
return value
def _positive_float_env(name: str, default: float) -> float:
value = float(os.getenv(name, str(default)))
if not math.isfinite(value) or value <= 0:
raise ValueError(f"{name} must be a finite number greater than 0")
return value
@dataclass(frozen=True)
class AMLSettings:
openviking_url: str = DEFAULT_OPENVIKING_URL
openviking_api_key: str | None = None
openviking_account: str | None = None
aml_api_key: str | None = None
retry_attempts: int = 3
retry_delay_seconds: float = 0.5
request_timeout_seconds: float = 120.0
extraction_timeout_seconds: float = 900.0
task_poll_seconds: float = 1.0
def __post_init__(self) -> None:
object.__setattr__(self, "openviking_url", self.openviking_url.rstrip("/"))
if not self.openviking_url.startswith(("http://", "https://")):
raise ValueError("OPENVIKING_URL must use http:// or https://")
if self.openviking_account is not None and not self.openviking_account.strip():
raise ValueError("OPENVIKING_ACCOUNT must not be blank")
if self.retry_attempts < 1:
raise ValueError("retry_attempts must be at least 1")
for name in (
"retry_delay_seconds",
"request_timeout_seconds",
"extraction_timeout_seconds",
"task_poll_seconds",
):
value = getattr(self, name)
if not math.isfinite(value) or value <= 0:
raise ValueError(f"{name} must be a finite number greater than 0")
@classmethod
def from_env(cls) -> "AMLSettings":
return cls(
openviking_url=os.getenv("OPENVIKING_URL", DEFAULT_OPENVIKING_URL),
openviking_api_key=os.getenv("OPENVIKING_API_KEY") or None,
openviking_account=os.getenv("OPENVIKING_ACCOUNT") or None,
aml_api_key=os.getenv("AML_API_KEY") or None,
retry_attempts=_positive_int_env("AML_RETRY_ATTEMPTS", 3),
retry_delay_seconds=_positive_float_env("AML_RETRY_DELAY_SECONDS", 0.5),
request_timeout_seconds=_positive_float_env("AML_OV_REQUEST_TIMEOUT_SECONDS", 120.0),
extraction_timeout_seconds=_positive_float_env(
"AML_OV_EXTRACTION_TIMEOUT_SECONDS", 900.0
),
task_poll_seconds=_positive_float_env("AML_OV_TASK_POLL_SECONDS", 1.0),
)
def _not_blank(value: str) -> str:
if not value.strip():
raise ValueError("value must not be blank")
return value
class AMLTextPart(BaseModel):
model_config = ConfigDict(extra="forbid")
type: Literal["text"]
text: str = Field(min_length=1)
_text_not_blank = field_validator("text")(_not_blank)
class AMLImageURL(BaseModel):
model_config = ConfigDict(extra="forbid")
url: str
detail: Literal["auto", "low", "high"] | None = None
@field_validator("url")
@classmethod
def validate_inline_image(cls, value: str) -> str:
header, _, encoded = value.partition(",")
if (
header
not in {
"data:image/jpeg;base64",
"data:image/png;base64",
"data:image/webp;base64",
}
or not encoded
):
raise ValueError("image_url must be an inline Base64 JPEG, PNG, or WebP Data URI")
if len(encoded) > 4 * ((MAX_IMAGE_BYTES + 2) // 3):
raise ValueError("image exceeds the 10 MiB decoded size limit")
try:
size = len(base64.b64decode(encoded, validate=True))
except (binascii.Error, ValueError) as exc:
raise ValueError("image_url contains invalid Base64 data") from exc
if size > MAX_IMAGE_BYTES:
raise ValueError("image exceeds the 10 MiB decoded size limit")
return value
@property
def decoded_size(self) -> int:
# Base64 was validated above; count bytes without decoding images again.
return len(self.url.partition(",")[2].rstrip("=")) * 3 // 4
class AMLImagePart(BaseModel):
model_config = ConfigDict(extra="forbid")
type: Literal["image_url"]
image_url: AMLImageURL
AMLContentPart = Annotated[AMLTextPart | AMLImagePart, Field(discriminator="type")]
class AMLMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
role: Literal["user", "assistant"]
content: str | list[AMLContentPart] = Field(min_length=1)
timestamp: int | None = Field(default=None, ge=0, strict=True)
@field_validator("content")
@classmethod
def content_not_blank(cls, value: str | list[AMLContentPart]) -> str | list[AMLContentPart]:
return _not_blank(value) if isinstance(value, str) else value
@field_validator("timestamp")
@classmethod
def timestamp_is_representable(cls, value: int | None) -> int | None:
if value is not None:
try:
datetime.fromtimestamp(value / 1000, tz=timezone.utc)
except (OverflowError, OSError, ValueError) as exc:
raise ValueError(
"timestamp is outside the supported Unix millisecond range"
) from exc
return value
class AMLAddRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
request_id: str = Field(min_length=1)
messages: list[AMLMessage] = Field(min_length=1, max_length=20)
user_id: str = Field(min_length=1)
session_id: str = Field(min_length=1)
_request_id_not_blank = field_validator("request_id")(_not_blank)
_user_id_not_blank = field_validator("user_id")(_not_blank)
_session_id_not_blank = field_validator("session_id")(_not_blank)
@field_validator("messages")
@classmethod
def validate_image_budget(cls, messages: list[AMLMessage]) -> list[AMLMessage]:
size = sum(
part.image_url.decoded_size
for message in messages
if isinstance(message.content, list)
for part in message.content
if isinstance(part, AMLImagePart)
)
if size > MAX_ADD_IMAGE_BYTES:
raise ValueError("images exceed the 30 MiB decoded size limit per Add request")
return messages
class AMLSearchRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
query: str | list[AMLContentPart] = Field(min_length=1)
options: list[str] | None = None
user_id: str = Field(min_length=1)
top_k: int = Field(ge=1, strict=True)
_user_id_not_blank = field_validator("user_id")(_not_blank)
@field_validator("query")
@classmethod
def validate_query(cls, value: str | list[AMLContentPart]) -> str | list[AMLContentPart]:
if isinstance(value, str):
return _not_blank(value)
size = sum(part.image_url.decoded_size for part in value if isinstance(part, AMLImagePart))
if size > MAX_QUERY_IMAGE_BYTES:
raise ValueError("images exceed the 30 MiB decoded size limit per Search request")
return value
class OpenVikingBackendError(RuntimeError):
pass
class OpenVikingBackend:
def __init__(
self,
settings: AMLSettings,
*,
client_factory: Callable[[str], AsyncHTTPClient] | None = None,
) -> None:
self.settings = settings
self._client_factory = client_factory
def _new_client(self, user_id: str) -> AsyncHTTPClient:
if self._client_factory is not None:
return self._client_factory(user_id)
return AsyncHTTPClient(
url=self.settings.openviking_url,
api_key=self.settings.openviking_api_key,
account=self.settings.openviking_account,
user=user_id,
timeout=self.settings.request_timeout_seconds,
extra_headers={},
profile_enabled=False,
)
@asynccontextmanager
async def _client(self, user_id: str) -> AsyncIterator[AsyncHTTPClient]:
client = self._new_client(user_id)
await client.initialize()
try:
yield client
finally:
await client.close()
async def _retry(self, operation: str, call: Callable[[], Awaitable[T]]) -> T:
for attempt in range(self.settings.retry_attempts):
try:
return await call()
except (httpx.RequestError, OpenVikingError) as exc:
retryable = isinstance(exc, httpx.RequestError) or (
exc.code in RETRYABLE_OPENVIKING_CODES
)
if not retryable or attempt + 1 == self.settings.retry_attempts:
raise OpenVikingBackendError(f"OpenViking {operation} failed: {exc}") from exc
await asyncio.sleep(self.settings.retry_delay_seconds * (2**attempt))
raise AssertionError("retry loop exited unexpectedly")
async def ready(self) -> bool:
try:
async with self._client("aml-health") as client:
return await client.health()
except (httpx.RequestError, OpenVikingError, RuntimeError, ValueError):
return False
async def add_and_commit(
self, *, user_id: str, session_id: str, messages: list[dict[str, Any]]
) -> None:
async with self._client(user_id) as client:
result = await self._retry(
"batch add",
lambda: client.batch_add_messages(session_id, messages),
)
if not isinstance(result, dict) or result.get("added") != len(messages):
raise OpenVikingBackendError("OpenViking did not add every message")
commit = await self._retry(
"commit",
lambda: client.commit_session(session_id, keep_recent_count=0),
)
if not isinstance(commit, dict):
raise OpenVikingBackendError("OpenViking did not accept the commit")
task_id = commit.get("task_id")
if commit.get("status") != "accepted" or not isinstance(task_id, str) or not task_id:
raise OpenVikingBackendError("OpenViking did not accept the commit")
deadline = time.monotonic() + self.settings.extraction_timeout_seconds
while True:
task = await self._retry("task poll", lambda: client.get_task(task_id))
if not isinstance(task, dict):
raise OpenVikingBackendError("OpenViking returned an invalid commit task")
task_status = task.get("status")
if task_status == "completed":
return
if task_status in {"failed", "cancelled"}:
raise OpenVikingBackendError(
f"OpenViking commit {task_status}: {task.get('error') or 'unknown error'}"
)
if task_status not in {"pending", "running", "cancelling"}:
raise OpenVikingBackendError("OpenViking returned an unknown commit status")
remaining = deadline - time.monotonic()
if remaining <= 0:
raise OpenVikingBackendError("OpenViking commit timed out")
await asyncio.sleep(min(self.settings.task_poll_seconds, remaining))
async def find(
self, *, user_id: str, query: str, limit: int, image: str | list[str] | None = None
) -> list[dict[str, Any]]:
async with self._client(user_id) as client:
result = await self._retry(
"find",
lambda: client.find(
query=query,
target_uri=MEMORY_ROOT_URI,
limit=limit,
**({"image": image} if image else {}),
options={
"context_type": ["memory"],
"level": 2,
},
),
)
memories = result.get("memories") if isinstance(result, dict) else None
if not isinstance(memories, list) or any(not isinstance(hit, dict) for hit in memories):
raise OpenVikingBackendError("OpenViking returned an invalid find result")
return memories
def _format_timestamp(timestamp_ms: int) -> str:
return (
datetime.fromtimestamp(timestamp_ms / 1000, tz=timezone.utc)
.isoformat(timespec="milliseconds")
.replace("+00:00", "Z")
)
class AMLAdapter:
def __init__(self, settings: AMLSettings, backend: OpenVikingBackend) -> None:
self.settings = settings
self.backend = backend
def authorize(self, request: Request) -> None:
if self.settings.aml_api_key is None:
return
candidates = [request.headers.get("x-api-key", "")]
scheme, separator, value = request.headers.get("authorization", "").partition(" ")
if separator and scheme.lower() in {"bearer", "token"}:
candidates.append(value)
if any(
hmac.compare_digest(candidate, self.settings.aml_api_key) for candidate in candidates
):
return
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid or missing Memory System Key",
)
async def add(self, request: AMLAddRequest) -> dict[str, Any]:
messages: list[dict[str, Any]] = []
for message in request.messages:
item: dict[str, Any] = {"role": message.role}
if isinstance(message.content, str):
item["content"] = message.content
else:
item["parts"] = [part.model_dump(exclude_none=True) for part in message.content]
if message.timestamp is not None:
item["created_at"] = _format_timestamp(message.timestamp)
messages.append(item)
try:
await self.backend.add_and_commit(
user_id=request.user_id,
session_id=request.session_id,
messages=messages,
)
except OpenVikingBackendError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)
) from exc
return {
"success": True,
"request_id": request.request_id,
"user_id": request.user_id,
"session_id": request.session_id,
}
async def search(self, request: AMLSearchRequest) -> dict[str, list[dict[str, Any]]]:
query = request.query
images = []
if isinstance(query, list):
images = [part.image_url.url for part in query if isinstance(part, AMLImagePart)]
query = "\n".join(part.text for part in query if isinstance(part, AMLTextPart))
if request.options:
options = "\n".join(
f"{index}. {option}" for index, option in enumerate(request.options, start=1)
)
query = f"{query}\n\nAnswer options:\n{options}"
try:
hits = await self.backend.find(
user_id=request.user_id,
query=query,
limit=request.top_k,
**({"image": images[0] if len(images) == 1 else images} if images else {}),
)
except OpenVikingBackendError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)
) from exc
data: list[dict[str, Any]] = []
for hit in hits:
content = hit.get("content") or hit.get("abstract")
uri = hit.get("uri")
if not isinstance(uri, str) or not uri or not isinstance(content, str) or not content:
continue
data.append({"id": uri, "content": content})
if len(data) == request.top_k:
break
return {"data": data}
def create_app(
*,
settings: AMLSettings | None = None,
backend: OpenVikingBackend | None = None,
) -> FastAPI:
resolved_settings = settings or AMLSettings.from_env()
resolved_backend = backend or OpenVikingBackend(resolved_settings)
adapter = AMLAdapter(resolved_settings, resolved_backend)
application = FastAPI(title="OpenViking AML Adapter", version="0.1.0")
async def require_key(request: Request) -> None:
adapter.authorize(request)
@application.get("/health")
async def health() -> dict[str, str]:
if not await resolved_backend.ready():
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="OpenViking is not ready",
)
return {"status": "ok"}
@application.post("/add", dependencies=[Depends(require_key)])
async def add(request: AMLAddRequest) -> dict[str, Any]:
return await adapter.add(request)
@application.post("/search", dependencies=[Depends(require_key)])
async def search(request: AMLSearchRequest) -> dict[str, list[dict[str, Any]]]:
return await adapter.search(request)
application.state.aml_adapter = adapter
return application
app = create_app()
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Start the OpenViking AML adapter")
parser.add_argument("--host", default=os.getenv("AML_HOST", DEFAULT_HOST))
parser.add_argument("--port", type=int, default=int(os.getenv("AML_PORT", str(DEFAULT_PORT))))
parser.add_argument("--log-level", default=os.getenv("AML_LOG_LEVEL", "info"))
return parser.parse_args()
def main() -> None:
args = parse_args()
uvicorn.run(
create_app(),
host=args.host,
port=args.port,
log_level=args.log_level,
access_log=False,
)
if __name__ == "__main__":
main()