Skip to content

docs: verified example — embed via any OpenAI-compatible API - #6

Merged
xerj-team merged 1 commit into
xerj-org:mainfrom
xerj-team:docs/external-embeddings-example
Jul 24, 2026
Merged

docs: verified example — embed via any OpenAI-compatible API#6
xerj-team merged 1 commit into
xerj-org:mainfrom
xerj-team:docs/external-embeddings-example

Conversation

@xerj-team

Copy link
Copy Markdown
Collaborator

XERJ can embed semantic_text through an external OpenAI-compatible /v1/embeddings endpoint (--embed-mode proxy), but there was no runnable proof of it. This adds a key-free, reproducible one.

docs/examples/external-embeddings/:

  • mock_embed_server.py — a ~40-line dependency-free server implementing the exact {input,model} -> {data:[{embedding,index}]} contract XERJ sends.
  • xerj-proxy.toml — the [embedding] mode=proxy config wiring XERJ to it.
  • run.sh — builds nothing, starts the mock, runs XERJ in proxy mode, indexes two docs, and shows the external API is called at ingest AND at query time.
  • README.md — how it's wired, the wire contract, a table of real endpoints (OpenAI / Gemini OpenAI-compatible / local), and the ingest=query embedder symmetry that keeps vectors comparable.

Verified end to end on this branch: XERJ logs embedding backend: external proxy; indexing two docs produces two /v1/embeddings calls; a semantic query for "database outage from too many open connections" is embedded by the same API (third call) and correctly returns the "connection pool was exhausted" document by vector similarity.

Honesty note kept in the README: verified against the reproducible mock (which speaks the exact contract). Real providers using the same OpenAI contract are drop-in, but endpoints/model names change — the doc points readers to each provider's current docs rather than freezing a claim.

Docs/example only; no engine code changed.

XERJ can embed `semantic_text` through an external OpenAI-compatible
`/v1/embeddings` endpoint (`--embed-mode proxy`), but there was no runnable
proof of it. This adds a key-free, reproducible one.

`docs/examples/external-embeddings/`:
  * mock_embed_server.py — a ~40-line dependency-free server implementing the
    exact `{input,model} -> {data:[{embedding,index}]}` contract XERJ sends.
  * xerj-proxy.toml — the `[embedding] mode=proxy` config wiring XERJ to it.
  * run.sh — builds nothing, starts the mock, runs XERJ in proxy mode, indexes
    two docs, and shows the external API is called at ingest AND at query time.
  * README.md — how it's wired, the wire contract, a table of real endpoints
    (OpenAI / Gemini OpenAI-compatible / local), and the ingest=query embedder
    symmetry that keeps vectors comparable.

Verified end to end on this branch: XERJ logs `embedding backend: external
proxy`; indexing two docs produces two `/v1/embeddings` calls; a semantic query
for "database outage from too many open connections" is embedded by the same
API (third call) and correctly returns the "connection pool was exhausted"
document by vector similarity.

Honesty note kept in the README: verified against the reproducible mock (which
speaks the exact contract). Real providers using the same OpenAI contract are
drop-in, but endpoints/model names change — the doc points readers to each
provider's current docs rather than freezing a claim.

Docs/example only; no engine code changed.
@xerj-team
xerj-team merged commit d1a4a7a into xerj-org:main Jul 24, 2026
4 checks passed
@xerj-team
xerj-team deleted the docs/external-embeddings-example branch July 24, 2026 02:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant