defmodule OpenResponses do
  @moduledoc """
  OpenResponses — a spec-compliant Open Responses server for Elixir/Phoenix.

  ## Quick start

  Start your Phoenix server and send requests to `POST /v1/responses`.
  Pass your provider API key directly in the request body — the server
  never uses a shared key on your behalf:

  ```bash
  curl http://localhost:4000/v1/responses \\
    -H "Content-Type: application/json" \\
    -d '{
      "model": "gpt-4o",
      "api_key": "sk-...",
      "input": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  The `api_key` field is required. Requests without it are rejected with
  `400 invalid_request`. Provider routing is determined by the `model`
  field — see `OpenResponses.Adapter` and the [Providers guide](providers.html).

  ## Extension points

  | What you want to do | Module to implement |
  |---|---|
  | Execute a tool server-side (no client round-trip) | `OpenResponses.Tool` |
  | Build a custom provider adapter | `OpenResponses.Adapter` |
  | Intercept the loop for logging, budgets, rate limits | `OpenResponses.Middleware` |

  ## Built-in adapters

  | Provider | Adapter module |
  |---|---|
  | OpenAI | `OpenResponses.Adapters.OpenAI` |
  | Anthropic / z.ai | `OpenResponses.Adapters.Anthropic` |
  | Google Gemini | `OpenResponses.Adapters.Gemini` |
  | Ollama (local) | `OpenResponses.Adapters.Ollama` |
  | Testing / mock | `OpenResponses.Adapters.Mock` |

  ## Guides

  - [Overview](overview.html)
  - [Getting Started](getting_started.html)
  - [Providers](providers.html)
  - [Streaming](streaming.html)
  - [Tool Dispatch](tool_dispatch.html)
  - [Conversation History](conversation_history.html)
  - [Middleware](middleware.html)
  - [MCP Integration](mcp_integration.html)
  - [Observability](observability.html)
  - [Configuration Reference](configuration_reference.html)
  - [Deploying](deploying.html)
  """
end