diff --git a/README.md b/README.md index f4a31e1..2ca9ee9 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ -# qorona +# Qorona -Standalone, zero-dependency OpenAI-compatible proxy gateway in Go for the **Qwen 3.8 Max** model (`Qwen/Qwen3.8-Max`) hosted on Hugging Face Spaces (`harpreetsahota-qwen38-max-openlogo-demo.hf.space`). +Free, standalone, zero-dependency OpenAI-compatible proxy gateway in Go for the **Qwen 3.8 Max** model (`Qwen/Qwen3.8-Max`) hosted on Hugging Face Spaces. -## Overview +## About -`qorona` reverse-engineers the FiftyOne plugin backend operator interface of the Hugging Face space and transforms it into a standard, production-ready OpenAI API endpoint (`/v1/chat/completions` and `/v1/models`). +Qorona reverse-engineers the FiftyOne plugin backend operator interface of the Hugging Face space and transforms it into a standard, production-ready OpenAI API endpoint (`/v1/chat/completions` and `/v1/models`). + +The name comes from Qwen + the default image of Corona Extra beer bottles that the target demo space passes to the model unless any other file is specified. ### Features -- **OpenAI Standard Compatibility**: Full drop-in replacement for OpenAI API clients (Curl, Python `openai`, LangChain, LiteLLM, Open-WebUI). +- **OpenAI Standard Compatibility**: Full drop-in replacement for OpenAI API clients (Curl, Python `openai`, LangChain, Open-WebUI). - **Zero External Dependencies**: Pure standard library Go implementation (`net/http`, `encoding/json`, `crypto/rand`, `time`). - **Fully Headless & Browserless**: No Chromium, Playwright, or X11 required. Runs directly on bare servers, containers, or embedded systems. - **Live Streaming SSE & Reasoning**: Streams real-time tokens with separation of reasoning content (`delta.reasoning_content`) and message content (`delta.content`). @@ -16,9 +18,7 @@ Standalone, zero-dependency OpenAI-compatible proxy gateway in Go for the **Qwen - **Session Lifecycle Management**: Thread-safe automatic session creation (`/__session/start`), periodic background heartbeats (`/__session/heartbeat`), and auto-reconnect recovery. - **Fibonacci Backoff Retry**: Resilient against network hiccups and transient timeouts. ---- - -## Architecture & Upstream Protocol +## Architecture & upstream protocol ``` +---------------------------+ OpenAI HTTP / SSE +------------------------+ @@ -36,16 +36,14 @@ Standalone, zero-dependency OpenAI-compatible proxy gateway in Go for the **Qwen +------------------------+ ``` -### Upstream Flow: +### Upstream flow 1. `POST /__session/start` -> Allocates an ephemeral session token `X-FiftyOne-Session` and dataset clone. 2. `POST /operators/execute` -> Dispatches the `@harpreetsahota/qwen38-max/qwen38_chat` operator with method `"ask"`. 3. Polling Loops: - `get_thinking_chunk`: Extracts newly generated reasoning tokens in real-time. - `get_stream_chunk`: Extracts newly generated message content tokens in real-time. ---- - -## Build & Run +## Build and Run ### Build ```bash @@ -59,7 +57,7 @@ Binary is output to `bin/qorona`. ./bin/qorona -port 8080 ``` -### CLI Flags +### CLI flags | Flag | Default | Description | |------|---------|-------------| @@ -71,16 +69,14 @@ Binary is output to `bin/qorona`. | `-user-agent` / `-ua` | `""` | Custom User-Agent header | | `-hf-token` | `""` | Optional Hugging Face token | ---- +## API usage examples -## API Usage Examples - -### 1. List Models +### 1. List models ```bash curl http://localhost:8080/v1/models ``` -### 2. Non-Streaming Chat Completion +### 2. Non-streaming chat completion ```bash curl -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ @@ -94,7 +90,7 @@ curl -X POST http://localhost:8080/v1/chat/completions \ }' ``` -### 3. Streaming Chat Completion with Reasoning +### 3. Streaming chat completion with reasoning ```bash curl -N -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ @@ -109,7 +105,7 @@ curl -N -X POST http://localhost:8080/v1/chat/completions \ }' ``` -### 4. Function / Tool Calling +### 4. Function / tool calling ```bash curl -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ @@ -138,7 +134,7 @@ curl -X POST http://localhost:8080/v1/chat/completions \ }' ``` -### 5. Python OpenAI Client Example +### 5. Python OpenAI client example ```python from openai import OpenAI @@ -164,8 +160,6 @@ for chunk in response: print() ``` ---- - ## Testing Run unit tests: @@ -178,8 +172,6 @@ Run end-to-end integration tests: ./xtest.sh 8080 ``` ---- +## Credits -## License - -Public Domain / Unlicense +Created by Luxferre in 2026, released into the public domain with no warranties. diff --git a/go.mod b/go.mod index 5b32a53..7e58bc4 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,3 @@ -module qorona +module code.luxferre.top/luxferre/qorona go 1.22 diff --git a/main.go b/main.go index ea091d8..c164366 100644 --- a/main.go +++ b/main.go @@ -1,4 +1,4 @@ -// qorona: Standalone OpenAI-compatible gateway for Qwen 3.8 Max HuggingFace Spaces +// Qorona: Standalone OpenAI-compatible gateway for Qwen 3.8 Max HuggingFace Spaces // Created by Luxferre in 2026, released into the public domain package main diff --git a/xtest.sh b/xtest.sh deleted file mode 100755 index dc02a52..0000000 --- a/xtest.sh +++ /dev/null @@ -1,67 +0,0 @@ -#!/usr/bin/env bash -set -e - -PORT=${1:-18080} -BASE_URL="http://localhost:${PORT}" - -echo "=== 1. Testing Models Endpoint ===" -curl -s "${BASE_URL}/v1/models" | jq . - -echo "" -echo "=== 2. Testing Non-Streaming Chat Completion ===" -curl -s -X POST "${BASE_URL}/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qorona", - "messages": [ - {"role": "user", "content": "What is the capital of Italy? Answer in 1 word."} - ], - "reasoning_effort": "none", - "max_tokens": 50 - }' | jq . - -echo "" -echo "=== 3. Testing Streaming SSE Completion (with reasoning) ===" -curl -N -s -X POST "${BASE_URL}/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qorona", - "messages": [ - {"role": "user", "content": "Calculate 25 * 25 and explain briefly in one sentence."} - ], - "stream": true, - "reasoning_effort": "medium", - "max_tokens": 150 - }' - -echo "" -echo "=== 4. Testing Function/Tool Calling ===" -curl -s -X POST "${BASE_URL}/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qorona", - "messages": [ - {"role": "user", "content": "What is the weather in Berlin?"} - ], - "tools": [ - { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get current weather for location", - "parameters": { - "type": "object", - "properties": { - "location": {"type": "string"} - }, - "required": ["location"] - } - } - } - ], - "reasoning_effort": "none", - "max_tokens": 200 - }' | jq . - -echo "" -echo "=== All qorona integration tests finished successfully! ==="