Metadata-Version: 2.4
Name: talon-tools
Version: 0.1.0
Summary: Unified toolkit for building AI-powered agents — Google, Microsoft, social media, productivity, and more
Project-URL: Homepage, https://github.com/bingkil/talon-tools
Project-URL: Repository, https://github.com/bingkil/talon-tools
Project-URL: Issues, https://github.com/bingkil/talon-tools/issues
Author: Chris Prakoso
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,automation,google,llm,microsoft,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: truststore>=0.9
Provides-Extra: all
Requires-Dist: aiohttp; extra == 'all'
Requires-Dist: atlassian-python-api>=3.41; extra == 'all'
Requires-Dist: browser-cookie3; extra == 'all'
Requires-Dist: ddgs; extra == 'all'
Requires-Dist: gkeepapi>=0.17.1; extra == 'all'
Requires-Dist: google-api-python-client; extra == 'all'
Requires-Dist: google-auth-httplib2; extra == 'all'
Requires-Dist: google-auth-oauthlib; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: httpx; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: msal>=1.28; extra == 'all'
Requires-Dist: notion-client>=3.0.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: playwright; extra == 'all'
Requires-Dist: pypdf>=6.10.2; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-pptx>=1.0; extra == 'all'
Requires-Dist: yt-dlp>=2024.0; extra == 'all'
Provides-Extra: atlassian
Requires-Dist: atlassian-python-api>=3.41; extra == 'atlassian'
Provides-Extra: catholic
Requires-Dist: aiohttp; extra == 'catholic'
Provides-Extra: docreader
Requires-Dist: openpyxl>=3.1; extra == 'docreader'
Requires-Dist: pypdf>=6.10.2; extra == 'docreader'
Requires-Dist: python-docx>=1.1; extra == 'docreader'
Requires-Dist: python-pptx>=1.0; extra == 'docreader'
Provides-Extra: facebook
Requires-Dist: browser-cookie3; extra == 'facebook'
Requires-Dist: playwright; extra == 'facebook'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == 'gemini'
Requires-Dist: openai>=1.0; extra == 'gemini'
Provides-Extra: google
Requires-Dist: gkeepapi>=0.17.1; extra == 'google'
Requires-Dist: google-api-python-client; extra == 'google'
Requires-Dist: google-auth-httplib2; extra == 'google'
Requires-Dist: google-auth-oauthlib; extra == 'google'
Provides-Extra: mcp
Requires-Dist: httpx; extra == 'mcp'
Provides-Extra: microsoft
Requires-Dist: httpx>=0.27; extra == 'microsoft'
Requires-Dist: msal>=1.28; extra == 'microsoft'
Provides-Extra: notion
Requires-Dist: notion-client>=3.0.0; extra == 'notion'
Provides-Extra: search
Requires-Dist: ddgs; extra == 'search'
Provides-Extra: servicenow
Requires-Dist: aiohttp; extra == 'servicenow'
Provides-Extra: spotify
Requires-Dist: httpx; extra == 'spotify'
Provides-Extra: wa
Provides-Extra: x
Requires-Dist: browser-cookie3; extra == 'x'
Requires-Dist: httpx; extra == 'x'
Provides-Extra: youtube
Requires-Dist: httpx; extra == 'youtube'
Requires-Dist: yt-dlp>=2024.0; extra == 'youtube'
Description-Content-Type: text/markdown

<p align="center">
  <img src="talon-tools.png" width="200" alt="talon-tools logo">
</p>

<h1 align="center">talon-tools</h1>

<p align="center">
  <strong>Unified Python toolkit for building AI-powered agents</strong><br>
  Google · Microsoft · Atlassian · Notion · Spotify · X · Facebook · and more
</p>

<p align="center">
  <a href="https://github.com/bingkil/talon-tools/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
</p>

---

## What is this?

**talon-tools** provides a batteries-included set of tool modules for AI agents. Each module wraps a service API and exposes a standard `build_tools() -> list[Tool]` interface that plugs into any LLM agent framework.

Features:
- **Multi-service**: Google Workspace, Microsoft 365, Atlassian, Notion, Spotify, X, Facebook, ServiceNow, web search, file system, terminal
- **Credential management**: Pluggable storage (`.env`, YAML, env vars, custom backends)
- **Interactive onboarding**: `python -m talon_tools.cli setup` walks through OAuth flows, cookie extraction, and credential entry
- **Modular installs**: Only install what you need via pip extras

## Install

```bash
pip install talon-tools          # core only
pip install talon-tools[google]  # with Google integrations
pip install talon-tools[all]     # everything
```

Requires **Python 3.11+**.

## Modules

| Module | Extra | Description |
|--------|-------|-------------|
| `credentials` | *(core)* | Unified credential manager — .env, YAML, or custom backend |
| `atlassian` | `[atlassian]` | Jira & Confluence API client |
| `google` | `[google]` | Gmail, Calendar, Drive, Sheets, Keep, Contacts, Photos, YouTube |
| `microsoft` | `[microsoft]` | Outlook, Teams, Calendar via Microsoft Graph |
| `notion` | `[notion]` | Notion pages & databases |
| `servicenow` | `[servicenow]` | ServiceNow incidents & change requests |
| `facebook` | `[facebook]` | Facebook session-based automation |
| `x` | `[x]` | X (Twitter) API |
| `spotify` | `[spotify]` | Spotify playback & library |
| `search` | `[search]` | Web search via DuckDuckGo |
| `docreader` | `[docreader]` | PDF, Excel, Word, PowerPoint parsing |
| `mcp` | `[mcp]` | Model Context Protocol client |
| `terminal` | *(core)* | Shell command execution |
| `workspace` | *(core)* | File system operations |

## Setup

Interactive setup walks you through credentials for each service:

```bash
python -m talon_tools.cli setup          # all tools
python -m talon_tools.cli setup google   # just Google
python -m talon_tools.cli setup x        # just X
```

Features:
- Automatic OAuth flows (Google, Microsoft, Spotify)
- Browser cookie extraction (X, Facebook)
- Signal: auto-downloads signal-cli + Java to `~/.config/talon/`
- Falls back to manual entry if automation fails
- Configurable credential storage (`.env` or YAML)

## Credentials

```python
from talon_tools.credentials import configure_storage, get, set_credential

# .env file
configure_storage("env", path=".env")

# YAML file
configure_storage("yaml", path="credentials.yaml")

# Custom path (format auto-detected from extension)
configure_storage("/path/to/secrets.env")
```

Lookup order: **file store → environment variables** (env vars always work as fallback/override).

### .env format

```bash
JIRA_URL=https://yourcompany.atlassian.net
JIRA_USERNAME=you@company.com
JIRA_API_TOKEN=your-api-token
NOTION_TOKEN=secret_abc123
```

### YAML format

```yaml
jira:
  url: https://yourcompany.atlassian.net
  username: you@company.com
  api_token: your-api-token

notion:
  token: secret_abc123
```

Nested YAML keys auto-flatten: `jira.url` → `JIRA_URL`.

See [`credentials.yaml.example`](credentials.yaml.example) for all available keys.

## Quick Start

### API client

```python
import asyncio
from talon_tools.atlassian.client import JiraClient
from talon_tools import credentials

credentials.configure_storage("env", path=".env")

async def main():
    jira = JiraClient()
    me = await jira.myself()
    print(f"Logged in as: {me['displayName']}")

    issues = await jira.search("assignee = currentUser()", limit=5)
    for issue in issues["issues"]:
        print(f"  {issue['key']}: {issue['fields']['summary']}")

asyncio.run(main())
```

### Agent tools

Each module exposes `build_tools() -> list[Tool]` — ready for any LLM agent loop:

```python
from talon_tools.atlassian.tools import build_tools as jira_tools
from talon_tools.notion.tools import build_tools as notion_tools

# Collect tools from the modules you need
tools = jira_tools() + notion_tools()

# Tools are async callables: tool.handler({"jql": "..."}) -> ToolResult
for tool in tools:
    print(f"  {tool.name}: {tool.description}")
```

### Dynamic skill loading

```python
import importlib
from talon_tools import Tool

def load_skills(skill_names: list[str]) -> list[Tool]:
    tools = []
    for name in skill_names:
        module = importlib.import_module(f"talon_tools.{name}.tools")
        tools.extend(module.build_tools())
    return tools

tools = load_skills(["atlassian", "notion", "search"])
```

### Custom tool

```python
from talon_tools import Tool, ToolResult

async def greet(args: dict) -> ToolResult:
    name = args.get("name", "world")
    return ToolResult(content=f"Hello, {name}!")

def build_tools() -> list[Tool]:
    return [
        Tool(
            name="greet",
            description="Greet someone by name.",
            parameters={
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "Name to greet."},
                },
            },
            handler=greet,
        )
    ]
```

## Development

```bash
git clone https://github.com/bingkil/talon-tools.git
cd talon-tools
pip install -e ".[all]"
```

### Project structure

```
talon_tools/
├── credentials.py         # Credential management
├── cli.py                 # Interactive setup CLI
├── types.py               # Tool/ToolResult base types
├── provider.py            # LLM provider interface
├── onboarding/            # Shared onboarding utilities
│   ├── base.py            # OnboardingStep/ToolOnboarding types
│   ├── registry.py        # Auto-discovery of tool onboardings
│   ├── installer.py       # Binary dependency installer
│   └── cookies.py         # Browser cookie extraction
├── google/                # Google Workspace tools
├── microsoft/             # Microsoft 365 tools
├── atlassian/             # Jira & Confluence tools
├── notion/                # Notion tools
├── spotify/               # Spotify tools
├── x/                     # X (Twitter) tools
├── facebook/              # Facebook tools
├── search/                # Web search tools
├── docreader/             # Document parsing tools
├── mcp/                   # MCP client
├── terminal/              # Shell execution tools
└── workspace/             # File system tools
```

### Adding a new tool module

1. Create `talon_tools/myservice/tools.py` with `build_tools() -> list[Tool]`
2. Create `talon_tools/myservice/onboarding.py` with `get_onboarding() -> ToolOnboarding`
3. Add the import to `talon_tools/onboarding/registry.py`
4. Add optional deps to `pyproject.toml` under `[project.optional-dependencies]`

## Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run the setup CLI to test: `python -m talon_tools.cli setup`
5. Open a PR

## License

[MIT](LICENSE)
