Gemini Service Client#

Source: examples/clients/gemini_service_client.py

Introduction#

Gemini hosted inference is useful when teams want multimodel experimentation through one provider SDK, while keeping request payloads under the framework’s provider-neutral LLM contracts. This example exercises the Gemini service client path with trace capture and deterministic output support for CI.

Technical Implementation#

  1. Configure Tracer with JSONL + console sinks so each run emits machine-readable traces.

  2. Build runtime inputs through public package APIs and invoke GeminiServiceLLMClient.generate(...).

  3. Construct LLMRequest payload fields and execute one representative remote-style call.

  4. Print a compact JSON payload that includes trace metadata for docs and deterministic tests.

        flowchart LR
    A["Prompt input"] --> B["main(): tracing setup"]
    B --> C["GeminiServiceLLMClient.generate(...)"]
    C --> D["LLMRequest and LLMResponse contracts"]
    C --> E["Tracer JSONL + console events"]
    D --> F["Output payload"]
    E --> F
    F --> G["Printed JSON result"]
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6import design_research_agents as drag
 7
 8
 9def _build_payload() -> dict[str, object]:
10    # Build the hosted Gemini client using public runtime APIs, then execute one representative request.
11    client = drag.GeminiServiceLLMClient(
12        name="gemini-prod",
13        default_model="gemini-2.5-flash",
14        api_key_env="GOOGLE_API_KEY",
15        max_retries=3,
16        model_patterns=("gemini-2.5-flash", "gemini-2.5-*"),
17    )
18    description = client.describe()
19    prompt = "In one sentence, when should engineers run an explicit design pre-mortem?"
20    response = client.generate(
21        drag.LLMRequest(
22            messages=(
23                drag.LLMMessage(role="system", content="You are a concise engineering design assistant."),
24                drag.LLMMessage(role="user", content=prompt),
25            ),
26            model=client.default_model(),
27            temperature=0.0,
28            max_tokens=120,
29        )
30    )
31    llm_call = {
32        "prompt": prompt,
33        "response_text": response.text,
34        "response_model": response.model,
35        "response_provider": response.provider,
36        "response_has_text": bool(response.text.strip()),
37    }
38    return {
39        "client_class": description["client_class"],
40        "default_model": description["default_model"],
41        "llm_call": llm_call,
42        "backend": description["backend"],
43        "capabilities": description["capabilities"],
44        "server": description["server"],
45    }
46
47
48def main() -> None:
49    """Run traced Gemini service client call payload."""
50    # Fixed request id keeps traces and docs output deterministic across runs.
51    request_id = "example-clients-gemini-service-call-001"
52    tracer = drag.Tracer(
53        enabled=True,
54        trace_dir=Path("artifacts/examples/traces"),
55        enable_jsonl=True,
56        enable_console=True,
57    )
58    payload = tracer.run_callable(
59        agent_name="ExamplesGeminiServiceClientCall",
60        request_id=request_id,
61        input_payload={"scenario": "gemini-service-client-call"},
62        function=_build_payload,
63    )
64    assert isinstance(payload, dict)
65    payload["example"] = "clients/gemini_service_client.py"
66    payload["trace"] = tracer.trace_info(request_id)
67    # Print the results
68    print(json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=True))
69
70
71if __name__ == "__main__":
72    main()

Expected Results#

Run Command

PYTHONPATH=tests/example_monkeypatch:src DRA_EXAMPLE_LLM_MODE=deterministic python examples/clients/gemini_service_client.py

This checkout-only command reproduces the documented output without a live backend. For real installs, credentials, and backend-specific setup, see LLM Clients.

Example output captured with DRA_EXAMPLE_LLM_MODE=deterministic (timestamps, durations, and trace filenames vary by run):

{
  "backend": {
    "api_key_env": "GOOGLE_API_KEY",
    "default_model": "gemini-2.5-flash",
    "kind": "gemini_service",
    "max_retries": 3,
    "model_patterns": [
      "gemini-2.5-flash",
      "gemini-2.5-*"
    ],
    "name": "gemini-prod"
  },
  "capabilities": {
    "json_mode": "native",
    "max_context_tokens": null,
    "streaming": true,
    "tool_calling": "none",
    "vision": false
  },
  "client_class": "GeminiServiceLLMClient",
  "default_model": "gemini-2.5-flash",
  "example": "clients/gemini_service_client.py",
  "llm_call": {
    "prompt": "In one sentence, when should engineers run an explicit design pre-mortem?",
    "response_has_text": true,
    "response_model": "gemini-2.5-flash",
    "response_provider": "example-test-monkeypatch",
    "response_text": "Run a design pre-mortem before committing architecture changes with high uncertainty or safety risk."
  },
  "server": null,
  "trace": {
    "request_id": "example-clients-gemini-service-call-001",
    "trace_dir": "artifacts/examples/traces",
    "trace_path": "artifacts/examples/traces/run_20260222T162206Z_example-clients-gemini-service-call-001.jsonl"
  }
}

References#