claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/benchmarks/retrieval_latency/scenarios.py

@@ -0,0 +1,134 @@
+"""
+Canned query set and vocabulary for the retrieval latency benchmark.
+
+The query set, vocabulary, and templates are frozen as module-level
+constants so that benchmark runs are bit-for-bit reproducible across
+machines and across time. Do not mutate.
+"""
+
+from __future__ import annotations
+
+# 20 queries spanning short / long / keyword-heavy / semantic-heavy.
+# Query diversity matters because hybrid search behavior depends on
+# how many FTS tokens match vs how well the query vector aligns.
+QUERIES: tuple[str, ...] = (
+    # short, keyword-heavy
+    "refund policy",
+    "shipping delay",
+    "cancel subscription",
+    "password reset",
+    "billing error",
+    # short, semantic
+    "user was frustrated with the agent",
+    "agent apologized and offered compensation",
+    "customer wants to speak to a manager",
+    "sales opportunity upsell",
+    "technical issue escalation",
+    # long, conversational
+    "the user complained that the previous agent had been rude and dismissive during a prior call",
+    "looking for playbooks where we recommend offering a discount when a customer threatens to churn",
+    "anything related to the enterprise plan negotiation playbook for high-value accounts",
+    "profiles of users who have reported repeated shipping problems in the last month",
+    # long, semantic
+    "what do we know about users who rely on the mobile app and have poor network conditions",
+    "situations where the agent should not offer a refund because policy prevents it",
+    "user asks about product roadmap and pricing changes",
+    # keyword-heavy, rare tokens
+    "api key rotation quota limit",
+    "webhook signature verification failure",
+    "gdpr data export request",
+)
+
+
+# Fixed small vocabulary used to build synthetic profiles and playbooks.
+# Enough diversity for non-trivial BM25 scoring but not large enough to
+# dominate memory at N=10_000.
+VOCABULARY: tuple[str, ...] = (
+    "refund",
+    "shipping",
+    "cancel",
+    "subscription",
+    "password",
+    "billing",
+    "frustrated",
+    "apologized",
+    "manager",
+    "sales",
+    "technical",
+    "escalation",
+    "rude",
+    "dismissive",
+    "discount",
+    "churn",
+    "enterprise",
+    "negotiation",
+    "mobile",
+    "network",
+    "roadmap",
+    "pricing",
+    "policy",
+    "quota",
+    "webhook",
+    "gdpr",
+    "export",
+    "verification",
+    "signature",
+    "rotation",
+    "limit",
+    "profile",
+    "playbook",
+    "agent",
+    "user",
+    "request",
+    "session",
+    "context",
+    "history",
+    "interaction",
+    "feedback",
+    "resolution",
+    "complaint",
+    "praise",
+    "upgrade",
+    "downgrade",
+    "trial",
+    "payment",
+    "invoice",
+    "receipt",
+    "tax",
+    "shipping",
+    "delivery",
+    "tracking",
+    "return",
+    "exchange",
+    "warranty",
+    "bug",
+    "crash",
+    "error",
+    "timeout",
+    "latency",
+    "performance",
+    "slow",
+    "fast",
+    "reliable",
+    "consistent",
+    "intermittent",
+    "regression",
+    "feature",
+)
+
+
+# Templated sentences used to build synthetic playbook/profile content.
+# Each template has at least one `{word}` slot so the synthetic text has
+# real token variety across the corpus.
+CONTENT_TEMPLATES: tuple[str, ...] = (
+    "The user asked about {word} and the agent should clarify policy details.",
+    "When the customer mentions {word}, confirm the account status first.",
+    "Escalate to a senior agent if the user repeats {word} after one attempt.",
+    "Offer a {word} to retain accounts showing churn risk indicators.",
+    "Capture the {word} and log it against the user's profile for follow-up.",
+    "The agent should proactively mention {word} during enterprise calls.",
+    "If {word} is unclear, ask a clarifying question before committing.",
+    "Document the {word} in the session notes with a timestamp.",
+    "Do not promise {word} without checking the internal knowledge base.",
+    "Recommend {word} as the next step when the user sounds uncertain.",
+)

package/plugin/vendor/reflexio/reflexio/benchmarks/retrieval_latency/seed.py

@@ -0,0 +1,255 @@
+"""
+Deterministic synthetic corpus for the retrieval latency benchmark.
+
+Builds ``UserProfile``, ``UserPlaybook``, and ``AgentPlaybook`` objects from
+a fixed vocabulary and template set, then inserts them through the real
+service-layer add methods (``Reflexio.add_user_profile`` et al.) so that the
+storage index, FTS table, and vector index are exercised through the same
+code paths that production uses.
+
+Profiles and user playbooks are spread across a small fixed user pool so
+that a per-user filter (``user_id``) still hits a non-trivial number of
+rows — without that, profile search would always return at most one row
+regardless of N.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import uuid
+from collections.abc import Iterable
+from datetime import UTC, datetime
+
+from reflexio.benchmarks.retrieval_latency.embed_cache import (
+    make_fake_document_embedder,
+    patch_storage_get_embedding,
+)
+from reflexio.benchmarks.retrieval_latency.scenarios import (
+    CONTENT_TEMPLATES,
+    VOCABULARY,
+)
+from reflexio.lib.reflexio_lib import Reflexio
+from reflexio.models.api_schema.domain.entities import (
+    AddAgentPlaybookRequest,
+    AddUserPlaybookRequest,
+    AddUserProfileRequest,
+    AgentPlaybook,
+    UserPlaybook,
+    UserProfile,
+)
+
+logger = logging.getLogger(__name__)
+
+# Small pool of user_ids — profiles and user-playbooks distribute across
+# these so that per-user filters still touch a meaningful number of rows.
+USER_POOL_SIZE = 10
+# Small pool of agent versions / playbook names — gives playbook-name filters
+# enough selectivity to look like real usage without being single-row lookups.
+AGENT_VERSION_POOL_SIZE = 3
+PLAYBOOK_NAME_POOL_SIZE = 5
+
+# Per-entity RNG seeds. All derived from a single base so the entire corpus
+# is reproducible from one number, but each entity type gets its own stream so
+# they don't collide content with each other.
+_BENCH_SEED_BASE = 42
+_PROFILE_SEED = _BENCH_SEED_BASE
+_USER_PLAYBOOK_SEED = _BENCH_SEED_BASE + 1
+_AGENT_PLAYBOOK_SEED = _BENCH_SEED_BASE + 2
+
+# Batch size used when sending profiles/playbooks through add_* — keeps
+# request objects under a sensible size and amortizes storage transactions.
+_SEED_BATCH_SIZE = 100
+
+
+def _user_id(idx: int) -> str:
+    """
+    Deterministically map an object index to a user_id in the fixed pool.
+
+    Args:
+        idx (int): The sequential index of the object being generated.
+
+    Returns:
+        str: A user_id string of the form ``bench_user_{i}``.
+    """
+    return f"bench_user_{idx % USER_POOL_SIZE}"
+
+
+def _agent_version(idx: int) -> str:
+    """
+    Deterministically map an object index to an agent_version.
+
+    Args:
+        idx (int): The sequential index of the object being generated.
+
+    Returns:
+        str: An agent_version string of the form ``bench_agent_v{i}``.
+    """
+    return f"bench_agent_v{idx % AGENT_VERSION_POOL_SIZE}"
+
+
+def _playbook_name(idx: int) -> str:
+    """
+    Deterministically map an object index to a playbook_name.
+
+    Args:
+        idx (int): The sequential index of the object being generated.
+
+    Returns:
+        str: A playbook_name string of the form ``bench_playbook_{i}``.
+    """
+    return f"bench_playbook_{idx % PLAYBOOK_NAME_POOL_SIZE}"
+
+
+def _content(rng: random.Random) -> str:
+    """
+    Build one line of synthetic content from the fixed vocabulary.
+
+    Picks a template and fills its single slot with a vocabulary word. Also
+    appends 3–8 extra vocabulary tokens to give BM25 some additional surface
+    area to match against.
+
+    Args:
+        rng (random.Random): Seeded RNG controlling all choices.
+
+    Returns:
+        str: A synthetic content string (typically 10–20 tokens).
+    """
+    template = rng.choice(CONTENT_TEMPLATES)
+    word = rng.choice(VOCABULARY)
+    extra_count = rng.randint(3, 8)
+    extras = " ".join(rng.choice(VOCABULARY) for _ in range(extra_count))
+    return f"{template.format(word=word)} {extras}"
+
+
+def build_profiles(n: int) -> list[UserProfile]:
+    """
+    Build ``n`` deterministic synthetic ``UserProfile`` objects.
+
+    Args:
+        n (int): Number of profiles to generate.
+
+    Returns:
+        list[UserProfile]: Profiles spread across the fixed user pool. Each
+        has a fresh UUID profile_id, a synthetic content string, and a
+        current timestamp (fixed across a single run via ``rng`` for
+        determinism at the seeding step).
+    """
+    rng = random.Random(_PROFILE_SEED)
+    now = int(datetime.now(UTC).timestamp())
+    return [
+        UserProfile(
+            profile_id=f"bench_profile_{i}_{uuid.UUID(int=rng.getrandbits(128))}",
+            user_id=_user_id(i),
+            content=_content(rng),
+            last_modified_timestamp=now,
+            generated_from_request_id=f"bench_req_{i}",
+        )
+        for i in range(n)
+    ]
+
+
+def build_user_playbooks(n: int) -> list[UserPlaybook]:
+    """
+    Build ``n`` deterministic synthetic ``UserPlaybook`` objects.
+
+    Args:
+        n (int): Number of user playbooks to generate.
+
+    Returns:
+        list[UserPlaybook]: Playbooks spread across the fixed user and
+        agent-version pools. ``user_playbook_id`` is left at the default
+        ``0`` so storage assigns fresh IDs during insertion.
+    """
+    rng = random.Random(_USER_PLAYBOOK_SEED)
+    return [
+        UserPlaybook(
+            user_id=_user_id(i),
+            agent_version=_agent_version(i),
+            playbook_name=_playbook_name(i),
+            request_id=f"bench_req_{i}",
+            content=_content(rng),
+        )
+        for i in range(n)
+    ]
+
+
+def build_agent_playbooks(n: int) -> list[AgentPlaybook]:
+    """
+    Build ``n`` deterministic synthetic ``AgentPlaybook`` objects.
+
+    Args:
+        n (int): Number of agent playbooks to generate.
+
+    Returns:
+        list[AgentPlaybook]: Playbooks spread across the fixed agent-version
+        and playbook-name pools.
+    """
+    rng = random.Random(_AGENT_PLAYBOOK_SEED)
+    return [
+        AgentPlaybook(
+            agent_version=_agent_version(i),
+            playbook_name=_playbook_name(i),
+            content=_content(rng),
+        )
+        for i in range(n)
+    ]
+
+
+def _batched[T](items: list[T], size: int) -> Iterable[list[T]]:
+    """
+    Yield contiguous batches of ``items`` with length up to ``size``.
+
+    Args:
+        items (list[T]): Input list to batch.
+        size (int): Maximum batch length.
+
+    Yields:
+        list[T]: Each batch in order.
+    """
+    for start in range(0, len(items), size):
+        yield items[start : start + size]
+
+
+def seed_corpus(reflexio: Reflexio, storage: object, n: int) -> None:
+    """
+    Insert a full synthetic corpus into the given Reflexio instance.
+
+    Document embeddings are generated from a deterministic fake embedder
+    for the duration of this call — document vector *content* doesn't affect
+    query-time latency (only row count does), so the optimization trades
+    vector meaningfulness for seeding speed. Query-time retrieval is
+    expected to patch the storage with a real query embedding cache instead.
+
+    Args:
+        reflexio (Reflexio): Service-layer facade with storage wired up.
+        storage: The underlying ``BaseStorage`` instance to patch.
+        n (int): Number of each entity type to seed (profiles, user
+            playbooks, agent playbooks — ``3 * n`` total rows).
+    """
+    fake = make_fake_document_embedder()
+    with patch_storage_get_embedding(storage, fake):
+        logger.info("Seeding %d profiles / user_playbooks / agent_playbooks", n)
+        for batch in _batched(build_profiles(n), _SEED_BATCH_SIZE):
+            reflexio.add_user_profile(AddUserProfileRequest(user_profiles=batch))
+        for batch in _batched(build_user_playbooks(n), _SEED_BATCH_SIZE):
+            reflexio.add_user_playbook(AddUserPlaybookRequest(user_playbooks=batch))
+        for batch in _batched(build_agent_playbooks(n), _SEED_BATCH_SIZE):
+            reflexio.add_agent_playbook(AddAgentPlaybookRequest(agent_playbooks=batch))
+    logger.info("Seeding complete (n=%d)", n)
+
+
+def pick_bench_user_id(query_idx: int) -> str:
+    """
+    Choose a user_id for profile/user-playbook search from the seeded pool.
+
+    Rotates through the pool by query index so successive queries aren't
+    always hitting the same user's rows.
+
+    Args:
+        query_idx (int): Index of the current query (0-based).
+
+    Returns:
+        str: A user_id that exists in the seeded corpus.
+    """
+    return f"bench_user_{query_idx % USER_POOL_SIZE}"

package/plugin/vendor/reflexio/reflexio/cli/README.md

@@ -0,0 +1,287 @@
+# Reflexio CLI
+
+`reflexio` is a first-class CLI for running the Reflexio service, publishing interactions, exploring extracted profiles and playbooks, and wiring results into your own agent. Every command is also runnable as `python -m reflexio ...`.
+
+## Table of Contents
+
+- [Install & invoke](#install--invoke)
+- [Global flags](#global-flags)
+- [Quick Reference](#quick-reference)
+- [Services](#services)
+- [Publishing interactions](#publishing-interactions)
+- [Search & context](#search--context)
+- [Interactions](#interactions)
+- [User profiles](#user-profiles)
+- [Agent playbooks](#agent-playbooks)
+- [User playbooks](#user-playbooks)
+- [Config](#config)
+- [Auth](#auth)
+- [Diagnostics](#diagnostics)
+- [Raw API access](#raw-api-access)
+- [Common Workflows](#common-workflows)
+- [Getting help](#getting-help)
+
+## Quick Reference
+
+Most common commands at a glance:
+
+| Task | Command |
+|------|---------|
+| Start server | `reflexio services start` |
+| Publish conversation | `reflexio publish --user-id USER --data '...'` |
+| Search everything | `reflexio search "query"` |
+| List profiles | `reflexio user-profiles list --user-id USER` |
+| List playbooks | `reflexio agent-playbooks list` |
+| Check health | `reflexio status check` |
+| Stop server | `reflexio services stop` |
+
+## Install & invoke
+
+The CLI ships with the `reflexio` package. After `uv sync`:
+
+```shell
+uv run reflexio --help
+uv run reflexio --version
+```
+
+## Global flags
+
+Available on every command (set on the root, before the subcommand):
+
+| Flag           | Env var              | Purpose                          |
+| -------------- | -------------------- | -------------------------------- |
+| `--json`       | —                    | Structured JSON output envelopes |
+| `--server-url` | `REFLEXIO_URL`       | Backend API URL                  |
+| `--api-key`    | `REFLEXIO_API_KEY`   | API bearer token                 |
+| `--version`    | —                    | Show CLI version                 |
+
+Example: `uv run reflexio --json search "refund policy"`.
+
+## Services
+
+Start and stop the backend, docs server, and optional local embedding daemon.
+
+```shell
+uv run reflexio services start                          # backend :8081, docs :8082
+uv run reflexio services start --storage sqlite         # sqlite (default) | supabase | postgres
+uv run reflexio services start --backend-port 9000 --docs-port 9001
+uv run reflexio services start --only backend --no-reload
+uv run reflexio embeddings serve --port 8072            # OpenAI-compatible local embeddings
+uv run reflexio services stop
+uv run reflexio services stop --force                   # SIGKILL instead of SIGTERM
+```
+
+When `REFLEXIO_EMBEDDING_PROVIDER=local_service` or
+`CLAUDE_SMART_USE_LOCAL_EMBEDDING=1`, `services start --only backend` starts an
+`embedding` service dependency automatically. The daemon exposes
+`POST /v1/embeddings` and supports `local/nomic-embed-v1.5`,
+`local/nomic-embed-text-v1.5`, and `local/minilm-l6-v2`. Local embedding
+requests allow extra time for model cold start; override with
+`REFLEXIO_EMBEDDING_SERVICE_TIMEOUT_MS` when needed.
+
+## Publishing interactions
+
+The top-level `publish` shortcut is the fastest way to get a conversation into Reflexio. It forwards to `interactions publish` and supports three input modes: single-turn flags, inline JSON, and file/stdin payloads.
+
+Reflexio learns most from interactions that contain a **signal** — a user correction, a stated preference, or an explicit choice between alternatives. Examples throughout this doc use that kind of content rather than trivial Q&A.
+
+### Mode 1 — Single-turn (shortcut flags)
+
+`--user-message` / `--agent-response` wrap a single user turn and a single assistant turn. Use this for quick preference captures or smoke-tests. It is **hard-coded to exactly 2 turns** — use Mode 2 or 3 below for anything longer.
+
+```shell
+uv run reflexio publish \
+  --user-id alice \
+  --user-message "Stop adding disclaimers and caveats. Give me the answer in one line." \
+  --agent-response "Understood — I'll drop the boilerplate from now on." \
+  --wait
+```
+
+### Mode 2 — Multi-turn via inline JSON (`--data`)
+
+For real dialogues (3+ turns, tool calls, corrections mid-conversation), pass a JSON object whose `interactions` field is a list of `{role, content}` items. Each item becomes one turn, in order. Roles are `user` and `assistant`; `system` and `tool` turns are also accepted.
+
+```shell
+uv run reflexio publish --user-id alice --wait --data '{
+  "interactions": [
+    {"role": "user",      "content": "Deploy the payments service to us-east-1."},
+    {"role": "assistant", "content": "Starting deployment to us-east-1..."},
+    {"role": "user",      "content": "Wait — production always runs in us-west-2. Never us-east-1."},
+    {"role": "assistant", "content": "Understood. Switching to us-west-2."},
+    {"role": "user",      "content": "Good. And always confirm the region with me before deploying."},
+    {"role": "assistant", "content": "Noted. I'll confirm the region on every deploy going forward."}
+  ]
+}'
+```
+
+This single call can populate **both** a user profile (`production region is us-west-2`) and an agent playbook (`confirm deploy region before executing`), which is exactly the loop Reflexio is designed for.
+
+You can also load inline JSON from a file with `@`: `--data @conversation.json`.
+
+### Mode 3 — JSON / JSONL file or stdin
+
+For bulk publishing or conversations you already have on disk, point at a file. A `.json` file should be a single object (or a list of objects); a `.jsonl` file is one JSON object per line, one conversation per line.
+
+```shell
+uv run reflexio publish --file conversations.jsonl --user-id alice --wait
+cat conversations.jsonl | uv run reflexio publish --stdin --user-id alice
+```
+
+Each payload object accepts the same fields as Mode 2 (`interactions`, and optionally per-payload overrides for `user_id`, `session_id`, `source`, `agent_version`). A payload's own `user_id` wins over the `--user-id` flag, so you can publish a mixed-user JSONL file in a single call.
+
+### Common flags
+
+Apply to all three modes:
+
+| Flag                | Purpose                                                                 |
+| ------------------- | ----------------------------------------------------------------------- |
+| `--wait`            | Block until server-side extraction finishes (returns real counts).      |
+| `--session-id`      | Group multiple `publish` calls into one session.                         |
+| `--agent-version`   | Tag the interaction with an agent version (used by playbook filtering). |
+| `--source`          | Free-form source tag (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. |
+
+Full options via `uv run reflexio interactions publish --help`.
+
+## Search & context
+
+Unified semantic search across profiles and playbooks:
+
+```shell
+uv run reflexio search "deployment region"
+uv run reflexio search "response style" --user-id alice --top-k 10 --threshold 0.5
+```
+
+Fetch formatted context for injection into your own agent. Both `--user-id` and `--agent-version` are required — the command fails loudly otherwise to avoid producing a misleading bootstrap:
+
+```shell
+uv run reflexio context --user-id alice --agent-version v1
+uv run reflexio context --user-id alice --agent-version v1 --query "deploy workflow"
+```
+
+## Interactions
+
+```shell
+uv run reflexio interactions list --user-id alice
+uv run reflexio interactions search "deployment"
+uv run reflexio interactions delete <interaction-id>
+uv run reflexio interactions delete-all
+```
+
+## User profiles
+
+```shell
+uv run reflexio user-profiles list --user-id alice
+uv run reflexio user-profiles search "preferences"
+uv run reflexio user-profiles add --user-id alice --data @profile.json
+uv run reflexio user-profiles regenerate --user-id alice
+uv run reflexio user-profiles delete <profile-id>
+uv run reflexio user-profiles delete-all
+```
+
+## Agent playbooks
+
+```shell
+uv run reflexio agent-playbooks list --agent-version v1
+uv run reflexio agent-playbooks search "error handling"
+uv run reflexio agent-playbooks aggregate --agent-version v1
+uv run reflexio agent-playbooks update-status <playbook-id> --status approved
+uv run reflexio agent-playbooks regenerate --agent-version v1
+uv run reflexio agent-playbooks delete <playbook-id>
+```
+
+## User playbooks
+
+```shell
+uv run reflexio user-playbooks list --user-id alice
+uv run reflexio user-playbooks search "preferences" --user-id alice
+uv run reflexio user-playbooks add --user-id alice --data @playbook.json
+uv run reflexio user-playbooks update <playbook-id> --data @patch.json
+uv run reflexio user-playbooks delete <playbook-id>
+```
+
+## Config
+
+```shell
+uv run reflexio config show
+uv run reflexio config set --data '{"api_key_config": {"openai": "sk-..."}}'
+uv run reflexio config set --data @config.json
+uv run reflexio config storage                           # show storage backend info
+uv run reflexio config pull                              # pull server config to local file
+```
+
+## Auth
+
+```shell
+uv run reflexio auth login --api-key $REFLEXIO_API_KEY --server-url http://localhost:8081
+uv run reflexio auth status
+uv run reflexio auth logout
+```
+
+## Diagnostics
+
+```shell
+uv run reflexio status check                             # server health
+uv run reflexio status whoami                            # resolved identity
+uv run reflexio doctor check                             # env + connectivity diagnostics
+uv run reflexio setup init                               # interactive setup wizard
+```
+
+## Raw API access
+
+Escape hatch for calling any endpoint directly. Supports `GET`, `POST`, `DELETE`:
+
+```shell
+uv run reflexio api GET /health
+uv run reflexio api POST /api/get_agent_playbooks --data '{"agent_version": "v1"}'
+uv run reflexio api POST /api/set_config --data @config.json
+```
+
+## Common Workflows
+
+A typical end-to-end workflow: publish a conversation, verify that Reflexio extracted the right data, then browse the results.
+
+### 1. Start services
+
+```shell
+uv run reflexio services start
+```
+
+### 2. Publish a conversation
+
+```shell
+uv run reflexio publish --user-id alice --wait --data '{
+  "interactions": [
+    {"role": "user",      "content": "Always use dark mode in the dashboard."},
+    {"role": "assistant", "content": "Noted — I will default to dark mode for you."}
+  ]
+}'
+```
+
+### 3. Search to verify extraction
+
+```shell
+uv run reflexio search "dark mode"
+```
+
+You should see a profile entry reflecting the user's preference.
+
+### 4. Browse profiles and playbooks
+
+```shell
+uv run reflexio user-profiles list --user-id alice
+uv run reflexio user-playbooks list --user-id alice
+uv run reflexio agent-playbooks list
+```
+
+## Getting help
+
+Every command and subcommand supports `--help`:
+
+```shell
+uv run reflexio --help
+uv run reflexio user-profiles --help
+uv run reflexio user-playbooks --help
+uv run reflexio agent-playbooks --help
+```