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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Tests for JSON and restricted-Python memory extraction output protocols."""
import json
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from openviking.session.memory.account_templates import memory_template_data
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
def _preference_schema(*, operation_mode: str = "upsert") -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type="preferences",
description="User preferences",
directory="viking://user/{{ user_space }}/memories/preferences",
filename_template="{{ topic }}.md",
operation_mode=operation_mode,
fields=[
MemoryField(
name="topic",
field_type=FieldType.STRING,
merge_op=MergeOp.IMMUTABLE,
),
MemoryField(
name="content",
field_type=FieldType.STRING,
merge_op=MergeOp.PATCH,
),
MemoryField(
name="score",
field_type=FieldType.INT64,
merge_op=MergeOp.SUM,
),
],
)
def _project_schema() -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type="projects",
description="Projects",
directory="viking://user/{{ user_space }}/memories/projects",
filename_template="{{ name }}.md",
fields=[
MemoryField(
name="name",
field_type=FieldType.STRING,
merge_op=MergeOp.IMMUTABLE,
),
MemoryField(
name="content",
field_type=FieldType.STRING,
merge_op=MergeOp.REPLACE,
),
],
)
def _renameable_entity_schema() -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type="entities",
description="Entities",
directory="viking://user/{{ user_space }}/memories/entities",
filename_template="{{ category }}/{{ name }}.md",
fields=[
MemoryField(
name="category",
field_type=FieldType.STRING,
merge_op=MergeOp.REPLACE,
),
MemoryField(
name="name",
field_type=FieldType.STRING,
merge_op=MergeOp.REPLACE,
),
MemoryField(
name="content",
field_type=FieldType.STRING,
merge_op=MergeOp.PATCH,
),
],
)
def _profile_schema() -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type="profile",
description="User profile",
directory="viking://user/{{ user_space }}/memories",
filename_template="profile.md",
fields=[
MemoryField(
name="content",
field_type=FieldType.STRING,
merge_op=MergeOp.PATCH,
)
],
)
def _context(
schemas: list[MemoryTypeSchema],
*,
files: list[MemoryFile] | None = None,
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, template_context=template_context
).create_structured_operations_model(role_scope)
page_id_map = PageIdMap()
read_file_contents = {}
for memory_file in files or []:
read_file_contents[memory_file.uri] = memory_file
page_id_map.get_page_id(memory_file.uri)
return ExtractionOutputContext(
operations_model=operations_model,
schemas=tuple(schemas),
page_id_map=page_id_map,
read_file_contents=read_file_contents,
link_enabled=link_enabled,
role_scope=role_scope,
available_tools=available_tools,
template_context=dict(template_context or {}),
)
def _existing_preference(uri: str, topic: str, content: str, score: int = 0) -> MemoryFile:
return MemoryFile(
uri=uri,
memory_type="preferences",
content=content,
extra_fields={
"topic": topic,
"score": score,
"version": 7,
"_uri": uri,
},
)
def _bind(protocol, context: ExtractionOutputContext) -> str:
protocol.render_contract(context)
return protocol.render_new_bindings(context, source="test read")
def test_json_protocol_preserves_stable_parser_and_empty_contract():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("json")
operations, error = protocol.parse(
'{"preferences": [], "delete_ids": [], "ignored": true}', context
)
assert error is None
assert operations.model_dump() == {"preferences": [], "delete_ids": []}
assert '"preferences": []' in protocol.render_final_instruction(context)
assert '"delete_ids": []' in protocol.render_final_instruction(context)
assert protocol.parse('{"memory_operations": [{"type": "edit"}]}', context) == (
None,
"No expected fields found; got fields: memory_operations",
)
def test_python_contract_and_bindings_expose_only_selected_schema_fields():
uri = "viking://user/alice/memories/preferences/editor.md"
body = 'Use Vim\n Keep "quotes", tabs\tand 中文; literal \\n.'
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", body, 2)],
)
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
bindings = protocol.render_new_bindings(context, source="search then read")
assert "sdk.create_preferences" in contract
assert "sdk.create_projects" not in contract
record = json.loads(bindings.split("\n", 1)[1])
assert record == {
"object_name": "preferences_1",
"memory_type": "preferences",
"fields": {"topic": "editor", "score": 2, "content": body},
}
assert "Existing-memory records are input context only." in contract
assert "Use each object_name as an already-bound variable" in contract
assert "sdk.existing" not in contract
assert "sdk.existing(" not in bindings
assert protocol.binding_name(uri) == record["object_name"]
assert "version" not in bindings
assert uri not in bindings
assert protocol.render_new_bindings(context, source="duplicate read") == ""
def test_python_update_preserves_unchanged_mutable_identity_fields():
uri = "viking://user/alice/memories/entities/person/阿珍.md"
file = MemoryFile(
uri=uri,
memory_type="entities",
content="大学室友",
extra_fields={"category": "person", "name": "阿珍"},
)
context = _context([_renameable_entity_schema()], files=[file])
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"entities_1.update(name='陈静娴')\nsdk.commit()",
context,
)
assert error is None
assert operations.entities[0].category == "person"
assert operations.entities[0].name == "陈静娴"
def test_python_contract_includes_link_rules_when_enabled():
context = _context([_preference_schema()], link_enabled=True)
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
assert "## Link Rules" in contract
assert "obj.link(target" in contract
assert "weight=0.5" in contract
assert "description=''" in contract
assert "match_text" in contract
assert "obj_a.link(" in contract
assert "assign the create/set call to a variable first" in contract
@pytest.mark.parametrize("language", ["en", "zh-CN"])
@pytest.mark.parametrize(
("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"})
protocol = create_extraction_output_protocol("python")
contract = protocol.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
assert "copied verbatim" in contract
assert "occur exactly once" in contract
assert "## Patch Context Rules" in protocol.render_context_rules(context)
@pytest.mark.parametrize("output_format", ["python", "json"])
def test_output_contract_preserves_core_add_only_and_upsert_capabilities(output_format):
context = _context([_preference_schema(operation_mode="add_only")], available_tools=())
protocol = create_extraction_output_protocol(output_format)
contract = protocol.render_contract(context)
rules = protocol.render_reference_rules(context)
assert "Create new memories only, with complete field values" in contract + rules
assert protocol.render_context_rules(context) == ""
for unsupported in (
"obj.update",
"obj.content.edit",
"obj.content.drop",
"replacement=",
):
assert unsupported not in contract + rules + protocol.render_final_instruction(context)
assert "delete_ids" not in rules + protocol.render_final_instruction(context)
program = (
'sdk.create_preferences(topic="editor", content="""Use Vim""", score=1)\nsdk.commit()'
if output_format == "python"
else '{"preferences": [{"page_id": 100, "topic": "editor", "content": "Use Vim", "score": 1}]}'
)
operations, error = protocol.parse(program, context)
assert error is None
assert operations.preferences[0].content == "Use Vim"
# A mixed batch must retain upsert/delete support, without teaching patches
# from an add-only schema or exposing inspection tools it does not have.
mixed = _context(
[_preference_schema(operation_mode="add_only"), _project_schema()], available_tools=()
)
rules = protocol.render_reference_rules(mixed)
contract = protocol.render_contract(mixed)
assert "replacement" in rules
assert "preserving every unaffected fact" in rules
assert protocol.render_context_rules(mixed) == ""
if output_format == "python":
assert "obj.content.update(" in contract
assert "obj.delete(replacement=None)" in contract
assert "obj.content.edit" not in contract
assert "obj.content.drop" not in contract
assert "call the available native" not in contract.lower()
assert "never drop a unique fact" in rules
else:
assert "When editing an existing item" in rules
assert "DELETE blocks" not in rules
@pytest.mark.asyncio
@pytest.mark.parametrize("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
assert "## Read Format Rules" not in prompt
assert "## Patch Context Rules" in prompt
def test_python_contract_omits_link_rules_when_disabled():
context = _context([_preference_schema()], link_enabled=False)
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
assert "## Link Rules" not in contract
assert "obj.link(...) is unavailable" in contract
def test_python_protocol_compiles_extracted_code_from_fence():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
compiled = []
def record_compile(self, code):
compiled.append(code)
return context.operations_model(preferences=[], delete_ids=[])
with patch(
"openviking.session.memory.extraction_output_protocol.python_protocol._PythonProgramCompiler.compile",
autospec=True,
side_effect=record_compile,
):
operations, error = protocol.parse("```python\nsdk.commit()\n```", context)
assert error is None
assert operations is not None
# The fenced code (not the raw fence wrapper) is what gets compiled.
assert compiled == ["sdk.commit()"]
def test_json_protocol_preserves_tool_result_context_shape():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("json")
result = {"memory_type": "preferences", "content": "1\tUse Vim"}
messages = protocol.render_tool_result_messages(
context,
call_id="call-1",
tool_name="read",
params={"uri": "viking://user/alice/memories/preferences/editor.md"},
result=result,
source="tool call",
)
assert messages == [
{
"role": "user",
"content": json.dumps(
{
"tool_call_name": "read",
"args": {"uri": "viking://user/alice/memories/preferences/editor.md"},
"result": result,
},
ensure_ascii=False,
),
}
]
def test_python_protocol_renders_search_result_as_read_tool_comment():
uri_a = "viking://user/alice/memories/entities/person/tim.md"
uri_b = "viking://user/alice/memories/entities/person/maria.md"
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
messages = protocol.render_tool_result_messages(
context,
call_id="call-1",
tool_name="search",
params={"query": "tim maria"},
result=[{"uri": uri_a, "score": 0.9}, {"uri": uri_b, "score": 0.8}],
source="tool call",
)
assert len(messages) == 1
content = messages[0]["content"]
assert content.startswith("# Search")
assert "query='tim maria'" in content
assert "read them with the read tool" in content
assert f"# - {uri_a}" in content
assert f"# - {uri_b}" in content
# Search yields no content, so it must not register an existing object.
assert "sdk.existing(" not in content
assert protocol.binding_name(uri_a) is None
assert protocol.binding_name(uri_b) is None
assert "search_results" not in content
assert "0.9" not in content
def test_python_protocol_renders_empty_search_result_as_comment():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
messages = protocol.render_tool_result_messages(
context,
call_id="call-1",
tool_name="search",
params={"query": "nobody"},
result=[],
source="tool call",
)
assert messages[0]["content"] == "# Search query='nobody' found no memory files."
def test_python_protocol_search_comment_omits_read_tool_when_unavailable():
uri = "viking://user/alice/memories/entities/person/tim.md"
# eager_prefetch preloads everything and exposes no tools to the model.
context = _context([_preference_schema()], available_tools=())
protocol = create_extraction_output_protocol("python")
messages = protocol.render_tool_result_messages(
context,
call_id="call-1",
tool_name="search",
params={"query": "tim"},
result=[{"uri": uri, "score": 0.9}],
source="prefetch",
)
content = messages[0]["content"]
assert "read them with the read tool" not in content
assert "there is no read tool" in content
assert "treat anything not shown above as new" in content
assert f"# - {uri}" in content
def test_python_protocol_renders_read_result_directly_as_existing_binding():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nKeep plugins small", 2)],
)
protocol = create_extraction_output_protocol("python")
protocol.render_contract(context)
messages = protocol.render_tool_result_messages(
context,
call_id="call-1",
tool_name="read",
params={"uri": uri, "offset": 1, "limit": 1},
result={
"memory_type": "preferences",
"topic": "editor",
"score": 2,
"content": "2\tKeep plugins small",
"page_id": 1,
"memory_maintenance_notice": {
"maintenance_required": True,
"guidance": "choose split or compact",
},
},
source="tool call",
)
assert len(messages) == 1
content = messages[0]["content"]
assert content.startswith("# Existing memory loaded by tool call")
record = json.loads(content.split("\n", 1)[1].split("\n# Memory maintenance notice:", 1)[0])
assert record["object_name"] == "preferences_1"
assert record["fields"]["content"] == "Keep plugins small"
assert "sdk.existing(" not in content
assert "2\\tKeep plugins small" not in content
assert "Use Vim" not in content
assert "tool_call_name" not in content
assert "page_id" not in content
assert uri not in content
assert "# Memory maintenance notice:" in content
assert '"maintenance_required": true' in content
assert "estimated_tokens" not in content
assert "content_characters" not in content
assert "choose split or compact" in content
reread = protocol.render_tool_result_messages(
context,
call_id="call-2",
tool_name="read",
params={"uri": uri},
result={"content": "Use Neovim\nKeep plugins small"},
source="tool call",
)
updated_record = json.loads(reread[0]["content"].split("\n", 1)[1])
assert updated_record["object_name"] == record["object_name"]
assert updated_record["fields"]["content"] == "Use Neovim\nKeep plugins small"
assert protocol.render_new_bindings(context, source="after reread") == ""
def test_python_protocol_converts_prefetch_tool_messages_without_duplicating_read_content():
uri = "viking://user/alice/memories/preferences/editor.md"
source_uri = "viking://user/alice/memories/trajectories/source.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim", 2)],
)
protocol = create_extraction_output_protocol("python")
protocol.render_contract(context)
prefetched = [
{"role": "user", "content": "Conversation History"},
{
"role": "user",
"content": json.dumps(
{
"tool_call_name": "search",
"args": {"query": "editor"},
"result": [{"uri": uri, "score": 0.9}],
}
),
},
{
"role": "user",
"content": json.dumps(
{
"tool_call_name": "read",
"args": {"uri": uri},
"result": {
"memory_type": "preferences",
"topic": "editor",
"score": 2,
"content": "1\tUse Vim",
},
}
),
},
]
prefetched.append(
{
"role": "user",
"content": json.dumps(
{
"tool_call_name": "read",
"args": {"uri": source_uri},
"result": {
"context_role": "candidate_source_trajectory",
"content": "Read-only source trajectory",
},
}
),
}
)
messages = protocol.render_prefetch_messages(prefetched, context)
combined = "\n".join(message["content"] for message in messages)
assert messages[0]["content"] == "Conversation History"
# Search only yields URIs, so it renders as a read-tool comment, not a binding.
assert "read them with the read tool" in combined
assert f"# - {uri}" in combined
assert "search_results = [" not in combined
# Only the writable memory gets an object reference; source trajectories stay read-only.
assert '"object_name": "preferences_1"' in combined
assert "sdk.existing(" not in combined
assert combined.count("Use Vim") == 1
assert "tool_call_name" not in combined
assert '"result"' not in combined
assert "Read-only context; this is not a mutable memory object." in combined
assert protocol.binding_name(source_uri) is None
operations, error = protocol.parse(
'preferences_1.content.edit(search="Use Vim", replace="Use Neovim")\nsdk.commit()',
context,
)
assert error is None
assert operations.model_dump()["preferences"][0]["content"]["blocks"] == [
{"search": "Use Vim", "replace": "Use Neovim"}
]
operations, error = protocol.parse(
'candidate_source_trajectory.content.update("not allowed")', context
)
assert operations is None and "unknown name" in error
def test_python_contract_uses_set_for_single_file_schema_and_create_for_collection():
context = _context(
[_profile_schema(), _preference_schema()],
role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),
)
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
assert "sdk.set_profile" in contract
assert "- sdk.create_profile(*," not in contract
assert (
"profile is a SINGLETON per identity: sdk.create_profile() does not exist, and "
"sdk.set_profile() must appear AT MOST ONCE for each identity"
) in contract
assert (
"Current identity peer_id='bob': exactly one "
"sdk.set_profile(peer_id='bob', ...) call; combine every person and section"
) in contract
assert "Memory type rules:" in contract
assert "User profile" in contract
assert "sdk.create_preferences" in contract
assert "sdk.set_preferences" not in contract
assert "canonical = sdk.create_<type>(...)" in contract
assert "duplicate_1.delete(replacement=canonical)" in contract
assert "Identity fields (primary key): peer_id." in contract
assert "Identity fields (primary key): peer_id, topic." in contract
assert "Current self identity: exactly one sdk.set_profile() call without peer_id" in contract
def test_python_reserved_existing_retry_explains_new_replacement_binding():
protocol = create_extraction_output_protocol("python")
retry = protocol.render_format_retry(
"Line 3: sdk.existing() is reserved for system-provided bindings"
)
assert "object_name from the system-provided existing-memory context record" in retry
assert "already-bound variable" in retry
assert "canonical = sdk.create_<type>(...)" in retry
assert "duplicate_1.delete(replacement=canonical)" in retry
def test_python_string_literal_retry_pushes_triple_quotes():
protocol = create_extraction_output_protocol("python")
retry = protocol.render_format_retry("Line 33: invalid syntax. Perhaps you forgot a comma?")
assert "offending line is shown above" in retry
assert 'triple-quoted string ("""...""")' in retry
def test_python_non_string_syntax_error_omits_quote_guidance():
protocol = create_extraction_output_protocol("python")
retry = protocol.render_format_retry("Line 3: unexpected indent")
assert "offending line is shown above" not in retry
def test_resolution_repair_matches_protocol_output_shape():
issues = [
{
"memory_type": "events",
"page_id": 100,
"reason_code": "no_writable_target",
"reason": "range out of bounds",
"operation": {"event_name": "yoga_class_started", "ranges": "99"},
}
]
json_repair = create_extraction_output_protocol("json").render_resolution_repair(issues)
assert "ONLY one JSON object" in json_repair
assert "yoga_class_started" in json_repair
python_repair = create_extraction_output_protocol("python").render_resolution_repair(issues)
assert "sdk.create_events" in python_repair
assert "Output only Python code." in python_repair
assert "JSON object" not in python_repair
def _kebab_schema() -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type="project-notes",
description="Project notes",
directory="viking://user/{{ user_space }}/memories/project-notes",
filename_template="{{ project_name }}.md",
fields=[
MemoryField(
name="project_name",
field_type=FieldType.STRING,
merge_op=MergeOp.IMMUTABLE,
),
MemoryField(
name="note-body",
field_type=FieldType.STRING,
merge_op=MergeOp.PATCH,
),
],
)
def test_python_contract_aliases_non_identifier_schema_names():
context = _context([_kebab_schema()])
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
# Method/parameter names are folded to valid identifiers on the DSL surface.
assert "sdk.create_project_notes(" in contract
assert "note_body" in contract
assert "sdk.create_project-notes" not in contract
def test_python_compiles_aliased_names_back_to_real_schema():
context = _context([_kebab_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"""
sdk.create_project_notes(
project_name="atlas",
note_body=\"\"\"Kickoff on 2023-06-09.\"\"\",
)
sdk.commit()
""",
context,
)
assert error is None, error
dumped = operations.model_dump()
# Real schema name and real field name are preserved in the operations.
assert dumped["project-notes"] == [
{"page_id": 100, "project_name": "atlas", "note-body": "Kickoff on 2023-06-09."}
]
def test_python_edits_aliased_field_on_existing_object():
existing = MemoryFile(
uri="viking://user/alice/memories/project-notes/atlas.md",
memory_type="project-notes",
content="",
extra_fields={
"project_name": "atlas",
"note-body": "Kickoff on 2023-06-09.",
"version": 3,
"_uri": "x",
},
)
context = _context([_kebab_schema()], files=[existing])
protocol = create_extraction_output_protocol("python")
bindings = _bind(protocol, context)
# Existing-object binding exposes the field under its identifier alias.
record = json.loads(bindings.split("\n", 1)[1])
assert record["fields"]["note_body"] == "Kickoff on 2023-06-09."
assert "note-body" not in record["fields"]
var = record["object_name"]
operations, error = protocol.parse(
f"""
{var}.note_body.edit(search=\"\"\"Kickoff on 2023-06-09.\"\"\", replace=\"\"\"Kickoff moved to 2023-07-01.\"\"\")
sdk.commit()
""",
context,
)
assert error is None, error
edited = operations.model_dump()["project-notes"]
assert edited and edited[0]["page_id"] == 1
def _schema_named(memory_type: str, field_names: list[str]) -> MemoryTypeSchema:
return MemoryTypeSchema(
memory_type=memory_type,
description=memory_type,
directory=f"viking://user/{{{{ user_space }}}}/memories/{memory_type}",
filename_template="{{ name }}.md",
fields=[
MemoryField(name=name, field_type=FieldType.STRING, merge_op=MergeOp.PATCH)
for name in field_names
],
)
def test_python_rejects_colliding_memory_type_aliases():
# 'project-notes' and 'project_notes' both fold to the same DSL alias.
context = _context(
[_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]
)
protocol = create_extraction_output_protocol("python")
with pytest.raises(ValueError, match="same Python DSL alias"):
protocol.render_contract(context)
def test_python_rejects_colliding_field_aliases():
# 'note-body' and 'note_body' collide within one schema.
context = _context([_schema_named("notes", ["note-body", "note_body"])])
protocol = create_extraction_output_protocol("python")
with pytest.raises(ValueError, match="same Python DSL alias"):
protocol.render_contract(context)
def test_python_parse_rejects_colliding_aliases_without_render():
# Collision must be caught even when parse() runs without render_contract().
context = _context(
[_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]
)
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse("sdk.commit()", context)
assert operations is None
assert "same Python DSL alias" in error
def test_python_syntax_error_includes_offending_source_line():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
# A double-quoted summary that itself embeds a double quote ends the string
# early; the compiler should surface the real offending line, not just the
# misleading "forgot a comma" hint.
_operations, error = protocol.parse(
'sdk.create_preferences(topic="x", content="he saw "Little Women" today", score=1)',
context,
)
assert error is not None
assert "invalid Python syntax" in error
assert "Little Women" in error
assert "^" in error
@pytest.mark.parametrize("ending", ["sdk.commit(", "sdk.commit())"])
@pytest.mark.parametrize(
"wrapper", ["{}", "```python\n{}\n```", "Explanation\n```python\n{}\n```\nDone."]
)
def test_python_rejects_invalid_program_containing_fenced_example(ending, wrapper):
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
program = (
'sdk.set_profile(content="""Example:\n```python\nsdk.commit()\n```\n'
f'Keep this example.""")\n{ending}'
)
operations, error = protocol.parse(wrapper.format(program), context)
assert operations is None
assert error is not None
def test_memory_schema_identity_fields_follow_scope_and_uri_template():
entities = MemoryTypeSchema(
memory_type="entities",
directory="viking://user/{{ user_space }}/memories/entities",
filename_template="{{ category|lower }}/{{ name|lower }}.md",
fields=[
MemoryField(name="category", field_type=FieldType.STRING),
MemoryField(name="name", field_type=FieldType.STRING),
MemoryField(name="content", field_type=FieldType.STRING),
],
)
preferences = MemoryTypeSchema(
memory_type="preferences",
directory="viking://user/{{ user_space }}/memories/preferences",
filename_template="{{ user }}/{{ topic }}.md",
fields=[
MemoryField(name="user", field_type=FieldType.STRING),
MemoryField(name="topic", field_type=FieldType.STRING),
MemoryField(name="content", field_type=FieldType.STRING),
],
)
assert _profile_schema().identity_fields() == ("peer_id",)
assert preferences.identity_fields() == ("peer_id", "user", "topic")
assert entities.identity_fields() == ("peer_id", "category", "name")
def test_memory_schema_identity_fields_ignore_jinja_token_collisions():
# `year` and `context` appear only inside a filter/function/attribute
# expression, never as referenced variables, so they must not be treated
# as identity fields. Only `ranges` and `event_name` are real references.
events = MemoryTypeSchema(
memory_type="events",
directory="viking://user/{{ user_space }}/memories/events",
filename_template="{{ extract_context.get_year(ranges) }}/{{ event_name }}.md",
fields=[
MemoryField(name="event_name", field_type=FieldType.STRING),
MemoryField(name="ranges", field_type=FieldType.STRING),
MemoryField(name="year", field_type=FieldType.STRING),
MemoryField(name="context", field_type=FieldType.STRING),
MemoryField(name="content", field_type=FieldType.STRING),
],
)
assert events.identity_fields() == ("peer_id", "event_name", "ranges")
@pytest.mark.parametrize(
"content",
[
"Engineer",
'Config:\n```nginx\nadd_header Cache-Control "no-cache";\n```\nDone.',
"Example:\n```python\nsdk.commit()\n```\nKeep this example.",
"Use the literal ``` marker.",
"```text\nfirst\n```\n```python\nsdk.commit()\n```",
],
)
@pytest.mark.parametrize(
"wrapper",
["{}", "```python\n{}\n```", "Explanation\n```python\n{}\n```\nDone."],
)
def test_python_set_single_file_memory_compiles_to_same_operations_as_json(content, wrapper):
context = _context([_profile_schema()])
python_protocol = create_extraction_output_protocol("python")
json_protocol = create_extraction_output_protocol("json")
python_operations, python_error = python_protocol.parse(
wrapper.format(f'sdk.set_profile(content="""{content}""")\nsdk.commit()'),
context,
)
json_operations, json_error = json_protocol.parse(
json.dumps({"profile": [{"page_id": 100, "content": content}], "delete_ids": []}),
context,
)
assert python_error is None
assert json_error is None
assert python_operations.model_dump() == json_operations.model_dump()
def test_python_commit_is_optional():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
# A program without a trailing sdk.commit() is accepted as-is.
without_commit, error = protocol.parse("sdk.set_profile(content='Engineer')", context)
assert error is None
assert without_commit.model_dump()["profile"][0]["content"] == "Engineer"
# An empty program means "no changes".
empty_operations, empty_error = protocol.parse("", context)
assert empty_error is None
assert empty_operations.model_dump() == {"profile": [], "delete_ids": []}
def test_python_rejects_create_for_single_file_and_set_for_collection():
context = _context([_profile_schema(), _preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"sdk.create_profile(content='Engineer')\nsdk.commit()", context
)
assert operations is None
assert "use sdk.set_profile()" in error
operations, error = protocol.parse(
"sdk.set_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",
context,
)
assert operations is None
assert "use sdk.create_preferences()" in error
def test_python_rejects_repeated_single_file_set_for_same_peer_scope():
context = _context(
[_profile_schema()],
role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),
)
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"""
sdk.set_profile(peer_id="bob", content="Engineer")
sdk.set_profile(peer_id="bob", content="Musician")
sdk.commit()
""",
context,
)
assert operations is None
assert "duplicate profile identity (peer_id='bob')" in error
assert "may be called only once for peer 'bob'" in error
assert "combine all people and content sections" in error
def test_python_rejects_repeated_single_file_set_for_self_scope():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"""
sdk.set_profile(content="Engineer")
sdk.set_profile(content="Musician")
sdk.commit()
""",
context,
)
assert operations is None
assert "may be called only once for self" in error
def test_python_allows_one_single_file_set_per_peer_scope():
context = _context(
[_profile_schema()],
role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
)
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"""
sdk.set_profile(peer_id="bob", content="Engineer")
sdk.set_profile(peer_id="carol", content="Musician")
sdk.commit()
""",
context,
)
assert error is None
assert operations.model_dump()["profile"] == [
{"peer_id": "bob", "page_id": 100, "content": "Engineer"},
{"peer_id": "carol", "page_id": 101, "content": "Musician"},
]
def test_python_create_compiles_to_same_operations_as_json():
context = _context([_preference_schema()])
python_protocol = create_extraction_output_protocol("python")
json_protocol = create_extraction_output_protocol("json")
python_operations, python_error = python_protocol.parse(
"""
topic = "editor".upper().lower()
score = len([1, 2]) + 1
sdk.create_preferences(
topic=topic,
content=f"Use {topic}",
score=score,
ignored=unknown_name_that_must_not_be_evaluated,
)
sdk.commit()
""",
context,
)
json_operations, json_error = json_protocol.parse(
"""
{
"preferences": [
{"page_id": 100, "topic": "editor", "content": "Use editor", "score": 3}
],
"delete_ids": []
}
""",
context,
)
assert python_error is None
assert json_error is None
assert python_operations.model_dump() == json_operations.model_dump()
def test_python_create_avoids_existing_page_id_collisions():
context = _context([_preference_schema()])
context.page_id_map.register_new_page_id("viking://existing/100.md", 100)
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"sdk.create_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",
context,
)
assert error is None
assert operations.model_dump()["preferences"][0]["page_id"] == 101
def test_python_protocol_includes_dynamic_peer_id_field():
schema = _preference_schema()
context = _context(
[schema],
role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
)
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
operations, error = protocol.parse(
"sdk.create_preferences(peer_id='bob', topic='editor', content='Use Vim', score=1)\nsdk.commit()",
context,
)
assert "peer_id: str" in contract
assert "Available peer_id values in this session: bob, carol" in contract
assert error is None
assert operations.model_dump()["preferences"][0]["peer_id"] == "bob"
def test_python_existing_binding_exposes_but_does_not_update_dynamic_peer_id():
schema = _preference_schema()
memory_file = _existing_preference(
"viking://user/alice/peers/bob/memories/preferences/editor.md",
"editor",
"Use Vim",
)
memory_file.extra_fields["peer_id"] = "bob"
context = _context(
[schema],
files=[memory_file],
role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
)
protocol = create_extraction_output_protocol("python")
bindings = _bind(protocol, context)
operations, error = protocol.parse(
"preferences_1.update(peer_id='carol')\npreferences_1.content.update('Use Emacs')\nsdk.commit()",
context,
)
assert json.loads(bindings.split("\n", 1)[1])["fields"]["peer_id"] == "bob"
assert error is None
item = operations.model_dump()["preferences"][0]
assert item["content"] == "Use Emacs"
assert item["peer_id"] is None
def test_python_existing_updates_emit_patch_blocks_and_accumulate_sum_delta():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nDark theme\nTabs", 10)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
preferences_1.update(score=2)
preferences_1.content.drop(text="Tabs")
preferences_1.update(
topic="ignored immutable change",
score=3,
unknown_field="ignored",
another_unknown=unknown_name_that_must_not_be_evaluated,
)
sdk.commit()
""",
context,
)
assert error is None
# edit/drop are emitted as StrPatch blocks (applied later by the shared path),
# while SUM deltas still accumulate at compile time.
item = operations.model_dump()["preferences"][0]
assert item["page_id"] == 1
assert item["topic"] == "editor"
assert item["score"] == 5
assert item["content"]["blocks"] == [
{"search": "Use Vim", "replace": "Use Neovim"},
{"delete": "Tabs"},
]
def test_python_patch_preserves_unescaped_markers_in_blocks():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "<<<<<<< literal", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
r"""
preferences_1.content.edit(search=r"\<<<<<<< literal", replace="plain")
sdk.commit()
""",
context,
)
assert error is None
blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
assert blocks == [{"search": r"\<<<<<<< literal", "replace": "plain"}]
def test_python_field_edit_chain_emits_blocks_in_order():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
preferences_1.content.edit(search="Use Vim", replace="Use Neovim").drop(text="Dark theme")
sdk.commit()
""",
context,
)
assert error is None
blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
assert blocks == [
{"search": "Use Vim", "replace": "Use Neovim"},
{"delete": "Dark theme"},
]
@pytest.mark.parametrize("supersedes", [None, "", "older_pattern"])
def test_python_experience_supersedes_is_optional(supersedes):
registry = MemoryTypeRegistry(load_schemas=False)
registry.load_from_yaml(str(resolve_memory_templates_dir() / "experiences.yaml"))
schema = registry.get("experiences")
schema = registry._parse_memory_type(memory_template_data(schema))
context = _context([schema])
protocol = create_extraction_output_protocol("python")
argument = "" if supersedes is None else f", supersedes={supersedes!r}"
operations, error = protocol.parse(
f"sdk.create_experiences(experience_name='pattern', content='insight'{argument})\n"
"sdk.commit()",
context,
)
assert error is None
assert operations.model_dump()["experiences"][0]["supersedes"] == supersedes
assert "supersedes is optional; may be omitted" in protocol.render_contract(context)
@pytest.mark.parametrize(
"filename_template, verb", [("{{ topic }}.md", "create"), ("fixed.md", "set")]
)
def test_python_optional_fields_do_not_relax_required_fields(filename_template, verb):
schema = _preference_schema()
schema.filename_template = filename_template
schema.fields[1].init_value = "initial content"
schema.fields[-1] = MemoryField(
name="score", field_type=FieldType.INT64, merge_op=MergeOp.SUM, required=False
)
context = _context([schema])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
f"sdk.{verb}_preferences(topic='editor', content='Use Vim')\nsdk.commit()", context
)
assert error is None
assert operations.model_dump()["preferences"][0]["score"] is None
operations, error = protocol.parse(
f"sdk.{verb}_preferences(topic='editor')\nsdk.commit()", context
)
assert operations is None
assert "missing: content" in error
@pytest.mark.parametrize("memory_type", ["experiences", "entities"])
@pytest.mark.parametrize("method", ['edit(search="old", replace="new")', 'drop(text="old")'])
def test_python_builtin_content_edit_accepts_replace_but_keeps_update_guidance(memory_type, method):
registry = MemoryTypeRegistry(load_schemas=False)
registry.load_from_yaml(str(resolve_memory_templates_dir() / f"{memory_type}.yaml"))
schema = registry.get(memory_type)
assert schema is not None
context = _context(
[schema],
files=[
MemoryFile(
uri=f"viking://user/alice/memories/{memory_type}/one.md",
memory_type=memory_type,
content="old text",
extra_fields=(
{"experience_name": "one", "supersedes": ""}
if memory_type == "experiences"
else {"category": "concept", "name": "one"}
),
)
],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(f"{memory_type}_1.content.{method}", context)
assert error is None
assert operations is not None
assert operations.model_dump()[memory_type][0]["content"]["blocks"]
if memory_type == "experiences":
contract = protocol.render_contract(context)
rules = protocol.render_reference_rules(context)
assert "obj.content.update(" in contract
assert "obj.content.edit(" not in contract
assert "obj.content.drop(" not in contract
assert "delete(replacement=canonical)" in rules
assert "never drop a unique fact" in rules
operations, error = protocol.parse(
'experiences_1.content.update("complete new value")', context
)
assert error is None
assert operations.model_dump()[memory_type][0]["content"] == "complete new value"
def test_python_field_update_replaces_whole_field():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
'''
preferences_1.content.update("""# Editor
- Use Neovim""")
sdk.commit()
''',
context,
)
assert error is None
assert operations.model_dump()["preferences"][0]["content"] == "# Editor\n- Use Neovim"
def test_python_field_edit_emits_block_even_when_search_absent():
# Matching/rejection is now the shared validation path's job (json parity),
# so parse() succeeds and just emits the block; a bad snippet no longer fails
# the whole program at compile time.
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
preferences_1.content.edit(search="Prefers Neovim", replace="Prefers Emacs")
sdk.commit()
""",
context,
)
assert error is None
blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
assert blocks == [{"search": "Prefers Neovim", "replace": "Prefers Emacs"}]
def test_python_unknown_field_is_silently_ignored():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"preferences_1.field.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",
context,
)
# Unknown field access is a no-op: the statement compiles without
# touching server state and the whole program still commits.
assert error is None
assert operations is not None
assert operations.preferences == []
def test_python_unknown_field_does_not_block_sibling_updates():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
preferences_1.bogus.update("ignored")
preferences_1.bogus.edit(search="Use Vim", replace="Use Neovim")
preferences_1.bogus.drop(text="Tabs")
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
sdk.commit()
""",
context,
)
assert error is None
item = operations.model_dump()["preferences"][0]
# The bogus field is silently dropped; the real content edit still applies.
assert item["content"]["blocks"] == [
{"search": "Use Vim", "replace": "Use Neovim"},
]
def test_python_field_edit_emits_block_regardless_of_uniqueness():
# Uniqueness enforcement now lives in the shared validation path, so parse()
# just emits the block; matching (and any non-unique rejection) happens later.
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nUse Vim", 0)],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"preferences_1.content.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",
context,
)
assert error is None
blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]
@pytest.mark.parametrize(
"operation",
[
"preferences_1.content.edit(search='Use Vim', replace='Use Neovim')",
"preferences_1.content.drop(text='Dark theme')",
],
)
def test_python_field_edit_and_drop_are_standalone_statements(operation: str):
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim\nDark theme")],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(f"x = {operation}\nsdk.commit()", context)
assert operations is None
assert "must be standalone statements" in error
def test_python_delete_replacement_and_links_compile_with_page_id_remapping():
duplicate = _existing_preference(
"viking://user/alice/memories/preferences/duplicate.md",
"duplicate",
"duplicate content",
)
project = MemoryFile(
uri="viking://user/alice/memories/projects/openviking.md",
memory_type="projects",
content="Memory platform",
extra_fields={"name": "openviking"},
)
context = _context(
[_preference_schema(), _project_schema()],
files=[duplicate, project],
link_enabled=True,
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
canonical = sdk.create_preferences(topic="editor", content="Use Neovim", score=1)
preferences_1.link(projects_1, match_text="editor")
preferences_1.delete(replacement=canonical)
sdk.commit()
""",
context,
)
assert error is None
payload = operations.model_dump()
assert payload["preferences"] == [
{"page_id": 100, "topic": "editor", "content": "Use Neovim", "score": 1}
]
assert payload["delete_ids"] == [{"delete_page_id": 1, "replacement_page_id": 100}]
assert payload["links"] == [
{
"f": 100,
"t": 2,
"link_type": "related_to",
"weight": 0.5,
"match_text": "editor",
"description": "",
}
]
def test_python_update_after_delete_restores_object_and_delete_after_update_discards_update():
first = _existing_preference(
"viking://user/alice/memories/preferences/first.md", "first", "old one"
)
second = _existing_preference(
"viking://user/alice/memories/preferences/second.md", "second", "old two"
)
context = _context([_preference_schema()], files=[first, second])
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""
preferences_1.delete()
preferences_1.update(content="restored")
preferences_2.update(content="discarded")
preferences_2.delete()
preferences_1.link(preferences_2) if False else None
sdk.commit()
""",
context,
)
assert error is not None
assert operations is None
operations, error = protocol.parse(
"""
preferences_1.delete()
preferences_1.update(content="restored")
preferences_2.update(content="discarded")
preferences_2.delete()
sdk.commit()
""",
context,
)
assert error is None
payload = operations.model_dump()
assert payload["preferences"] == [
{"page_id": 1, "topic": "first", "content": "restored", "score": None}
]
assert payload["delete_ids"] == [{"delete_page_id": 2, "replacement_page_id": None}]
@pytest.mark.parametrize(
("program", "message"),
[
("sdk.commit()\nsdk.commit()", "final statement"),
("for item in []:\n pass\nsdk.commit()", "only assignments"),
("sdk.existing(memory_type='preferences')\nsdk.commit()", "reserved"),
("sdk.create_preferences(topic='x', content='y')\nsdk.commit()", "missing: score"),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\nx.delete()\nsdk.commit()",
"cannot be deleted",
),
(
"obj = sdk.create_preferences(topic='x', content='y', score=1)\n"
"obj.content.edit(search='y', replace='z')\nsdk.commit()",
"can only patch an existing memory",
),
(
"sdk.replace(search='x', replacement='y')\nsdk.commit()",
"unknown SDK method sdk.replace()",
),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\n"
"x.content.update('a', 'b')\nsdk.commit()",
"exactly one positional argument",
),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\nstr(x)\nsdk.commit()",
"memory objects cannot be converted",
),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\nitems = [x]\nsdk.commit()",
"memory objects cannot be stored",
),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\ntext = f'{x}'\nsdk.commit()",
"memory objects cannot be formatted",
),
(
"x = sdk.create_preferences(topic='x', content='y', score=1)\nx.update(content=x)\nsdk.commit()",
"memory objects cannot be used as business field values",
),
(
"sdk.create_preferences(topic='x', content='y', score=1).update(content='z')\nsdk.commit()",
"assign a new memory object",
),
("import os\nsdk.commit()", "only assignments"),
("sdk.commit()\nprint('after')", "final statement"),
],
)
def test_python_rejects_invalid_or_unsafe_programs(program: str, message: str):
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(program, context)
assert operations is None
assert message in error
def test_python_rejects_delete_for_add_only_schema():
memory_file = _existing_preference(
"viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"
)
context = _context([_preference_schema(operation_mode="add_only")], files=[memory_file])
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)
assert operations is None
assert "delete() is unavailable" in error
def test_python_rejects_add_only_delete_when_another_schema_enables_deletes():
memory_file = _existing_preference(
"viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"
)
context = _context(
[_preference_schema(operation_mode="add_only"), _project_schema()],
files=[memory_file],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)
assert operations is None
assert "delete() is unavailable" in error
def test_python_aliases_non_identifier_memory_type_instead_of_raising():
schema = _preference_schema()
schema.memory_type = "user-preferences"
context = _context([schema])
protocol = create_extraction_output_protocol("python")
contract = protocol.render_contract(context)
assert "sdk.set_user_preferences(" in contract or "sdk.create_user_preferences(" in contract
assert "user-preferences" not in contract.split("Memory type rules")[0]
def test_python_accepts_one_fence_with_surrounding_text():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse("```python\nsdk.commit()\n```", context)
assert error is None
assert operations.model_dump() == {"preferences": [], "delete_ids": []}
operations, error = protocol.parse("Explanation\n```python\nsdk.commit()\n```", context)
assert error is None
assert operations.model_dump() == {"preferences": [], "delete_ids": []}
def test_python_accepts_trace_style_explanation_around_program():
context = _context(
[_preference_schema()],
files=[
_existing_preference(
"viking://user/alice/memories/preferences/editor.md",
"editor",
"Use Vim",
)
],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(
"""Update the existing preference.
```python
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
sdk.commit()
```
The program above applies the requested update.""",
context,
)
assert error is None
blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]
@pytest.mark.parametrize(
("call", "error_fragment"),
[
("sdk.read('viking://user/alice/memories/preferences/editor.md')", "sdk.read()"),
("read('viking://user/alice/memories/preferences/editor.md')", "function 'read'"),
("sdk.search('editor')", "sdk.search()"),
("search('editor')", "function 'search'"),
],
)
def test_python_read_search_errors_keep_native_tools_available_for_retry(
call: str, error_fragment: str
):
protocol = create_extraction_output_protocol("python")
context = _context([_preference_schema()])
operations, error = protocol.parse(
f"item = {call}\nsdk.commit()",
context,
)
assert operations is None
assert error_fragment in error
assert protocol.keep_tools_enabled_after_parse_error(error)
retry = protocol.render_format_retry(error)
assert "native read tool" in retry
assert "Do not emit sdk.search(), sdk.read()" in retry
def test_python_sdk_read_error_takes_priority_over_reassigning_existing_binding():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim")],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse(f"preferences_1 = sdk.read({uri!r})\nsdk.commit()", context)
assert operations is None
assert "unknown SDK method sdk.read()" in error
assert protocol.keep_tools_enabled_after_parse_error(error)
def test_python_object_read_error_keeps_native_tools_available_for_retry():
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "Use Vim")],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
operations, error = protocol.parse("preferences_1.read()\nsdk.commit()", context)
assert operations is None
assert "unknown memory method read()" in error
assert protocol.keep_tools_enabled_after_parse_error(error)
@pytest.mark.parametrize(
"program",
[
"```python\nsdk.commit()\n```\n```python\nsdk.commit()\n```",
"Explanation\n```python\nsdk.commit()\n```\n```text\nextra\n```",
],
)
def test_python_rejects_multiple_fences(program: str):
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(program, context)
assert operations is None
assert "only one complete" in error
@pytest.mark.parametrize(
"program",
[
"```python\nsdk.commit()```",
"```python\nsdk.commit()",
"Explanation\n```python\nsdk.commit()",
],
)
def test_python_accepts_single_recoverable_fence_variants(program: str):
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(program, context)
assert error is None
assert operations.model_dump() == {"preferences": [], "delete_ids": []}
def test_python_unclosed_fence_still_rejects_truncated_python():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse("```python\npreferences_1.update(", context)
assert operations is None
assert "invalid Python syntax" in error
def test_python_rejects_bare_markdown_with_actionable_error():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"# Caroline\n- Transgender woman (as of 2023-06-09)", context
)
assert operations is None
assert "bare Markdown, not a Python SDK program" in error
assert "leading zeros" not in error
retry = protocol.render_format_retry(error)
assert "Markdown memory content inside quoted SDK arguments" in retry
def test_python_accepts_update_only_program_with_markdown_content():
# A valid program that only uses obj.update() (no literal "sdk." token) and
# embeds Markdown bullets in a triple-quoted string must not be mistaken for
# bare Markdown just because a comment starts with "# " and bullets appear.
uri = "viking://user/alice/memories/preferences/editor.md"
context = _context(
[_preference_schema()],
files=[_existing_preference(uri, "editor", "# Editor\n- Use Vim")],
)
protocol = create_extraction_output_protocol("python")
_bind(protocol, context)
program = (
"# Merge updates to the editor preference\n"
'preferences_1.update(content="""# Editor\n'
"A friend of Dave's who is involved in music.\n"
"## Key Facts\n"
"- Enjoys Japanese culture (as of 2023-10-19)\n"
"- Relaxes by taking long walks\n"
'""")'
)
operations, error = protocol.parse(program, context)
assert error is None
assert "# Editor" in operations.model_dump()["preferences"][0]["content"]
def test_python_rejects_huge_string_multiplication_before_allocation():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
'sdk.set_profile(content="x" * 1_000_000_000)\nsdk.commit()',
context,
)
assert operations is None
assert "size limit" in error
def test_python_rejects_huge_string_multiplication_reversed_operands():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
'sdk.set_profile(content=1_000_000_000 * "x")\nsdk.commit()',
context,
)
assert operations is None
assert "size limit" in error
def test_python_allows_small_string_repetition():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
"sdk.set_profile(content='ab' * 3)\nsdk.commit()",
context,
)
assert error is None
assert operations.model_dump()["profile"][0]["content"] == "ababab"
def test_python_rejects_multiplication_between_two_non_literals():
context = _context([_preference_schema()])
protocol = create_extraction_output_protocol("python")
# Multiplying a non-literal local value by a non-literal local value has
# no bounded literal to repeat and must not be evaluated.
operations, error = protocol.parse(
"a = 'ab'\nn = 3\nsdk.create_preferences(topic='x', score=1, content=a * n)\nsdk.commit()",
context,
)
assert operations is None
assert "multiplication is only supported" in error
def test_python_rejects_numeric_multiplication():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
# Number * number cannot repeat a literal and is useless for memory content.
operations, error = protocol.parse(
"sdk.set_profile(content=str(2 * 3))\nsdk.commit()",
context,
)
assert operations is None
assert "multiplication is only supported" in error
def test_python_rejects_huge_join_before_allocation():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
'sdk.set_profile(content="".join(["xxxxxxxxxx"] * 200_000))\nsdk.commit()',
context,
)
assert operations is None
assert "size limit" in error
def test_python_rejects_huge_replace_before_allocation():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
# 'x' occurs 1000 times; replacing each with a 10000-char string would
# inflate the result to ~10MB. The projected-size check must reject it
# before str.replace builds the string.
operations, error = protocol.parse(
'sdk.set_profile(content=("x" * 1000).replace("x", "y" * 10000))\nsdk.commit()',
context,
)
assert operations is None
assert "size limit" in error
def test_python_allows_small_replace():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
'sdk.set_profile(content="a-b-c".replace("-", " "))\nsdk.commit()',
context,
)
assert error is None
assert operations.model_dump()["profile"][0]["content"] == "a b c"
def test_python_rejects_fstring_width_format_spec():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
# A width format spec turns a small integer literal into a huge padded string
# with no repeat operator; format specs are disallowed.
operations, error = protocol.parse(
"sdk.set_profile(content=f\"{'x':>1000001}\")\nsdk.commit()",
context,
)
assert operations is None
assert "format spec" in error
def test_python_allows_plain_fstring():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
operations, error = protocol.parse(
'name = "Ada"\nsdk.set_profile(content=f"# {name}")\nsdk.commit()',
context,
)
assert error is None
assert operations.model_dump()["profile"][0]["content"] == "# Ada"
def test_python_rejects_string_percent_formatting():
context = _context([_profile_schema()])
protocol = create_extraction_output_protocol("python")
# "%1000001s" % "x" pads to ~1M chars via a width field, no repeat operator.
operations, error = protocol.parse(
'sdk.set_profile(content="%1000001s" % "x")\nsdk.commit()',
context,
)
assert operations is None
assert "%-formatting is not allowed" in error