Batrachian Toad

0.6.15 · active · verified Fri Apr 17

Batrachian Toad provides a unified Pythonic interface for interacting with various AI models directly from your terminal. It abstracts away the complexities of different AI providers (OpenAI, Anthropic, Google Gemini, etc.) into a simple API. The current version is 0.6.15, and as a pre-1.0 library, it is under active development with frequent releases.

Common errors

```
ERROR: batrachian-toad requires Python >=3.14
```
cause Attempting to install or run `batrachian-toad` on a Python version older than 3.14.

fix Upgrade your Python environment to version 3.14 or higher. Verify your Python version with `python --version`.
```
openai.APIAuthenticationError: Invalid Authentication. Your API key is incorrect, expired, or revoked.
```
cause The `OPENAI_API_KEY` environment variable is either missing, has an incorrect value, or the key itself is no longer valid.

fix Ensure `OPENAI_API_KEY` (or the relevant API key for your chosen provider) is correctly set as an environment variable with a valid, active key. Double-check for typos and leading/trailing spaces.
```
ImportError: cannot import name 'Toad' from 'batrachian_toad'
```
cause Likely a typo in the import statement or an outdated import path if the library's structure changed in a new version.

fix Verify the import statement is `from batrachian_toad import Toad`. If on an older version, consult release notes or ensure `batrachian_toad` is installed correctly.

Warnings

breaking Batrachian Toad requires Python 3.14 or newer. Attempting to install or run on older Python versions will result in an error.
Fix: Upgrade your Python installation to 3.14 or later. Consider using `pyenv` or a virtual environment manager to manage multiple Python versions.
gotcha API keys for AI providers (e.g., OpenAI, Anthropic, Google) must be set as environment variables (e.g., `OPENAI_API_KEY`). The library will not prompt for keys and will fail if they are missing or invalid.
Fix: Before running your application, set the necessary environment variables: `export OPENAI_API_KEY="your_key_here"` on Linux/macOS or `$env:OPENAI_API_KEY="your_key_here"` in PowerShell.
gotcha By default, Batrachian Toad uses OpenAI as the primary provider for AI interactions. If you wish to use a different provider (e.g., Anthropic, Google), you must explicitly set it using `Toad.set_default_provider('anthropic')`.
Fix: Call `Toad.set_default_provider('your_provider_name')` early in your application's lifecycle if you don't intend to use OpenAI or need to switch providers.
gotcha As a library in active development (pre-1.0), internal APIs and behaviors may change in minor versions. While the public interface aims for stability, occasional adjustments might be necessary.
Fix: Monitor the project's GitHub releases and changelog for specific breaking changes. Pin your dependency to a specific minor version (`batrachian-toad==0.6.*`) to prevent unexpected updates.

Install

pip install batrachian-toad Install latest version

Imports

Toad
```
from batrachian_toad import Toad
```
TerminalAI
```
from batrachian_toad import TerminalAI
```
TerminalAI provides a more direct terminal-focused experience, while Toad is the primary unified API.

Quickstart

This quickstart demonstrates basic chat and image generation using the `Toad` class. It expects API keys like `OPENAI_API_KEY` to be set as environment variables. Without valid API keys, the actual AI calls will fail, though the Python code itself will execute up to the point of API interaction. Python 3.14 or newer is required.

import os
from batrachian_toad import Toad

# IMPORTANT: Set your API key as an environment variable, e.g.,
# export OPENAI_API_KEY="sk-your-openai-key"
# export ANTHROPIC_API_KEY="sk-your-anthropic-key"
# If not set, API calls will likely fail.

print("Attempting to use Toad for AI interactions...")

try:
    # Chat example (uses OpenAI by default)
    print("\n--- Chat Example ---")
    chat_response = Toad.chat("Tell me a short, inspiring quote.")
    print(f"Toad Chat: {chat_response.content}")

    # Image generation example (requires a provider like DALL-E, and a valid API key)
    # This may fail if the default provider doesn't support image generation or key is invalid.
    print("\n--- Image Generation Example ---")
    image_url = Toad.generate_image("A futuristic city at sunset in an anime style.")
    print(f"Toad Image URL: {image_url}")

    # Example of changing provider (uncomment and set ANTHROPIC_API_KEY to test)
    # Toad.set_default_provider("anthropic")
    # print("\n--- Summarization Example (using Anthropic if configured) ---")
    # summary_response = Toad.summarize("Long text to summarize...", model="claude-3-haiku-20240307")
    # print(f"Toad Summary: {summary_response.content}")

except Exception as e:
    print(f"\nAn error occurred during quickstart execution: {e}")
    print("Please ensure Python >=3.14 is installed and relevant API keys (e.g., OPENAI_API_KEY) are set in your environment.")

view raw JSON →