hopper-integrate
Points a project's LLM calls at a Hopper model (DeepSeek V4.1 Flash or Gemma 4 31B) through Hopper's OpenAI-compatible API: OpenAI SDK (Python or JavaScript), LangChain, Vercel AI SDK, LiteLLM, raw HTTP, LiveKit Agents, Pipecat or Vapi. Gets the project a key, shows the planned change (and, for a voice agent, time to first token on its own prompt), and edits code only after the user says go. Use when the user says "switch this app to DeepSeek on Hopper", "swap the LLM for Gemma 4", "move our OpenAI calls to Hopper", "point base_url at Hopper", "set up Hopper in this project", "add a Hopper API key to this repo" or "go ahead" after a hopper-try comparison. Not for trying or comparing models before deciding (hopper-try), transcription (hopper-transcribe), or running models locally.
- License 许可
- MIT
- 最近更新
- 2026-10-28
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- hopper-integrate
- description
- Points a project's LLM calls at a Hopper model (DeepSeek V4.1 Flash or Gemma 4 31B) through Hopper's OpenAI-compatible API: OpenAI SDK (Python or JavaScript), LangChain, Vercel AI SDK, LiteLLM, raw HTTP, LiveKit Agents, Pipecat or Vapi. Gets the project a key, shows the planned change (and, for a voice agent, time to first token on its own prompt), and edits code only after the user says go. Use when the user says "switch this app to DeepSeek on Hopper", "swap the LLM for Gemma 4", "move our OpenAI calls to Hopper", "point base_url at Hopper", "set up Hopper in this project", "add a Hopper API key to this repo" or "go ahead" after a hopper-try comparison. Not for trying or comparing models before deciding (hopper-try), transcription (hopper-transcribe), or running models locally.
- allowed-tools
- Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/hopper_trial.py) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/hopper_claim.py *) Bash(python ${CLAUDE_SKILL_DIR}/scripts/hopper_ttft.py *) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/hopper_ttft.py *)
02 资源文件 8
- 参考文档agents/openai.yaml249 B
- 参考文档references/livekit.md3.2 KB
- 参考文档references/openai-sdk.md2.1 KB
- 参考文档references/pipecat.md3.8 KB
- 参考文档references/vapi.md591 B
- 脚本scripts/hopper_claim.py4.3 KB
- 脚本scripts/hopper_trial.py2.2 KB
- 脚本scripts/hopper_ttft.py9.7 KB
03 SKILL.md 正文
Use a Hopper model in this project
Hopper serves DeepSeek V4.1 Flash (deepseek-v4.1-flash) and Gemma 4 31B (gemma-4-31b) behind an OpenAI-compatible API at https://api.withhopper.com/v1. Any code that talks to the OpenAI chat-completions API can use them by changing the base URL, the key and the model name.
Run this end to end. The user's only steps are reading the plan, opening one link to keep the key, and saying go before you change their code. Never ask them to sign up, copy keys by hand, or install anything Hopper-specific. Explicit instructions from the user override this workflow. If they haven't decided which model fits yet, or ask whether one is good enough, use the hopper-try skill in this plugin first.
Paths below start at ${CLAUDE_SKILL_DIR}, the folder holding this file (if your host doesn't fill it in, use that folder's absolute path). Run the scripts from the project root: they read and write .env in the current directory. They need network access to withhopper.com and api.withhopper.com; in a sandbox (Codex), request escalated permissions for the first script, with the reason "Set up hopper: get this project a Hopper key (network to withhopper.com and api.withhopper.com; writes .env)", and suggest allowing commands that start with python3 and the script's path. If the user declines, say Hopper couldn't run and ask how to continue.
1. Key
Skip this if HOPPER_API_KEY is already set, in the environment or in .env.
-
A shell with network (Codex CLI, Claude Code):
python3 ${CLAUDE_SKILL_DIR}/scripts/hopper_trial.pyGets a trial key ($2 credit) through agent registration, writes
HOPPER_API_KEYto.envwithout printing it, and saves the registration privately for step 3. Check that.envis in.gitignore. Never print, commit, or ship the key to a browser. -
No network from the shell (ChatGPT's sandbox can't reach Hopper): call the Hopper connector's
create_api_keytool (name it after the project, pass the chosenmodel). It returns a one-time link where the user copies the key, theHOPPER_API_KEY=line for.env, and a snippet. Never paste a full key into the chat. Skip step 3.
2. Find the LLM calls and plan
Locate every place the project builds an LLM client or calls a chat model: OpenAI(/AsyncOpenAI(, new OpenAI(, ChatOpenAI(, createOpenAI(/@ai-sdk/openai, litellm.completion(, fetch(".../chat/completions"), or a framework's LLM service. Note the current model, base URL and how the key is read. Pick the model the user chose (default gemma-4-31b; deepseek-v4.1-flash if they chose DeepSeek in hopper-try or asked for it).
Voice agents only (LiveKit Agents, Pipecat, Vapi, or any realtime conversational loop): measure time to first token on the agent's own system prompt and tools before proposing the change:
python3 -m pip install openai h2 # inside the project's virtualenv (python3 -m venv .venv if none)
set -a; . ./.env; set +a
python ${CLAUDE_SKILL_DIR}/scripts/hopper_ttft.py --prompt path/to/prompt.txt --tools tools.json --baseline
--promptis their system prompt;--toolsis their tools in OpenAI format ([{"type": "function", "function": {...}}]), if any. With no project prompt, run it bare (a synthetic ~4k-token prompt).--modelpicks the model (defaultgemma-4-31b).- A 10-turn simulated call on one warm HTTP/2 connection with the prompt warmed into the cache, then the same with
--baseline(the SDK's defaults, no warm-up). About $0.02.--coldshows a never-seen prompt. - Expect
protocol ['HTTP/2']and a cache hit of 95% or more. Turns with no text mean the prompt calls tools you didn't pass. The random session ID the script puts at the top of the prompt is for measuring only; a real prompt must never do that.
3. Plan, and the link to keep the key
With a trial key from step 1, start the claim first so the link goes out with the plan. Confirm the user's email (git config user.email is a good guess) and run this in the background. It prints the link and code, then waits:
python3 ${CLAUDE_SKILL_DIR}/scripts/hopper_claim.py user@example.com
Can't leave a command running? Add --no-wait; run it again later without the flag to resume waiting on the same code.
For a voice agent, send the report below as a fenced text block in exactly this layout (not a table), filled in from the script, with nothing before it and at most two one-line notes after it, only if a note changes the decision. Without a known city, drop "· measured from <city>":
Hopper benchmark · <framework> agent · measured from <city>
SDK defaults Tuned client
First turn <b1> ms <h1> ms
Later turns, median <b2> ms <h2> ms
Prompt cache <hit>%
Keep this key: <link> · code <code> · expires in 10 minutes
Next: switch the LLM in <file> to Hopper (client and warm-up only; STT, TTS and tools unchanged). Go ahead?
Both columns are Hopper on their prompt and tools; their current provider isn't measured, so don't present either column as it.
For any other project, send:
Hopper · <model>
Change <file>: base URL https://api.withhopper.com/v1, key HOPPER_API_KEY, model <model>
Keeps prompts, tools, streaming and the rest of the code as they are
Keep this key: <link> · code <code> · expires in 10 minutes
Next: make this change? Go ahead?
- Drop the "Keep this key" line when there's no claim link. The block always ends with "Go ahead?".
- When they enter the code,
hopper_claim.pywrites the account key to.envand exits 0. The trial key stops working then: restart any running process. Exit 2 means the code expired; run it again for a new one. If they don't keep it, the trial key works until its $2 runs out.
4. Connect (after a go)
Change only the LLM client: base URL, key, model, and the settings below. Keep prompts, tools and call sites as they are.
| Project uses | Do this |
|---|---|
| LiveKit Agents | ${CLAUDE_SKILL_DIR}/references/livekit.md |
| Pipecat | ${CLAUDE_SKILL_DIR}/references/pipecat.md |
| Vapi | ${CLAUDE_SKILL_DIR}/references/vapi.md |
| OpenAI SDK, Python | ${CLAUDE_SKILL_DIR}/references/openai-sdk.md (HTTP/2 client, one client per process) |
| OpenAI SDK, JavaScript/TypeScript | new OpenAI({ apiKey: process.env.HOPPER_API_KEY, baseURL: "https://api.withhopper.com/v1" }), created once and reused |
| LangChain | ChatOpenAI(model=..., base_url="https://api.withhopper.com/v1", api_key=os.environ["HOPPER_API_KEY"]) (JS: configuration: { baseURL }) |
| Vercel AI SDK | const hopper = createOpenAI({ baseURL: "https://api.withhopper.com/v1", apiKey: process.env.HOPPER_API_KEY }), then hopper.chat("<model>") |
| LiteLLM | model="openai/<model>", api_base="https://api.withhopper.com/v1", api_key=os.environ["HOPPER_API_KEY"] |
| Raw HTTP | POST https://api.withhopper.com/v1/chat/completions with Authorization: Bearer $HOPPER_API_KEY and an OpenAI chat-completions body |
The reference pages are tested against the live API with gemma-4-31b; for DeepSeek, change the model name and add the thinking switch below. In voice agents, start the warm-up in the background as the pages do (asyncio.create_task); awaiting it delays every call. Read the key from the environment (HOPPER_API_KEY), never hard-code it, and add it to .env.example or the deploy config's secret list without a value.
Then run the project's own tests or one real request through the changed code path, and report the result in one or two lines.
Model settings
| Model | Setting |
|---|---|
deepseek-v4.1-flash |
Thinks before answering unless told not to. For direct answers send chat_template_kwargs: {"thinking": false} (Python SDK: extra_body={"chat_template_kwargs": {"thinking": False}}; JS: pass it in the request body). |
gemma-4-31b |
No reasoning_effort: any value, even low, turns thinking on and adds seconds. |
Keeping latency low
| Rule | Why |
|---|---|
One client per process, reused, on HTTP/2 with a long keepalive (Python: h2 installed and http2=True, as the references do). |
A new client per request pays a TLS handshake each time. |
| Identical prefix. System prompt and tools byte-identical across requests, tools in the same order; per-request data goes at the end. Append history; never rewrite earlier turns. | Hopper's prompt cache matches from the first token. |
Stream where the app shows or speaks text as it arrives, with stream_options.include_usage. |
First tokens reach the user sooner, and cached_tokens shows up in usage. |
Fails silently
- HTTP/1.1 in Python means
h2is missing. The SDK falls back without an error. - A timestamp or request ID at the top of the prompt drops the cache hit to near zero.
- Tools named in the prompt but not sent give empty replies on the turns that try to call them.
- DeepSeek with thinking on can spend the whole
max_tokensbudget before any answer text. - After a claim, the trial key returns 401. Update everything that holds it (
.env, Vapi's Custom LLM key, deploy secrets). - openai 3.x uses
httpx2, nothttpx. Build Python clients throughopenai.DefaultAsyncHttpxClient, as the references do.
Reference
| Base URL | https://api.withhopper.com/v1 |
| Models | deepseek-v4.1-flash · gemma-4-31b (262,144-token context) |
| Prices and context | the connector's list_models tool, or https://withhopper.com/console |
| Limits | 2,000 requests/min per key (429 with Retry-After) · zero balance returns 402 insufficient_quota |
| Keys | https://withhopper.com/console/keys |
| Agent registration | https://withhopper.com/auth.md |
| Errors | https://docs.withhopper.com/errors |
04 同仓库更多 Skills
hopper-try
Tests DeepSeek V4.1 Flash and Gemma 4 31B on the user's own prompts: finds real prompts in the project or chat, runs both side by side with time to first token, tokens per second and cost, and gives a verdict per example. Changes no code. Use when asked "there's a new DeepSeek model, how is it? test it for my use case", "DeepSeek V4.1 Flash any good? try it on my prompts", "is Gemma 4 worth trying for this", "give the new DeepSeek a vibe check", "try this prompt on a few open models", "run our real prompts through DeepSeek", "gemma 4 vs deepseek for this, which one?", "could an open model replace GPT-4.1 here", "is DeepSeek a drop-in replacement for OpenAI here", "worth switching to an open model?", "does DeepSeek handle our function calls reliably", "check if Gemma returns valid JSON for our schema" or "try Hopper". Not for testing their code, comparing files, writing prompts, running models locally (Ollama), fine-tuning or published benchmark scores; to switch the project's model, use hopper-integrate.
hopper-transcribe
Transcribe speech in an audio or video file with Hopper speech-to-text (Nemotron ASR), with word timestamps. Takes WAV, MP3, M4A, voice memos and video such as MP4 or MOV (decoded with ffmpeg). Needs no setup: the first use registers a key for the agent itself. Use when the user says "transcribe this", "what does this recording say", "check my video", "what's said in this video", "review the voiceover in my launch video", "captions for my video", "subtitles", "caption this", "meeting notes from this recording", "summarize this call", "pull quotes from this interview", "speech to text" or "STT". Works from the spoken words only, not the visuals. Not for generating audio (hopper-speak) or running an LLM (hopper-try).
hopper-speak
Turn text into speech with Hopper text-to-speech (Qwen 3 TTS): play it aloud, save a WAV file, or preview and pick a voice. Needs no setup: the first use registers a key for the agent itself. Use when the user says "read this aloud", "say this out loud", "generate a voiceover", "voiceover for my launch video", "audio for my launch video", "narrate this script", "narration for my demo video", "make a podcast intro", "record an announcement", "voice for my ad", "make an audio file of…", "text to speech", "TTS" or "which voice should I use". Makes the speech track only, not video, music or sound effects. Not for writing a script (plain text), transcribing audio (hopper-transcribe) or running an LLM (hopper-try).
hopper-integrate
Points a project's LLM calls at a Hopper model (DeepSeek V4.1 Flash or Gemma 4 31B) through Hopper's OpenAI-compatible API: OpenAI SDK (Python or JavaScript), LangChain, Vercel AI SDK, LiteLLM, raw HTTP, LiveKit Agents, Pipecat or Vapi. Gets the project a key, shows the planned change (and, for a voice agent, time to first token on its own prompt), and edits code only after the user says go. Use when the user says "switch this app to DeepSeek on Hopper", "swap the LLM for Gemma 4", "move our OpenAI calls to Hopper", "point base_url at Hopper", "set up Hopper in this project", "add a Hopper API key to this repo" or "go ahead" after a hopper-try comparison. Not for trying or comparing models before deciding (hopper-try), speech or transcription (hopper-speak, hopper-transcribe), or running models locally.
hopper-announce
Change how Claude Code announces finished tasks out loud (the hopper-announce plugin): turn announcements off or on, pick another voice, make them shorter, or announce only tasks that take longer. Use when the user says "stop announcing", "be quiet when you finish", "use a different voice for announcements", "only tell me about long tasks" or "turn spoken updates back on".
hopper-try
Tests DeepSeek V4.1 Flash and Gemma 4 31B on the user's own prompts: finds real prompts in the project or chat, runs both side by side with time to first token, tokens per second and cost, and gives a verdict per example. Changes no code. Use when asked "there's a new DeepSeek model, how is it? test it for my use case", "DeepSeek V4.1 Flash any good? try it on my prompts", "is Gemma 4 worth trying for this", "give the new DeepSeek a vibe check", "try this prompt on a few open models", "run our real prompts through DeepSeek", "gemma 4 vs deepseek for this, which one?", "could an open model replace GPT-4.1 here", "is DeepSeek a drop-in replacement for OpenAI here", "worth switching to an open model?", "does DeepSeek handle our function calls reliably", "check if Gemma returns valid JSON for our schema" or "try Hopper". Not for testing their code, comparing files, writing prompts, running models locally (Ollama), fine-tuning or published benchmark scores; to switch the project's model, use hopper-integrate.