genkit 0.3.0.dev2__tar.gz → 0.3.2__tar.gz

{genkit-0.3.0.dev2 → genkit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: genkit
-Version: 0.3.0.dev2
+Version: 0.3.2
 Summary: Genkit AI Framework
 Author: Google
 License: Apache-2.0
@@ -30,7 +30,6 @@ Requires-Dist: partial-json-parser>=0.2.1.1.post5
 Requires-Dist: pillow
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic>=2.10.5
-Requires-Dist: requests>=2.32.3
 Requires-Dist: sse-starlette>=2.2.1
 Requires-Dist: starlette>=0.46.1
 Requires-Dist: strenum>=0.4.15; python_version < '3.11'
@@ -66,14 +65,13 @@ pip install genkit-plugin-google-genai
 ```
 
 ```python
-import asyncio
 import json
 from pydantic import BaseModel, Field
 from genkit.ai import Genkit
-from genkit.plugins.google_genai import GoogleGenai
+from genkit.plugins.google_genai import GoogleAI
 
 ai = Genkit(
-    plugins=[GoogleGenai()],
+    plugins=[GoogleAI()],
     model='googleai/gemini-2.0-flash',
 )
 
@@ -97,5 +95,7 @@ async def main() -> None:
     """Main function."""
     print(json.dumps(await generate_character('Goblorb')))
 
-asyncio.run(main())
+ai.run_main(main())
 ```
+
+See https://python.api.genkit.dev for more details.

{genkit-0.3.0.dev2 → genkit-0.3.2}/README.md

@@ -16,14 +16,13 @@ pip install genkit-plugin-google-genai
 ```
 
 ```python
-import asyncio
 import json
 from pydantic import BaseModel, Field
 from genkit.ai import Genkit
-from genkit.plugins.google_genai import GoogleGenai
+from genkit.plugins.google_genai import GoogleAI
 
 ai = Genkit(
-    plugins=[GoogleGenai()],
+    plugins=[GoogleAI()],
     model='googleai/gemini-2.0-flash',
 )
 
@@ -47,5 +46,7 @@ async def main() -> None:
     """Main function."""
     print(json.dumps(await generate_character('Goblorb')))
 
-asyncio.run(main())
+ai.run_main(main())
 ```
+
+See https://python.api.genkit.dev for more details.

{genkit-0.3.0.dev2 → genkit-0.3.2}/pyproject.toml

@@ -20,7 +20,6 @@ dependencies = [
   "opentelemetry-api>=1.29.0",
   "opentelemetry-sdk>=1.29.0",
   "pydantic>=2.10.5",
-  "requests>=2.32.3",
   "partial-json-parser>=0.2.1.1.post5",
   "json5>=0.10.0",
   "structlog>=25.2.0",
@@ -39,7 +38,7 @@ license = { text = "Apache-2.0" }
 name = "genkit"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.3.0.dev2"
+version = "0.3.2"
 
 [project.optional-dependencies]
 dev-local-vectorstore = ["genkit-plugin-dev-local-vectorstore"]

{genkit-0.3.0.dev2 → genkit-0.3.2}/src/genkit/ai/_base.py

@@ -20,12 +20,13 @@ import asyncio
 import threading
 from collections.abc import Coroutine
 from http.server import HTTPServer
-from typing import Any
+from typing import Any, TypeVar
 
 import structlog
 
 from genkit.aio.loop import create_loop, run_async
 from genkit.blocks.formats import built_in_formats
+from genkit.blocks.generate import define_generate_action
 from genkit.core.environment import is_dev_environment
 from genkit.core.reflection import make_reflection_server
 from genkit.web.manager import find_free_port_sync
@@ -36,6 +37,8 @@ from ._server import ServerSpec, init_default_runtime
 
 logger = structlog.get_logger(__name__)
 
+T = TypeVar('T')
+
 
 class GenkitBase(GenkitRegistry):
     """Base class with shared infra for Genkit instances (sync and async)."""
@@ -57,8 +60,9 @@ class GenkitBase(GenkitRegistry):
         super().__init__()
         self._initialize_server(reflection_server_spec)
         self._initialize_registry(model, plugins)
+        define_generate_action(self.registry)
 
-    def run_main(self, coro: Coroutine[Any, Any, Any] | None = None) -> Any:
+    def run_main(self, coro: Coroutine[Any, Any, T] | None = None) -> T:
         """Runs the provided coroutine on an event loop.
 
         Args:
@@ -67,7 +71,6 @@ class GenkitBase(GenkitRegistry):
         Returns:
             The result of the coroutine.
         """
-
         if not coro:
 
             async def blank_coro():
@@ -78,7 +81,7 @@ class GenkitBase(GenkitRegistry):
         result = None
         if self._loop:
 
-            async def run() -> Any:
+            async def run() -> T:
                 return await coro
 
             result = run_async(self._loop, run)

{genkit-0.3.0.dev2 → genkit-0.3.2}/src/genkit/ai/_base_async.py

@@ -14,7 +14,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""Base/shared implementation for Genkit user-facing API."""
+"""Asynchronous server gateway interface implementation for Genkit."""
 
 from collections.abc import Coroutine
 from typing import Any, TypeVar
@@ -91,15 +91,17 @@ class GenkitBase(GenkitRegistry):
                 else:
                     raise ValueError(f'Invalid {plugin=} provided to Genkit: must be of type `genkit.ai.Plugin`')
 
-    def run(self, coro: Coroutine[Any, Any, T]) -> T:
+    def run_main(self, coro: Coroutine[Any, Any, T]) -> T:
         """Run the user's main coroutine.
 
-        In development mode (`GENKIT_ENV=dev`), this starts the Genkit reflection
-        server and runs the user's coroutine concurrently within the same event loop,
-        blocking until the server is stopped (e.g., via Ctrl+C).
+        In development mode (`GENKIT_ENV=dev`), this starts the Genkit
+        reflection server and runs the user's coroutine concurrently within the
+        same event loop, blocking until the server is stopped (e.g., via
+        Ctrl+C).
 
         In production mode, this simply runs the user's coroutine to completion
-        using `asyncio.run()`.
+        using `uvloop.run()` for performance if available, otherwise
+        `asyncio.run()`.
 
         Args:
             coro: The main coroutine provided by the user.
@@ -111,7 +113,6 @@ class GenkitBase(GenkitRegistry):
             logger.info('Running in production mode.')
             return run_loop(coro)
 
-        # Development mode: Start reflection server and user coro concurrently.
         logger.info('Running in development mode.')
 
         spec = self._reflection_server_spec
@@ -138,24 +139,24 @@ class GenkitBase(GenkitRegistry):
                 finally:
                     user_task_finished_event.set()
 
-            reflection_server = make_reflection_server(self.registry, spec)
+            reflection_server = _make_reflection_server(self.registry, spec)
 
             try:
                 async with RuntimeManager(spec):
-                    # We use anyio's task group because it's compatible with
+                    # We use anyio.TaskGroup because it is compatible with
                     # asyncio's event loop and works with Python 3.10
-                    # (asyncio.create_task_group was added in 3.11, and we can switch
-                    # to that if we drop support for 3.10).
+                    # (asyncio.TaskGroup was added in 3.11, and we can switch to
+                    # that when we drop support for 3.10).
                     async with anyio.create_task_group() as tg:
                         # Start reflection server in the background.
                         tg.start_soon(reflection_server.serve, name='genkit-reflection-server')
-                        await anyio.sleep(0.2)
-                        logger.info(f'Started Genkit reflection server at {spec.scheme}://{spec.host}:{spec.port}')
+                        await logger.ainfo(f'Started Genkit reflection server at {spec.url}')
 
                         # Start the (potentially short-lived) user coroutine wrapper
                         tg.start_soon(run_user_coro_wrapper, name='genkit-user-coroutine')
+                        await logger.ainfo('Started Genkit user coroutine')
 
-                        # Block here until the TaskGroup is cancelled (e.g. Ctrl+C)
+                        # Block here until the task group is canceled (e.g. Ctrl+C)
                         # or a task raises an unhandled exception. It should not
                         # exit just because the user coroutine finishes.
 
@@ -166,19 +167,30 @@ class GenkitBase(GenkitRegistry):
                 logger.exception(e)
                 raise
 
-            # After the TaskGroup finishes (error or cancellation)
+            # After the TaskGroup finishes (error or cancelation).
             if user_task_finished_event.is_set():
-                logger.debug('User coroutine finished before TaskGroup exit.')
+                await logger.adebug('User coroutine finished before TaskGroup exit.')
                 return user_result
             else:
-                logger.debug('User coroutine did not finish before TaskGroup exit.')
+                await logger.adebug('User coroutine did not finish before TaskGroup exit.')
                 return None
 
         return anyio.run(dev_runner)
 
 
-def make_reflection_server(registry: GenkitRegistry, spec: ServerSpec) -> uvicorn.Server:
-    """Make a reflection server for the given registry and spec."""
+def _make_reflection_server(registry: GenkitRegistry, spec: ServerSpec) -> uvicorn.Server:
+    """Make a reflection server for the given registry and spec.
+
+    This is a helper function to make it easier to test the reflection server
+    in isolation.
+
+    Args:
+        registry: The registry to use for the reflection server.
+        spec: The spec to use for the reflection server.
+
+    Returns:
+        A uvicorn server instance.
+    """
     app = create_reflection_asgi_app(registry=registry)
     config = uvicorn.Config(app, host=spec.host, port=spec.port, loop='asyncio')
     return uvicorn.Server(config)

{genkit-0.3.0.dev2 → genkit-0.3.2}/src/genkit/ai/_runtime.py

@@ -145,18 +145,18 @@ class RuntimeManager:
         """
         self.spec = spec
         if runtime_dir is None:
-            self.runtime_dir = Path(os.getcwd()) / DEFAULT_RUNTIME_DIR_NAME
+            self._runtime_dir = Path(os.getcwd()) / DEFAULT_RUNTIME_DIR_NAME
         else:
-            self.runtime_dir = Path(runtime_dir)
+            self._runtime_dir = Path(runtime_dir)
 
         self._runtime_file_path: Path | None = None
 
     async def __aenter__(self) -> RuntimeManager:
         """Create the runtime directory and file."""
         try:
-            await logger.adebug(f'Ensuring runtime directory exists: {self.runtime_dir}')
-            self.runtime_dir.mkdir(parents=True, exist_ok=True)
-            runtime_file_path = _create_and_write_runtime_file(self.runtime_dir, self.spec)
+            await logger.adebug(f'Ensuring runtime directory exists: {self._runtime_dir}')
+            self._runtime_dir.mkdir(parents=True, exist_ok=True)
+            runtime_file_path = _create_and_write_runtime_file(self._runtime_dir, self.spec)
             _register_atexit_cleanup_handler(runtime_file_path)
 
         except Exception as e:
@@ -186,9 +186,9 @@ class RuntimeManager:
     def __enter__(self) -> RuntimeManager:
         """Synchronous entry point: Create the runtime directory and file."""
         try:
-            logger.debug(f'[sync] Ensuring runtime directory exists: {self.runtime_dir}')
-            self.runtime_dir.mkdir(parents=True, exist_ok=True)
-            self._runtime_file_path = _create_and_write_runtime_file(self.runtime_dir, self.spec)
+            logger.debug(f'[sync] Ensuring runtime directory exists: {self._runtime_dir}')
+            self._runtime_dir.mkdir(parents=True, exist_ok=True)
+            self._runtime_file_path = _create_and_write_runtime_file(self._runtime_dir, self.spec)
             _register_atexit_cleanup_handler(self._runtime_file_path)
 
         except Exception as e:

{genkit-0.3.0.dev2 → genkit-0.3.2}/src/genkit/blocks/generate.py

@@ -56,6 +56,23 @@ StreamingCallback = Callable[[GenerateResponseChunkWrapper], None]
 DEFAULT_MAX_TURNS = 5
 
 
+def define_generate_action(registry: Registry):
+    """Registers generate action in the provided registry."""
+    async def genereate_action_fn(input: GenerateActionOptions, ctx: ActionRunContext) -> GenerateResponse:
+        return await generate_action(
+            registry=registry,
+            raw_request=input,
+            on_chunk=ctx.send_chunk if ctx.is_streaming else None,
+            context=ctx.context,
+        )
+
+    registry.register_action(
+        kind=ActionKind.UTIL,
+        name='generate',
+        fn=genereate_action_fn,
+    )
+
+
 async def generate_action(
     registry: Registry,
     raw_request: GenerateActionOptions,

{genkit-0.3.0.dev2 → genkit-0.3.2}/src/genkit/core/constants.py

@@ -17,7 +17,7 @@
 """Module containing various core constants."""
 
 # The version of Genkit sent over HTTP in the headers.
-DEFAULT_GENKIT_VERSION = '0.0.1'
+DEFAULT_GENKIT_VERSION = '0.3.2'
 
 # TODO: make this dynamic
 GENKIT_VERSION = DEFAULT_GENKIT_VERSION

genkit-0.3.2/src/genkit/core/trace/__init__.py

@@ -0,0 +1,31 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Trace module for defining opentelemetry managing."""
+
+from .default_exporter import (
+    TelemetryServerSpanExporter,
+    init_telemetry_server_exporter,
+)
+from .types import (
+    GenkitSpan,
+)
+
+__all__ = [
+    TelemetryServerSpanExporter.__name__,
+    init_telemetry_server_exporter.__name__,
+    GenkitSpan.__name__,
+]

genkit-0.3.2/src/genkit/core/trace/default_exporter.py

@@ -0,0 +1,172 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Telemetry and tracing default exporter for the Genkit framework.
+
+This module provides functionality for collecting and exporting telemetry data
+from Genkit operations. It uses OpenTelemetry for tracing and exports span
+data to a telemetry server for monitoring and debugging purposes.
+
+The module includes:
+    - A custom span exporter for sending trace data to a telemetry server
+    - Utility functions for converting and formatting trace attributes
+"""
+
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Awaitable, Sequence
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+import structlog
+from opentelemetry import trace as trace_api
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import (
+    SpanExporter,
+    SpanExportResult,
+)
+
+ATTR_PREFIX = 'genkit'
+logger = structlog.get_logger(__name__)
+
+
+def extract_span_data(span: ReadableSpan) -> dict[str, Any]:
+    """Extract span data from a ReadableSpan object.
+
+    This function extracts the span data from a ReadableSpan object and returns
+    a dictionary containing the span data.
+    """
+    span_data = {'traceId': f'{span.context.trace_id}', 'spans': {}}
+    span_data['spans'][span.context.span_id] = {
+        'spanId': f'{span.context.span_id}',
+        'traceId': f'{span.context.trace_id}',
+        'startTime': span.start_time / 1000000,
+        'endTime': span.end_time / 1000000,
+        'attributes': {**span.attributes},
+        'displayName': span.name,
+        # "links": span.links,
+        'spanKind': trace_api.SpanKind(span.kind).name,
+        'parentSpanId': f'{span.parent.span_id}' if span.parent else None,
+        'status': (
+            {
+                'code': trace_api.StatusCode(span.status.status_code).value,
+                'description': span.status.description,
+            }
+            if span.status
+            else None
+        ),
+        'instrumentationLibrary': {
+            'name': 'genkit-tracer',
+            'version': 'v1',
+        },
+    }
+    if not span_data['spans'][span.context.span_id]['parentSpanId']:  # type: ignore
+        del span_data['spans'][span.context.span_id]['parentSpanId']  # type: ignore
+
+    if not span.parent:
+        span_data['displayName'] = span.name
+        span_data['startTime'] = span.start_time
+        span_data['endTime'] = span.end_time
+
+    return span_data
+
+
+class TelemetryServerSpanExporter(SpanExporter):
+    """Exports spans to a Genkit telemetry server.
+
+    This exporter sends span data in a specific JSON format to a telemetry server,
+    typically running locally during development, for visualization and debugging.
+
+    Attributes:
+        telemetry_server_url: The URL of the telemetry server endpoint.
+    """
+
+    def __init__(self, telemetry_server_url: str, telemetry_server_endpoint: str | None = None):
+        """Initializes the TelemetryServerSpanExporter.
+
+        Args:
+            telemetry_server_url: The URL of the telemetry server.
+            telemetry_server_endpoint (optional): The telemetry server's trace endpoint.
+        """
+        self.telemetry_server_url = telemetry_server_url
+        if telemetry_server_endpoint is None:
+            self.telemetry_server_endpoint = '/api/traces'
+        else:
+            self.telemetry_server_endpoint = telemetry_server_endpoint
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        """Exports a sequence of ReadableSpans to the configured telemetry server.
+
+        Iterates through the provided spans, extracts relevant data using
+        `extract_span_data`, converts it to JSON, and sends it via an HTTP POST
+        request to the `telemetry_server_url`.
+
+        Args:
+            spans: A sequence of OpenTelemetry ReadableSpan objects to export.
+
+        Returns:
+            SpanExportResult.SUCCESS upon successful processing (does not guarantee
+            server-side success).
+        """
+        with httpx.Client() as client:
+            for span in spans:
+                client.post(
+                    urljoin(self.telemetry_server_url, self.telemetry_server_endpoint),
+                    data=json.dumps(extract_span_data(span)),
+                    headers={
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                    },
+                )
+
+        sys.stdout.flush()
+
+        return SpanExportResult.SUCCESS
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Forces the exporter to flush any buffered spans.
+
+        Since this exporter sends spans immediately in the `export` method,
+        this method currently does nothing but return True.
+
+        Args:
+            timeout_millis: The maximum time in milliseconds to wait for the flush.
+                            This parameter is ignored in the current implementation.
+
+        Returns:
+            True, indicating the flush operation is considered complete.
+        """
+        return True
+
+
+def init_telemetry_server_exporter() -> SpanExporter | None:
+    """Initializes tracing with a provider and optional exporter."""
+    telemetry_server_url = os.environ.get('GENKIT_TELEMETRY_SERVER')
+    processor = None
+
+    if telemetry_server_url:
+        processor = TelemetryServerSpanExporter(
+            telemetry_server_url=telemetry_server_url,
+        )
+    else:
+        logger.warn(
+            'GENKIT_TELEMETRY_SERVER is not set. If running with `genkit start`, make sure `genkit-cli` is up to date.'
+        )
+
+    return processor

genkit-0.3.2/src/genkit/core/trace/types.py

@@ -0,0 +1,108 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Telemetry and tracing types for the Genkit framework.
+
+This module defines the core tracing types for the Genkit framework.
+
+Genkit flows are instrumented to trace key data points, primarily the inputs
+sent to and the outputs received from Language Learning Models (LLMs) or
+other models.  Outputs may be streamed as chunks. This module establishes
+how these interactions are recorded and exported for observability.
+
+Key Features:
+
+-   **GenkitSpan Class:** Provides a core class, `GenkitSpan`, for representing
+    and exporting telemetry data related to Genkit operations.  This class
+    is intended for internal use by the Genkit framework.
+"""
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import structlog
+from opentelemetry import trace as trace_api
+from opentelemetry.util import types
+from pydantic import BaseModel
+
+ATTR_PREFIX = 'genkit'
+
+logger = structlog.get_logger(__name__)
+
+
+class GenkitSpan:
+    """Light wrapper for Span, specific to Genkit."""
+
+    is_root: bool
+    _span: trace_api.Span
+
+    def __init__(self, span: trace_api.Span, labels: dict[str, str] | None = None):
+        """Create GenkitSpan."""
+        self._span = span
+        parent = span.parent
+        self.is_root = False
+        if parent is None:
+            self.is_root = True
+        if labels is not None:
+            self.set_attributes(labels)
+
+    def __getattr__(self, name) -> Any:
+        """Passthrough for all OpenTelemetry Span attributes."""
+        return getattr(self._span, name)
+
+    def set_genkit_attribute(self, key: str, value: types.AttributeValue) -> None:
+        """Set Genkit specific attribute, with the `genkit` prefix."""
+        if key == 'metadata' and isinstance(value, dict) and value:
+            for meta_key, meta_value in value.items():
+                self._span.set_attribute(f'{ATTR_PREFIX}:metadata:{meta_key}', str(meta_value))
+        elif isinstance(value, dict):
+            self._span.set_attribute(f'{ATTR_PREFIX}:{key}', json.dumps(value))
+        else:
+            self._span.set_attribute(f'{ATTR_PREFIX}:{key}', str(value))
+
+    def set_genkit_attributes(self, attributes: Mapping[str, types.AttributeValue]) -> None:
+        """Set Genkit specific attributes, with the `genkit` prefix."""
+        for key, value in attributes.items():
+            self.set_genkit_attribute(key, value)
+
+    @property
+    def span_id(self) -> str:
+        """Returns the span_id."""
+        return str(self._span.get_span_context().span_id)
+
+    @property
+    def trace_id(self) -> str:
+        """Returns the trace_id."""
+        return str(self._span.get_span_context().trace_id)
+
+    def set_input(self, input: Any) -> None:
+        """Set Genkit Span input, visible in the trace viewer."""
+        value = None
+        if isinstance(input, BaseModel):
+            value = input.model_dump_json(by_alias=True, exclude_none=True)
+        else:
+            value = json.dumps(input)
+        self.set_genkit_attribute('input', value)
+
+    def set_output(self, output: Any) -> None:
+        """Set Genkit Span output, visible in the trace viewer."""
+        value = None
+        if isinstance(output, BaseModel):
+            value = output.model_dump_json(by_alias=True, exclude_none=True)
+        else:
+            value = json.dumps(output)
+        self.set_genkit_attribute('output', value)