feat: select open-world tuning evidence

AI_AGENT_INTEGRATION.md

@@ -95,7 +95,7 @@ learns, what stays private to a user scope, and what transfers to other users.
 | `user_id` | Scope for profiles and user playbooks | Use the human user, tenant, workspace, repo, or project whose preferences should be isolated. For example, use a project id when repo-specific rules should not leak into unrelated repos. |
 | `agent_version` | Scope for shared agent playbooks | Use a stable agent name plus major behavior version, for example `my-agent-v1`. Keep it stable if learnings should transfer across users/projects. If you omit it, the SDK uses `DEFAULT_AGENT_VERSION` (`"agent-v0"`) — fine for a single agent, but set an explicit value before you run more than one. |
 | `session_id` | Group turns for one conversation | Use the host session/conversation id. Generate a UUID if the host does not provide one. |
-| `source` | Audit label | Use the integration name, for example `my-agent-plugin`. |
+| `source` | Producer/workflow label | Use a non-sensitive machine label such as `support-agent:v2`. Where the API permits an empty value, empty means the source is absent. Every non-empty value must match `^[a-z0-9][a-z0-9._:-]{0,127}$` and is limited to 128 ASCII characters. Do not include user identifiers, email addresses, or other PII. |
 
 `user_id` and `agent_version` work together:
 
@@ -234,13 +234,17 @@ Publish request fields:
 | --- | --- | --- | --- |
 | `user_id` | Yes | The user, tenant, workspace, repo, or project scope whose private profiles and user playbooks should be isolated. | `"alice"`, `"tenant-acme"`, `"repo-reflexio"` |
 | `interactions` / `interaction_data_list` | Yes | Ordered conversation turns to publish. Include at least one turn; multi-turn correction examples are best for learning. | `[{"role": "User", "content": "Use pnpm here."}, {"role": "Assistant", "content": "Got it, I will use pnpm."}]` |
-| `source` | No | Integration label for debugging and filtering. Use a stable name for the plugin, framework, or adapter. | `"my-agent-plugin"`, `"vscode-assistant"`, `"support-chatbot"` |
+| `source` | No | Non-sensitive producer/workflow machine label for debugging and filtering. Empty means the source is absent where the API permits it. Every non-empty value must match `^[a-z0-9][a-z0-9._:-]{0,127}$` and is limited to 128 ASCII characters. Do not include user identifiers, email addresses, or other PII. | `"support-agent:v2"` |
 | `agent_version` | Strongly recommended | The shared-agent learning boundary. Use the same value when playbooks should transfer across users. Change it when old playbooks should not transfer. | `"support-agent-v1"`, `"coding-agent-2026-05"` |
 | `session_id` | Yes | Host conversation/session id. Generate a UUID if the host has no session id, and reuse it for all turns in that conversation. | `"sess_01HX8Y..."`, `"3f02b7f8-..."` |
 | `skip_aggregation` | No | `False` when user playbooks should be eligible to roll up into shared agent playbooks. `True` when you want user-level extraction only. | `false` |
 | `force_extraction` | No | `False` for normal background publishing. `True` for manual learn-now, tests, or final flushes where you intentionally want extraction to run immediately. | `false` |
 | `wait_for_response` | SDK/query option | `False` on interactive paths. `True` only when the caller is prepared to wait for extraction results. | `false` |
 
+The source contract applies to new publish and filter inputs. Read responses may
+return historical source values created before this contract; Reflexio preserves
+those values exactly because source participates in session-outcome identity.
+
 Each interaction row should resemble Reflexio's `InteractionData` shape:
 
 ```json
@@ -315,7 +319,7 @@ def publish_turns(
         response = client.publish_interaction(
             user_id=user_id,
             interactions=interactions,
-            source="my-agent-plugin",
+            source="support-agent:v2",
             agent_version=agent_version,
             session_id=session_id,
             wait_for_response=False,

README.md

@@ -105,8 +105,15 @@ Publish conversations from your agent, and Reflexio closes the self-improvement
 | --- | --- |
 | [Python](https://www.python.org/) >= 3.12 | Required for PyPI and source installs |
 | [uv](https://docs.astral.sh/uv/getting-started/installation/) | Required when running from source |
+| Python's linked SQLite runtime | >= 3.35.0 (required for local SQLite storage; not the standalone `sqlite3` CLI) |
 | [Node.js](https://nodejs.org/) >= 18 | Required only for the local docs site in a source checkout |
 
+Check the SQLite runtime linked to Python with:
+
+```shell
+python -c "import sqlite3; print(sqlite3.sqlite_version_info)"
+```
+
 <p align="center">
   <img src="docs/images/demo.gif" width="800px" alt="Reflexio Demo">
 </p>

docs/lib/methods/requests-sessions.ts

@@ -7,7 +7,7 @@ export const requestSessionMethods: MethodDef[] = [
     displayName: "Mark Session Outcome",
     group: "requests-sessions",
     description:
-      "Record the lifetime-durable first success or failure marker for an existing session. User and source are derived from the first request.",
+      "Record the lifetime-durable first terminal outcome for an existing session. Idempotency requires unchanged payload, governance context, and finalized trajectory/session context; changed values conflict. User and source are derived from the first request.",
     httpMethod: "POST",
     endpoint: "/api/session_outcome",
     requestStyle: "json_body",
@@ -17,8 +17,8 @@ export const requestSessionMethods: MethodDef[] = [
         name: "outcome",
         type: "enum",
         required: true,
-        description: "Terminal outcome",
-        enumValues: ["success", "failure"],
+        description: "Terminal outcome: success, failure, or unknown",
+        enumValues: ["success", "failure", "unknown"],
       },
       { name: "occurred_at", type: "number", required: true, description: "Unix epoch seconds when the outcome occurred" },
       { name: "label", type: "string", required: false, description: "Optional label, at most 128 characters" },
@@ -43,8 +43,8 @@ export const requestSessionMethods: MethodDef[] = [
         name: "outcome",
         type: "enum",
         required: false,
-        description: "Exact outcome filter",
-        enumValues: ["success", "failure"],
+        description: "Exact outcome filter: success, failure, or unknown",
+        enumValues: ["success", "failure", "unknown"],
       },
       { name: "label", type: "string", required: false, description: "Exact label filter" },
       { name: "start_time", type: "number", required: false, description: "Inclusive minimum event time" },

docs/lib/methods/unified-search.ts

@@ -23,7 +23,7 @@ export const unifiedSearchMethods: MethodDef[] = [
         type: "number",
         required: false,
         default: 5,
-        description: "Maximum results per entity type",
+        description: "Maximum results per entity type, from 1 to 100",
       },
       {
         name: "threshold",
@@ -50,7 +50,8 @@ export const unifiedSearchMethods: MethodDef[] = [
         name: "user_id",
         type: "string",
         required: false,
-        description: "Filter by user ID (profiles, user_playbooks)",
+        description:
+          "Filter by user ID (profiles, user_playbooks), at most 255 characters",
       },
       {
         name: "entity_types",
@@ -90,12 +91,26 @@ export const unifiedSearchMethods: MethodDef[] = [
           "Search mode: vector (embedding similarity), fts (full-text search), or hybrid (combined with RRF)",
         enumValues: ["vector", "fts", "hybrid"],
       },
+      {
+        name: "request_id",
+        type: "string",
+        required: false,
+        description:
+          "Caller correlation ID for the search turn, at most 255 characters",
+      },
       {
         name: "session_id",
         type: "string",
         required: false,
         description:
-          "Agent session this search serves. When set, results already returned to the same session are skipped and next-best matches backfilled; searches without it neither read nor record session dedup state",
+          "Agent session this search serves, at most 255 characters. When set, results already returned to the same session are skipped and next-best matches backfilled; searches without it neither read nor record session dedup state",
+      },
+      {
+        name: "interaction_id",
+        type: "number",
+        required: false,
+        description:
+          "Caller interaction ID for the search turn; must be a positive integer (minimum 1)",
       },
     ],
   },

docs/lib/methods/user-playbooks.ts

@@ -70,6 +70,18 @@ export const userPlaybookMethods: MethodDef[] = [
         required: false,
         description: "Filter by user (via request_id linkage to requests table)",
       },
+      {
+        name: "request_id",
+        type: "string",
+        required: false,
+        description: "Caller correlation ID, at most 255 characters",
+      },
+      {
+        name: "session_id",
+        type: "string",
+        required: false,
+        description: "Caller session ID, at most 255 characters",
+      },
       {
         name: "agent_version",
         type: "string",
@@ -105,7 +117,7 @@ export const userPlaybookMethods: MethodDef[] = [
         type: "number",
         required: false,
         default: 10,
-        description: "Maximum number of results to return",
+        description: "Maximum number of results to return, from 1 to 100",
       },
       {
         name: "threshold",

reflexio/cli/README.md

@@ -144,7 +144,7 @@ Apply to all three modes:
 | `--wait`            | Block until server-side extraction finishes (returns real counts).      |
 | `--session-id`      | Required unless each payload includes `session_id`; group publishes into one session. |
 | `--agent-version`   | Tag the interaction with an agent version (used by playbook filtering). |
-| `--source`          | Free-form source tag (defaults to `cli`).                                |
+| `--source`          | Non-sensitive producer/workflow label matching `^[a-z0-9][a-z0-9._:-]{0,127}$`; never use user identifiers or PII (defaults to `cli`). |
 | `--skip-aggregation`| Extract profiles/playbooks but skip playbook aggregation.                |
 | `--force-extraction`| Bypass all extraction gates (`stride_size`, cheap pre-filter, LLM `should_run`) and always run extractors. |
 | `--evaluation-only` | Store the request for session-level evaluation only; requires `--session-id` and skips profile/playbook extraction. |

reflexio/cli/utils.py

@@ -504,8 +504,24 @@ def run_services(
     for path in supervisor.stop_request_paths.values():
         remove_pidfile(path)
 
+    service_names = {svc.name for svc in services}
+    gate_local_embedding = {"embedding", "backend"}.issubset(service_names)
+
     try:
+        if gate_local_embedding:
+            embedding = next(svc for svc in services if svc.name == "embedding")
+            supervisor.start_service(embedding)
+            if not _wait_for_all_ready(
+                {"embedding": supervisor.ready_events["embedding"]},
+                {"embedding": supervisor.processes["embedding"]},
+            ):
+                raise RuntimeError(
+                    "embedding service did not become ready before backend startup"
+                )
+
         for svc in services:
+            if gate_local_embedding and svc.name == "embedding":
+                continue
             supervisor.start_service(svc)
         supervisor.write_current_pidfile()
     except (OSError, RuntimeError):

reflexio/client/client.py

@@ -528,7 +528,9 @@ def publish_interaction(
         Args:
             user_id: The user ID.
             interactions: List of interaction data.
-            source: The source of the interaction.
+            source: Non-sensitive producer/workflow label. A non-empty value
+                must match ``^[a-z0-9][a-z0-9._:-]{0,127}$`` and must not
+                contain user identifiers or PII.
             agent_version: The agent version.
             session_id: Required non-empty session ID for grouping requests.
             wait_for_response: If True, the **server** waits for
@@ -893,6 +895,8 @@ def search_user_playbooks(
         threshold: float | None = None,
         enable_reformulation: bool | None = None,
         search_mode: SearchMode | None = None,
+        request_id: str | None = None,
+        session_id: str | None = None,
     ) -> SearchUserPlaybooksViewResponse:
         """Search for user playbooks with semantic/text search and filtering.
 
@@ -906,10 +910,14 @@ def search_user_playbooks(
             end_time (Optional[datetime]): End time for created_at filter
             status_filter (Optional[list[Optional[Status]]]): Filter by status (None for CURRENT, PENDING, ARCHIVED)
             tags (Optional[list[str]]): Match playbooks having any of these tags.
-            top_k (Optional[int]): Maximum number of results to return (default: 10)
+            top_k (Optional[int]): Maximum results to return, from 1 to 100 (default: 10)
             threshold (Optional[float]): Similarity threshold for vector search.
                 When omitted, the embedding model's default is used.
             enable_reformulation (Optional[bool]): Enable LLM query reformulation (default: False)
+            request_id (Optional[str]): Caller correlation ID for the search turn,
+                at most 255 characters.
+            session_id (Optional[str]): Caller session ID for the search turn,
+                at most 255 characters.
 
         Returns:
             SearchUserPlaybooksViewResponse: Response containing matching user playbooks
@@ -929,6 +937,8 @@ def search_user_playbooks(
             threshold=threshold,
             enable_reformulation=enable_reformulation,
             search_mode=search_mode,
+            request_id=request_id,
+            session_id=session_id,
         )
         response = self._make_request(
             "POST", "/api/search_user_playbooks", json=req.model_dump(mode="json")
@@ -1210,13 +1220,20 @@ def mark_session_outcome(
         value: float | None = None,
         metadata: dict[str, Any] | None = None,
     ) -> SetSessionOutcomeResponse:
-        """Record the first terminal outcome for a published session.
+        """Record the immutable first outcome for a published session.
 
         The session must already contain at least one published request. Reflexio
         derives both ``user_id`` and ``source`` from the earliest request ordered
-        by ``(created_at, request_id)``. Only the first outcome is recorded;
-        retries return ``success=True`` and ``recorded=False``. Sessions are not
-        required to report an outcome.
+        by ``(created_at, request_id)``. New canonical rows bind the outcome to
+        the server-owned outcome contract and canonical finalized trajectory. An
+        exact canonical retry must match the payload, contract, and trajectory;
+        otherwise it is rejected with ``reason="conflicting_finalization"``.
+        Rolling-upgrade rows with all four identity fields null compare the
+        caller payload and any available server-derived session context, but
+        cannot compare absent contract or trajectory digests. An accepted retry
+        preserves all four null identity fields and returns ``success=True`` and
+        ``recorded=False``. Sessions may report ``success``, ``failure``, or
+        ``unknown`` and are not required to report an outcome.
         """
         request = SetSessionOutcomeRequest(
             session_id=session_id,
@@ -2822,12 +2839,14 @@ def search(
         Args:
             request (Optional[UnifiedSearchRequest]): The search request object (alternative to kwargs)
             query (str): Search query text
-            top_k (Optional[int]): Maximum results per entity type (default: 5)
+            top_k (Optional[int]): Maximum results per entity type, from 1 to 100
+                (default: 5).
             threshold (Optional[float]): Similarity threshold for vector search.
                 When omitted, the embedding model's default is used.
             agent_version (Optional[str]): Filter by agent version (agent_playbooks, user_playbooks)
             playbook_name (Optional[str]): Filter by playbook name (agent_playbooks, user_playbooks)
-            user_id (Optional[str]): Filter by user ID (profiles, user_playbooks)
+            user_id (Optional[str]): Filter by user ID (profiles, user_playbooks),
+                at most 255 characters.
             tags (Optional[list[str]]): Match entities having any requested tag.
             entity_types (Optional[list[str]]): Entity types to search. Valid values:
                 "profiles", "user_playbooks", "agent_playbooks".
@@ -2843,9 +2862,12 @@ def search(
                 the configured search backend supports it (default: False).
             conversation_history (Optional[list[ConversationTurn] | list[dict]]): Prior conversation turns for context-aware query reformulation. Accepts ConversationTurn objects or dicts with "role" and "content" keys.
             search_mode (Optional[SearchMode | str]): Search mode to use. Accepts SearchMode enum or string value ("vector", "fts", "hybrid").
-            request_id (Optional[str]): Caller correlation id for the search turn.
-            session_id (Optional[str]): Caller session id for the search turn.
-            interaction_id (Optional[int]): Caller interaction id for the search turn.
+            request_id (Optional[str]): Caller correlation ID for the search turn,
+                at most 255 characters.
+            session_id (Optional[str]): Caller session ID for the search turn,
+                at most 255 characters. Also enables session-scoped result deduplication.
+            interaction_id (Optional[int]): Caller interaction ID for the search
+                turn; must be a positive integer (minimum 1).
 
         Returns:
             UnifiedSearchViewResponse: Combined search results from all entity types