Skip to content

Genkit Python SDK v0.14.0

Latest

Choose a tag to compare

@huangjeff5 huangjeff5 released this 19 Nov 15:54
· 2 commits to main since this release
aec146f

0.13 rewrote Genkit Python's veneer layer and public API surface to clean up ergonomics and typing ahead of 1.0. 0.14 keeps that API surface intact and focuses on hardening it before 1.0: we ran bug bashes across all surfaces—with an emphasis on Dev UI compatibility and provider plugins—and shipped those fixes alongside multi-tenant embedder configuration and a simpler response.media accessor.

1.0 is coming very soon—we're holding the 1.0 tag until we finish moving the Google GenAI plugin onto the Interactions API and cleaning up the Vertex AI plugin naming to match organizational changes, avoiding post-1.0 deprecations. We expect both to ship very soon, and in the meantime we will continue to ship small improvements and bug fixes we find from our thorough bug bashing.

uv add --upgrade genkit
# or: pip install --upgrade genkit

Genkit Python has its own repo

Genkit Python now lives in genkit-ai/genkit-python, not in the py/ folder of genkit-ai/genkit.

  • Releases come from main here: Going forward, the latest release matches main on genkit-python.
  • py/ is going away: The py/ folder will be deleted from genkit-ai/genkit. Open issues and PRs on genkit-python.
  • Installs don't change: Package names on PyPI are the same, so pip install genkit and existing pins keep working.

Configure embedders for multi-tenant use cases

GoogleAI() previously raised at startup if no environment API key was set, and ai.embed() had no way to pass a per-request key or tenant context down to an embedder (#49, #114).

GoogleAI() now starts keyless (logging one warning), and ai.embed() / ai.embed_many() accept context={'secrets': {'api_key': ...}}. Rejected keys report ErrorReason.INVALID_CREDENTIALS with status UNAUTHENTICATED.

from genkit import ErrorReason, Genkit
from genkit.embedder import EmbedContext, EmbedRequest, EmbedResponse
from genkit_google_genai import GoogleAI

# 1. Start without a server-wide API key
ai = Genkit(plugins=[GoogleAI()])

# 2. Bill each embed call to the caller's key
vectors = await ai.embed(
    embedder=GoogleAI.embedder('gemini-embedding-001'),
    content='Mushroom Risotto',
    context={'secrets': {'api_key': tenant_key}},
)
# => [Embedding(embedding=[...])]

# 3. Embedder handlers read the same context via EmbedContext
class MenuEmbedConfig(BaseModel):
    dimensions: int = 768

async def embed_menu(req: EmbedRequest[MenuEmbedConfig], ctx: EmbedContext) -> EmbedResponse:
    api_key = ctx.context['secrets']['api_key']
    ...

ai.define_embedder('custom/menu', embed_menu, config_schema=MenuEmbedConfig)

# 4. Detect rejected tenant keys on generate() calls
response = await ai.generate(
    model=GoogleAI.gemini('gemini-flash-latest'),
    prompt='Suggest a dish without peanuts.',
    context={'secrets': {'api_key': tenant_key}},
)
if response.error and response.error.reason is ErrorReason.INVALID_CREDENTIALS:
    await notify_tenant('Your Gemini key was rejected.')

response.media returns the first media item

Reading a generated image or audio part previously required indexing response.media[0]. response.media (along with Message.media and ModelResponseChunk.media) now returns Media | None directly, while the full list moves to media_parts (#47).

response = await ai.generate(
    model=GoogleAI.gemini_image('gemini-2.5-flash-image'),
    prompt='A watercolor of a cozy bakery.',
)

# 1. Single-image convenience accessor
if response.media:
    print(response.media.url)
    # => data:image/png;base64,iVBORw0KGgoAAAANSU...

# 2. Iterate all media parts when a model returns more than one
for part in response.media_parts:
    save_image(part.url)

Bug fixes

Dev UI & tracing

  • Failure traces: Show the error message, failure source, and a stack starting at your code instead of an empty Error box (#63, #113, #115).
  • Per-turn spans: Each tool-loop turn and prompt call gets its own span (#64, #66), and "Open in model runner" pre-fills your config (#116).
  • CLI & catalog: genkit start works from subdirectories (#53), and Dev UI catalog models run instead of returning 404 (#87).

Provider plugins

  • Google GenAI: Lazy model discovery avoids startup 429s (#69), and Gemini tools + output_schema stops looping (#107).
  • Anthropic: Preserves multiple Role.SYSTEM messages (#146), validates temperature / top_p locally, and maps prompt-cache token counts (#70).
  • OpenAI: Skips blank transcription prompts so gpt-4o-transcribe-diarize works from the Dev UI (#136).
  • Google Cloud: Exports metrics again, forwards credentials= to all exporters, and adds trace IDs to structlog (#62).
  • MCP: Names the failing server/host with its cause and wraps malformed replies in GenkitError (#72, #74).

Runtime, typing & prompts

  • Stream cancellation: Dropping a stream stops the model/tool loop; genkit-fastapi stops on client disconnect and returns 499 (#51).
  • Middleware: Inline use=[...] instances keep constructor state, and Retry / Fallback never retry after streaming starts (#86).
  • Usage & reasoning: response.total_usage sums every model call in a run, .reasoning returns thinking text, and Part.from_tool_response supports multipart content (#48).
  • Type checking: Catches typed flows/tools called without input and mismatched model configs like VeoConfig on a Gemini ref (#46).
  • Prompts & JSON: One broken .prompt file no longer skips its folder, output.constrained works, and NaN / Infinity serialize as null instead of 500s (#85).
  • Flows & tools: ai.run() accepts positional args and async callables (#84), interrupt restarts record approved input (#83), and Filesystem / Skills stay confined to their roots (#52).

Before you upgrade

FirestoreSessionStore requires an extra (#54)

genkit-google-cloud no longer installs google-cloud-firestore by default. Add the firestore extra if your app imports FirestoreSessionStore:

uv add 'genkit-google-cloud[firestore]'
# or: pip install 'genkit-google-cloud[firestore]'

response.media returns a single Media | None (#47)

# Before (0.13)
url = response.media[0].url
for item in response.media: ...

# After (0.14)
url = response.media.url
for item in response.media_parts: ...

Run your type checker to catch for item in response.media: loops—iterating a Pydantic model yields (field, value) tuples instead of raising at runtime.

Other notes

  • Evaluators are deprecated (#131): Still work in 0.14 (with a FutureWarning) and will be removed next release (genkit-evaluators is capped at <0.15).
  • Skills uses folder names (#52): use_skill() matches the skill's directory name rather than YAML name:.
  • Plugin authors (#114, #133): Embedder handlers receive EmbedContext and background/custom actions receive ActionContext instead of FlowContext; handlers now accept (req), (req, ctx), or (ctx, req).