From b6fd77e0be959e1b7fc14e60759eb2a0218b6640 Mon Sep 17 00:00:00 2001 From: bucolucas Date: Sat, 9 Aug 2025 18:35:27 -0500 Subject: [PATCH] Docs: add comprehensive tools overview and contribution guide --- tools/README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/tools/README.md b/tools/README.md index e69de29..dbe8da7 100644 --- a/tools/README.md +++ b/tools/README.md @@ -0,0 +1,57 @@ +# Tools Overview + +This repository contains a set of pluggable tools that the assistant can use to operate on itself and on the surrounding GitHub repository. Each tool follows a simple interface defined by BaseTool and exposes a set of callable functions that higher-level orchestration can invoke. + +## Architecture + +- BaseTool: All tools inherit from tools/base_tool.py and implement: + - get_functions(): returns a list of function specs (name, description, JSON schema for parameters) + - execute(function_name, **kwargs): dispatches calls to concrete implementations + - clear(): resets transient state + +- Discovery: Tools are simple Python modules under tools/. They can be imported and registered by the host application. Each tool is self-contained and may use environment variables for configuration. + +## Available tools + +- GitHubTool (tools/github_tool.py) + - Rich integration with the GitHub REST API for repository tasks. + - Examples of capabilities: read_file, list_files, search_code, create_branch, commit_file, commit_file_patch, create_pull_request, PR review helpers, issues and project boards, branch utilities, and more. + +- GitHubCIHelper (tools/github_ci_tool.py) + - Focused helpers for GitHub Actions CI: discover PR workflow runs, fetch job logs, and parse unittest failure blocks from logs. + +- LogTool (tools/log_tool.py) + - Reads the local logs/output.log file. Supports tailing by line count or filtering to the last 24 hours using a timestamp-aware parser. + +- StandaloneLLMTool (tools/standalone_llm_tool.py) + - Bridges to external LLMs or a separate copilot service. + - Functions: call_external_llm (uses OPENAI_API_KEY), call_external_copilot (uses COPILOT_API_URL). + +- RepoIndexTool (tools/repo_index_tool.py) [NEW] + - Quickly builds a lightweight index of repository paths via the GitHub Contents API to aid navigation, discovery, and targeted reads. + - Functions: + - get_repo_tree(path="", ref="main", max_depth=3, include_files=True, include_dirs=True) + - find_files(pattern, path="", ref="main", max_results=50) + - get_file_head(path, ref="main", max_bytes=4096) + +## Adding a new tool + +1) Create a new module under tools/ and subclass BaseTool. +2) Implement get_functions() to describe your function signatures and parameters. +3) Implement execute() to route to internal methods and return structured results or error strings. +4) Prefer dependency injection and env vars over hardcoding. Reuse a shared requests.Session where practical. +5) Log responsibly using the logging module; do not print directly. Attach a NullHandler by default to avoid handler warnings. +6) Avoid storing secrets in memory; prefer short-lived per-request usage. Implement clear() to drop state. + +## Environment variables (common) + +- GITHUB_TOKEN: required for GitHub API access in most tools. +- GITHUB_REPOSITORY: owner/repo used by GitHubTool and RepoIndexTool. +- OPENAI_API_KEY: used by StandaloneLLMTool. +- COPILOT_API_URL: used by StandaloneLLMTool for external copilot calls. + +## Notes + +- Tools should be defensive and return clear error messages on failures. +- Keep function results concise and JSON-serializable where possible. +- If your tool fetches large data, consider pagination or size limits and expose parameters for control.