Files
EverOS/tests/integration/test_reflection_integration.py
T
Kendrick-SongandClaude Opus 4.7 b1441da607 refactor(config): make [embedding] and [rerank] soft dependencies (#361)
* refactor(config): make [embedding] and [rerank] soft dependencies

Make [embedding] and [rerank] soft runtime dependencies so a
freshly-onboarded user can run EverOS end-to-end with only [llm]
configured. Previously the server refused to start without embedding,
locking out anyone who just wanted keyword-only search.

## Capability tiers

- Tier 1 ([llm] only)                   KEYWORD search, add/flush, md
                                        writes, cascade sync
- Tier 2 ([llm] + [embedding])          + VECTOR / HYBRID search,
                                        reflection, skill extraction,
                                        backfill
- Tier 3 ([llm] + [embedding] + rerank) + AGENTIC search, knowledge

Tier upgrades require a server restart (capability accessors cache
for the process lifetime). Tier downgrades are read-safe: a Tier-3
user who drops [rerank] can still read/rename/delete existing
knowledge documents; only write/search endpoints return 422.

## What changed

- Component accessors — component/{embedding,rerank,llm}/accessor.py
  are the single process-wide provider singletons. service/* never
  maintains parallel singletons; it consumes get_embedding_capability()
  / get_rerank_capability() / get_llm_client() directly. Build-time
  ValueError from the factory is logged as capability_build_failed
  (was silently swallowed).
- Error mapping — ProviderNotConfiguredError -> 422 with everos.toml
  section hints (never EVEROS_* env-var strings).
  LanceDBMigrationError fails loud with escalating recovery guidance
  (restart -> wipe index). LLMNotConfiguredError in search maps to
  None for KEYWORD degradation.
- Nullable-vector LanceDB migration — schema v2 makes the vector
  column nullable so Tier-1 rows can land without embeddings.
  Migration is guarded by a cross-process memory_root_lock
  (fcntl.flock + anyio.to_thread) and runs optimize() per table
  after Phase-1 backfill to reclaim manifest bloat.
- Cascade — knowledge handlers register unconditionally (Tier-3 ->
  Tier-2/1 downgrade no longer strands DELETE); embed-requiring
  strategies use body-guards that check capability.available at
  execution time. _TABLE_SPECS has an import-time drift assertion
  against BUSINESS_SCHEMAS_WITH_VECTOR.
- `everos cascade backfill` CLI — Phase-1 (embed missing vectors) /
  Phase-2 (emit synthetic events for cascaded processing) / Phase-3
  (sync new skill files). Exit codes: 0 / 1 / 2 / 3 (server running
  preflight) / 4 (COMPLETED_WITH_FAILURES — per-row failures rolled
  up) / 130 (SIGINT). OMEConfig.crash_recovery_enabled=False in
  backfill engines prevents stale-RUNNING rows re-enqueuing into a
  smaller strategy registry.
- /health — reports capabilities + disabled_features per tier so ops
  can distinguish "boots but degraded" from "boots and full".
- Presentation split — memory / service / infra never import typer /
  click. TyperPresenter Protocol + run_backfill() live in
  entrypoints/cli/commands/_backfill_cmd.py. Enforced by
  import-linter.
- Startup hint — unconditional count_rows(filter="vector IS NULL")
  sweep emits unbackfilled_memory_rows (event name + hint text
  pinned) when Tier-1 rows exist. ParserLifespanProvider warms the
  everalgo.parser import at boot so /health doesn't block on first
  call.
- Knowledge upload UTF-8 short-circuit — _looks_like_utf8_text()
  routes text/* mime and known plaintext extensions (md/txt/rst)
  straight to UTF-8 decode instead of the parser. Prevents 503
  Multimodal-not-configured when Tier 3 sans [multimodal] uploads a
  markdown doc.

## Sync history with main (2 merges collapsed into this squash)

Merged origin/main at 6dcd3eb (v1.1.4 -> v1.2.0 adds OTel tracing,
/api/v2 alias, TracingLifespanProvider, per-cascade-embedding span
fix, memory-op instrumentation) and later at 42629df (PR #366
backfills v1.1.4 CWE-22 knowledge path traversal fix + cascade
retry-budget rework + errors.py -> core.errors.ExternalServiceError).
Key merge decisions:
- service/search.py adopts single wrap site — component.llm accessor
  already applies UsageRecordingClient when observability is on;
  service layer never keeps a parallel LLM singleton (Round-1 CR
  rule: "service layer never maintains parallel singletons").
- Knowledge router prefix moved to /knowledge; create_app() mounts
  it under both /api/v1 and /api/v2.
- Cascade retry classification uses ExternalServiceError from
  core.errors (cascade/errors.py deleted). _MAX_TOTAL_RETRIES=12
  cross-cycle budget preserved.
- Fixed backport typo: MemoryRoot.default() -> MemoryRoot.resolve()
  (no .default() classmethod exists — main PR #366 shipped a broken
  call).

## Verified layering

    $ git grep -l "^import typer\|^from typer" src/everos/{memory,service,infra}
    # empty
    $ git grep -l "^import click\|^from click" src/everos/{memory,service,infra}
    # empty

Memory / service / infra layers clean of CLI presentation libraries.

## Review history

Three rounds of Fable 5 (opus) code review across the pre-squash
commit history closed 38 findings total:
- Round 1: 10 findings (fail-loud migration, backfill hardening,
  knowledge router gate scoping, SearchManager guards, profile
  throttle lift)
- Round 2: 13 findings (hermetic test env, hot-reload doc drift,
  knowledge handler registration, Phase 3 sync guarantee, Phase 2
  idempotency, profile event-first path, OMEConfig crash-recovery
  gate, cross-process migration lock, batch embed per-row fallback,
  LanceDB optimize, typer/click layer split)
- Round 3: 15 Minor cleanups (accessor unification, marker revert,
  episode query hygiene, --verbose subcommand, parser lifespan warm,
  task-number scrub, temporal-overlap test, real-SIGINT slow mark,
  4 design-note back-references)

Full per-round context lives in the PR description on GitHub.

## Test plan

- make lint (ruff + import-linter 3 contracts + assets +
  deprecated-names + github-docs + datetime + OpenAPI drift)
- Hermetic env full pytest — 2027 passed / 7 deselected (7 = slow +
  live_llm markers)
- Manual e2e across Tier 1/2/3 (21/21 assertions across v1/v2
  double-mount and Tier 3 -> Tier 2 downgrade)
- /health reports correct capabilities + disabled_features per tier

## Known follow-ups

- .superpowers/sdd/followup-http-bridge.md (gitignored) — Path A for
  spec §10's "backfill 期间 EverOS 完全可用" promise
- _TABLE_SCHEMA_VERSION docstring — v3+ migrations need a version
  dispatch table
- extract_user_profile.py throttle-counter block — replace LanceDB
  count_by_owner with a sqlite memcell count

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(review): close 3 blockers surfaced by round-4 review

N1. cluster_repo.find_cluster_id_for_member was cross-owner-unsafe.
Its reverse index (member_type, member_id) alone cannot disambiguate
two owners whose entry_id happens to collide — entry_id is
deliberately only per-owner unique (see entries.py:47:
'Cross-user uniqueness is handled at the database layer via a
composite <user_id>_<entry_id> field; it is not encoded into the
EntryId string itself'). Phase 2's _scan_all_rows crosses all
owners, so on any multi-owner root, same-day seq=1 episodes under
different owners would either false-hit each other's cluster or
be silently skipped from clustering. Add required (app_id,
project_id, owner_id) keyword args + JOIN Cluster (which already
carries scope) to filter by parent scope. Prior signature had zero
production callers except two the same PR just added, so the
API break is contained. Regression test: two owners persist a
cluster each around the same entry_id, each lookup resolves to
its own owner's cluster, a third owner's lookup returns None.

N2. Ctrl-C / EOF at the y/N prompt was landing on the generic
except Exception branch (exit 2 with rich traceback) instead of
the exit-130 interrupt path. Root cause: typer 0.15+ vendored
click under typer._click, so typer.Abort and the standalone
click.exceptions.Abort are distinct classes. The interrupt-branch
catch only listed the standalone one; every existing 'abort'
test was manually raising click.exceptions.Abort so the miss
was a false-positive guard rail. Widen the catch to
(typer.Abort, click.exceptions.Abort) and declare click as a
first-class dependency (it was only pulled in via uvicorn).
Regression test: raise real typer.Abort() at the confirm step
and assert exit 130 + INTERRUPTED banner.

N3. _looks_like_utf8_text used mime.startswith('text/'), which
caught text/html as well. HTML uploads then bypassed everalgo's
_aparse_html — losing clean_html_for_llm (strips <script>/<style>
/<nav>/<iframe> + HTML comments) and the 1 MiB output cap. A
40 MiB .html with <script> bodies and <!-- prompt injection -->
comments would flow straight into the extraction LLM. Replace
with explicit allowlist {text/plain, text/markdown, text/x-rst,
text/x-markdown}; text/html and any future text/* mime now
default to the parser path. Test matrix asserts text/html →
False (was regressed as True by the earlier commit).

Hermetic env full pytest: 2033 passed / 7 deselected (+6 tests
from these regressions).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(review): close round-4 major + minor + PR body errata

Round-4 review-driven cleanup. Blocker fixes (N1/N2/N3) landed in
561b5fe. This commit closes the remaining CONFIRMED items:

Major:
- J3 MemoryRoot.default() -> resolve() was a breaking public API
  rename this branch introduced (main still has default()). Adds
  default() as a backward-compat alias forwarding to resolve()
  with DeprecationWarning; CHANGELOG entry under Unreleased.
- J4 episode_repo.list_by_owner_after_ts(limit=N) truncates in
  fragment order (== insertion order), NOT newest-first. Docstring
  now spells out the trap so a future caller passing limit for a
  'newest N' window doesn't silently get the oldest N.
- J5.2 TyperPresenter.nothing_to_backfill picked colour via
  'could not be read' in message — a domain wording change
  would silently flip yellow -> green. Signature gains explicit
  scan_failed: bool kwarg; CLI colour-picks off the flag.
- J5.5 phase_header was Protocol-declared but never dispatched
  (run_backfill calls _print_phase_header directly). Removed the
  dead Protocol method + both no-op implementations.
- J6.3 3 inline from everos.core.errors import ... inside
  Phase 1/2/3 preflights promoted to a single top-level import.
- J7 subject-side embed failure was silently exit-0 because
  rows_processed advanced whenever any side wrote. Now: a row with
  a needed side still NULL counts as rows_failed (exit 4 =
  COMPLETED_WITH_FAILURES). Gated on spec.subject_of + row.needs_*
  + row.subject_text so non-Episode tables and subject-empty rows
  don't false-positive.
- J9 test_migration_cross_process.py did NOT actually test cross-
  process (all 5 tests mock memory_root_lock). Renamed to
  test_migration_lock_wiring.py; docstring now scopes it to
  'lock-invocation wiring' and points at test_core/…/test_locking.py
  for real flock coverage.
- J10 Phase 1 lacked the server-running preflight Phase 2/3 have.
  --phase all against a live server would burn Phase 1 embed API
  calls (real cost) before Phase 2 halted with exit 3. Phase 1 now
  probes _probe_ome_lock_available first; regression test in
  test_backfill_preflight.py; upgrade_path integration patches the
  probe so its in-process 'server + backfill' scenario stays valid.

Minor:
- M1 knowledge upload with NUL byte or filename > 255 bytes UTF-8
  used to raise ValueError/OSError at write_bytes → 500 with a
  half-written md left on disk. _safe_original_filename now
  rejects both up front with InvalidInputError (→ 400).
- M2 backfill optimize() now passes cleanup_older_than=timedelta(0)
  so older manifest versions are physically pruned (previous call
  compacted fragments but left the manifest chain on disk).
- M3 verify_business_schemas remediation text used to jump straight
  to 'rm -rf ~/.everos/.index/lancedb'; now walks restart → wipe.
- M5 multimodal/accessor.py capability_build_failed warning added
  so all four provider accessors log symmetrically (was silent).
- M7 test_knowledge_api parser-absence tests call
  parser_available.cache_clear() around the sys.modules patch so
  the lru_cache doesn't strand a stale True/False.
- M8 cascade_handler_embed_skipped (6 handlers) demoted INFO → DEBUG:
  Tier 1 imports were generating N × 6 handler-info lines per md.
- M10.1 test_drift_scenario_would_raise was a tautology (compared
  two hardcoded string sets, never touched the guard). Now
  monkey-patches BUSINESS_SCHEMAS_WITH_VECTOR to a superset and
  reloads _backfill, proving the import-time RuntimeError fires.
- M11 test_cascade_verbose_position subprocess.run calls gain
  env= — scrubs EVEROS_* from the developer environment so the
  same footgun as round-2 B1 doesn't re-appear inside subprocesses.
- M14 health() -> dict degraded the OpenAPI schema to
  additionalProperties: true. Introduce HealthResponse +
  HealthCapabilities Pydantic models so clients get real field
  shape; docs/openapi.json regenerated.
- M16 routes/knowledge.py:_require_knowledge_capabilities docstring
  claimed cascade.registry.build_handlers still gates
  knowledge_topic/knowledge_document, contradicting
  registry.py:177-194 (gate removed there, moved to HTTP layer).
  Rewritten to describe the current design accurately.

Hermetic env full pytest: 2037 passed / 7 deselected.

Explicitly deferred to followup:
- J1 lazy multimodal client (needs everalgo signature change)
- J2 tier definition (knowledge = Tier 3 whole)
- J5.1/3/4 broader presentation-split refactor
- J6.1/2 backfill dispatch and _backfill_table refactor
- J8 Phase 1 keyset pagination for bulk migration OOM
- M4 flock timeout/waiting log/re-entry (core/persistence refactor)
- M6 UTF-8 codec strategy (BOM/UTF-16/GBK)
- M9 count_by_owner monotonicity (latent, INTERVAL=1 short-circuits)
- M13 --phase all multi-phase combined-outcome test coverage
- M15 PR-marker rationale comments (16 occurrences, all inert)

M12 was refuted (both event names exist).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-07-29 11:05:23 +08:00

848 lines
30 KiB
Python

"""End-to-end Reflection INIT cycle integration test.
Drives ``ReflectionOrchestrator.run()`` with real SQLite (cluster +
report repos), real LanceDB (episode + atomic_fact stores), real
EpisodeWriter (md files), a ``FakeLLMClient``-backed
``EpisodeReflector``, and a stub embedder. Verifies the full flow:
select candidates → merge episodes (FakeLLM) → write merged md →
emit EpisodeExtracted + wait (no-op via FakeStrategyContext) →
deprecate originals → update cluster membership → write report
White-box surfaces: sqlite cluster_member / reflection_report tables,
LanceDB episode.deprecated_by column, md file existence + frontmatter.
"""
from __future__ import annotations
import datetime as _dt
import hashlib
import json
from pathlib import Path
import numpy as np
import pytest
from everalgo.clustering import Cluster as AlgoCluster
from everalgo.testing.fake_llm import FakeLLMClient
from everalgo.user_memory.reflect import EpisodeReflector
from sqlmodel import SQLModel
from everos.config import LanceDBSettings, load_settings
from everos.core.persistence import (
MemoryRoot,
open_lancedb_connection,
)
from everos.core.persistence.lancedb import LanceDailyLogRepoBase, LanceRepoBase
from everos.infra.ome.testing import FakeStrategyContext
from everos.infra.persistence.lancedb.tables.atomic_fact import AtomicFact
from everos.infra.persistence.lancedb.tables.episode import Episode as LanceEpisode
from everos.infra.persistence.markdown.writers.episode_writer import EpisodeWriter
from everos.infra.persistence.sqlite import cluster_repo, reflection_report_repo
from everos.memory._partition_locks import _reset_for_tests
from everos.memory.reflection.orchestrator import ReflectionOrchestrator
# ---------------------------------------------------------------------------
# Stub embedder
# ---------------------------------------------------------------------------
class _StubEmbedder:
"""Return deterministic 1024-dim vectors seeded by input text."""
dim: int = 1024
async def embed(self, text: str) -> list[float]:
digest = hashlib.sha256(text.encode("utf-8")).digest()
seed = int.from_bytes(digest[:8], "little")
rng = np.random.default_rng(seed)
vec = rng.standard_normal(self.dim).astype(np.float32)
norm = float(np.linalg.norm(vec)) or 1.0
vec /= norm
return vec.tolist()
# ---------------------------------------------------------------------------
# LanceDB repo wrappers (inject table directly)
# ---------------------------------------------------------------------------
class _EpisodeRepo(LanceDailyLogRepoBase[LanceEpisode]):
schema = LanceEpisode
class _AtomicFactRepo(LanceDailyLogRepoBase[AtomicFact]):
schema = AtomicFact
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
def _reset_locks() -> None:
"""Drop per-table write locks + partition locks between tests."""
LanceRepoBase._reset_locks_for_tests()
_reset_for_tests()
@pytest.fixture(autouse=True)
def _embed_available(monkeypatch: pytest.MonkeyPatch) -> None:
"""Force embedding capability to ``available=True`` for the whole file.
``ReflectionOrchestrator.run()`` reads
``get_embedding_capability().available`` at body entry and no-ops when
the capability is unavailable. The autouse fixture in
``tests/conftest.py`` seeds a ``Capability(provider=None)`` for
hermeticity; every test here needs the orchestrator body to execute,
so override with a real (stub) provider — the orchestrator itself is
constructed with the same ``_StubEmbedder`` for its actual embed
calls.
"""
from everos.component.embedding import EmbeddingCapability
from everos.component.embedding import accessor as acc
monkeypatch.setattr(
acc, "_capability", EmbeddingCapability(provider=_StubEmbedder())
)
@pytest.fixture
def memory_root(tmp_path: Path) -> MemoryRoot:
mr = MemoryRoot(tmp_path)
mr.ensure()
(tmp_path / ".index" / "sqlite").mkdir(parents=True, exist_ok=True)
(tmp_path / "ome.toml").write_text("# test\n")
return mr
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _make_lance_episode(
*,
entry_id: str,
owner_id: str,
episode: str,
timestamp: _dt.datetime,
parent_type: str = "memcell",
parent_id: str,
session_id: str | None = "s_test",
md_path: str = "",
) -> LanceEpisode:
"""Build a LanceDB Episode row with required fields."""
digest = hashlib.sha256(episode.encode("utf-8")).digest()
seed = int.from_bytes(digest[:8], "little")
rng = np.random.default_rng(seed)
vec = rng.standard_normal(1024).astype(np.float32)
vec /= float(np.linalg.norm(vec)) or 1.0
return LanceEpisode(
id=f"{owner_id}_{entry_id}",
entry_id=entry_id,
owner_id=owner_id,
owner_type="user",
app_id="default",
project_id="default",
session_id=session_id,
timestamp=timestamp,
parent_type=parent_type,
parent_id=parent_id,
sender_ids=[owner_id],
subject="test",
summary=None,
episode=episode,
episode_tokens=episode.lower(),
md_path=md_path,
content_sha256=hashlib.sha256(episode.encode()).hexdigest(),
deprecated_by=None,
vector=vec.tolist(),
)
def _make_lance_fact(
*,
entry_id: str,
owner_id: str,
fact: str,
parent_id: str,
parent_type: str = "memcell",
timestamp: _dt.datetime,
) -> AtomicFact:
"""Build a LanceDB AtomicFact row."""
digest = hashlib.sha256(fact.encode("utf-8")).digest()
seed = int.from_bytes(digest[:8], "little")
rng = np.random.default_rng(seed)
vec = rng.standard_normal(1024).astype(np.float32)
vec /= float(np.linalg.norm(vec)) or 1.0
return AtomicFact(
id=f"{owner_id}_{entry_id}",
entry_id=entry_id,
owner_id=owner_id,
owner_type="user",
app_id="default",
project_id="default",
session_id="s_test",
timestamp=timestamp,
parent_type=parent_type,
parent_id=parent_id,
sender_ids=[owner_id],
fact=fact,
fact_tokens=fact.lower(),
md_path="",
content_sha256=hashlib.sha256(fact.encode()).hexdigest(),
deprecated_by=None,
vector=vec.tolist(),
)
async def _setup_sqlite(monkeypatch: pytest.MonkeyPatch) -> None:
"""Reset the sqlite_manager singleton and create_all tables."""
from everos.infra.persistence.sqlite import sqlite_manager
if sqlite_manager._engine is not None:
await sqlite_manager.dispose_engine()
monkeypatch.setattr(sqlite_manager, "_engine", None, raising=False)
monkeypatch.setattr(sqlite_manager, "_session_factory", None, raising=False)
engine = sqlite_manager.get_engine()
async with engine.begin() as conn:
await conn.run_sync(SQLModel.metadata.create_all)
async def _teardown_sqlite() -> None:
from everos.infra.persistence.sqlite import sqlite_manager
if sqlite_manager._engine is not None:
await sqlite_manager.dispose_engine()
# ---------------------------------------------------------------------------
# Test
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_reflection_init_merges_cluster_episodes(
tmp_path: Path,
memory_root: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Full INIT Reflection cycle: 3 episodes in a cluster -> merge -> verify.
Verifies:
- ReflectionReport created with mode="init", source_count=3
- Source episodes deprecated in LanceDB (deprecated_by is set)
- Merged episode written to md with parent_type="cluster"
- Cluster members updated: old 3 removed, 1 new episode member
- Report.merged_entry_id matches the new cluster member's member_id
- Atomic facts for source episodes are deprecated
"""
# -- Redirect MemoryRoot.resolve() to tmp_path.
monkeypatch.setattr(
MemoryRoot,
"resolve",
classmethod(lambda cls: MemoryRoot(root=tmp_path)),
)
monkeypatch.setenv("EVEROS_LLM__API_KEY", "fake-key")
monkeypatch.setenv("EVEROS_LLM__BASE_URL", "https://fake.example.com")
load_settings.cache_clear()
await _setup_sqlite(monkeypatch)
try:
# -- LanceDB setup: create tables + insert test episodes.
conn = await open_lancedb_connection(memory_root.lancedb_dir, LanceDBSettings())
ep_table = await conn.create_table("episode", schema=LanceEpisode)
af_table = await conn.create_table("atomic_fact", schema=AtomicFact)
ep_repo = _EpisodeRepo(table=ep_table)
af_repo = _AtomicFactRepo(table=af_table)
owner_id = "u_test"
cluster_id = "cl_test_reflect"
ts1 = _dt.datetime(2026, 6, 10, 10, 0, 0, tzinfo=_dt.UTC)
ts2 = _dt.datetime(2026, 6, 10, 11, 0, 0, tzinfo=_dt.UTC)
ts3 = _dt.datetime(2026, 6, 10, 12, 0, 0, tzinfo=_dt.UTC)
ep1 = _make_lance_episode(
entry_id="ep_20260610_0001",
owner_id=owner_id,
episode="Andrew has no pets",
timestamp=ts1,
parent_id="mc_001",
)
ep2 = _make_lance_episode(
entry_id="ep_20260610_0002",
owner_id=owner_id,
episode="Andrew adopted Toby",
timestamp=ts2,
parent_id="mc_002",
)
ep3 = _make_lance_episode(
entry_id="ep_20260610_0003",
owner_id=owner_id,
episode="Andrew adopted Buddy",
timestamp=ts3,
parent_id="mc_003",
)
await ep_repo.add([ep1, ep2, ep3])
# Insert atomic facts linked to the source memcells.
fact1 = _make_lance_fact(
entry_id="af_20260610_0001",
owner_id=owner_id,
fact="Andrew has no pets",
parent_id="ep_20260610_0001",
timestamp=ts1,
)
fact2 = _make_lance_fact(
entry_id="af_20260610_0002",
owner_id=owner_id,
fact="Andrew adopted Toby",
parent_id="ep_20260610_0002",
timestamp=ts2,
)
fact3 = _make_lance_fact(
entry_id="af_20260610_0003",
owner_id=owner_id,
fact="Andrew adopted Buddy",
parent_id="ep_20260610_0003",
timestamp=ts3,
)
await af_repo.add([fact1, fact2, fact3])
# -- SQLite: create cluster + cluster_members.
centroid = np.zeros(1024, dtype=np.float32)
algo_cluster = AlgoCluster(
id=cluster_id,
centroid=centroid,
count=3,
last_ts=int(ts3.timestamp() * 1000),
preview=["Andrew has no pets", "Andrew adopted Toby"],
members=["ep_20260610_0001", "ep_20260610_0002", "ep_20260610_0003"],
)
await cluster_repo.upsert_with_members(
algo_cluster,
owner_id=owner_id,
owner_type="user",
kind="user_memory",
member_type="episode",
)
# Verify cluster members are created.
members_before = await cluster_repo.get_members_with_type(cluster_id)
assert len(members_before) == 3
# -- Build the EpisodeReflector with FakeLLM.
merged_content = (
"Andrew initially had no pets. He later adopted a dog named Toby, "
"and then adopted another dog named Buddy."
)
merged_title = "Andrew's pet adoption journey"
reflect_response = json.dumps(
{"content": merged_content, "title": merged_title}
)
fake_llm = FakeLLMClient(responses=[reflect_response])
reflector = EpisodeReflector(llm=fake_llm)
# -- Build the EpisodeWriter.
episode_writer = EpisodeWriter(memory_root)
# -- Build the orchestrator with real repos.
orchestrator = ReflectionOrchestrator(
cluster_repo=cluster_repo,
episode_store=ep_repo,
atomic_fact_store=af_repo,
episode_writer=episode_writer,
report_repo=reflection_report_repo,
reflector=reflector,
embedder=_StubEmbedder(),
)
# -- Run the orchestrator.
fake_ctx = FakeStrategyContext()
reports = await orchestrator.run(ctx=fake_ctx, owner_id=owner_id)
# -- Verify: exactly one report created.
assert len(reports) == 1
report = reports[0]
assert report.mode == "init"
assert report.source_count == 3
assert report.status == "completed"
assert report.cluster_id == cluster_id
merged_entry_id = report.merged_entry_id
# -- Verify: source episodes deprecated in LanceDB.
for ep in [ep1, ep2, ep3]:
rows = await ep_repo.find_where(
f"entry_id = '{ep.entry_id}' AND owner_id = '{owner_id}'"
)
assert len(rows) == 1, f"expected 1 row for {ep.entry_id}"
assert rows[0].deprecated_by == merged_entry_id, (
f"{ep.entry_id} should be deprecated by {merged_entry_id}"
)
# -- Verify: atomic facts deprecated in LanceDB.
for fact in [fact1, fact2, fact3]:
rows = await af_repo.find_where(
f"entry_id = '{fact.entry_id}' AND owner_id = '{owner_id}'"
)
assert len(rows) == 1, f"expected 1 row for {fact.entry_id}"
assert rows[0].deprecated_by == merged_entry_id, (
f"{fact.entry_id} should be deprecated by {merged_entry_id}"
)
# -- Verify: cluster membership updated.
members_after = await cluster_repo.get_members_with_type(cluster_id)
assert len(members_after) == 1, (
f"expected 1 member after merge, got {len(members_after)}"
)
new_member_id, new_member_type = members_after[0]
assert new_member_type == "episode"
assert new_member_id == merged_entry_id
# -- Verify: merged episode written to md.
users_dir = memory_root.users_dir("default", "default")
episode_files = sorted(
(users_dir / owner_id / "episodes").rglob("episode-*.md")
)
assert len(episode_files) == 1
md_text = episode_files[0].read_text()
assert merged_content in md_text
assert "parent_type" in md_text
assert "cluster" in md_text
# -- Verify: FakeStrategyContext received an EpisodeExtracted event.
assert len(fake_ctx.emitted) == 1
emitted_event = fake_ctx.emitted[0]
assert emitted_event.episode_entry_id == merged_entry_id
assert emitted_event.owner_id == owner_id
assert emitted_event.source == "reflection"
# -- Verify: report in sqlite matches.
db_report = await reflection_report_repo.get_latest_for_cluster(cluster_id)
assert db_report is not None
assert db_report.merged_entry_id == merged_entry_id
assert db_report.mode == "init"
finally:
conn.close()
await _teardown_sqlite()
@pytest.mark.asyncio
async def test_reflection_update_merges_new_episodes_with_existing_merged(
tmp_path: Path,
memory_root: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""INIT -> add 4th episode -> UPDATE cycle: verify incremental merge.
Verifies:
- Second report has mode="update", source_count=2 (old merged + mc_004)
- Old merged episode (v1) deprecated in LanceDB
- New merged episode (v2) exists with updated content
- mc_004's episode deprecated in LanceDB
- Cluster members: exactly 1, member_type="episode", member_id = v2
- Old atomic facts from v1's sources remain deprecated
"""
monkeypatch.setattr(
MemoryRoot,
"resolve",
classmethod(lambda cls: MemoryRoot(root=tmp_path)),
)
monkeypatch.setenv("EVEROS_LLM__API_KEY", "fake-key")
monkeypatch.setenv("EVEROS_LLM__BASE_URL", "https://fake.example.com")
load_settings.cache_clear()
await _setup_sqlite(monkeypatch)
try:
# -- LanceDB setup.
conn = await open_lancedb_connection(memory_root.lancedb_dir, LanceDBSettings())
ep_table = await conn.create_table("episode", schema=LanceEpisode)
af_table = await conn.create_table("atomic_fact", schema=AtomicFact)
ep_repo = _EpisodeRepo(table=ep_table)
af_repo = _AtomicFactRepo(table=af_table)
owner_id = "u_test"
cluster_id = "cl_test_update"
ts1 = _dt.datetime(2026, 6, 10, 10, 0, 0, tzinfo=_dt.UTC)
ts2 = _dt.datetime(2026, 6, 10, 11, 0, 0, tzinfo=_dt.UTC)
ts3 = _dt.datetime(2026, 6, 10, 12, 0, 0, tzinfo=_dt.UTC)
ep1 = _make_lance_episode(
entry_id="ep_20260610_0001",
owner_id=owner_id,
episode="Andrew has no pets",
timestamp=ts1,
parent_id="mc_001",
)
ep2 = _make_lance_episode(
entry_id="ep_20260610_0002",
owner_id=owner_id,
episode="Andrew adopted Toby",
timestamp=ts2,
parent_id="mc_002",
)
ep3 = _make_lance_episode(
entry_id="ep_20260610_0003",
owner_id=owner_id,
episode="Andrew adopted Buddy",
timestamp=ts3,
parent_id="mc_003",
)
await ep_repo.add([ep1, ep2, ep3])
# Atomic facts for source episodes.
fact1 = _make_lance_fact(
entry_id="af_20260610_0001",
owner_id=owner_id,
fact="Andrew has no pets",
parent_id="ep_20260610_0001",
timestamp=ts1,
)
fact2 = _make_lance_fact(
entry_id="af_20260610_0002",
owner_id=owner_id,
fact="Andrew adopted Toby",
parent_id="ep_20260610_0002",
timestamp=ts2,
)
fact3 = _make_lance_fact(
entry_id="af_20260610_0003",
owner_id=owner_id,
fact="Andrew adopted Buddy",
parent_id="ep_20260610_0003",
timestamp=ts3,
)
await af_repo.add([fact1, fact2, fact3])
# -- SQLite: cluster with 3 memcell members.
centroid = np.zeros(1024, dtype=np.float32)
algo_cluster = AlgoCluster(
id=cluster_id,
centroid=centroid,
count=3,
last_ts=int(ts3.timestamp() * 1000),
preview=["Andrew has no pets", "Andrew adopted Toby"],
members=["ep_20260610_0001", "ep_20260610_0002", "ep_20260610_0003"],
)
await cluster_repo.upsert_with_members(
algo_cluster,
owner_id=owner_id,
owner_type="user",
kind="user_memory",
member_type="episode",
)
# -- Phase 1: INIT merge.
init_response = json.dumps(
{"content": "Andrew adopted Toby and Buddy.", "title": "Andrew pets v1"}
)
update_response = json.dumps(
{
"content": "Andrew adopted Toby, Buddy, and Scout.",
"title": "Andrew pets v2",
}
)
fake_llm = FakeLLMClient(responses=[init_response, update_response])
reflector = EpisodeReflector(llm=fake_llm)
episode_writer = EpisodeWriter(memory_root)
orchestrator = ReflectionOrchestrator(
cluster_repo=cluster_repo,
episode_store=ep_repo,
atomic_fact_store=af_repo,
episode_writer=episode_writer,
report_repo=reflection_report_repo,
reflector=reflector,
embedder=_StubEmbedder(),
)
fake_ctx = FakeStrategyContext()
reports_init = await orchestrator.run(ctx=fake_ctx, owner_id=owner_id)
assert len(reports_init) == 1
report_init = reports_init[0]
assert report_init.mode == "init"
merged_v1_entry_id = report_init.merged_entry_id
# FakeStrategyContext is a no-op, so the merged episode is not
# inserted into LanceDB by the extraction pipeline. Simulate the
# real pipeline by inserting the merged v1 episode manually.
merged_v1_ep = _make_lance_episode(
entry_id=merged_v1_entry_id,
owner_id=owner_id,
episode="Andrew adopted Toby and Buddy.",
timestamp=ts3,
parent_type="cluster",
parent_id=cluster_id,
session_id=None,
)
await ep_repo.add([merged_v1_ep])
# -- Phase 2: add a 4th episode + cluster member, then run UPDATE.
ts4 = _dt.datetime(2026, 6, 10, 13, 0, 0, tzinfo=_dt.UTC)
ep4 = _make_lance_episode(
entry_id="ep_20260610_0004",
owner_id=owner_id,
episode="Andrew adopted Scout",
timestamp=ts4,
parent_id="mc_004",
)
await ep_repo.add([ep4])
await cluster_repo.add_member(cluster_id, "ep_20260610_0004", "episode")
# Fresh orchestrator, same FakeLLM (next pop = update_response).
orchestrator2 = ReflectionOrchestrator(
cluster_repo=cluster_repo,
episode_store=ep_repo,
atomic_fact_store=af_repo,
episode_writer=episode_writer,
report_repo=reflection_report_repo,
reflector=reflector,
embedder=_StubEmbedder(),
)
fake_ctx2 = FakeStrategyContext()
reports_update = await orchestrator2.run(ctx=fake_ctx2, owner_id=owner_id)
# -- Verify: second report is UPDATE with source_count=2.
assert len(reports_update) == 1
report_update = reports_update[0]
assert report_update.mode == "update"
assert report_update.source_count == 2
merged_v2_entry_id = report_update.merged_entry_id
# -- Verify: old merged episode (v1) deprecated.
v1_rows = await ep_repo.find_where(
f"entry_id = '{merged_v1_entry_id}' AND owner_id = '{owner_id}'"
)
assert len(v1_rows) == 1
assert v1_rows[0].deprecated_by == merged_v2_entry_id
# -- Verify: mc_004's episode deprecated.
mc4_rows = await ep_repo.find_where(
f"parent_type = 'memcell' AND parent_id = 'mc_004' "
f"AND owner_id = '{owner_id}'"
)
assert len(mc4_rows) == 1
assert mc4_rows[0].deprecated_by == merged_v2_entry_id
# -- Verify: new merged episode (v2) written to markdown.
# (FakeStrategyContext does not run the extraction pipeline, so v2
# is not yet in LanceDB — verify via the md file instead.)
users_dir = memory_root.users_dir("default", "default")
episode_files = sorted(
(users_dir / owner_id / "episodes").rglob("episode-*.md")
)
assert len(episode_files) >= 1
# Both v1 and v2 land in the same daily-log file; check full text.
all_md = "\n".join(f.read_text() for f in episode_files)
assert "Andrew adopted Toby, Buddy, and Scout." in all_md
assert "parent_type" in all_md and "cluster" in all_md
# -- Verify: cluster members = exactly 1, type=episode, id=v2.
members_final = await cluster_repo.get_members_with_type(cluster_id)
assert len(members_final) == 1
final_mid, final_mtype = members_final[0]
assert final_mtype == "episode"
assert final_mid == merged_v2_entry_id
# -- Verify: original atomic facts still deprecated by v1
# (they were deprecated in the INIT phase; UPDATE does not touch them).
for fact in [fact1, fact2, fact3]:
rows = await af_repo.find_where(
f"entry_id = '{fact.entry_id}' AND owner_id = '{owner_id}'"
)
assert len(rows) == 1
assert rows[0].deprecated_by == merged_v1_entry_id, (
f"{fact.entry_id} should still be deprecated by v1"
)
finally:
conn.close()
await _teardown_sqlite()
@pytest.mark.asyncio
async def test_reflected_episodes_visible_in_search_deprecated_excluded(
tmp_path: Path,
memory_root: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""After INIT Reflection, search filters correctly include/exclude episodes.
Verifies:
- ``deprecated_by IS NULL`` returns only the merged episode
- Merged episode has parent_type="cluster" and session_id=None
- Adding session_id filter excludes the merged episode (session_id IS NULL)
"""
monkeypatch.setattr(
MemoryRoot,
"resolve",
classmethod(lambda cls: MemoryRoot(root=tmp_path)),
)
monkeypatch.setenv("EVEROS_LLM__API_KEY", "fake-key")
monkeypatch.setenv("EVEROS_LLM__BASE_URL", "https://fake.example.com")
load_settings.cache_clear()
await _setup_sqlite(monkeypatch)
try:
# -- LanceDB setup.
conn = await open_lancedb_connection(memory_root.lancedb_dir, LanceDBSettings())
ep_table = await conn.create_table("episode", schema=LanceEpisode)
af_table = await conn.create_table("atomic_fact", schema=AtomicFact)
ep_repo = _EpisodeRepo(table=ep_table)
af_repo = _AtomicFactRepo(table=af_table)
owner_id = "u_test"
cluster_id = "cl_test_search"
ts1 = _dt.datetime(2026, 6, 10, 10, 0, 0, tzinfo=_dt.UTC)
ts2 = _dt.datetime(2026, 6, 10, 11, 0, 0, tzinfo=_dt.UTC)
ts3 = _dt.datetime(2026, 6, 10, 12, 0, 0, tzinfo=_dt.UTC)
ep1 = _make_lance_episode(
entry_id="ep_20260610_0001",
owner_id=owner_id,
episode="Andrew has no pets",
timestamp=ts1,
parent_id="mc_001",
)
ep2 = _make_lance_episode(
entry_id="ep_20260610_0002",
owner_id=owner_id,
episode="Andrew adopted Toby",
timestamp=ts2,
parent_id="mc_002",
)
ep3 = _make_lance_episode(
entry_id="ep_20260610_0003",
owner_id=owner_id,
episode="Andrew adopted Buddy",
timestamp=ts3,
parent_id="mc_003",
)
await ep_repo.add([ep1, ep2, ep3])
# Atomic facts (needed for the orchestrator to complete).
fact1 = _make_lance_fact(
entry_id="af_20260610_0001",
owner_id=owner_id,
fact="Andrew has no pets",
parent_id="ep_20260610_0001",
timestamp=ts1,
)
fact2 = _make_lance_fact(
entry_id="af_20260610_0002",
owner_id=owner_id,
fact="Andrew adopted Toby",
parent_id="ep_20260610_0002",
timestamp=ts2,
)
fact3 = _make_lance_fact(
entry_id="af_20260610_0003",
owner_id=owner_id,
fact="Andrew adopted Buddy",
parent_id="ep_20260610_0003",
timestamp=ts3,
)
await af_repo.add([fact1, fact2, fact3])
# -- SQLite: cluster with 3 memcell members.
centroid = np.zeros(1024, dtype=np.float32)
algo_cluster = AlgoCluster(
id=cluster_id,
centroid=centroid,
count=3,
last_ts=int(ts3.timestamp() * 1000),
preview=["Andrew has no pets", "Andrew adopted Toby"],
members=["ep_20260610_0001", "ep_20260610_0002", "ep_20260610_0003"],
)
await cluster_repo.upsert_with_members(
algo_cluster,
owner_id=owner_id,
owner_type="user",
kind="user_memory",
member_type="episode",
)
# -- Run INIT Reflection.
merged_content = (
"Andrew initially had no pets. He later adopted a dog named Toby, "
"and then adopted another dog named Buddy."
)
merged_title = "Andrew's pet adoption journey"
reflect_response = json.dumps(
{"content": merged_content, "title": merged_title}
)
fake_llm = FakeLLMClient(responses=[reflect_response])
reflector = EpisodeReflector(llm=fake_llm)
episode_writer = EpisodeWriter(memory_root)
orchestrator = ReflectionOrchestrator(
cluster_repo=cluster_repo,
episode_store=ep_repo,
atomic_fact_store=af_repo,
episode_writer=episode_writer,
report_repo=reflection_report_repo,
reflector=reflector,
embedder=_StubEmbedder(),
)
fake_ctx = FakeStrategyContext()
reports = await orchestrator.run(ctx=fake_ctx, owner_id=owner_id)
assert len(reports) == 1
merged_entry_id = reports[0].merged_entry_id
# FakeStrategyContext is a no-op, so the merged episode is not
# inserted into LanceDB by the extraction pipeline. Simulate the
# real pipeline by inserting the merged episode manually.
merged_ep = _make_lance_episode(
entry_id=merged_entry_id,
owner_id=owner_id,
episode=merged_content,
timestamp=ts3,
parent_type="cluster",
parent_id=cluster_id,
session_id=None,
)
await ep_repo.add([merged_ep])
# -- Verify: non-deprecated episodes = only the merged one.
active_rows = await ep_repo.find_where(
f"owner_id = '{owner_id}' AND deprecated_by IS NULL"
)
assert len(active_rows) == 1
merged_row = active_rows[0]
assert merged_row.entry_id == merged_entry_id
assert merged_row.parent_type == "cluster"
assert merged_row.session_id is None
# -- Verify: session_id filter excludes the merged episode.
session_rows = await ep_repo.find_where(
f"owner_id = '{owner_id}' AND deprecated_by IS NULL "
f"AND session_id = 's_test'"
)
assert len(session_rows) == 0
finally:
conn.close()
await _teardown_sqlite()