Ragex.AI.Behaviour behaviour (Ragex v0.3.0)

View Source

Defines the behaviour for AI provider implementations.

This abstraction allows Ragex to support multiple AI providers (DeepSeek, OpenAI, Anthropic, local LLMs) with a unified interface.

Summary

Types

chunk()

Streaming chunk from AI provider

opts()

Generation options

response()

AI provider response

Callbacks

generate(prompt, context, opts)

Generate a response from the AI provider.

info()

Get provider information (name, models, capabilities).

stream_generate(prompt, context, opts)

Stream a response from the AI provider.

validate_config()

Validate provider configuration.

Types

chunk()

@type chunk() :: %{content: String.t(), done: boolean(), metadata: map()}

Streaming chunk from AI provider

opts()

@type opts() :: keyword()

Generation options

response()

@type response() :: %{
  content: String.t(),
  model: String.t(),
  usage: map(),
  metadata: map()
}

AI provider response

Callbacks

generate(prompt, context, opts)

@callback generate(prompt :: String.t(), context :: map() | nil, opts()) ::
  {:ok, response()} | {:error, term()}

Generate a response from the AI provider.

Parameters

  • prompt - User query or instruction
  • context - Retrieved code context (optional)
  • opts - Provider-specific options

Options

  • :temperature - Sampling temperature (0.0-2.0)
  • :max_tokens - Maximum response length
  • :system_prompt - System instructions
  • :model - Model override

Returns

  • {:ok, response} - Successful generation
  • {:error, reason} - API error, rate limit, etc.

info()

@callback info() :: map()

Get provider information (name, models, capabilities).

stream_generate(prompt, context, opts)

@callback stream_generate(prompt :: String.t(), context :: map() | nil, opts()) ::
  {:ok, Enumerable.t(chunk())} | {:error, term()}

Stream a response from the AI provider.

Returns a stream of chunks that can be consumed incrementally. Useful for real-time UI updates in MCP clients.

validate_config()

@callback validate_config() :: :ok | {:error, String.t()}

Validate provider configuration.

Called at application startup to ensure API keys, endpoints, etc. are valid.