Skip to content

docs: XERJ + Google AI — EmbeddingGemma (verified), Gemini API, ADK - #7

Merged
xerj-team merged 1 commit into
xerj-org:mainfrom
xerj-team:docs/google-ai-examples
Jul 24, 2026
Merged

docs: XERJ + Google AI — EmbeddingGemma (verified), Gemini API, ADK#7
xerj-team merged 1 commit into
xerj-org:mainfrom
xerj-team:docs/google-ai-examples

Conversation

@xerj-team

Copy link
Copy Markdown
Collaborator

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.

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.
@xerj-team
xerj-team merged commit e6e8e6a into xerj-org:main Jul 24, 2026
4 checks passed
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