Developing Genkit Python

# Genkit Python

## Prerequisites

- **Runtime**: Python **3.14+**, **`uv`** for deps ([install](https://docs.astral.sh/uv/getting-started/installation/)).
- **CLI**: `genkit --version` — install via `npm install -g genkit-cli` if missing.

**New projects:** [Setup](references/setup.md) (bootstrap + env). **Patterns and code samples:** [Examples](references/examples.md).

## Hello World

```python
from genkit import Genkit
from genkit.plugins.google_genai import GoogleAI

ai = Genkit(
    plugins=[GoogleAI()],
    model='googleai/gemini-flash-latest',
)

async def main():
    response = await ai.generate(prompt='Tell me a joke about Python.')
    print(response.text)

if __name__ == '__main__':
    ai.run_main(main())
```

## Critical: Do Not Trust Internal Knowledge

The Python SDK changes often — verify imports and APIs against the references here or upstream docs. On **any** error, read [Common Errors](references/common-errors.md) first.

## Development Workflow

1. Default provider: **Google AI** (`GoogleAI()`), **`GEMINI_API_KEY`** in the environment.
2. Model IDs: always prefixed, e.g. **`googleai/gemini-flash-latest`** (always-on-latest Flash alias; same pattern as other skills).
3. Entrypoint: **`ai.run_main(main())`** for Genkit-driven apps (not `asyncio.run()` for long-lived servers started with `genkit start` — see [Common Errors](references/common-errors.md)).
4. After generating code, follow [Dev Workflow](references/dev-workflow.md) for `genkit start` and the Dev UI.
5. On errors: step 1 is always [Common Errors](references/common-errors.md).

## References

- [Examples](references/examples.md): Structured output, streaming, flows, tools, embeddings.
- [Setup](references/setup.md): New project bootstrap and plugins.
- [Common Errors](references/common-errors.md): Read first when something breaks.
- [FastAPI](references/fastapi.md): HTTP, `genkit_fastapi_handler`, parallel flows.
- [Dotprompt](references/dotprompt.md): `.prompt` files and helpers.
- [Evals](references/evals.md): Evaluators and datasets.
- [Dev Workflow](references/dev-workflow.md): `genkit start`, Dev UI, checklist.


# Common Errors — Genkit Python

## Before anything else: read this file when you hit any error.

---

## ModuleNotFoundError: No module named 'genkit.plugins.google_genai'

**Cause:** Plugin package not installed.

**Fix:** Add dependencies from PyPI:
```bash
uv add genkit genkit-plugin-google-genai
```

---

## 400 INVALID_ARGUMENT: functionDeclaration parameters schema should be of type OBJECT

**Cause:** Tool function has bare scalar parameters (e.g. `city: str`). Gemini requires object schema.

**Fix:** Wrap parameters in a Pydantic BaseModel:
```python
from pydantic import BaseModel

# Wrong
@ai.tool()
async def get_weather(city: str) -> str: ...

# Right
from pydantic import BaseModel

class WeatherInput(BaseModel):
    city: str

@ai.tool()
async def get_weather(input: WeatherInput) -> str: ...
```

---

## AttributeError: 'Genkit' object has no attribute 'define_tool'

**Cause:** Wrong decorator name.

**Fix:** Use `@ai.tool()`, not `@ai.define_tool()`.

---

## RuntimeError / event loop errors when using asyncio.run()

**Cause:** For apps you start with **`genkit start`**, Genkit runs your entrypoint with an event loop suited to the framework (including uvloop where used). There is no “default” loop for you to manage in that mode.

**Fix:** For long-running Genkit apps (servers, flows served under `genkit start`), use **`ai.run_main(main())`** as your entrypoint instead of `asyncio.run(main())`. For one-off scripts that exit when done, using `asyncio.run()` can still be appropriate when you are not using `genkit start`.

---

## Wrong model ID