From da98ddc4a104d2d063d55888f1494f5b2fa9f19a Mon Sep 17 00:00:00 2001 From: Yi Lu Date: Tue, 4 Aug 2026 01:43:43 +0000 Subject: [PATCH] docs: sync README files with latest repo state --- reflexio/README.md | 3 ++- reflexio/server/README.md | 5 +++-- reflexio/server/services/README.md | 3 ++- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/reflexio/README.md b/reflexio/README.md index 95c423be..caaac3e3 100644 --- a/reflexio/README.md +++ b/reflexio/README.md @@ -148,8 +148,9 @@ client (Python SDK) - `braintrust/` - Braintrust eval export/sync support - `lineage/` - Resolve current records and schedule tombstone garbage collection for superseded profile/playbook rows - `governance/` - Subject-reference contracts and retention/barrier helpers used by storage and lineage - - `storage/` - Abstract layer (SQLite prod, LocalJSON test) with governance-aware write validation and durable `learning_jobs` contracts + - `storage/` - Abstract layer (SQLite prod, LocalJSON test) with governance-aware write validation, durable `learning_jobs` contracts, and canonical session-outcome identity helpers - `pre_retrieval/` - Query rewriting and document expansion helpers + - `search_exposure.py` - Optional enterprise boundary for recording served user-playbook exposure sets after unified search - `configurator/` - YAML config loader - **`billing_meter.py`**: OSS usage-event facade for learning/search metering; keep imports function-local at call sites so enterprise emitters remain optional - **`site_var/`**: Global settings singleton diff --git a/reflexio/server/README.md b/reflexio/server/README.md index ec432b1a..08930b40 100644 --- a/reflexio/server/README.md +++ b/reflexio/server/README.md @@ -501,14 +501,14 @@ Reformulates user search queries into clean, normalized natural language for imp ### Unified Search Service -**File**: `services/unified_search_service.py` - `run_unified_search()` +**Files**: `services/unified_search_service.py` - `run_unified_search()`; `services/search_exposure.py` - optional final user-playbook exposure recorder boundary Searches across all entity types (profiles, agent_playbooks, user_playbooks) in parallel via a two-phase approach: - **Phase A**: Query rewriting + embedding generation (parallel via ThreadPoolExecutor) - **Phase B**: Entity searches across all types (parallel via ThreadPoolExecutor, 3 workers) -Pre-computed embeddings passed to storage methods via `query_embedding` parameter to avoid redundant embedding calls. +Pre-computed embeddings passed to storage methods via `query_embedding` parameter to avoid redundant embedding calls. `routes/search.py` meters search requests / surfaced learnings and synchronously calls `record_search_exposures()` for the final user-playbook set in unified search before response release; enterprise deployments register the recorder via `SEARCH_EXPOSURE_RECORDER`. ### Storage @@ -519,6 +519,7 @@ Pre-computed embeddings passed to storage methods via `query_embedding` paramete | `storage_base/` | BaseStorage interface split by domain. Legacy facades (`_profiles.py`, `_playbook.py`, `_agent_run.py`, etc.) preserve imports while subpackages (`profiles/`, `playbook/`, `agent_run/`, `governance/`) hold focused abstract store contracts. | | `sqlite_storage/` | SQLite-backed implementation split across matching facades and subpackages (`profiles/`, `playbook/`, `agent_run/`, `governance/`, `base/`), including governance-aware retention/barrier handling, lineage/tombstone support, and durable incremental playbook-aggregation state. | | `governance_validation.py` | Shared validation helpers for subject references and governance contracts before storage writes. | +| `session_outcome_identity.py` | Canonical session trajectory projection plus `trajectory_digest()` / `outcome_contract_digest()` helpers for immutable session outcome identity. | | `retention.py`, `retention_mixin.py` | Data retention and cleanup helpers | | `constants.py`, `error.py` | Storage constants and shared errors | diff --git a/reflexio/server/services/README.md b/reflexio/server/services/README.md index b6d7cd30..ddf4cbeb 100644 --- a/reflexio/server/services/README.md +++ b/reflexio/server/services/README.md @@ -57,13 +57,14 @@ strings before deleting old import paths in the same PR. | `pre_retrieval/` | `QueryReformulator` (`_query_reformulator.py`) + `DocumentExpander` (`_document_expander.py`) - query rewrite and doc expansion for recall. Compact by design; see [README](pre_retrieval/README.md). | | `tagging/` | `TaggingService` (`service.py`) + deferred `tagging_scheduler.py` - post-generation profile/playbook tagging. Compact by design; see [README](tagging/README.md). | | `unified_search_service.py` | `run_unified_search()` — two-phase parallel search across profiles / agent playbooks / user playbooks. | +| `search_exposure.py` | Optional enterprise recorder boundary for final user-playbook search exposure sets; `routes/search.py` calls it synchronously before releasing unified-search responses. | | `retrieval/` | `relevance_floor.py` — result relevance thresholding. `temporal.py` — temporal post-processing driven by reformulation signals: query time windows → per-arm SQL filters, near-duplicate freshness collapse for current-value questions, timestamp ordering for latest-value questions. `user_context_guard.py` — high-precision detection of explicit personalization opt-outs before user-context retrieval. (Superseded/expired rows are already excluded by storage search SQL.) | ## Persistence & Config | Path | Purpose | |------|---------| -| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, durable `learning_jobs`, and SQLite `base/` helpers. `storage_base/playbook/_aggregation.py` defines fenced aggregation state; SQLite implements it in the matching playbook package. Access via `request_context.storage` only. | +| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, durable `learning_jobs`, and SQLite `base/` helpers. `storage_base/playbook/_aggregation.py` defines fenced aggregation state; SQLite implements it in the matching playbook package. `session_outcome_identity.py` owns canonical trajectory/outcome digests for immutable session outcomes. Access via `request_context.storage` only. | | `configurator/` | `DefaultConfigurator` — loads YAML config and creates the storage backend. | ## Key Rules