embedflow 0.5.0__tar.gz → 0.6.0__tar.gz

{embedflow-0.5.0 → embedflow-0.6.0}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v0.6.0 — Migration planner
+
+- Added an advisory `embedflow plan` command and Python API that combine
+  source-index preflight, registry evidence, representative probes, frozen
+  T2-v1 diagnostics, candidate-depth selection, cache planning, economics, and
+  staged rollout guidance without routing traffic or mutating the source.
+- Added structured JSON/YAML plan artifacts with explicit warnings and
+  measured/user-supplied/modeled/unknown provenance.
+
 ## v0.5.0 — Weaviate backend
 
 - Added a read-only Weaviate v4 backend for existing externally-vectorized

{embedflow-0.5.0 → embedflow-0.6.0}/CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 title: "EmbedFlow: Upgrading Legacy Embeddings Without Full Upfront Re-Embedding"
 message: "If EmbedFlow contributes to your work, please cite this software release."
 type: software
-version: 0.5.0
+version: 0.6.0
 date-released: 2026-09-13
 repository-code: "https://github.com/arnsri33/embedflow"
 url: "https://github.com/arnsri33/embedflow"

{embedflow-0.5.0 → embedflow-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embedflow
-Version: 0.5.0
+Version: 0.6.0
 Summary: Progressive embedding-model migration over existing vector indexes.
 Author: Arnav Srivastav
 License-Expression: AGPL-3.0-only
@@ -189,6 +189,21 @@ Selected core records (nDCG@10, `G(50)`):
 See the [registry documentation](https://github.com/arnsri33/embedflow/blob/main/docs/registry.md)
 for matching levels, contract fingerprints, and provenance.
 
+## Advisory migration plans
+
+Use representative query probes to produce a bounded migration recommendation
+before serving:
+
+```bash
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl --format json --output migration-plan.json
+```
+
+The planner reports preflight, registry evidence, frozen T2-v1 finite-tail
+behavior, candidate K, cache/economics projections, and staged rollout
+guidance. It never routes traffic or mutates the source index; `SAFE` is not a
+qrels-based retrieval-quality guarantee. See the [planner guide](https://github.com/arnsri33/embedflow/blob/main/docs/planner.md).
+
 ## Research
 
 For candidate depth `K`, EmbedFlow measures:
@@ -229,6 +244,7 @@ See the [Weaviate guide](https://github.com/arnsri33/embedflow/blob/main/docs/in
 ```bash
 embedflow --help
 embedflow analyze --help
+embedflow plan --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
@@ -242,7 +258,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.5.0 is an alpha release for research and early real-world
+EmbedFlow v0.6.0 is a pre-1.0 release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.5.0 → embedflow-0.6.0}/README.md

@@ -142,6 +142,20 @@ session = embedflow.migrate(
 results = session.search("what causes auroras?", top_k=10)
 ```
 
+## Plan a migration
+
+Build a conservative, evidence-aware recommendation before serving. The
+planner reuses backend preflight, registry matching, and frozen T2-v1; it is
+advisory and never routes traffic or mutates the source index.
+
+```bash
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl --format json --output migration-plan.json
+```
+
+`SAFE` is an empirical finite-tail signal, not a retrieval-quality guarantee.
+See [`docs/planner.md`](https://github.com/arnsri33/embedflow/blob/main/docs/planner.md).
+
 Search responses expose `COLD`, `PARTIAL`, or `WARM`, cache hits and misses,
 synchronous work, queued work, and stage timings. Once the candidate vectors
 are warm, target scoring over that candidate set is deterministic.
@@ -227,6 +241,7 @@ Backend-specific setup and examples:
 ```bash
 embedflow --help
 embedflow analyze --help
+embedflow plan --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
@@ -254,7 +269,7 @@ OpenAPI documentation; see
 
 ## Status
 
-EmbedFlow v0.5.0 is an alpha release for research and early real-world
+EmbedFlow v0.6.0 is a pre-1.0 release for research and early real-world
 testing.
 
 - T2-v1 reports an empirical finite-tail diagnostic.

{embedflow-0.5.0 → embedflow-0.6.0}/README_PYPI.md

@@ -123,6 +123,21 @@ Selected core records (nDCG@10, `G(50)`):
 See the [registry documentation](https://github.com/arnsri33/embedflow/blob/main/docs/registry.md)
 for matching levels, contract fingerprints, and provenance.
 
+## Advisory migration plans
+
+Use representative query probes to produce a bounded migration recommendation
+before serving:
+
+```bash
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl --format json --output migration-plan.json
+```
+
+The planner reports preflight, registry evidence, frozen T2-v1 finite-tail
+behavior, candidate K, cache/economics projections, and staged rollout
+guidance. It never routes traffic or mutates the source index; `SAFE` is not a
+qrels-based retrieval-quality guarantee. See the [planner guide](https://github.com/arnsri33/embedflow/blob/main/docs/planner.md).
+
 ## Research
 
 For candidate depth `K`, EmbedFlow measures:
@@ -163,6 +178,7 @@ See the [Weaviate guide](https://github.com/arnsri33/embedflow/blob/main/docs/in
 ```bash
 embedflow --help
 embedflow analyze --help
+embedflow plan --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
@@ -176,7 +192,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.5.0 is an alpha release for research and early real-world
+EmbedFlow v0.6.0 is a pre-1.0 release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.5.0 → embedflow-0.6.0}/docs/api.md

@@ -48,6 +48,11 @@ The response includes the result list and migration fields such as:
 request. A partial response scores the available target vectors; it can differ
 from the fully warm ranking.
 
+The advisory migration planner is exposed through the Python API and the
+`embedflow plan` CLI. It is intentionally not a synchronous FastAPI endpoint:
+probe analysis may load models and perform bounded candidate work, so operators
+should generate a plan artifact out of band and publish/read it as needed.
+
 `/status` includes safe backend metadata. For pgvector this names the
 schema/table and vector contract; for Pinecone it names the host/index,
 namespace, dimension, metric, and safe vector counts. Neither backend returns

{embedflow-0.5.0 → embedflow-0.6.0}/docs/cli.md

@@ -9,6 +9,7 @@ list. The commands below are the main public entry points.
 embedflow init --config ./embedflow.yaml
 embedflow analyze --config ./embedflow.yaml --output-dir ./analysis
 embedflow evaluate --config ./experiment.yaml --output-dir ./results
+embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl
 ```
 
 `analyze` is the no-target-index workflow. It uses probe queries and frozen
@@ -16,6 +17,15 @@ T2-v1 logic. `evaluate` is the labelled workflow; it computes source quality,
 native target quality, target-within-source-candidates quality, candidate gap,
 containment, and migration depth when the required inputs are available.
 
+`plan` is the advisory migration planner. It runs source preflight and registry
+matching, optionally samples a JSONL probe set, and reports a candidate-depth
+recommendation, cache/economics projections, warnings, and staged rollout
+guidance. Use `--format json` (or `yaml`) for a structured artifact. A plan
+with no probes reports `T2-v1: NOT_RUN`; `SAFE` is a finite-tail diagnostic,
+not a qrels-based retrieval-quality guarantee. A `DEFER`/`EXPAND_PROBE` result
+is still a successful analytical command and exits zero; invalid configuration
+or failed preflight exits nonzero.
+
 ## Serving and operations
 
 ```bash

{embedflow-0.5.0 → embedflow-0.6.0}/docs/configuration.md

@@ -58,6 +58,25 @@ economics:
   gpu_price_per_hour: null
   target_docs_per_second: null
 
+# Optional advisory planner settings. CLI flags override these values.
+planner:
+  max_probes: 250
+  seed: 42
+  k_grid: [20, 50, 100, 200, 500]
+  max_candidates: null
+  max_target_encodes: null
+  max_sync_misses: null
+  background_batch_size: null
+  gpu_hourly_cost: null
+  target_docs_per_second: null
+  queries_per_second: null
+  daily_queries: null
+  cache_hit_rate: null
+  latency_budget_ms: null
+  access_trace: null
+  corpus_name: null
+  corpus_fingerprint: null
+
 state_path: ./embedflow_state.json
 ```
 
@@ -130,6 +149,21 @@ EMBEDFLOW_CANDIDATE_DEPTH
 EMBEDFLOW_MAX_SYNC_MISSES
 EMBEDFLOW_BACKGROUND_BATCH_SIZE
 EMBEDFLOW_PROBE_KMAX
+EMBEDFLOW_PLANNER_MAX_PROBES
+EMBEDFLOW_PLANNER_SEED
+EMBEDFLOW_PLANNER_MAX_CANDIDATES
+EMBEDFLOW_PLANNER_MAX_TARGET_ENCODINGS
+EMBEDFLOW_PLANNER_MAX_SYNC_MISSES
+EMBEDFLOW_PLANNER_BACKGROUND_BATCH_SIZE
+EMBEDFLOW_PLANNER_GPU_HOURLY_COST
+EMBEDFLOW_PLANNER_TARGET_DOCS_PER_SECOND
+EMBEDFLOW_PLANNER_QPS
+EMBEDFLOW_PLANNER_DAILY_QUERIES
+EMBEDFLOW_PLANNER_CACHE_HIT_RATE
+EMBEDFLOW_PLANNER_LATENCY_BUDGET_MS
+EMBEDFLOW_PLANNER_ACCESS_TRACE
+EMBEDFLOW_PLANNER_CORPUS_NAME
+EMBEDFLOW_PLANNER_CORPUS_FINGERPRINT
 ```
 
 ## Input files

{embedflow-0.5.0 → embedflow-0.6.0}/docs/limitations.md

@@ -1,6 +1,6 @@
 # Limitations and release scope
 
-EmbedFlow v0.5.0 is an alpha release for research and early real-world
+EmbedFlow v0.6.0 is a pre-1.0 release for research and early real-world
 testing. The serving path is designed to make migration experiments concrete;
 production rollout still requires application-specific validation.
 

embedflow-0.6.0/docs/planner.md

@@ -0,0 +1,111 @@
+# Migration planner
+
+`embedflow plan` is a bounded, advisory analysis for moving from an existing
+source vector index to a target embedding model. It composes the existing
+backend audit, model contracts, retained registry evidence, probe retrieval,
+frozen T2-v1 diagnostic, cache behavior, and economics helpers. It never
+routes traffic and does not create, update, or delete source-index data.
+
+## Quickstart
+
+Install EmbedFlow with the optional dependency for the configured backend, then
+provide representative query probes as JSONL:
+
+```json
+{"id":"q1","query":"how do I reset my password?"}
+{"id":"q2","query":"what is the vacation policy?"}
+```
+
+Run a terminal plan or save a machine-readable artifact:
+
+```bash
+embedflow plan --config embedflow.yaml --queries probes.jsonl
+embedflow plan --config embedflow.yaml --queries probes.jsonl \
+  --k-grid 20,50,100,200,500 --format json --output migration-plan.json
+```
+
+For a deterministic, network-free walkthrough, run `examples/planner/run_demo.sh`.
+The demo uses the same planner API and tiny hash encoders; it is not a quality
+benchmark.
+
+## What the result means
+
+The result is a versioned (`schema_version: 1`) object with source/target
+contracts, preflight checks, evidence, candidate-depth diagnostics, cache and
+rollout guidance, economics, and structured warnings. The Python API is:
+
+```python
+from embedflow.planner import MigrationPlanner
+
+result = MigrationPlanner("embedflow.yaml").plan("probes.jsonl")
+artifact = result.to_dict()
+```
+
+Recommendation states are deliberately small:
+
+- `PROCEED`: probe evidence and preflight are strong enough for an operator-controlled shadow/canary sequence.
+- `PROCEED_WITH_CAUTION`: probes are acceptable, but evidence coverage or contract/ANN provenance is limited.
+- `EXPAND_PROBE`: T2-v1 asks for a deeper pool or the evidence is too small.
+- `DEFER`: finite-tail behavior is `UNSAFE_OR_UNCERTAIN`; do not canary based on this plan.
+- `BLOCKED`: structural/backend preflight failed; no candidate K is certified.
+
+These are recommendations, not automatic deployment actions. The suggested
+rollout is Validate → Shadow → small canary → expanded canary → target-primary
+path, with the source remaining authoritative until the operator approves each
+step. Stop conditions include source/target errors, p95 latency, queue depth,
+cache hit rate, and any native/qrels evaluation regressions.
+
+## Evidence and T2-v1
+
+Registry matching preserves the existing hierarchy: `EXACT REGISTRY MATCH`,
+`PRIOR EVIDENCE AVAILABLE` (same contracts, different/unknown corpus),
+`RELATED EVIDENCE ONLY`, and `NO REGISTRY MATCH`. Prior or related evidence can
+seed context but cannot override current probe results or certify a new corpus.
+
+The planner calls the existing frozen T2-v1 implementation unchanged. T2-v1 is
+a no-qrels finite-tail diagnostic of candidate behavior. `SAFE` does **not**
+prove a candidate gap, nDCG, recall, or zero quality loss. Without actual qrels
+or native-target evaluation, `candidate_gap` is `null`/`UNKNOWN`. ANN fidelity
+is also `UNKNOWN` unless an exact/reference comparison is supplied by the
+backend audit workflow.
+
+No probes is a valid preflight/economics mode, but T2 is `NOT_RUN`, confidence
+is `INSUFFICIENT`, and no K is presented as safe. Probe JSONL rows may use
+`query` (or the existing `text` alias) and an optional `id`; empty, malformed,
+or duplicate IDs are rejected. `--max-probes` and `--seed` provide deterministic
+bounded sampling. Candidate documents are deduplicated by canonical ID and
+encoded in bounded batches; `--max-target-encodes` can impose a hard cap.
+
+## Cache, performance, and economics
+
+Planning uses an ephemeral target-cache/state directory when it opens a runtime,
+so the normal serving cache is not polluted. It recommends conservative sync
+miss and background batch settings and defaults to traffic-driven progressive
+warming when no access trace is supplied. An access trace can be supplied with
+`--access-trace` as rows such as `{"document_id":"abc","count":192}` to
+model hot-document coverage.
+
+Performance values retain provenance (`measured`, `user_supplied`, `modeled`,
+`registry`, or `unknown`). `--profile` performs only a small local encode/search
+sample with one unmeasured warmup pass excluded; it is diagnostic and is not a
+formal benchmark. Economics accepts `--target-docs-per-second` and
+`--gpu-hourly-cost`; absent inputs remain `UNKNOWN`. Raw vector storage is
+`documents × target dimension × dtype bytes` and excludes ANN overhead,
+metadata, replicas, backups, and database overhead. Progressive percentages
+are materialization scenarios, not claims that a percentage is sufficient.
+
+## Configuration and privacy
+
+An optional `planner:` section mirrors the CLI options (`max_probes`, `seed`,
+`k_grid`, work caps, cache hints, throughput/cost inputs, and corpus identity).
+CLI values take precedence. `EMBEDFLOW_PLANNER_*` environment overrides follow
+the normal config mechanism. Probe text is never copied into plan artifacts or
+telemetry by default; only counts, IDs used for diagnostics, and aggregates are
+reported. Backend credentials are handled by the existing backend adapters and
+are redacted from errors and structured output.
+
+The planner does not provide qrel evaluation, traffic routing, rollback
+automation, distributed scheduling, ANN tuning, integrated-vectorizer contract
+verification, or production cost guarantees. Use `embedflow evaluate` with
+qrels/native target rankings when empirical retrieval-quality claims are
+required.

{embedflow-0.5.0 → embedflow-0.6.0}/docs/releasing.md

@@ -18,8 +18,8 @@ python -m twine check dist/*
 Inspect both archives before uploading:
 
 ```bash
-unzip -l dist/embedflow-0.5.0-py3-none-any.whl
-tar -tzf dist/embedflow-0.5.0.tar.gz
+unzip -l dist/embedflow-0.6.0-py3-none-any.whl
+tar -tzf dist/embedflow-0.6.0.tar.gz
 sha256sum dist/*
 ```
 
@@ -32,7 +32,7 @@ Test the wheel outside the source tree:
 ```bash
 python -m venv /tmp/embedflow-wheel-test
 /tmp/embedflow-wheel-test/bin/python -m pip install --upgrade pip
-/tmp/embedflow-wheel-test/bin/python -m pip install dist/embedflow-0.5.0-py3-none-any.whl
+/tmp/embedflow-wheel-test/bin/python -m pip install dist/embedflow-0.6.0-py3-none-any.whl
 cd /tmp
 /tmp/embedflow-wheel-test/bin/python -c "import embedflow; print(embedflow.__version__)"
 /tmp/embedflow-wheel-test/bin/embedflow --help
@@ -65,7 +65,7 @@ python -m venv /tmp/embedflow-testpypi
 /tmp/embedflow-testpypi/bin/python -m pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  embedflow==0.5.0
+  embedflow==0.6.0
 cd /tmp
 /tmp/embedflow-testpypi/bin/python -c "import embedflow; print(embedflow.__version__)"
 /tmp/embedflow-testpypi/bin/embedflow --help
@@ -79,11 +79,11 @@ Test optional integrations in a second clean environment:
 /tmp/embedflow-testpypi/bin/python -m pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  "embedflow[faiss,dashboard,pinecone,milvus,weaviate]==0.5.0"
+  "embedflow[faiss,dashboard,pinecone,milvus,weaviate]==0.6.0"
 ```
 
 If the same filename already exists on TestPyPI, use a pre-release such as
-`0.5.0rc1` for the TestPyPI-only trial. Keep production `0.5.0` unchanged.
+`0.6.0rc1` for the TestPyPI-only trial. Keep production `0.6.0` unchanged.
 
 ## Trusted Publishing configuration
 
@@ -115,7 +115,7 @@ above keeps the test step explicit.
 3. Run the final release gate and review the generated report.
 4. Configure the PyPI pending publisher and protected `pypi` environment.
 5. Create a Git tag and GitHub Release for the exact package version, for
-   example `v0.5.0`.
+   example `v0.6.0`.
 6. Approve the `pypi` environment when the release workflow is ready.
 7. Verify the files and metadata on PyPI.
 8. Install from production PyPI in a directory outside this checkout.

{embedflow-0.5.0 → embedflow-0.6.0}/embedflow/__init__.py

@@ -1,8 +1,14 @@
 """EmbedFlow: progressive embedding-model migration for existing indexes."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
-from .config import EmbedFlowConfig, load_config
+from .config import EmbedFlowConfig, PlannerConfig, load_config
+
+
+def plan(*args, **kwargs):
+    """Generate an advisory migration plan without changing source traffic."""
+    from .planner import plan_migration
+    return plan_migration(*args, **kwargs)
 
 
 def migrate(*args, **kwargs):
@@ -22,4 +28,4 @@ def analyze_migration(*args, **kwargs):
     return _analyze_migration(*args, **kwargs)
 
 
-__all__ = ["EmbedFlowConfig", "load_config", "migrate", "analyze_migration", "__version__"]
+__all__ = ["EmbedFlowConfig", "PlannerConfig", "load_config", "migrate", "plan", "analyze_migration", "__version__"]

{embedflow-0.5.0 → embedflow-0.6.0}/embedflow/cli.py

@@ -7,6 +7,7 @@ import os
 import platform
 import random
 import sys
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -31,6 +32,7 @@ from .config import (
 from .migration.compatibility import run_probe, save_probe
 from .migration.state import DocumentStore
 from .models import HashEmbeddingModel, load_embedding_model
+from .planner import MigrationPlanner, render_plan
 from .registry import (
     MATCH_EXACT,
     load_benchmark_profiles,
@@ -45,6 +47,26 @@ from .runtime import build_faiss_from_documents, load_documents, open_engine
 def _json(value: Any) -> None: print(json.dumps(value, indent=2, ensure_ascii=False, default=float))
 
 
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Replace a text artifact atomically in its destination directory."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary: str | None = None
+    try:
+        fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent))
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        temporary = None
+    finally:
+        if temporary is not None:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+
 def _normalize_device(value: str | None) -> str | None:
     """Accept the common human spelling ``gpu`` while PyTorch uses ``cuda``."""
     if value is None:
@@ -606,6 +628,53 @@ def cmd_analyze(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_plan(args: argparse.Namespace) -> int:
+    """Generate a structured, advisory migration plan.
+
+    Planning uses an isolated temporary target-cache/state directory and never
+    routes traffic or writes to the configured source index. Progress is sent
+    to stderr so JSON/YAML stdout remains machine-readable.
+    """
+    planner = MigrationPlanner(args.config, device=_normalize_device(args.device), demo=args.demo,
+                               model_root=args.model_root)
+    progress = None if args.quiet or args.format != "text" else lambda message: print(message, file=sys.stderr)
+    result = planner.plan(
+        probe_queries=args.queries,
+        max_probes=args.max_probes,
+        seed=args.seed,
+        k_grid=args.k_grid,
+        max_candidates=args.max_candidates,
+        max_target_encodes=args.max_target_encodes,
+        profile=args.profile,
+        gpu_hourly_cost=args.gpu_hourly_cost,
+        target_docs_per_second=args.target_docs_per_second,
+        queries_per_second=args.queries_per_second,
+        daily_queries=args.daily_queries,
+        cache_hit_rate=args.cache_hit_rate,
+        latency_budget_ms=args.latency_budget_ms,
+        access_trace=args.access_trace,
+        corpus_name=args.corpus_name,
+        corpus_fingerprint=args.corpus_fingerprint,
+        progress=progress,
+    )
+    if args.format == "json":
+        rendered = result.to_json()
+    elif args.format == "yaml":
+        rendered = result.to_yaml()
+    else:
+        rendered = render_plan(result)
+    if args.output:
+        destination = Path(args.output).expanduser()
+        _atomic_write_text(destination, rendered)
+        if not args.quiet:
+            print(f"wrote migration plan to {destination}", file=sys.stderr)
+    if not args.output or not args.quiet:
+        print(rendered, end="" if rendered.endswith("\n") else "\n")
+    # A DEFER/EXPAND result is a valid analytical outcome; only structural
+    # configuration/backend failures raise and become a non-zero CLI exit.
+    return 0
+
+
 def cmd_evaluate(args: argparse.Namespace) -> int:
     """Run Mode A evaluation with qrels and native target evidence."""
     cfg = load_config(args.config)
@@ -882,7 +951,11 @@ def cmd_doctor(args: argparse.Namespace) -> int:
             checks.append({"name": "target_fingerprint", "ok": True, "detail": config.target.fingerprint[:16]})
         except Exception as exc:
             checks.append({"name": "config", "ok": False, "detail": str(exc)})
-    optional_checks = {"faiss", "qdrant_client", "fastapi", "torch", "pytorch", "psycopg", "pinecone", "pymilvus", "weaviate"}
+    # The display label for the ``weaviate`` import is ``weaviate_client``
+    # (``weaviate-client`` is the distribution name).  Keep both spellings
+    # optional so a base install does not fail ``doctor`` merely because an
+    # optional backend is absent.
+    optional_checks = {"faiss", "qdrant_client", "fastapi", "torch", "pytorch", "psycopg", "pinecone", "pymilvus", "weaviate", "weaviate_client"}
     failed = [check for check in checks if not check["ok"] and check["name"] not in optional_checks]
     if args.json:
         _json({"checks": checks, "status": "FAIL" if failed else "PASS"})
@@ -1425,6 +1498,31 @@ def build_parser() -> argparse.ArgumentParser:
     analyze.add_argument("--output")
     analyze.add_argument("--output-dir")
     analyze.set_defaults(func=cmd_analyze)
+    plan_cmd = sub.add_parser("plan", help="build an advisory migration plan from source-index evidence")
+    plan_cmd.add_argument("--config", required=True, help="EmbedFlow YAML configuration")
+    plan_cmd.add_argument("--queries", help="JSONL probe queries; omit to run preflight/evidence/economics only")
+    plan_cmd.add_argument("--max-probes", type=int, help="maximum deterministic probe sample size")
+    plan_cmd.add_argument("--seed", type=int, help="deterministic probe sampling seed")
+    plan_cmd.add_argument("--k-grid", help="comma-separated candidate depths, e.g. 20,50,100,200,500")
+    plan_cmd.add_argument("--max-candidates", type=int, help="hard cap on candidate depth/work")
+    plan_cmd.add_argument("--max-target-encodes", type=int, help="bound unique target document encodes")
+    plan_cmd.add_argument("--format", choices=["text", "json", "yaml"], default="text")
+    plan_cmd.add_argument("--output", help="optional plan artifact path")
+    plan_cmd.add_argument("--profile", action="store_true", help="run a small optional local encode/search profile")
+    plan_cmd.add_argument("--gpu-hourly-cost", type=float)
+    plan_cmd.add_argument("--target-docs-per-second", type=float)
+    plan_cmd.add_argument("--queries-per-second", type=float)
+    plan_cmd.add_argument("--daily-queries", type=float)
+    plan_cmd.add_argument("--cache-hit-rate", type=float)
+    plan_cmd.add_argument("--latency-budget-ms", type=float)
+    plan_cmd.add_argument("--access-trace", help="optional JSONL document access trace")
+    plan_cmd.add_argument("--corpus-name", help="canonical registry corpus identifier, when known")
+    plan_cmd.add_argument("--corpus-fingerprint", help="precomputed corpus fingerprint for exact registry matching")
+    plan_cmd.add_argument("--model-root", help="directory containing staged model snapshots")
+    plan_cmd.add_argument("--device", default=None, help="model device (cpu, cuda, or gpu)")
+    plan_cmd.add_argument("--demo", action="store_true", help="use deterministic demo encoders")
+    plan_cmd.add_argument("--quiet", action="store_true", help="suppress progress and stdout when --output is supplied")
+    plan_cmd.set_defaults(func=cmd_plan)
     evaluate = sub.add_parser("evaluate", help="compute qrels/native-target candidate gaps (Mode A)")
     evaluate.add_argument("--config", required=True)
     evaluate.add_argument("--queries")