# Adapters Package Documentation

## Overview

The Adapters package facilitates communication between different language model APIs by providing a unified interface for interaction. This ensures ease of use and flexibility in integrating multiple models from various providers.

## Getting Started

### Prerequisites

- Python version: 3.11.6
- [Poetry](https://python-poetry.org/docs/#installation)

### Installation

1. **Install Python:** Ensure Python `3.11.6` is installed on your system.
2. **Install Poetry:** Follow the installation guide on the [official Poetry website](https://python-poetry.org/docs/#installation).
3. **Install Dependencies:**
   ```bash
   poetry install
   ```
4. **Install Pre-commit Hooks:**
   ```bash
   poetry run pre-commit install
   ```
5. **Run Commands via Poetry:**
   ```bash
   poetry run pytest
   ```

### Setting Up Pre-commit

Pre-commit hooks help maintain code quality and standards. Install them with the following command:

```bash
poetry run pre-commit install
```

To run pre-commit manually:

```bash
poetry run pre-commit run --all-files
```

### Environment Configuration

The package requires certain environment variables to be set by the users:

- Copy `.env-example` to `.env` and populate it with appropriate values.

### Running Tests

Ensure Python 3.11 is used:

```bash
poetry run pytest
```

## Usage

### Creating and Using Adapters

1. **Instantiate an Adapter:**

   ```python
   adapter1 = AdapterFactory.get_adapter("adapter_name")
   ```

   Here, `"adapter_name"` should follow the format `provider/vendor/model_name`. Use `AdapterFactory.get_supported_models()` to retrieve all valid names.

2. **Convert Input:**

   ```python
   adapter1.convert_to_input(prompt)
   ```

3. **Execute Adapter:**
   ```python
   adapter1.execute_async(input_data)
   ```

### Disabling Specific Models

To disable models, set the `ADAPTER_DISABLED_MODELS` environment variable:

```bash
export ADAPTER_DISABLED_MODELS="model1,model2"
```

Disabled models will not appear in the supported models list.

### Retrieving Supported Models

```python
AdapterFactory.get_supported_models()
```

## Contributing

### Adding New Models

1. **Existing Providers:**
   Add new models to the `SUPPORTED_MODELS` array if the provider is already supported.

2. **New Providers:**
   - If the provider follows the OpenAI format, model integration is straightforward. See the "_Together_" provider class as an example.
   - For providers with different schemas, see the "_Anthropic_" provider class for guidance.

### Development Steps

1. **Add the Provider and Model:** Update `provider_adapters/__init__.py` and test files accordingly.
2. **Write Tests:** Add tests in the relevant directories. Use `@pytest.mark.vcr` for tests making network requests.
3. **Run Tests:**
   ```bash
   poetry run pytest
   ```
4. **Check-in Cassette Files:** Include any new cassette YAML files in your commit.
5. **Send a Pull Request:** Ensure all tests pass before requesting a review.

### Re-creating Cassette Files

Use the `--record-mode=rewrite` option with pytest to update cassette files.

## Additional Notes

Some models may only be accessible from specific locations (e.g., the U.S.). In such cases, running tests might require access to a U.S.-based server.

This documentation provides a streamlined approach to using and contributing to the Adapters package, emphasizing practical steps and clear examples.
