mabemi/onellmWeb
0
1---2title: OneLLM3emoji: 🚀4colorFrom: blue5colorTo: purple6sdk: docker7app_port: 76808pinned: false9license: mit10---11 12<p align="center">13 <img src="https://raw.githubusercontent.com/onellm/onellm-java/main/assets/logo.png" alt="OneLLM Logo" width="180"/>14</p>15 16<h1 align="center">🚀 OneLLM</h1>17 18<p align="center">19 <strong>One Interface. Eighteen Providers. Your API Keys.</strong>20</p>21 22<p align="center">23 <a href="#-quick-start">Quick Start</a> •24 <a href="#-providers">Providers</a> •25 <a href="#-rest-api">REST API</a> •26 <a href="#-sdk-usage">SDK Usage</a> •27 <a href="#-configuration">Configuration</a>28</p>29 30<p align="center">31 <img src="https://img.shields.io/badge/Java-17+-blue?style=for-the-badge&logo=openjdk" alt="Java 17+"/>32 <img src="https://img.shields.io/badge/Spring%20Boot-3.2.0-brightgreen?style=for-the-badge&logo=springboot" alt="Spring Boot 3.2.0"/>33 <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT License"/>34 <img src="https://img.shields.io/badge/BYOK-Bring%20Your%20Own%20Key-orange?style=for-the-badge" alt="BYOK"/>35</p>36 37---38 39**OneLLM** is a unified Java SDK and REST API that provides a single interface for calling **18 different LLM providers**. Users bring their own API keys — just specify the model name and your API key, and OneLLM automatically routes your request to the right provider.40 41> 🔑 **Bring Your Own Key (BYOK)**: OneLLM doesn't store or require server-side API keys. Users provide their own API keys in each request, making it perfect for multi-tenant applications.42 43## ✨ Features44 45| Feature | Description |46|---------|-------------|47| 🔌 **18 Providers** | OpenAI, Anthropic, Google Gemini/Gemma, Azure, Groq, Cerebras, Ollama, OpenRouter, xAI, GitHub Copilot, GitHub Models, Hugging Face, FreeLLM, LlamaCpp, RWKV, **Perplexity**, and **AIML API** |48| 🔑 **BYOK Model** | Users provide their own API keys — no server-side credential storage |49| 🎯 **Auto-Routing** | Automatically routes requests based on model name |50| 🔍 **Web Search** | Real-time web search for current information (set `search: true`) |51| 🌊 **Streaming** | Full support for streaming responses via SSE |52| ⚡ **Async** | Non-blocking async completions with `CompletableFuture` |53| 🛡️ **Type-Safe** | Builder pattern with validation for all request parameters |54| 📊 **Usage Tracking** | Token usage and latency metrics in every response |55 56---57 58## 🚀 Quick Start59 60### Prerequisites61 62- Java 17 or higher63- Maven 3.6+64 65### Run the Server66 67```bash68# Clone and build69git clone https://github.com/onellm/onellm-java.git70cd onellm71 72# Run (no API keys needed - users provide their own!)73mvn spring-boot:run74```75 76The server starts at `http://localhost:8080`77 78### Make Your First Request79 80```bash81curl -X POST http://localhost:8080/api/chat/completions \82 -H "Content-Type: application/json" \83 -d '{84 "apiKey": "YOUR_OPENAI_API_KEY",85 "model": "gpt-4",86 "messages": [{"role": "user", "content": "Hello!"}]87 }'88```89 90> **Note**: Replace `YOUR_OPENAI_API_KEY` with your actual API key from the respective provider.91 92---93 94## 🔌 Providers95 96OneLLM supports **18 LLM providers** out of the box:97 98| Provider | Models | Required Fields |99|----------|--------|-----------------|100| **OpenAI** | `gpt-4`, `gpt-4-turbo`, `gpt-4o`, `gpt-3.5-turbo`, `o1`, `o3`, `chatgpt-*` | `apiKey` |101| **Anthropic** | `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`, `claude-3.5-sonnet`, `claude-4-*` | `apiKey` |102| **Google Gemini** | `gemini-pro`, `gemini-ultra`, `gemini-1.5-pro`, `gemini-2.0-flash`, `gemini-2.5-flash` | `apiKey` |103| **Google Gemma** 🆓 | `gemma-3-27b-it`, `gemma-3-12b-it`, `gemma-2-27b-it`, `gemma-2-9b-it` | `apiKey` (Google API key) |104| **Azure OpenAI** | Your deployed models | `apiKey`, `azureResourceName`, `azureDeploymentName` |105| **Groq** | `llama-3`, `mixtral` | `apiKey` |106| **Cerebras** | `cerebras-gpt` variants | `apiKey` |107| **Ollama** 🆓 | Any local model (`gemma`, `mistral`, `llama`, etc.) | `baseUrl` (optional) |108| **OpenRouter** | 100+ models | `apiKey`, optionally `openRouterSiteName`, `openRouterSiteUrl` |109| **xAI** | `grok-*` models | `apiKey` |110| **GitHub Copilot** | Copilot models | `apiKey` |111| **GitHub Models** | `github/gpt-4o`, `github/Llama-3.3-70B`, Mistral, Phi, DeepSeek | `apiKey` (GitHub PAT) |112| **Hugging Face** | `meta-llama/*`, `mistralai/*`, `Qwen/*`, any HF model | `apiKey` (hf_token) |113| **FreeLLM** 🆓 | `TinyLlama/*`, `Qwen/*` | None (free!) |114| **LlamaCpp** 🆓 | GGUF models via llama.cpp server | `baseUrl` (optional) |115| **RWKV** 🆓 | RWKV models | `baseUrl` (optional) |116| **Perplexity** | `sonar`, `sonar-pro` (with web search) | `apiKey` |117| **AIML API** | GPT-4o, Gemma, Llama, Mistral, Qwen via aimlapi.com | `apiKey` |118 119### Model Auto-Detection120 121OneLLM automatically routes to the correct provider based on model name:122 123```124"gpt-4" → OpenAI125"claude-3-opus" → Anthropic126"gemini-1.5-pro" → Google127"llama-3-70b" → Groq128"grok-1" → xAI129```130 131You can also use explicit provider prefixes:132 133```134"openai/gpt-4"135"anthropic/claude-3-opus"136"google/gemini-pro"137"gemma/gemma-3-27b-it"138"azure/my-deployment"139"huggingface/meta-llama/Llama-3.3-70B-Instruct"140"hf/mistralai/Mistral-7B-Instruct-v0.3"141"freellm/TinyLlama/TinyLlama-1.1B-Chat-v1.0"142"perplexity/sonar"143"aiml/openai/gpt-4o"144```145 146---147 148## 🌐 REST API149 150### Base URL151 152```153http://localhost:8080/api154```155 156### Endpoints157 158| Method | Endpoint | Description |159|--------|----------|-------------|160| `POST` | `/chat/completions` | Synchronous chat completion |161| `POST` | `/chat/completions/stream` | Streaming chat completion (SSE) |162| `GET` | `/providers` | List supported providers |163| `GET` | `/health` | Health check |164 165---166 167### `POST /api/chat/completions`168 169Send a chat completion request with your own API key.170 171**Request Body:**172 173```json174{175 "apiKey": "sk-your-api-key-here",176 "model": "gpt-4",177 "messages": [178 { "role": "system", "content": "You are a helpful assistant." },179 { "role": "user", "content": "Hello, who are you?" }180 ],181 "temperature": 0.7,182 "maxTokens": 1000,183 "topP": 0.9,184 "frequencyPenalty": 0.0,185 "presencePenalty": 0.0,186 "stop": ["END"],187 "stream": false,188 189 "baseUrl": "https://custom-endpoint.com/v1",190 "azureResourceName": "my-resource",191 "azureDeploymentName": "gpt-4",192 "openRouterSiteName": "MyApp",193 "openRouterSiteUrl": "https://myapp.com"194}195```196 197**Request Attributes:**198 199| Field | Type | Required | Description | Valid Range |200|-------|------|----------|-------------|-------------|201| `apiKey` | `string` | ✅ **Yes** | Your API key for the provider | - |202| `model` | `string` | ✅ **Yes** | Model identifier (routes to provider automatically) | - |203| `messages` | `array` | ✅ **Yes** | Array of message objects | Min 1 message |204| `messages[].role` | `string` | ✅ **Yes** | Role: `system`, `user`, or `assistant` | - |205| `messages[].content` | `string` | ✅ **Yes** | Message content | - |206| `temperature` | `number` | ❌ No | Sampling temperature | `0.0` - `2.0` |207| `maxTokens` | `integer` | ❌ No | Maximum tokens to generate | `≥ 1` |208| `topP` | `number` | ❌ No | Nucleus sampling probability | `0.0` - `1.0` |209| `frequencyPenalty` | `number` | ❌ No | Frequency penalty | `-2.0` - `2.0` |210| `presencePenalty` | `number` | ❌ No | Presence penalty | `-2.0` - `2.0` |211| `stop` | `array` | ❌ No | Stop sequences | - |212| `stream` | `boolean` | ❌ No | Enable streaming | - |213 214**Provider-Specific Fields:**215 216| Field | Type | Required For | Description |217|-------|------|--------------|-------------|218| `baseUrl` | `string` | Optional | Custom base URL (OpenAI-compatible endpoints) |219| `azureResourceName` | `string` | Azure | Your Azure resource name |220| `azureDeploymentName` | `string` | Azure | Your Azure deployment name |221| `openRouterSiteName` | `string` | Optional | Your app name (for OpenRouter) |222| `openRouterSiteUrl` | `string` | Optional | Your app URL (for OpenRouter) |223 224**Web Search Fields (Real-Time Data):**225 226| Field | Type | Required | Description |227|-------|------|----------|-------------|228| `search` | `boolean` | ❌ No | Enable web search for real-time data (default: `false`) |229| `searchResultCount` | `integer` | ❌ No | Number of search results to inject (default: `3`) |230| `searchLanguage` | `string` | ❌ No | Language code for search (e.g., `en`) |231| `searchCountry` | `string` | ❌ No | Country code for search (e.g., `US`) |232 233**Response:**234 235```json236{237 "id": "chatcmpl-abc123",238 "model": "gpt-4-0613",239 "content": "Hello! I'm an AI assistant powered by GPT-4...",240 "finishReason": "stop",241 "provider": "openai",242 "latencyMs": 1234,243 "usage": {244 "promptTokens": 25,245 "completionTokens": 45,246 "totalTokens": 70247 }248}249```250 251---252 253### `POST /api/chat/completions/stream`254 255Stream responses using Server-Sent Events (SSE).256 257**Request:** Same as `/chat/completions`258 259**Response:** SSE stream with events:260 261```262event: chunk263data: {"content": "Hello"}264 265event: chunk266data: {"content": ", I'm"}267 268event: complete269data: {"id": "...", "model": "gpt-4", "content": "Hello, I'm...", ...}270```271 272---273 274### `GET /api/providers`275 276List all supported providers.277 278**Response:**279 280```json281{282 "providers": ["openai", "anthropic", "google", "azure", "groq", "cerebras", "ollama", "openrouter", "xai", "copilot", "github", "huggingface", "freellm", "llamacpp", "rwkv", "perplexity", "aiml"],283 "count": 17284}285```286 287---288 289### `GET /api/health`290 291Health check endpoint.292 293**Response:**294 295```json296{297 "status": "ok",298 "service": "OneLLM"299}300```301 302---303 304## 📝 API Examples305 306### OpenAI (GPT-4)307 308```bash309curl -X POST http://localhost:8080/api/chat/completions \310 -H "Content-Type: application/json" \311 -d '{312 "apiKey": "sk-your-openai-key",313 "model": "gpt-4",314 "messages": [315 {"role": "system", "content": "You are a helpful coding assistant."},316 {"role": "user", "content": "Write a Python function to reverse a string."}317 ],318 "temperature": 0.5,319 "maxTokens": 500320 }'321```322 323### Anthropic (Claude)324 325```bash326curl -X POST http://localhost:8080/api/chat/completions \327 -H "Content-Type: application/json" \328 -d '{329 "apiKey": "sk-ant-your-anthropic-key",330 "model": "claude-3-opus",331 "messages": [332 {"role": "user", "content": "Explain quantum computing in simple terms."}333 ],334 "maxTokens": 1000335 }'336```337 338### Google Gemini339 340```bash341curl -X POST http://localhost:8080/api/chat/completions \342 -H "Content-Type: application/json" \343 -d '{344 "apiKey": "AIza-your-google-key",345 "model": "gemini-1.5-pro",346 "messages": [347 {"role": "user", "content": "What is the meaning of life?"}348 ]349 }'350```351 352### Google Gemma (Free via Google API)353 354```bash355curl -X POST http://localhost:8080/api/chat/completions \356 -H "Content-Type: application/json" \357 -d '{358 "apiKey": "AIza-your-google-key",359 "model": "gemma/gemma-3-27b-it",360 "messages": [361 {"role": "user", "content": "Explain machine learning simply."}362 ]363 }'364```365 366> **Note**: Gemma models use the same Google API key as Gemini. Available models: `gemma-3-27b-it`, `gemma-3-12b-it`, `gemma-3-4b-it`, `gemma-2-27b-it`, `gemma-2-9b-it`.367 368### Azure OpenAI369 370```bash371curl -X POST http://localhost:8080/api/chat/completions \372 -H "Content-Type: application/json" \373 -d '{374 "apiKey": "your-azure-api-key",375 "model": "azure/my-gpt4-deployment",376 "azureResourceName": "my-azure-resource",377 "azureDeploymentName": "my-gpt4-deployment",378 "messages": [379 {"role": "user", "content": "Hello from Azure!"}380 ]381 }'382```383 384### Groq (Fast Inference)385 386```bash387curl -X POST http://localhost:8080/api/chat/completions \388 -H "Content-Type: application/json" \389 -d '{390 "apiKey": "gsk_your-groq-key",391 "model": "llama-3-70b",392 "messages": [393 {"role": "user", "content": "Write a haiku about coding."}394 ]395 }'396```397 398### OpenRouter (100+ Models)399 400```bash401curl -X POST http://localhost:8080/api/chat/completions \402 -H "Content-Type: application/json" \403 -d '{404 "apiKey": "sk-or-your-openrouter-key",405 "model": "openrouter/anthropic/claude-3-opus",406 "openRouterSiteName": "MyApp",407 "openRouterSiteUrl": "https://myapp.com",408 "messages": [409 {"role": "user", "content": "Hello via OpenRouter!"}410 ]411 }'412```413 414### xAI (Grok)415 416```bash417curl -X POST http://localhost:8080/api/chat/completions \418 -H "Content-Type: application/json" \419 -d '{420 "apiKey": "xai-your-xai-key",421 "model": "grok-1",422 "messages": [423 {"role": "user", "content": "Tell me a joke."}424 ]425 }'426```427 428### Perplexity (with Web Search)429 430```bash431curl -X POST http://localhost:8080/api/chat/completions \432 -H "Content-Type: application/json" \433 -d '{434 "apiKey": "pplx-your-perplexity-key",435 "model": "perplexity/sonar",436 "messages": [437 {"role": "user", "content": "What are the latest AI news?"}438 ]439 }'440```441 442> **Note**: Perplexity models (`sonar`, `sonar-pro`) include built-in web search capabilities for real-time information.443 444### AIML API (Multiple Providers)445 446```bash447curl -X POST http://localhost:8080/api/chat/completions \448 -H "Content-Type: application/json" \449 -d '{450 "apiKey": "your-aiml-api-key",451 "model": "aiml/openai/gpt-4o",452 "messages": [453 {"role": "user", "content": "Hello from AIML API!"}454 ]455 }'456```457 458> **Note**: AIML API provides access to 200+ models including GPT-4o, Gemma, Llama, Mistral, and Qwen. Get your API key at [aimlapi.com](https://aimlapi.com).459### GitHub Models460 461```bash462curl -X POST http://localhost:8080/api/chat/completions \463 -H "Content-Type: application/json" \464 -d '{465 "apiKey": "github_pat_your-token",466 "model": "github/gpt-4o",467 "messages": [468 {"role": "user", "content": "Hello from GitHub Models!"}469 ]470 }'471```472 473> **Note**: Use your GitHub Personal Access Token (PAT) as the API key. GitHub Models provides access to GPT-4o, Llama, Mistral, Phi, and other models.474 475### Ollama (Free Hosted Models) 🆓476 477Ollama is hosted on Hugging Face Spaces - **no local installation required!**478 479```bash480curl -X POST http://localhost:8080/api/chat/completions \481 -H "Content-Type: application/json" \482 -d '{483 "model": "ollama/gemma:2b",484 "messages": [485 {"role": "user", "content": "Hello from Ollama!"}486 ]487 }'488```489 490> **Note**: No API key required! Ollama is completely free to use via our hosted endpoint.491 492**Free Ollama Models:**493| Model | Size | Speed | Quality | Description |494|-------|------|-------|---------|-------------|495| `gemma:270M` | 270M | ⚡⚡⚡ | ⭐⭐⭐ | Google's lightweight Gemma model |496| `gemma:4b` | 4B | ⚡⚡ | ⭐⭐⭐⭐ | Google's Gemma model |497| `mistral:7b` | 7B | ⚡⚡ | ⭐⭐⭐⭐ | Mistral AI's powerful model |498 499**Using Local Ollama:**500To use a local Ollama instance instead, specify a custom `baseUrl`:501```bash502curl -X POST http://localhost:8080/api/chat/completions \503 -H "Content-Type: application/json" \504 -d '{505 "model": "ollama/llama2",506 "baseUrl": "http://localhost:11434",507 "messages": [508 {"role": "user", "content": "Hello from local Ollama!"}509 ]510 }'511```512 513### Hugging Face514 515```bash516curl -X POST http://localhost:8080/api/chat/completions \517 -H "Content-Type: application/json" \518 -d '{519 "apiKey": "hf_your-huggingface-token",520 "model": "huggingface/meta-llama/Llama-3.3-70B-Instruct",521 "messages": [522 {"role": "user", "content": "Hello from Hugging Face!"}523 ],524 "maxTokens": 500525 }'526```527 528### 🔍 Web Search (Real-Time Data)529 530Enable real-time web search to give LLMs access to current information:531 532```bash533curl -X POST http://localhost:8080/api/chat/completions \534 -H "Content-Type: application/json" \535 -d '{536 "apiKey": "sk-your-openai-key",537 "model": "gpt-4o",538 "search": true,539 "searchResultCount": 3,540 "messages": [541 {"role": "user", "content": "Who won the 2024 US presidential election?"}542 ]543 }'544```545 546> **How it works**: When `search: true` is set, OneLLM:547> 1. Extracts the user's question548> 2. Searches the web for relevant, current information549> 3. Injects the search results as context for the LLM550> 4. Returns a response with up-to-date data551 552**Search Parameters:**553| Parameter | Description |554|-----------|-------------|555| `search` | Enable web search (`true`/`false`) |556| `searchResultCount` | Number of results (default: 3) |557| `searchLanguage` | Language code (e.g., `en`) |558| `searchCountry` | Country code (e.g., `US`) |559 560### Streaming Example561 562```bash563curl -X POST http://localhost:8080/api/chat/completions/stream \564 -H "Content-Type: application/json" \565 -d '{566 "apiKey": "sk-your-openai-key",567 "model": "gpt-4",568 "messages": [{"role": "user", "content": "Count from 1 to 10 slowly."}]569 }'570```571 572### FreeLLM (Free - No API Key!)573 574```bash575curl -X POST http://localhost:8080/api/chat/completions \576 -H "Content-Type: application/json" \577 -d '{578 "model": "freellm/TinyLlama/TinyLlama-1.1B-Chat-v1.0",579 "messages": [580 {"role": "user", "content": "Hello! What can you help me with?"}581 ],582 "maxTokens": 256583 }'584```585 586> **Note**: FreeLLM is completely free - no API key required! It's hosted on Hugging Face Spaces with no rate limiting or billing. Perfect for testing and development.587 588**Free FreeLLM Models (No API Key Required!):**589| Model | Size | Speed | Quality | Description |590|-------|------|-------|---------|-------------|591| `TinyLlama/TinyLlama-1.1B-Chat-v1.0` | 1.1B | ⚡⚡⚡ | ⭐⭐ | Fast, lightweight chat model |592| `Qwen/Qwen2.5-0.5B-Instruct` | 0.5B | ⚡⚡⚡ | ⭐⭐ | Ultra-fast, smallest model |593| `Qwen/Qwen2.5-1.5B-Instruct` | 1.5B | ⚡⚡ | ⭐⭐⭐ | Balanced speed and quality |594 595### Streaming Example596 597```bash598curl -X POST http://localhost:8080/api/chat/completions/stream \599 -H "Content-Type: application/json" \600 -d '{601 "apiKey": "sk-your-openai-key",602 "model": "gpt-4",603 "messages": [{"role": "user", "content": "Count from 1 to 10 slowly."}]604 }'605```606 607---608 609## 💻 JavaScript/TypeScript Client610 611```typescript612// Basic request613const response = await fetch('http://localhost:8080/api/chat/completions', {614 method: 'POST',615 headers: { 'Content-Type': 'application/json' },616 body: JSON.stringify({617 apiKey: 'sk-your-api-key',618 model: 'gpt-4',619 messages: [620 { role: 'user', content: 'Hello!' }621 ]622 })623});624 625const data = await response.json();626console.log(data.content);627 628// Streaming request629const eventSource = new EventSource('http://localhost:8080/api/chat/completions/stream', {630 method: 'POST',631 headers: { 'Content-Type': 'application/json' },632 body: JSON.stringify({633 apiKey: 'sk-your-api-key',634 model: 'gpt-4',635 messages: [{ role: 'user', content: 'Write a story' }]636 })637});638 639eventSource.addEventListener('chunk', (e) => {640 const data = JSON.parse(e.data);641 process.stdout.write(data.content);642});643 644eventSource.addEventListener('complete', (e) => {645 console.log('\nDone!');646 eventSource.close();647});648```649 650---651 652## 📦 SDK Usage653 654Use OneLLM programmatically in your Java application:655 656### Basic Usage657 658```java659import io.onellm.OneLLM;660import io.onellm.core.*;661 662// Build the client with your API keys663OneLLM llm = OneLLM.builder()664 .openai("sk-your-openai-key")665 .anthropic("sk-ant-your-anthropic-key")666 .google("AIza-your-google-key")667 .build();668 669// Send a completion request670LLMResponse response = llm.complete(671 LLMRequest.builder()672 .model("gpt-4")673 .system("You are a helpful assistant.")674 .user("Explain quantum computing in simple terms.")675 .temperature(0.7)676 .maxTokens(500)677 .build()678);679 680System.out.println(response.getContent());681System.out.println("Provider: " + response.getProvider());682System.out.println("Latency: " + response.getLatencyMs() + "ms");683```684 685### Streaming686 687```java688llm.streamComplete(689 LLMRequest.builder()690 .model("claude-3-opus")691 .user("Write a story about a robot learning to cook.")692 .build(),693 new StreamHandler() {694 @Override695 public void onChunk(String chunk) {696 System.out.print(chunk);697 }698 699 @Override700 public void onComplete(LLMResponse response) {701 System.out.println("\n\nDone! Tokens: " + response.getUsage().getTotalTokens());702 }703 704 @Override705 public void onError(Throwable error) {706 System.err.println("Error: " + error.getMessage());707 }708 }709);710```711 712### Builder Methods713 714```java715OneLLM llm = OneLLM.builder()716 .openai("sk-...") // OpenAI717 .openai("sk-...", "https://custom-url.com") // Custom base URL718 .anthropic("sk-ant-...") // Anthropic719 .google("AIza...") // Google Gemini & Gemma720 .azure("api-key", "resource", "deployment") // Azure OpenAI721 .groq("gsk_...") // Groq722 .cerebras("cbs-...") // Cerebras723 .ollama() // Ollama (localhost)724 .ollama("http://custom-host:11434") // Ollama (custom)725 .openRouter("or-...") // OpenRouter726 .openRouter("or-...", "MySite", "https://...") // OpenRouter with site727 .xai("xai-...") // xAI728 .copilot("token") // GitHub Copilot729 .huggingface("hf_...") // Hugging Face730 .huggingface("hf_...", "https://endpoint") // Hugging Face (dedicated endpoint)731 .freellm() // FreeLLM (free, no API key!)732 .freellm("https://custom-freellm") // FreeLLM (custom host)733 .perplexity("pplx-...") // Perplexity AI (web search)734 .aiml("aiml-...") // AIML API (200+ models)735 .provider(myCustomProvider) // Custom provider736 .build();737```738 739---740 741## 🛡️ Error Handling742 743OneLLM provides structured error responses:744 745```json746{747 "error": true,748 "message": "API key is required",749 "timestamp": "2024-12-12T14:30:00Z",750 "type": "validation_error",751 "fields": {752 "apiKey": "API key is required"753 }754}755```756 757### Error Types758 759| Type | HTTP Status | Description |760|------|-------------|-------------|761| `validation_error` | 400 | Invalid request parameters (e.g., missing API key) |762| `model_not_found` | 404 | No provider supports the model |763| `provider_not_configured` | 503 | Provider not configured |764| `authentication_error` | 401 | Invalid API key |765| `rate_limit_error` | 429 | Rate limit exceeded |766| `server_error` | 502 | Provider server error |767| `internal_error` | 500 | Unexpected server error |768 769---770 771## 🏗️ Project Structure772 773```774onellm/775├── src/main/java/io/onellm/776│ ├── OneLLM.java # SDK entry point777│ ├── OneLLMApplication.java # Spring Boot application778│ ├── config/779│ │ └── LLMConfig.java # Spring configuration780│ ├── controller/781│ │ └── ChatController.java # REST API endpoints782│ ├── service/783│ │ └── ProviderFactory.java # Dynamic provider creation784│ ├── core/785│ │ ├── LLMProvider.java # Provider interface786│ │ ├── LLMRequest.java # Request model787│ │ ├── LLMResponse.java # Response model788│ │ ├── Message.java # Chat message789│ │ ├── StreamHandler.java # Streaming callback790│ │ └── Usage.java # Token usage791│ ├── dto/792│ │ ├── ChatCompletionRequest.java793│ │ ├── ChatCompletionResponse.java794│ │ └── MessageDTO.java795│ ├── exception/796│ │ ├── GlobalExceptionHandler.java797│ │ ├── LLMException.java798│ │ ├── ModelNotFoundException.java799│ │ └── ProviderNotConfiguredException.java800│ ├── providers/801│ │ ├── BaseProvider.java802│ │ ├── OpenAIProvider.java803│ │ ├── AnthropicProvider.java804│ │ ├── GoogleProvider.java # Gemini & Gemma models805│ │ ├── AzureOpenAIProvider.java806│ │ ├── GroqProvider.java807│ │ ├── CerebrasProvider.java808│ │ ├── OllamaProvider.java809│ │ ├── OpenRouterProvider.java810│ │ ├── XAIProvider.java811│ │ ├── CopilotProvider.java812│ │ ├── GitHubModelsProvider.java813│ │ ├── HuggingFaceProvider.java814│ │ ├── FreeLLMProvider.java815│ │ ├── LlamaCppProvider.java816│ │ ├── RWKVProvider.java817│ │ ├── PerplexityProvider.java818│ │ └── AIMLProvider.java819│ └── util/820│ └── HttpClientWrapper.java821└── pom.xml822```823 824---825 826## 🔒 Security Notes827 828- **API keys are never stored** on the server829- Each request is processed independently with the provided credentials830- Use HTTPS in production to encrypt API keys in transit831- Consider implementing rate limiting for production deployments832 833---834 835## 🤝 Contributing836 837Contributions are welcome! Please feel free to submit a Pull Request.838 8391. Fork the repository8402. Create your feature branch (`git checkout -b feature/amazing-feature`)8413. Commit your changes (`git commit -m 'Add amazing feature'`)8424. Push to the branch (`git push origin feature/amazing-feature`)8435. Open a Pull Request844 845---846 847## 📄 License848 849This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.850 851---852 853## 🙏 Acknowledgments854 855Built with ❤️ using:856- [Spring Boot](https://spring.io/projects/spring-boot)857- [Apache HttpClient 5](https://hc.apache.org/httpcomponents-client-5.3.x/)858- [Gson](https://github.com/google/gson)859 860---861 862<p align="center">863 Made with ☕ by the OneLLM Team864</p>865