cyclop/tools/README.md

# 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.