docs: XERJ + Google AI — EmbeddingGemma (verified), Gemini API, ADK - #7
Merged
Merged
Conversation
Worked, verified examples of using XERJ with Google's AI stack, in docs/examples/google-ai/. XERJ speaks the OpenAI-compatible /v1/embeddings contract and an ES REST/MCP surface, which is what Google's embedding API and agent framework plug into. Contents, each labelled by how it was checked: 1. EmbeddingGemma (google/embeddinggemma-300m, Google's open model) — embeddinggemma.toml points XERJ's proxy at Ollama's OpenAI endpoint for fully local, key-free embeddings. VERIFIED END-TO-END: four docs indexed through EmbeddingGemma, then three semantic queries with NO shared words with their answers all matched correctly (0.878 / 0.876 / 0.902) — real neural understanding, not lexical overlap. 2. Gemini Embeddings API (gemini-embedding-001) — gemini-embeddings.toml uses the endpoint from Google's OpenAI-compatibility docs (generativelanguage.googleapis.com/v1beta/openai/embeddings). Config matches the documented contract; the contract itself is proven by the offline mock test and the EmbeddingGemma run (identical OpenAI shape). Running the managed API additionally needs a GEMINI_API_KEY. 3. ADK agent (adk_xerj_agent.py) — a Google ADK Agent (gemini-2.5-flash) whose search_documents tool queries XERJ and returns cited snippets. VERIFIED: the agent constructs and the tool returns real cited results from the EmbeddingGemma-backed index. The full Gemini reasoning loop needs a GOOGLE_API_KEY; the XERJ tool integration does not. 4. run-offline-test.sh + mock_embed_server.py — a key-free, dependency-free proof of the whole path: mock /v1/embeddings server, XERJ in proxy mode, external API called at ingest AND query time. Honesty notes kept in the README: EmbeddingGemma and the ADK tool are verified here; the managed Gemini API config is verified structurally (matches Google's documented contract, same shape as the runs that do work) and needs a key to execute. Endpoints/model names change — the README links each Google source. Docs/example only; no engine code changed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Worked, verified examples of using XERJ with Google's AI stack, in docs/examples/google-ai/. XERJ speaks the OpenAI-compatible /v1/embeddings contract and an ES REST/MCP surface, which is what Google's embedding API and agent framework plug into.
Contents, each labelled by how it was checked:
EmbeddingGemma (google/embeddinggemma-300m, Google's open model) — embeddinggemma.toml points XERJ's proxy at Ollama's OpenAI endpoint for fully local, key-free embeddings. VERIFIED END-TO-END: four docs indexed through EmbeddingGemma, then three semantic queries with NO shared words with their answers all matched correctly (0.878 / 0.876 / 0.902) — real neural understanding, not lexical overlap.
Gemini Embeddings API (gemini-embedding-001) — gemini-embeddings.toml uses the endpoint from Google's OpenAI-compatibility docs (generativelanguage.googleapis.com/v1beta/openai/embeddings). Config matches the documented contract; the contract itself is proven by the offline mock test and the EmbeddingGemma run (identical OpenAI shape). Running the managed API additionally needs a GEMINI_API_KEY.
ADK agent (adk_xerj_agent.py) — a Google ADK Agent (gemini-2.5-flash) whose search_documents tool queries XERJ and returns cited snippets. VERIFIED: the agent constructs and the tool returns real cited results from the EmbeddingGemma-backed index. The full Gemini reasoning loop needs a GOOGLE_API_KEY; the XERJ tool integration does not.
run-offline-test.sh + mock_embed_server.py — a key-free, dependency-free proof of the whole path: mock /v1/embeddings server, XERJ in proxy mode, external API called at ingest AND query time.
Honesty notes kept in the README: EmbeddingGemma and the ADK tool are verified here; the managed Gemini API config is verified structurally (matches Google's documented contract, same shape as the runs that do work) and needs a key to execute. Endpoints/model names change — the README links each Google source.
Docs/example only; no engine code changed.