---
title: "Installation"
---

Get Talk Box up and running in your Python environment with these simple installation steps.

## Requirements

- **Python 3.8 or higher**
- **pip** or **conda** package manager

## Basic Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install talk-box
```

### Option 2: Development Installation

For the latest features or to contribute to development:

```bash
git clone https://github.com/rich-iannone/talk-box.git
cd talk-box
pip install -e .
```

## AI Provider Setup

Talk Box integrates with multiple AI providers. You'll need to set up at least one provider to use real AI models.

::: {.callout-tip}
## Using a `.env` file (Recommended)

For security and convenience, you can store all your API keys in a `.env` file in your project directory:

1. Create a file named `.env` in your project root
2. Add your API keys (one per line):
   ```
   OPENAI_API_KEY=your-openai-key-here
   ANTHROPIC_API_KEY=your-anthropic-key-here
   GOOGLE_API_KEY=your-google-key-here
   ```
3. Install python-dotenv: `pip install python-dotenv`
4. Load in Python:
   ```python
   from dotenv import load_dotenv
   load_dotenv()  # Loads variables from .env file
   ```

**Important:** Add `.env` to your `.gitignore` file to avoid committing API keys to version control!
:::

### OpenAI (Recommended for beginners)

1. **Get an API key** from [OpenAI](https://platform.openai.com/api-keys)

2. **Set your API key** (choose one method):

   **Environment Variable:**
   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```

   **In Python:**
   ```python
   import os
   os.environ["OPENAI_API_KEY"] = "your-api-key-here"
   ```

### Anthropic (Claude)

1. **Get an API key** from [Anthropic](https://console.anthropic.com/)

2. **Set your API key:**
   ```bash
   export ANTHROPIC_API_KEY="your-api-key-here"
   ```

### Google (Gemini)

1. **Get an API key** from [Google AI Studio](https://makersuite.google.com/app/apikey)

2. **Set your API key:**
   ```bash
   export GOOGLE_API_KEY="your-api-key-here"
   ```

## Verify Installation

Test your installation with this simple script:

```python
import talk_box as tb

# Check if Talk Box is working
bot = tb.ChatBot()
print("✅ Talk Box installed successfully!")

# Check AI integration (requires API key)
try:
    response = bot.chat("Say hello!")
    print("LLM integration working!")
    print(f"Response: {response.get_last_message().content}")
except Exception as e:
    print("LLM integration needs setup:")
    print(f"   {e}")
    print("   See the AI Provider Setup section above")
```

## Installation Troubleshooting

### Common Issues

**"ModuleNotFoundError: No module named 'talk_box'"**

- Make sure you installed with the correct Python environment
- Try: `python -m pip install talk-box`

**"API key not found" errors**

- Verify your API key is set correctly
- Check the environment variable name matches your provider
- Restart your Python session after setting environment variables

**Permission errors on installation**

- Try: `pip install --user talk-box`
- Or use a virtual environment (recommended)

## Optional Dependencies

**Development tools:**

```bash
pip install talk-box[dev]
```

**All optional dependencies:**

```bash
pip install talk-box[all]
```
