feat(py): implement resource support (#4204)

Co-authored-by: Mengqin Shen <mengqin@google.com>

Author: MengqinShen

py/bin/sanitize_schema_typing.py

@@ -233,9 +233,55 @@ def visit_ClassDef(self, node: ast.ClassDef) -> Any:
             # For other classes, just copy the rest of the body
             new_body.extend(node.body[body_start_index:])
 
+        # PYTHON EXTENSION: Add resources field to GenerateActionOptions
+        if node.name == 'GenerateActionOptions':
+            self._inject_resources_field(new_body)
+
         node.body = cast(list[ast.stmt], new_body)
         return node
 
+    def _inject_resources_field(self, body: list[ast.stmt | ast.Constant | ast.Assign]) -> None:
+        """Inject resources field after tools field in GenerateActionOptions.
+
+        This adds the resources field to match the JS SDK implementation without
+        modifying the shared schema file. The JS SDK manually adds this field in
+        model-types.ts line 398.
+        """
+
+        tools_index = -1
+        for i, stmt in enumerate(body):
+            if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                if stmt.target.id == 'tools':
+                    tools_index = i
+                    break
+
+        if tools_index == -1:
+            return  # tools field not found, skip injection
+
+        # Check if resources field already exists
+        for stmt in body:
+            if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                if stmt.target.id == 'resources':
+                    return  # Already exists, don't add again
+
+        # Create the resources field: resources: list[str] | None = None
+        resources_field = ast.AnnAssign(
+            target=ast.Name(id='resources', ctx=ast.Store()),
+            annotation=ast.BinOp(
+                left=ast.Subscript(
+                    value=ast.Name(id='list', ctx=ast.Load()), slice=ast.Name(id='str', ctx=ast.Load()), ctx=ast.Load()
+                ),
+                op=ast.BitOr(),
+                right=ast.Constant(value=None),
+            ),
+            value=ast.Constant(value=None),
+            simple=1,
+        )
+
+        # Insert after tools field
+        body.insert(tools_index + 1, resources_field)
+        self.modified = True
+
 
 def add_header(content: str) -> str:
     """Add the generated header to the content."""

py/packages/genkit/src/genkit/blocks/generate.py

@@ -29,12 +29,15 @@
     MessageWrapper,
     ModelMiddleware,
 )
+from genkit.blocks.resource import ResourceInput, find_matching_resource, resolve_resources
 from genkit.blocks.tools import ToolInterruptError
 from genkit.codec import dump_dict
 from genkit.core.action import ActionRunContext
 from genkit.core.error import GenkitError, StatusName
 from genkit.core.registry import Action, ActionKind, Registry
 from genkit.core.typing import (
+    DocumentData,
+    DocumentPart,
     GenerateActionOptions,
     GenerateRequest,
     GenerateResponse,
@@ -101,6 +104,9 @@ async def generate_action(
 
     raw_request, formatter = apply_format(raw_request, format_def)
 
+    if raw_request.resources:
+        raw_request = await apply_resources(registry, raw_request)
+
     assert_valid_tool_names(tools)
 
     (
@@ -412,6 +418,131 @@ def apply_transfer_preamble(next_request: GenerateActionOptions, preamble: Gener
     return next_request
 
 
+def _extract_resource_uri(resource_obj: Any) -> str | None:
+    """Extract URI from a resource object.
+
+    Handles various Pydantic wrapper structures (Resource, Resource1, RootModel, dict).
+
+    Args:
+        resource_obj: The resource object to extract URI from.
+
+    Returns:
+        The extracted URI string, or None if not found.
+    """
+    # Direct uri attribute (Resource1, ResourceInput, etc.)
+    if hasattr(resource_obj, 'uri'):
+        return resource_obj.uri
+
+    # Unwrap RootModel structures
+    if hasattr(resource_obj, 'root'):
+        return _extract_resource_uri(resource_obj.root)
+
+    # Unwrap nested resource attribute
+    if hasattr(resource_obj, 'resource'):
+        return _extract_resource_uri(resource_obj.resource)
+
+    # Handle dict representation
+    if isinstance(resource_obj, dict) and 'uri' in resource_obj:
+        return resource_obj['uri']
+
+    return None
+
+
+async def apply_resources(registry: Registry, raw_request: GenerateActionOptions) -> GenerateActionOptions:
+    """Applies resources to the request messages by hydrating resource parts.
+
+    Args:
+        registry: The registry to use for resolving resources.
+        raw_request: The generation request.
+
+    Returns:
+        The updated generation request with hydrated resources.
+    """
+    # Quick check if any message has a resource part
+    has_resource = False
+    for msg in raw_request.messages:
+        for part in msg.content:
+            if part.root.resource:
+                has_resource = True
+                break
+        if has_resource:
+            break
+
+    if not has_resource:
+        return raw_request
+
+    # Resolve all declared resources
+    resources = []
+    if raw_request.resources:
+        resources = await resolve_resources(registry, raw_request.resources)
+
+    updated_messages = []
+    for msg in raw_request.messages:
+        if not any(p.root.resource for p in msg.content):
+            updated_messages.append(msg)
+            continue
+
+        updated_content = []
+        for part in msg.content:
+            if not part.root.resource:
+                updated_content.append(part)
+                continue
+
+            resource_obj = part.root.resource
+
+            # Extract URI from the resource object
+            # The resource can be wrapped in various Pydantic structures (Resource, Resource1, etc.)
+            ref_uri = _extract_resource_uri(resource_obj)
+            if not ref_uri:
+                logger.warning(
+                    f'Unable to extract URI from resource part: {type(resource_obj).__name__}. '
+                    f'Resource part will be skipped.'
+                )
+                continue
+
+            # Find matching resource action
+            if not resources:
+                raise GenkitError(
+                    status='NOT_FOUND',
+                    message=f'failed to find matching resource for {ref_uri}',
+                )
+
+            from genkit.blocks.resource import ResourceInput, find_matching_resource
+
+            # Normalize to ResourceInput for matching
+            resource_input = ResourceInput(uri=ref_uri)
+            resource_action = await find_matching_resource(registry, resources, resource_input)
+
+            if not resource_action:
+                raise GenkitError(
+                    status='NOT_FOUND',
+                    message=f'failed to find matching resource for {ref_uri}',
+                )
+
+            # Execute the resource
+            # Create a simple context for the resource execution
+            resource_ctx = ActionRunContext(on_chunk=None, context=None)
+            response = await resource_action.arun(resource_input, resource_ctx)
+
+            # response.response is ResourceOutput which has .content (list of Parts)
+            # It usually returns a dict if coming from dynamic_resource (model_dump called)
+            output_content = None
+            if hasattr(response.response, 'content'):
+                output_content = response.response.content
+            elif isinstance(response.response, dict) and 'content' in response.response:
+                output_content = response.response['content']
+
+            if output_content:
+                updated_content.extend(output_content)
+
+        updated_messages.append(Message(role=msg.role, content=updated_content, metadata=msg.metadata))
+
+    # Return a new request with updated messages
+    new_request = raw_request.model_copy()
+    new_request.messages = updated_messages
+    return new_request
+
+
 def assert_valid_tool_names(raw_request: GenerateActionOptions):
     """Assert that tool names in the request are valid.
 

py/packages/genkit/src/genkit/blocks/prompt.py

@@ -106,6 +106,7 @@ class PromptConfig(BaseModel):
     use: list[ModelMiddleware] | None = None
     docs: list[DocumentData] | Callable | None = None
     tool_responses: list[Part] | None = None
+    resources: list[str] | None = None
 
 
 class ExecutablePrompt:
@@ -134,6 +135,7 @@ def __init__(
         tool_choice: ToolChoice | None = None,
         use: list[ModelMiddleware] | None = None,
         docs: list[DocumentData] | Callable | None = None,
+        resources: list[str] | None = None,
         _name: str | None = None,  # prompt name for action lookup
         _ns: str | None = None,  # namespace for action lookup
         _prompt_action: Action | None = None,  # reference to PROMPT action
@@ -164,6 +166,7 @@ def __init__(
             tool_choice: The tool choice strategy.
             use: A list of model middlewares to apply.
             docs: A list of documents to be used for grounding.
+            resources: A list of resource URIs to be used for grounding.
         """
         self._registry = registry
         self._variant = variant
@@ -186,6 +189,7 @@ def __init__(
         self._tool_choice = tool_choice
         self._use = use
         self._docs = docs
+        self._resources = resources
         self._cache_prompt = PromptCache()
         self._name = _name  # Store name/ns for action lookup (used by as_tool())
         self._ns = _ns
@@ -298,6 +302,7 @@ async def render(
             input_schema=self._input_schema,
             metadata=self._metadata,
             docs=self._docs,
+            resources=self._resources,
         )
 
         model = options.model or self._registry.default_model

py/packages/genkit/src/genkit/core/action/_tracing.py

@@ -56,4 +56,8 @@ def record_output_metadata(span, output) -> None:
         output: The output data returned by the action.
     """
     span.set_attribute('genkit:state', 'success')
-    span.set_attribute('genkit:output', dump_json(output))
+    try:
+        span.set_attribute('genkit:output', dump_json(output))
+    except Exception:
+        # Fallback for non-serializable output
+        span.set_attribute('genkit:output', str(output))

py/packages/genkit/src/genkit/core/action/types.py

@@ -49,6 +49,7 @@ class ActionKind(StrEnum):
     """
 
     CUSTOM = 'custom'
+    DYNAMIC_ACTION_PROVIDER = 'dynamic-action-provider'
     EMBEDDER = 'embedder'
     EVALUATOR = 'evaluator'
     EXECUTABLE_PROMPT = 'executable-prompt'

py/packages/genkit/src/genkit/core/registry.py

@@ -193,6 +193,29 @@ def lookup_action(self, kind: ActionKind, name: str) -> Action | None:
                 if plugin_name and plugin_name in self._action_resolvers:
                     self._action_resolvers[plugin_name](kind, name)
 
+            if (
+                (kind not in self._entries or name not in self._entries[kind])
+                and kind != ActionKind.DYNAMIC_ACTION_PROVIDER
+                and ActionKind.DYNAMIC_ACTION_PROVIDER in self._entries
+            ):
+                for provider in self._entries[ActionKind.DYNAMIC_ACTION_PROVIDER].values():
+                    try:
+                        # Construct input for the provider action
+                        input_data = {'kind': kind, 'name': name}
+                        # Execute the provider action synchronously
+                        response = provider.run(input_data)
+                        action = response.response
+
+                        if action:
+                            self.register_action_from_instance(action)
+                            break
+                    except Exception as e:
+                        logger.debug(
+                            f'Dynamic action provider {provider.name} failed for {kind}/{name}',
+                            exc_info=e,
+                        )
+                        continue
+
             if kind in self._entries and name in self._entries[kind]:
                 return self._entries[kind][name]
 

py/packages/genkit/src/genkit/core/typing.py

@@ -993,6 +993,7 @@ class GenerateActionOptions(BaseModel):
     docs: list[DocumentData] | None = None
     messages: list[Message]
     tools: list[str] | None = None
+    resources: list[str] | None = None
     tool_choice: ToolChoice | None = Field(None, alias='toolChoice')
     config: Any | None = None
     output: GenerateActionOutputConfig | None = None