OpenaiEx

While designed for OpenAI, OpenaiEx is compatible with:

• Azure OpenAI API
• Local LLMs via OpenAI-compatible proxies
• Third-party integrations like Portkey

The library uses Finch for HTTP transport, allowing for fine-grained control over connection pools and timeouts.

The primary way to learn and test OpenaiEx is through its Livebook-based User Guide. Because the library uses a Livebook-first design, you can run the guide directly to see working examples of almost every API call without setting up a local project.

Detailed usage examples and the full user guide are available on hexdocs.

To use OpenaiEx in your Elixir project, add it to your mix.exs dependencies. It is a community-maintained OpenAI API client that supports all current endpoints, including the Responses API and Container APIs.

{:openai_ex, "~> 0.1.0"} # Replace with the latest version

The library provides comprehensive streaming API implementations with request cancellation capabilities. You can find specialized Livebook examples for different patterns:

• Streaming Chatbots: See the Streaming Orderbot example for using ChatCompletion streaming.
• Standard Completions: See the Completions Chatbot for both normal and streaming completion forms.
• Image Generation: See the Image Generation UI for DALL-E integration.

When developing locally using the provided devcontainer, you can manage secrets and configuration by creating a .env file in the .devcontainer/ directory.

Commonly used variables include:

• OPENAI_API_KEY: Your OpenAI credentials.
• LIVEBOOK_PASSWORD: The password required to access Livebook within the devcontainer.

# Example .devcontainer/.env content
OPENAI_API_KEY=sk-...
LIVEBOOK_PASSWORD=your_password_here

If you want to reference an existing file by its ID instead of uploading a new one, use new_reference/1. This prepares a request containing the :file_id key.

Example:

OpenaiEx.ContainerFiles.new_reference(file_id: "file-123")
# => %{file_id: "file-123"}

Retrieve the details of a specific run using OpenaiEx.Beta.Threads.Runs.retrieve/2. You must provide a map containing both thread_id and run_id.

params = %{thread_id: "thread_foo", run_id: "run_bar"}
run = OpenaiEx.Beta.Threads.Runs.retrieve(openai_client, params)

Use OpenaiEx.Containers.list!/2 to retrieve a list of all containers belonging to your organization. You can pass optional query parameters to filter the results. The bang version (!) raises an error on failure.

# List all containers
containers = OpenaiEx.Containers.list!(openai_client)

# List containers with specific query parameters
containers = OpenaiEx.Containers.list!(openai_client, %{limit: 10})

To download or view the raw content of an uploaded file, use OpenaiEx.Files.content!(openai, file_id). This calls the /files/{file_id}/content endpoint and returns the undecoded response body.

content = OpenaiEx.Files.content!(openai, "file-123")

To fetch the details of a specific container, use OpenaiEx.Containers.retrieve!/2 and provide the container_id. The bang version (!) raises an error if the container is not found or the request fails.

container = OpenaiEx.Containers.retrieve!(openai_client, "cont-123")

When a tool requires input from the user or an external system, use OpenaiEx.Beta.Threads.Runs.submit_tool_outputs/2 to provide the results back to the run.

Required keys in the params map:

• thread_id
• run_id
• tool_outputs

Supports streaming via stream: true.

params = %{
  thread_id: "thread_foo",
  run_id: "run_bar",
  tool_outputs: [%{tool_call_id: "call_123", output: "result_data"}]
}
OpenaiEx.Beta.Threads.Runs.submit_tool_outputs(openai_client, params)

Retrieve a list of all files within a specific container. You can pass optional query parameters via the params argument.

Signature: list(openai, container_id, params \ %{})