Skip to content

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

fix(memory): render field descriptions in Python extraction (#5162)

agent535f0e003444
diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.py
index f26b7f13f..ccca4ddb6 100644
--- a/openviking/session/memory/extract_loop.py
+++ b/openviking/session/memory/extract_loop.py
@@ -253,6 +253,7 @@ class ExtractLoop:
link_enabled=self._link_enabled,
role_scope=role_scope,
available_tools=tuple(allowed_tools),
+ template_context={"language": output_language},
)
tracer.set("memory.extraction.output_format", output_format)
diff --git a/openviking/session/memory/extraction_output_protocol/base.py b/openviking/session/memory/extraction_output_protocol/base.py
index 2f408076e..7da0bf0c7 100644
--- a/openviking/session/memory/extraction_output_protocol/base.py
+++ b/openviking/session/memory/extraction_output_protocol/base.py
@@ -5,7 +5,7 @@
from __future__ import annotations
from abc import ABC, abstractmethod
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import Any
from pydantic import BaseModel
@@ -32,6 +32,7 @@ class ExtractionOutputContext:
link_enabled: bool
role_scope: Any | None = None
available_tools: tuple[str, ...] = ()
+ template_context: dict[str, Any] = field(default_factory=dict)
class ExtractionOutputProtocol(ABC):
diff --git a/openviking/session/memory/extraction_output_protocol/python_protocol.py b/openviking/session/memory/extraction_output_protocol/python_protocol.py
index 682811612..9574cd610 100644
--- a/openviking/session/memory/extraction_output_protocol/python_protocol.py
+++ b/openviking/session/memory/extraction_output_protocol/python_protocol.py
@@ -26,6 +26,7 @@ from openviking.session.memory.merge_op import (
SearchReplaceBlock,
StrPatch,
)
+from openviking.session.memory.utils.description_template import render_description_template
from openviking.session.memory.utils.line_numbers import (
every_line_has_line_numbers,
strip_line_numbers,
@@ -215,6 +216,11 @@ class PythonExtractionOutputProtocol(ExtractionOutputProtocol):
for field in schema.fields
}
for name, _type_name, description in fields:
+ if name in merge_ops:
+ # Render only YAML field descriptions, using the same context and
+ # restricted renderer as JSON. Keep the DSL's own edit instructions
+ # instead of copying the JSON model's merge-operation wrappers.
+ description = render_description_template(description, context.template_context)
normalized_description = " ".join(str(description or "").split())
qualifier = f" [{merge_ops[name]}]" if name in merge_ops else ""
lines.append(f" - {_identifier_alias(name)}{qualifier}: {normalized_description}")
diff --git a/tests/session/memory/test_account_descriptions.py b/tests/session/memory/test_account_descriptions.py
index b04db2e51..de77e45e6 100644
--- a/tests/session/memory/test_account_descriptions.py
+++ b/tests/session/memory/test_account_descriptions.py
@@ -11,7 +11,12 @@ from openviking.session.memory.account_templates import (
_validate_template,
memory_template_data,
)
+from openviking.session.memory.extraction_output_protocol import (
+ ExtractionOutputContext,
+ create_extraction_output_protocol,
+)
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.page_id_map import PageIdMap
from openviking.session.memory.schema_model_generator import (
SchemaModelGenerator,
SchemaPromptGenerator,
@@ -92,8 +97,18 @@ def test_descriptions_render_identically_in_all_schema_prompts(memory_type, orig
prompts = SchemaPromptGenerator([schema], template_context={"language": "en"})
type_prompt = prompts.generate_type_descriptions()
field_prompt = prompts.generate_field_descriptions(memory_type)
+ protocol_context = ExtractionOutputContext(
+ operations_model=operations,
+ schemas=(schema,),
+ page_id_map=PageIdMap(),
+ read_file_contents={},
+ link_enabled=False,
+ template_context={"language": "en"},
+ )
+ python_contract = create_extraction_output_protocol("python").render_contract(protocol_context)
assert "TYPE: " + expected in operations.model_fields[memory_type].description
assert "TYPE: " + expected in type_prompt
+ assert "TYPE: " + expected in python_contract
for field in schema.fields:
if field.name in editable:
assert not hasattr(field, "_account_description")
@@ -101,6 +116,7 @@ def test_descriptions_render_identically_in_all_schema_prompts(memory_type, orig
assert field.name + ": " + expected in model.model_fields[field.name].description
assert field.name + ": " + expected in type_prompt
assert field.name + ": " + expected in field_prompt
+ assert field.name + ": " + expected in python_contract
@pytest.mark.parametrize("request_kind", ["empty", "roundtrip", "type_only", "field_only"])
diff --git a/tests/session/memory/test_extraction_output_protocol.py b/tests/session/memory/test_extraction_output_protocol.py
index a00fac020..03a6776ae 100644
--- a/tests/session/memory/test_extraction_output_protocol.py
+++ b/tests/session/memory/test_extraction_output_protocol.py
@@ -4,16 +4,26 @@
import json
from types import SimpleNamespace
-from unittest.mock import patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from openviking.session.memory.dataclass import MemoryField, MemoryFile, MemoryTypeSchema
+from openviking.session.memory.dataclass import (
+ MemoryField,
+ MemoryFile,
+ MemoryTypeSchema,
+ ResolvedOperations,
+)
+from openviking.session.memory.extract_loop import ExtractLoop
from openviking.session.memory.extraction_output_protocol import (
ExtractionOutputContext,
create_extraction_output_protocol,
)
from openviking.session.memory.memory_isolation_handler import RoleScope
+from openviking.session.memory.memory_type_registry import (
+ MemoryTypeRegistry,
+ resolve_memory_templates_dir,
+)
from openviking.session.memory.merge_op import FieldType, MergeOp
from openviking.session.memory.page_id_map import PageIdMap
from openviking.session.memory.schema_model_generator import SchemaModelGenerator
@@ -90,12 +100,13 @@ def _context(
link_enabled: bool = False,
role_scope: RoleScope | None = None,
available_tools: tuple[str, ...] = ("read",),
+ template_context: dict[str, str] | None = None,
) -> ExtractionOutputContext:
config = SimpleNamespace(memory=SimpleNamespace(link_enabled=link_enabled))
with patch("openviking_cli.utils.config.get_openviking_config", return_value=config):
- operations_model = SchemaModelGenerator(schemas).create_structured_operations_model(
- role_scope
- )
+ operations_model = SchemaModelGenerator(
+ schemas, template_context=template_context
+ ).create_structured_operations_model(role_scope)
page_id_map = PageIdMap()
read_file_contents = {}
for memory_file in files or []:
@@ -109,6 +120,7 @@ def _context(
link_enabled=link_enabled,
role_scope=role_scope,
available_tools=available_tools,
+ template_context=dict(template_context or {}),
)
@@ -178,6 +190,88 @@ def test_python_contract_includes_link_rules_when_enabled():
assert "obj_a.link(" in contract
assert "assign the create/set call to a variable first" in contract
+
[email protected]("language", ["en", "zh-CN"])
+ ("memory_type", "field_name"),
+ [("preferences", "topic"), ("entities", "category"), ("events", "event_name")],
+)
+def test_python_contract_renders_builtin_field_descriptions_like_json(
+ language, memory_type, field_name
+):
+ registry = MemoryTypeRegistry(load_schemas=False)
+ registry.load_from_yaml(str(resolve_memory_templates_dir() / f"{memory_type}.yaml"))
+ schema = registry.get(memory_type)
+ original = next(field.description for field in schema.fields if field.name == field_name)
+ assert "{{ language }}" in original
+ context = _context([schema], template_context={"language": language})
+
+ python_contract = create_extraction_output_protocol("python").render_contract(context)
+ json_contract = create_extraction_output_protocol("json").render_contract(context)
+ json_schema = json.loads(json_contract.split("```json\n", 1)[1].split("```", 1)[0])
+ model_ref = json_schema["properties"][memory_type]["items"]["$ref"].rsplit("/", 1)[1]
+ rendered = json_schema["$defs"][model_ref]["properties"][field_name]["description"]
+
+ assert " ".join(rendered.split()) in python_contract
+ assert language in rendered
+ assert "{{ language }}" not in python_contract
+ assert "{% if language" not in python_contract
+ assert ("Use lowercase with underscores" in rendered) == (language == "en")
+ assert (
+ next(field.description for field in schema.fields if field.name == field_name) == original
+ )
+
+
+def test_python_field_description_keeps_dsl_patch_instructions():
+ schema = _preference_schema()
+ schema.fields[1].description = "Write content in {{ language.upper() }}."
+ context = _context([schema], template_context={"language": "en"})
+
+ contract = create_extraction_output_protocol("python").render_contract(context)
+
+ assert "content [editable string: obj.field.edit/drop/update]: Write content in EN." in contract
+ assert "obj.content.edit(search=..., replace=...)" in contract
+ assert "PATCH operation for" not in contract
+ assert "Use a DELETE block" not in contract
+
+
[email protected]("language", ["en", "zh-CN"])
+async def test_default_python_extract_loop_passes_language_to_field_descriptions(language):
+ schema = _preference_schema()
+ schema.description = "Preferences in {{ language }}."
+ schema.fields[1].description = "Write content in {{ language }}."
+ provider = MagicMock()
+ provider.get_memory_schemas.return_value = [schema]
+ provider.get_output_language.return_value = language
+ provider.get_tools.return_value = []
+ provider.get_extract_context.return_value = SimpleNamespace(page_id_map=PageIdMap())
+ provider.read_file_contents = {}
+ provider.instruction.return_value = "Extract memory operations."
+ provider.prefetch = AsyncMock(return_value=[])
+ vlm = SimpleNamespace(
+ model="test-model", get_completion_async=AsyncMock(return_value="sdk.commit()")
+ )
+ loop = ExtractLoop(vlm=vlm, viking_fs=MagicMock(), context_provider=provider, max_iterations=1)
+ empty = ResolvedOperations(upsert_operations=[], delete_file_contents=[], errors=[])
+ loop.resolve_operations = AsyncMock(return_value=(empty, []))
+ loop._check_unread_existing_files = AsyncMock(return_value={})
+ # Exercise the default protocol selection rather than explicitly choosing Python.
+ config = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))
+ with (
+ patch("openviking.session.memory.extract_loop.get_openviking_config", return_value=config),
+ patch("openviking_cli.utils.config.get_openviking_config", return_value=config),
+ ):
+ operations, _ = await loop.run()
+
+ assert operations is empty
+ prompt = vlm.get_completion_async.call_args.kwargs["messages"][0]["content"]
+ assert "restricted Python memory SDK" in prompt
+ assert f"Preferences in {language}." in prompt
+ assert f"Write content in {language}." in prompt
+ assert "{{ language }}" not in prompt
+
+
def test_python_contract_omits_link_rules_when_disabled():
context = _context([_preference_schema()], link_enabled=False)
protocol = create_extraction_output_protocol("python")