talon-tools 0.1.0

Unified toolkit for building AI-powered agents — Google, Microsoft, social media, productivity, and more

talon-tools

Unified Python toolkit for building AI-powered agents
Google · Microsoft · Atlassian · Notion · Spotify · X · Facebook · and more

---

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

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:

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

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

JIRA_URL=https://yourcompany.atlassian.net
JIRA_USERNAME=[e-mail]
JIRA_API_TOKEN=your-api-token
NOTION_TOKEN=secret_abc123

YAML format

jira:
  url: https://yourcompany.atlassian.net
  username: [e-mail]
  api_token: your-api-token

notion:
  token: secret_abc123

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

See credentials.yaml.example for all available keys.

Quick Start

API client

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:

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

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

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

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