altar_ai

# Altar.AI

<p align="center">
  <img src="assets/altar_ai.svg" alt="Altar.AI Logo" width="200"/>
</p>

**Unified AI adapter foundation for Elixir** - Protocol-based abstractions for multiple AI providers

[![Hex.pm](https://img.shields.io/hexpm/v/altar_ai.svg)](https://hex.pm/packages/altar_ai)
[![Documentation](https://img.shields.io/badge/docs-hexdocs-blue.svg)](https://hexdocs.pm/altar_ai)
[![License](https://img.shields.io/hexpm/l/altar_ai.svg)](https://github.com/nshkrdotcom/altar_ai/blob/main/LICENSE)

## Features

- **Protocol-Based Architecture** - Uses protocols instead of behaviours for maximum flexibility
- **Runtime Capability Detection** - Introspect what each adapter supports at runtime
- **Composite Adapters** - Automatic fallback chains across multiple providers
- **Framework Agnostic** - No dependencies on FlowStone, Synapse, or other frameworks
- **Unified Telemetry** - Standard telemetry events for monitoring and debugging
- **Comprehensive Testing** - Mock adapters and test utilities included

## Supported Providers

- **Gemini** - Google Gemini AI (via `gemini_ex`)
- **Gemini** - Anthropic Claude (via `claude_agent_sdk`)
- **Codex** - OpenAI models (via `codex_sdk`)
- **OpenAI** - OpenAI chat + embeddings (via `openai_ex`)
- **Fallback** - Heuristic fallback (no external API required)
- **Mock** - Configurable mock for testing

All SDK dependencies are **optional** - Altar.AI works with whatever you have installed.

## Installation

Add `altar_ai` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:altar_ai, "~> 0.1.0"},
    # Optional: Add the AI SDKs you want to use
    # {:gemini_ex, "~> 0.1.0"},
    # {:claude_agent_sdk, "~> 0.1.0"},
    # {:codex_sdk, "~> 0.1.0"},
    # {:openai_ex, "~> 0.9.18"}
  ]
end
```

## Quick Start

### Basic Usage

```elixir
# Create an adapter
adapter = Altar.AI.Adapters.Gemini.new(api_key: "your-api-key")

# Generate text
{:ok, response} = Altar.AI.generate(adapter, "Explain Elixir protoc