Metadata-Version: 2.5
Name: aden-tools
Version: 1.0.3
Summary: Tools library for the Aden agent framework
Author-email: Aden <team@aden.ai>
License: Apache-2.0
Keywords: agents,ai,llm,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aden-hive==1.0.3
Requires-Dist: arxiv>=2.1.0
Requires-Dist: asana>=3.2.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: diff-match-patch>=20230430
Requires-Dist: dnspython>=2.4.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: fpdf2>=2.7.0
Requires-Dist: google-analytics-data>=0.18.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: litellm==1.83.4
Requires-Dist: pandas>=2.0.0
Requires-Dist: pdfplumber>=0.11.9
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright-stealth>=2.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: pypdfium2>=4.0.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: reportlab>=4.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: resend>=2.0.0
Requires-Dist: stripe>=14.3.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: databricks-mcp>=0.1.0; extra == 'all'
Requires-Dist: databricks-sdk>=0.30.0; extra == 'all'
Requires-Dist: duckdb>=1.0.0; extra == 'all'
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == 'all'
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: pillow>=10.0.0; extra == 'all'
Requires-Dist: pytesseract>=0.3.10; extra == 'all'
Requires-Dist: restrictedpython>=7.0; extra == 'all'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == 'bigquery'
Provides-Extra: browser
Requires-Dist: pillow>=10.0.0; extra == 'browser'
Provides-Extra: databricks
Requires-Dist: databricks-mcp>=0.1.0; extra == 'databricks'
Requires-Dist: databricks-sdk>=0.30.0; extra == 'databricks'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
Provides-Extra: ocr
Requires-Dist: pillow>=10.0.0; extra == 'ocr'
Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
Provides-Extra: sandbox
Requires-Dist: restrictedpython>=7.0; extra == 'sandbox'
Provides-Extra: sql
Requires-Dist: duckdb>=1.0.0; extra == 'sql'
Description-Content-Type: text/markdown

# Hive Tools

Tool library for the Hive framework. Provides a collection of tools that AI agents can use to interact with external systems, process data, and perform actions via the Model Context Protocol (MCP).

## Installation

```bash
uv pip install -e tools
```

For development:

```bash
uv pip install -e "tools[dev]"
```

## Environment Setup

Some tools require API keys to function. Credentials are managed through the encrypted credential store at `~/.hive/credentials`, which is configured automatically during initial setup:

```bash
./quickstart.sh
```

| Variable               | Required For                  | Get Key                                                 |
| ---------------------- | ----------------------------- | ------------------------------------------------------- |
| `ANTHROPIC_API_KEY`    | MCP server startup, LLM nodes | [console.anthropic.com](https://console.anthropic.com/) |
| `BRAVE_SEARCH_API_KEY` | `web_search` tool (Brave)     | [brave.com/search/api](https://brave.com/search/api/)   |
| `GOOGLE_API_KEY`       | `web_search` tool (Google)    | [console.cloud.google.com](https://console.cloud.google.com/) |
| `GOOGLE_CSE_ID`        | `web_search` tool (Google)    | [programmablesearchengine.google.com](https://programmablesearchengine.google.com/) |

> **Note:** `web_search` supports multiple providers. Set either Brave OR Google credentials. Brave is preferred for backward compatibility.

Alternatively, export credentials as environment variables:

```bash
export ANTHROPIC_API_KEY=your-key-here
export BRAVE_SEARCH_API_KEY=your-key-here
```

See the [credentials module](src/aden_tools/credentials/) for details on how credentials are resolved.

## Quick Start

### As an MCP Server

```python
from fastmcp import FastMCP
from aden_tools.tools import register_all_tools

mcp = FastMCP("tools")
register_all_tools(mcp)
mcp.run()
```

Or run directly:

```bash
python mcp_server.py
```

## Available Tools

### File System

> **Note:** `read_file` / `write_file` / `edit_file` / `search_files` are
> **no longer exposed to agents** — queens/workers do file I/O through the
> terminal tools (`terminal_exec` for cat/sed/heredoc, `terminal_rg` /
> `terminal_glob` for search), which default their cwd to the session workdir.
> The functions below remain in `aden_tools.file_ops` for internal helpers and
> the standalone `files_server.py`.

All file tools live in `aden_tools.file_ops` and share one path policy
(relative paths anchor to a registered `home`; absolute paths are honored
verbatim; system + credential paths are on a deny list).

| Tool | Description |
| ---- | ----------- |
| `read_file` | Read file contents (with optional hashline anchors) |
| `write_file` | Create or overwrite a file |
| `edit_file` | Find/replace with fuzzy fallback |
| `search_files` | Grep file contents (`target='content'`) or list/find files (`target='files'`) — replaces grep, find, and ls |
| `save_data` / `load_data` | Persist and retrieve structured data across steps |
| `serve_file_to_user` | Serve a file for the user to download |
| `list_data_files` | List persisted data files in the session |
| `append_data` / `edit_data` | Append or edit persisted data files |

### Data Files

| Tool | Description |
| ---- | ----------- |
| `csv_read` | Read rows from a CSV file |
| `csv_write` | Write a new CSV file |
| `csv_append` | Append rows to a CSV file |
| `csv_info` | Get CSV file metadata |
| `csv_sql` | Query a CSV file with SQL (DuckDB) |
| `excel_read` | Read rows from an Excel sheet |
| `excel_write` | Write a new Excel file |
| `excel_append` | Append rows to an Excel file |
| `excel_info` | Get Excel file metadata |
| `excel_sheet_list` | List sheets in an Excel workbook |
| `excel_sql` | Query Excel sheets with SQL (DuckDB) |
| `excel_search` | Search for values across Excel sheets |
| `pdf_read` | Read and extract text from PDF files |

### Web & Search

| Tool | Description |
| ---- | ----------- |
| `web_search` | Search the web (Google or Brave, auto-detected) |
| `web_scrape` | Scrape and extract content from webpages |
| `search_wikipedia` | Search Wikipedia for pages and summaries |
| `scholar_search`, `scholar_get_citations`, `scholar_get_author` | Search academic papers, get citations and author profiles via SerpAPI |
| `patents_search`, `patents_get_details` | Search patents and retrieve patent details via SerpAPI |
| `exa_search`, `exa_answer`, `exa_find_similar`, `exa_get_contents` | Semantic search and content retrieval via Exa AI |
| `news_search`, `news_headlines`, `news_by_company`, `news_sentiment` | Search news articles and analyse sentiment |
| `search_papers`, `download_paper` | Search arXiv for scientific papers and download PDFs |

### Communication

| Tool | Description |
| ---- | ----------- |
| `gmail_*` | Read, reply, draft, and manage Gmail messages |
| `send_email` | Send email via SMTP |
| `slack_*` | Send messages, manage channels, users, and files in Slack |
| `discord_send_message`, `discord_get_messages`, `discord_list_channels`, `discord_list_guilds` | Send and read Discord messages |
| `telegram_send_message`, `telegram_send_document` | Send messages and documents via Telegram Bot API |

### Productivity & CRM

| Tool | Description |
| ---- | ----------- |
| `calendar_list_calendars` | List all accessible calendars |
| `calendar_list_events` | List events from a calendar |
| `calendar_get_event` | Get details of a specific event |
| `calendar_create_event` | Create a new calendar event |
| `calendar_update_event` | Update an existing calendar event |
| `calendar_delete_event` | Delete a calendar event |
| `calendar_get_calendar` | Get calendar metadata |
| `calendar_check_availability` | Check free/busy status for attendees |
| `hubspot_*` | HubSpot CRM: contacts, companies, deals, notes |
| `apollo_*` | Apollo.io: prospect search and enrichment |
| `calcom_*` | Cal.com: scheduling and bookings |

### Cloud & APIs

| Tool | Description |
| ---- | ----------- |
| `vision_*` | Analyze images with Google Cloud Vision (labels, OCR, faces, objects, etc.) |
| `google_docs_*` | Read and write Google Docs |
| `maps_*` | Places search, geocoding, directions (Google Maps) |
| `run_bigquery_query`, `describe_dataset` | Run queries against Google BigQuery |
| `razorpay_*` | Razorpay payments and orders |
| `github_*` | GitHub repos, issues, and pull requests |

### Security

| Tool | Description |
| ---- | ----------- |
| `port_scan` | TCP port scan with service banner grabbing |
| `dns_security_scan` | Check SPF, DMARC, DKIM, DNSSEC, zone transfer |
| `ssl_tls_scan` | Analyze SSL/TLS configuration and certificate |
| `http_headers_scan` | Check security-related HTTP response headers |
| `subdomain_enumerate` | Enumerate subdomains via DNS |
| `tech_stack_detect` | Detect technologies used by a website |
| `risk_score` | Compute an overall security risk grade |

### Utilities

| Tool | Description |
| ---- | ----------- |
| `get_current_time` | Get current date/time with timezone support |

## Project Structure

```
tools/
├── src/aden_tools/
│   ├── __init__.py          # Main exports
│   ├── file_ops.py          # ALL file tools (read, write, edit, hashline_edit, search_files, apply_patch)
│   ├── credentials/         # Credential management
│   └── tools/               # Tool implementations
│       ├── file_system_toolkits/  # Sandbox path helpers (security.py)
│       │   └── security.py
│       ├── web_search_tool/
│       ├── web_scrape_tool/
│       ├── pdf_read_tool/
│       ├── wikipedia_tool/
│       ├── time_tool/
│       └── calendar_tool/
├── tests/                   # Test suite
├── mcp_server.py            # MCP server entry point
├── README.md
├── BUILDING_TOOLS.md        # Tool development guide
└── pyproject.toml
```

## Creating Custom Tools

Tools use FastMCP's native decorator pattern:

```python
from fastmcp import FastMCP


def register_tools(mcp: FastMCP) -> None:
    @mcp.tool()
    def my_tool(query: str, limit: int = 10) -> dict:
        """
        Search for items matching the query.

        Args:
            query: The search query
            limit: Max results to return

        Returns:
            Dict with results or error
        """
        try:
            results = do_search(query, limit)
            return {"results": results, "total": len(results)}
        except Exception as e:
            return {"error": str(e)}
```

See [BUILDING_TOOLS.md](BUILDING_TOOLS.md) for the full guide.

## Documentation

- [Building Tools Guide](BUILDING_TOOLS.md) - How to create new tools
- Individual tool READMEs in `src/aden_tools/tools/*/README.md`

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/aden-hive/hive/blob/main/LICENSE) file for details.
