Skip to content

symfonic.diagnostics.checks.check_embedding_provider

check_embedding_provider

Embedding-provider env audit (v7.16, item 5).

Closes 4 of the 9 documented silent-fail traps:

  1. EMBEDDING_PROVIDER unset / empty -> stub embedder (silent keyword-only retrieval). ERROR.
  2. EMBEDDING_PROVIDER=openai + non-openai OPENAI_API_BASE -> OpenRouter / DeepSeek / Together routes lack the embeddings API and the request 404s on every memory write. ERROR.
  3. EMBEDDING_PROVIDER=sentence-transformers without the extra installed -> ValueError at construction. ERROR.
  4. EMBEDDING_PROVIDER=sentence-transformers with EMBEDDING_MODEL empty -> silently defaults to all-MiniLM-L6-v2. INFO.

The check inspects os.environ only; the agent argument is unused but preserved to match the uniform async def check_*(agent) -> list signature consumed by :mod:symfonic.diagnostics.runner.

check_embedding_provider async 

check_embedding_provider(
    agent: SymfonicAgent,
) -> list[CheckResult]

Audit EMBEDDING_PROVIDER configuration and the 4 traps it hides.

Source code in src/symfonic/diagnostics/checks/check_embedding_provider.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
async def check_embedding_provider(
    agent: SymfonicAgent,  # noqa: ARG001 -- uniform signature
) -> list[CheckResult]:
    """Audit ``EMBEDDING_PROVIDER`` configuration and the 4 traps it hides."""
    raw = os.environ.get("EMBEDDING_PROVIDER")
    identifier = (raw or "").strip().lower()

    if identifier in {"", "none"}:
        return [
            CheckResult(
                name="embedding_provider.stub",
                severity=Severity.ERROR,
                message=(
                    "EMBEDDING_PROVIDER is unset -- semantic retrieval will "
                    "fall back to keyword-only matching."
                ),
                fix_hint=(
                    "Set EMBEDDING_PROVIDER=sentence-transformers (or openai) "
                    "in .env.  See docs/guides on embedder activation."
                ),
            ),
        ]

    results: list[CheckResult] = []

    if identifier == "openai":
        results.extend(_check_openai_base_url())
    elif identifier == "sentence-transformers":
        results.extend(_check_sentence_transformers_extra())
        results.extend(_check_sentence_transformers_model())
    else:
        results.append(
            CheckResult(
                name="embedding_provider.unknown",
                severity=Severity.ERROR,
                message=(
                    f"EMBEDDING_PROVIDER={raw!r} is not a recognised identifier."
                ),
                fix_hint=(
                    "Supported identifiers: 'sentence-transformers', 'openai', "
                    "'none'.  Anything else raises ValueError at "
                    "make_embedding_provider() time."
                ),
            ),
        )

    return results