# Installation

## Requirements

- Elixir 1.15+
- Phoenix 1.8+
- An existing Phoenix application (or create one with `mix phx.new`)

## Automatic installation (recommended)

OpenResponses ships an [Igniter](https://github.com/ash-project/igniter) installer that handles everything:

```bash
mix igniter.install open_responses
```

This will:

1. Add `open_responses` to your dependencies
2. Register the Ash domain in your config
3. Mount `POST /v1/responses` in your router
4. Add `Cachex` and `OpenResponses.LoopSupervisor` to your supervision tree
5. Create a provider config block in `config/runtime.exs`

## Manual installation

If you prefer to wire things up yourself, add to `mix.exs`:

```elixir
defp deps do
  [
    {:open_responses, "~> 0.1"},
    {:cachex, "~> 3.6"}
  ]
end
```

Then follow the steps below.

### 1. Add to your supervision tree

In `lib/your_app/application.ex`, add after `Phoenix.PubSub`:

```elixir
children = [
  # ... existing children ...
  {Cachex, name: :response_cache},
  OpenResponses.LoopSupervisor
]
```

### 2. Register the Ash domain

In `config/config.exs`:

```elixir
config :your_app,
  ash_domains: [
    # ... existing domains ...
    OpenResponses.Responses
  ]
```

### 3. Mount the router scope

In `lib/your_app_web/router.ex`:

```elixir
scope "/v1", OpenResponsesWeb do
  pipe_through :api

  post "/responses", OpenResponsesWeb.ResponseController, :create
end
```

### 4. Configure providers

In `config/runtime.exs`:

```elixir
config :open_responses, :provider_config, %{
  openai: [api_key: System.fetch_env!("OPENAI_API_KEY")],
  anthropic: [api_key: System.fetch_env!("ANTHROPIC_API_KEY")],
  gemini: [api_key: System.fetch_env!("GEMINI_API_KEY")]
}
```

## Optional: Prometheus metrics

OpenResponses ships a PromEx plugin. To enable it, add `OpenResponses.PromEx` to your supervision tree and mount the metrics endpoint:

```elixir
# application.ex
children = [OpenResponses.PromEx, ...]

# router.ex
get "/metrics", PromEx.Plug, prom_ex_module: OpenResponses.PromEx
```

See [Observability](observability.html) for full details.

## Verifying the installation

Start your server and send a test request:

```bash
curl -X POST http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "mock-model", "input": [{"role": "user", "content": "hello"}]}'
```

You should receive a JSON response with `"status": "completed"`.