[TASK-3-3] Implement Select_file() Tool

by ADMIN 40 views

Overview

The select_file() tool is a crucial component of the Agent Development Kit (ADK) that enables the selection of unprocessed files and saves them as artifacts. This tool is designed to work seamlessly with the ADK's state management system, ensuring that files are processed efficiently and effectively. In this article, we will delve into the implementation of the select_file() tool, covering its functionality, unit testing, and acceptance criteria.

Background / Why

According to the MVP breakdown, the select_file() tool is a key feature that needs to be implemented as part of Task T3. The relevant line from the MVP breakdown is:

  • [ ] T3 select_file() ― Select an unprocessed file and save_artifact; exit_loop if none

This tool is essential for the ADK's functionality, as it enables the selection of unprocessed files and saves them as artifacts, which can then be used for further processing or analysis.

What to do / How

Step 1: Fetch and Understand ADK Documentation

To implement the select_file() tool, we need to fetch and understand the ADK documentation. We can use the MCP tool Context7 to fetch the documentation from the Agent Development Kit (ADK) Documentation. Once we have the documentation, we need to understand how to implement tools using the ToolContext, save_artifact, and manage state (e.g., context.state, context.actions.save_artifact, context.actions.escalate).

Step 2: Implement select_file() Tool Function

The select_file() tool function should be placed in questions_extractor_agent/tools/select_file.py (or a relevant shared tools module like questions_extractor_agent/tools/file_tools.py). The function should access a list/queue of unprocessed files (e.g., from context.state["files"] or a similar agreed-upon state management key). It should select one file from this list that has not yet been processed. We need to define a clear mechanism for tracking processed/selected files.

Step 3: Handle File Selection

If an unprocessed file is found, we need to mark the file as "selected" or "in-progress" to prevent reprocessing. We then call context.actions.save_artifact(name=<unique_artifact_name_for_file>, content=<file_content_or_path_as_bytes>) to save the selected file's content or reference as an artifact. We need to clarify if the content itself or just a reference/path needs to be saved by this tool.

Step 4: Handle No Files Remaining

If no unprocessed files are available in the list, we need to trigger the exit_loop behavior by setting context.actions.escalate = True.

Step 5: Unit Testing

We need to create unit tests in tests/tools/test_select_file.py. We should mock dependencies like context.state, context.actions.save_artifact, and context.actions.escalate. We should test the scenario where unprocessed files are available and one is selected and save_artifact is called. We should also test the edge case where the list of unprocessed files is empty, ensuring context.actions.escalate is set to True and save_artifact is not called.

Acceptance Criteria / AC

The select_file() tool should meet the following acceptance criteria:

  • select_file() correctly identifies and selects an unprocessed file from the available list when one exists.
  • Upon selecting a file, context.actions.save_artifact is called appropriately for that file.
  • If no unprocessed files are available, select_file() sets context.actions.escalate = True.
  • Unit tests for select_file() are implemented in tests/tools/test_select_file.py.
  • Unit tests cover:
    • Successful file selection and save_artifact call.
    • Empty file list and exit_loop (escalation) behavior.
  • ruff, black, isort checks pass on the new code.
  • Type checks (mypy | pyright) pass on the new code.
  • Docstrings and comments are added to the select_file() function, explaining its purpose, parameters, and behavior.
  • Setup instructions are added to README (if necessary, unlikely for this tool).

Predefined Checklist

The following checklist should be completed:

  • Code style unified (ruff/black/isort)
  • Type check (mypy | pyright)
  • Docstring & comments
  • Test cases added
  • Documentation updated (if applicable)

Related Materials

The following materials are related to this task:

  • PRD: ../prd.md
  • Roadmap: ../roadmap.md
  • Break-down Line Number: ../mvp_breakdown.md (Task T3 in section '3. Tool Implementation (ADK Tool Functions)')

Q: What is the purpose of the select_file() tool?

A: The select_file() tool is designed to select an unprocessed file from a list and save it as an artifact. This tool is essential for the Agent Development Kit (ADK) functionality, as it enables the selection of unprocessed files and saves them as artifacts, which can then be used for further processing or analysis.

Q: Where should the select_file() tool function be placed?

A: The select_file() tool function should be placed in questions_extractor_agent/tools/select_file.py (or a relevant shared tools module like questions_extractor_agent/tools/file_tools.py).

Q: How does the select_file() tool select an unprocessed file?

A: The select_file() tool selects an unprocessed file by accessing a list/queue of unprocessed files (e.g., from context.state["files"] or a similar agreed-upon state management key). It then selects one file from this list that has not yet been processed.

Q: What happens if no unprocessed files are available?

A: If no unprocessed files are available, the select_file() tool triggers the exit_loop behavior by setting context.actions.escalate = True.

Q: How does the select_file() tool save the selected file as an artifact?

A: The select_file() tool saves the selected file as an artifact by calling context.actions.save_artifact(name=<unique_artifact_name_for_file>, content=<file_content_or_path_as_bytes>). We need to clarify if the content itself or just a reference/path needs to be saved by this tool.

Q: What are the acceptance criteria for the select_file() tool?

A: The select_file() tool should meet the following acceptance criteria:

  • select_file() correctly identifies and selects an unprocessed file from the available list when one exists.
  • Upon selecting a file, context.actions.save_artifact is called appropriately for that file.
  • If no unprocessed files are available, select_file() sets context.actions.escalate = True.
  • Unit tests for select_file() are implemented in tests/tools/test_select_file.py.
  • Unit tests cover:
    • Successful file selection and save_artifact call.
    • Empty file list and exit_loop (escalation) behavior.
  • ruff, black, isort checks pass on the new code.
  • Type checks (mypy | pyright) pass on the new code.
  • Docstrings and comments are added to the select_file() function, explaining its purpose, parameters, and behavior.
  • Setup instructions are added to README (if necessary, unlikely for this tool).

Q: What are the predefined checklist items for the select_file() tool?

A: The following checklist items should be completed:

  • Code style unified (ruff/black/isort)
  • Type check (mypy | pyright)
  • Docstring & comments
  • Test cases added
  • Documentation updated (if applicable)

Q: What are the related materials for this task?

A: The following materials are related to this task:

  • PRD: ../prd.md
  • Roadmap: ../roadmap.md
  • Break-down Line Number: ../mvp_breakdown.md (Task T3 in section '3. Tool Implementation (ADK Tool Functions)')

By answering these frequently asked questions, we can ensure that the select_file() tool is implemented correctly and efficiently, providing a seamless experience for users of the ADK.