Agent skill

Lemonade Client Patterns

by amd in amd/gaia

Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite.

MITAuto-check passedTesting & QA

Install Lemonade Client Patterns

skills CLI
$ npx skills add amd/gaia --skill lemonade-client-patterns -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install amd/gaia lemonade-client-patterns --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/amd/gaia.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/lemonade-client-patterns .claude/skills/lemonade-client-patterns && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
lemonade-client-patterns
GitHub stars
1.6k
Token cost
~2.5k tokens
SKILL.md length
1,050 words
Files
1
Skills in repo
44
Repo updated
First seen
Licence
MIT

At a glance

Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite.

  • Tasks that involve Test generation
  • SKILL.md covers Context, Key Patterns, Important Files & Locations and Conventions, plus 2 more sections
  • Calls git and python; needs LEMONADE_API_KEY

What it does

Lemonade Client Patterns is an agent skill from amd/gaia. Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite. Apply when modifying lemonadeclient.py, its providers, VLMClient, UI routers, or any file that calls Lemonade HTTP endpoints.

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Testing & QA, covering Test generation. The repository describes itself as: Build AI agents for your PC. The licence is MIT.

When your agent uses it

  • Tasks that involve Test generation

Example prompts

  • “/lemonade-client-patterns”

Requirements

  • Python 3
  • A credential in LEMONADE_API_KEY

What it can do on your machine

Read from SKILL.md and the folder at commit 6c3bb5c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git
    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • LEMONADE_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Lemonade Client Patterns loads about 2.5k tokens when it runs. Until then it costs about 68 tokens; SKILL.md has 1,050 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~68
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from amd/gaia at commit 6c3bb5c, republished under its MIT licence (© amd). 1,050 words, ~2,458 tokens.

Download SKILL.mdSave it as .claude/skills/lemonade-client-patterns/SKILL.md (or your agent's skills folder).
name
lemonade-client-patterns
description
Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite. Apply when modifying lemonade_client.py, its providers, VLMClient, UI routers, or any file that calls Lemonade HTTP endpoints.

Lemonade Client Patterns

Context

src/gaia/llm/lemonade_client.py is GAIA's primary Lemonade HTTP client. Changes to its interface ripple through LemonadeProvider, VLMClient, Agent UI routers, _chat_helpers.py, server.py, and agents/base/agent.py. The test suite mixes responses (for requests-based calls) and mocker.patch on httpx (for async calls).

Key Patterns

HTTP call sites — not just _send_request

LemonadeClient has a central _send_request, but several call sites bypass it with a direct requests.post (non-streaming chat/completions, the responses API, and the SSE endpoints), plus OpenAI(...) constructor sites. Any change that must affect ALL outbound calls (e.g. adding an auth header) has to reach every one of them.

Enumerate them, don't trust a count — the set grows, and a stale number here is exactly the miss this section exists to prevent:

bash
grep -n "requests\.post\|requests\.get\|OpenAI(" src/gaia/llm/lemonade_client.py
Factory must mirror __init__

create_lemonade_client() at the bottom of lemonade_client.py is a convenience factory. When adding a new LemonadeClient.__init__ parameter, update the factory to accept and forward it, or callers that use the factory won't pick up the new param.

It is a public SDK surface that real user paths reach. In-tree callers: __main__, the client's own tests, the flagship sidecar's warm-up turn (hub/agents/gaia/python/gaia_agent/server.py) and the audio tools' transcript-refinement LLM (src/gaia/agents/tools/audio_tools.py). Both of those pass no host/port, so a change to how the factory resolves the server address changes audio transcription and the flagship's warm-up (#3558).

Module-level helpers should be PUBLIC (no underscore)

Helpers shared across packages (vlm_client.py, ui/routers/system.py, ui/_chat_helpers.py, ui/server.py, agents/base/agent.py) must be public-named (no leading _). Leading underscore signals "package-internal" and creates confusion. Precedent: system.py already imports DEFAULT_CONTEXT_SIZE from lemonade_client.

agents/base/agent.py — mostly deferred imports, but not Lemonade-free

agent.py imports a few constants and helpers from gaia.llm.lemonade_client at module level (DEFAULT_MODEL_NAME, the ctx-budget helpers) and CONNECTION_FAILURE_RE from gaia.llm.providers.lemonade, so importing the base Agent already loads lemonade_client. Everything else (LemonadeClient, LemonadeManager, cloud_model_provider, …) is imported inside the methods that use it. Keep new Lemonade-specific behavior behind those deferred imports, and keep lemonade_client cheap to import, since every agent pays for it.

VLMClient does NOT resolve env vars itself

VLMClient forwards api_key= raw to LemonadeClient, which does the single canonical resolution. VLMClient has no direct HTTP calls (delegates everything to self.client), so pre-resolving env vars there violates single-source-of-truth.

401 errors — use fixed-string messages, never response.text

Misconfigured reverse proxies can reflect the Authorization header back in a 401 response body. If response.text is included in a user-visible error message, the API key leaks to CLI output, logs, and bug reports. Always use a fixed-string 401 error that names LEMONADE_API_KEY without including the response body.

OpenAI SDK auth error handling

openai.AuthenticationError is NOT a subclass of openai.APIError in openai>=1.0. It must be caught separately, and the except openai.AuthenticationError: branch MUST come BEFORE the generic except (openai.APIError, openai.APIConnectionError, openai.RateLimitError) branch — Python evaluates except clauses in order and AuthenticationError would otherwise fall through to the generic one. Never include str(e) from an OpenAI exception (the SDK may stringify the request including the Authorization header).

Important Files & Locations

  • src/gaia/llm/lemonade_client.py — Primary client; _send_request is the central chokepoint, but direct requests.post bypass sites exist (grep for them — see above)
  • src/gaia/llm/providers/lemonade.py — LemonadeProvider.__init__ uses backend_kwargs dict to forward to LemonadeClient; add new params with if param is not None: backend_kwargs["param"] = param
  • src/gaia/llm/vlm_client.py — VLMClient.__init__ uses deferred import of LemonadeClient
  • src/gaia/ui/routers/system.py — already imports DEFAULT_CONTEXT_SIZE from lemonade_client (established cross-package import precedent)
  • src/gaia/ui/_chat_helpers.py — 4 Lemonade-bound httpx call sites: auto-title POST (~337), health GET (~1006, ~1058), stats GET (~2289). (Line numbers drift — grep the call, don't trust the offset.)
  • src/gaia/ui/server.py — 2 health probe httpx GET sites (~299, ~311)
  • src/gaia/agents/base/agent.py — _is_loaded_ctx_too_small() is the reference for the deferred pattern (lemonade_client and LemonadeManager imported inside the method)
  • tests/unit/test_lemonade_client_http.py — mocked HTTP via the responses library (TestLemonadeClientMock); _mock_cold_load / _assert_one_load answer and check the pre-request ctx load
  • tests/test_lemonade_client.py — live-server TestLemonadeClientIntegration only (CI selects it with -k Integration)
  • docs/.env.example — This is a Mintlify/docs-proxy config file, NOT GAIA's env var file. GAIA env vars go in .env.example at the repo root.
Show full SKILL.md (414 more words)Show less

Conventions

  • Env var resolution helpers live in lemonade_client.py as public module-level functions (single source of truth)
  • Empty/whitespace env values are treated as unset: value.strip() or None
  • OpenAI SDK sites use api_key=self.api_key or "lemonade" placeholder when unauthenticated — the SDK rejects None/"" with OpenAIError; Lemonade ignores the placeholder value
  • Auth headers: {"Authorization": f"Bearer {api_key}"} — omit the header entirely when key is None (don't send Bearer )
  • Log key presence at DEBUG level only: self.log.debug("Lemonade API key configured") — NEVER log the value

Gotchas & Learned the Hard Way

Deferred imports break the standard patch target

When a class uses deferred imports (import inside __init__ or a method body), patching via the IMPORTING module fails with AttributeError. Patch at the SOURCE module where the symbol is defined.

Wrong: mocker.patch("gaia.llm.vlm_client.LemonadeClient") (deferred import; the name doesn't exist at module level)

Right: mocker.patch("gaia.llm.lemonade_client.LemonadeClient") (patches the definition, affects all users)

assertLogs doesn't escalate child logger levels

self.assertLogs("gaia", level=logging.DEBUG) does NOT force child loggers like gaia.llm.lemonade_client to DEBUG — they inherit their configured level. To capture DEBUG messages from a specific child logger in tests:

python
lc_logger = logging.getLogger("gaia.llm.lemonade_client")
original_level = lc_logger.level
lc_logger.setLevel(logging.DEBUG)
try:
    with self.assertLogs("gaia", level=logging.DEBUG) as cm:
        # ... test body
finally:
    lc_logger.setLevel(original_level)
SSE tests hang without a terminating body

Tests that call SSE-generating methods (pull_model, load_model) via responses library will block forever on iter_lines() unless the mock body is a complete SSE event ending with \n\n:

python
responses.add(
    responses.POST, f"{base_url}/pull",
    body=b"event: complete\ndata: {}\n\n",
    content_type="text/event-stream",
    stream=True,
)
gen = client.pull_model("model")
next(gen)  # consume one item; don't iterate fully or it blocks
_ensure_model_loaded makes its own network calls

In test_401_does_not_trigger_auto_download_retry-style tests, forgetting to mock _ensure_model_loaded causes the test to fail because _ensure_model_loaded itself calls get_status() → list_models(), which makes HTTP requests that can trigger model loading. Always patch _ensure_model_loaded when testing chat_completions error paths. On happy paths, answer it instead (_mock_cold_load) and assert the /load body (model_name, ctx_size, llamacpp_args) — patching it away hides the load the user actually triggers.

Never assume a failure is pre-existing — check main

tests/unit/test_lemonade_client_http.py (formerly the mock class in tests/test_lemonade_client.py) has historically carried a few failures unrelated to any given change (model-name drift, removed kwargs, deprecated APIs). Do not work from a remembered list — a test that was broken last month may have been fixed since, and dismissing it as "pre-existing" would hide a real regression you just introduced.

Confirm empirically for each failing test, every time:

bash
git stash && python -m pytest tests/unit/test_lemonade_client_http.py::<Class>::<test> -x; git stash pop

Fails on a clean main too → pre-existing. Passes there → you broke it.

docs/.env.example is NOT the GAIA env vars file

docs/.env.example is a Mintlify/docs-proxy configuration file. GAIA env variable documentation belongs in .env.example at the repo root.

Reporting what you changed

Follow CLAUDE.md → How You Communicate: lead with the plain-language outcome ("auth headers now reach every Lemonade call site"), then layer the file.py:line detail underneath. Say each point once.

© amd, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/lemonade-client-patterns of amd/gaia.

Open the folder on GitHubat commit 6c3bb5c

Compare with similar skills

Lemonade Client Patterns next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Lemonade Client Patterns compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Lemonade Client Patterns this skillamd/gaia1.6k—~2.5kAutomated safety check: PassMIT
Emcaklofas/kicad-happy1.3k1 repos~2.8kAutomated safety check: PassMIT
Swig Testswig/swig6.3k—~2.3kAutomated safety check: PassCustom licence
Generate Test Cases342164796/generate-test-cases1191 repos~2.9kAutomated safety check: PassNone
Verify Cc Safety Netkenryu42/cc-safety-net1.6k—~2kAutomated safety check: PassMIT
Wioworkersio/skills180—~5.8kAutomated safety check: PassMIT

Similar skills

  • Emc

    aklofas/kicad-happy

    EMC pre-compliance risk analysis for KiCad PCB designs — 18 check categories, 44 rule IDs covering ground planes, decoupling, I/O filtering, switching harmonics, clock routing, differential pair…

    1.3k GitHub starsUsed in 1 repo~2.8k tokens
    Testing & QAAuto-check passed
  • Swig Test

    swig/swig

    Run SWIG test suite for specific languages. An agent skill from swig/swig.

    6.3k GitHub stars~2.3k tokensUpdated today
    Testing & QAAuto-check passed
  • Generate Test Cases

    342164796/generate-test-cases

    自主学习型测试文档生成器。从需求文档(Markdown)生成测试用例 XMind 文件,支持持久化记忆和持续学习。当用户提到"生成测试用例"、"根据需求生成测试"时触发。

    119 GitHub starsUsed in 1 repo~2.9k tokens
    Testing & QAAuto-check passed
  • Verify Cc Safety Net

    kenryu42/cc-safety-net

    Launch and drive the real cc-safety-net CLI — the hook decision path, explain, status/doctor, logs, and the local policy GUI — against an isolated home, capturing evidence.

    1.6k GitHub stars~2k tokensUpdated yesterday
    Testing & QAAuto-check passed
  • Wio

    workersio/skills

    Testing workflow skill for finding high-value test candidates, writing focused tests, generating realistic workloads, reviewing test value, and diagnosing test-suite health.

    180 GitHub stars~5.8k tokensUpdated 2 mo ago
    Testing & QAAuto-check passed
  • File Server

    microsoft/WindowsProtocolTestSuites

    Official

    ALWAYS LOAD THIS SKILL when working with FileServer, SMB, SMB2, SMB3, CIFS, file sharing, MS-SMB2, MS-FSCC, MS-FSA, MS-DFSC, MS-FSRVP, MS-RSVD, MS-SQOS, or any file server protocol test…

    567 GitHub stars~4.1k tokensUpdated 22 days ago
    Testing & QAAuto-check passed

More from amd/gaia

All 44 skills in this repo
  • Adds a release eval scorecard to a GAIA hub agent by writing a harness adapter, running a real eval, and wiring the result into the agent's README and release gate.

    1.6k GitHub stars~2.6k tokensUpdated today
    Auto-check passed
  • Walks through releasing a GAIA sidecar agent as a frozen binary plus npm client through the tag-triggered Agent Hub CI pipeline, with a human gate before publishing.

    1.6k GitHub stars~3.6k tokensUpdated today
    Auto-check passed
  • Mines local Claude Code session transcripts with a deterministic Python pipeline to show what the agent is actually used for, how often it fails and what it costs.

    1.6k GitHub stars~2.3k tokensUpdated today
    Auto-check passed
  • Benchmarks AMD's GAIA agent against Claude Code and across models on quality, honesty, steps, tokens, time and real cost, using gaia eval tasks.

    1.6k GitHub stars~1.8k tokensUpdated today
    Auto-check passed
  • Guides safe code changes by finding the right file with grep or semantic search, reading before editing, reproducing bugs first, and proving a fix with a real test run.

    1.6k GitHub stars~2.1k tokensUpdated today
    Auto-check passed
  • Walks through scaffolding, writing and testing a new GAIA agent as a Python class with the SDK, from the base Agent subclass to registered tool methods.

    1.6k GitHub stars~1.5k tokensUpdated today
    Auto-check passed

Categories

Questions about Lemonade Client Patterns

What does Lemonade Client Patterns do?

Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite. Lemonade Client Patterns is an agent skill from amd/gaia. Patterns, gotchas, and conventions for threading changes through LemonadeClient, its callers, and the GAIA test suite.

When should I use Lemonade Client Patterns?

Lemonade Client Patterns fits situations like: tasks that involve Test generation.

How do I install Lemonade Client Patterns in Claude Code?

Run `npx skills add amd/gaia --skill lemonade-client-patterns -a claude-code`. Or copy the skill folder (.claude/skills/lemonade-client-patterns in amd/gaia) into .claude/skills/lemonade-client-patterns in your project. Claude Code loads it when a task matches its description.

How do I install Lemonade Client Patterns in Codex?

Run `npx skills add amd/gaia --skill lemonade-client-patterns -a codex`. Or copy the skill folder (.claude/skills/lemonade-client-patterns in amd/gaia) into .agents/skills/lemonade-client-patterns in your project. Codex loads it when a task matches its description.

Can I use Lemonade Client Patterns in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add amd/gaia --skill lemonade-client-patterns -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/lemonade-client-patterns, .gemini/skills/lemonade-client-patterns, .github/skills/lemonade-client-patterns and .opencode/skills/lemonade-client-patterns in your project.

What does Lemonade Client Patterns need to run?

Going by SKILL.md and its folder, Lemonade Client Patterns needs the command-line tools its instructions call (git and python) and credentials named LEMONADE_API_KEY. Our summary lists: Python 3; A credential in LEMONADE_API_KEY.

Does Lemonade Client Patterns access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Lemonade Client Patterns safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Lemonade Client Patterns use?

Lemonade Client Patterns is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Lemonade Client Patterns use?

About 2.5k tokens (SKILL.md is roughly 9.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Lemonade Client Patterns?

Skills that share tags, products or a category with Lemonade Client Patterns: Emc (aklofas/kicad-happy, 1.3k stars), Swig Test (swig/swig, 6.3k stars), Generate Test Cases (342164796/generate-test-cases, 119 stars) and Verify Cc Safety Net (kenryu42/cc-safety-net, 1.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Lemonade Client Patterns?

amd (a GitHub organization) maintains it in amd/gaia, which has 1,580 GitHub stars. The repository holds 44 skills in this directory. The repository was last updated on October 6, 2026.

Source: amd/gaia on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.