openai gpt-3.5-turbo api client with streaming support
Provides a Go wrapper around OpenAI's GPT-3.5-turbo API that handles HTTP request construction, authentication via Bearer tokens, and response parsing. Implements both standard request-response and server-sent event (SSE) streaming patterns to consume the API's streaming endpoint, allowing real-time token-by-token consumption of model outputs without buffering the entire response.
Unique: Lightweight Go-native wrapper that avoids heavy SDK dependencies by directly implementing OpenAI's HTTP API contract, with explicit streaming support via SSE parsing rather than relying on third-party HTTP client abstractions
vs alternatives: Simpler and more portable than the official OpenAI Go SDK for basic use cases, with lower memory overhead for streaming applications, though lacking advanced features like function calling and automatic retries
chat message history management with role-based formatting
Manages a sequence of chat messages with structured role (system, user, assistant) and content fields, formatting them into the JSON array structure required by OpenAI's chat completion API. Handles message ordering, role validation, and serialization to ensure API-compliant payloads without manual JSON construction by the caller.
Unique: Provides explicit Go struct types for message roles and content rather than generic maps, enabling compile-time type checking and IDE autocomplete for chat message construction
vs alternatives: More type-safe than raw JSON construction or map-based approaches, reducing runtime errors from malformed message structures compared to untyped alternatives
request-response and streaming mode selection with unified interface
Abstracts two distinct API consumption patterns — synchronous request-response and asynchronous server-sent event streaming — behind a unified client interface. Allows callers to switch between modes (buffered vs. streamed) without changing core request construction logic, routing to either standard HTTP POST or streaming endpoint based on configuration.
Unique: Provides a single client struct that internally routes to different API endpoints and response handlers based on a streaming flag, avoiding code duplication while maintaining type safety for both modes
vs alternatives: Cleaner than maintaining separate streaming and non-streaming client classes, with less boilerplate than manually switching between different HTTP libraries for each mode
server-sent event (sse) parsing for token-by-token streaming
Implements SSE protocol parsing to consume OpenAI's streaming endpoint, extracting JSON-encoded token deltas from each event line and yielding them to the caller. Handles SSE framing (data: prefix, newline delimiters), JSON unmarshaling of delta objects, and stream termination detection via [DONE] markers without requiring external SSE libraries.
Unique: Implements SSE parsing from first principles using Go's bufio.Scanner and JSON unmarshaling rather than relying on external SSE libraries, keeping dependencies minimal and giving fine-grained control over frame handling
vs alternatives: More lightweight than generic SSE libraries and avoids dependency bloat, though less robust than battle-tested streaming libraries for handling edge cases in malformed streams
bearer token authentication with openai api key injection
Injects OpenAI API keys into HTTP request headers as Bearer tokens in the Authorization header, following OAuth 2.0 bearer token convention. Accepts API keys as configuration at client initialization and automatically applies them to all outbound requests without requiring caller-side header management.
Unique: Implements simple Bearer token injection at the HTTP middleware level, avoiding the need for caller-side header management while keeping the authentication mechanism transparent and testable
vs alternatives: Simpler than OAuth 2.0 flows for API key authentication, with less overhead than external auth libraries, though lacking advanced features like key rotation or multi-factor authentication
http error response handling with api error message extraction
Parses HTTP error responses from OpenAI's API, extracting structured error messages and status codes to provide meaningful feedback to callers. Maps HTTP status codes (401, 429, 500, etc.) to semantic error types and includes the API's error message body in the returned error, avoiding generic HTTP status code errors.
Unique: Extracts and wraps OpenAI's structured error responses into Go error types, providing semantic error classification (auth, rate limit, server error) rather than generic HTTP status codes
vs alternatives: More informative than raw HTTP status code errors, with better support for conditional error handling than generic error wrapping, though lacking automatic retry logic found in higher-level SDKs
json request/response marshaling with openai api contract compliance
Automatically marshals Go structs into JSON payloads conforming to OpenAI's chat completion API contract, and unmarshals JSON responses back into typed Go structs. Handles field naming conventions (camelCase in JSON, PascalCase in Go), optional fields, and nested structures without requiring manual JSON tag management by callers.
Unique: Uses Go's standard library json.Marshal/Unmarshal with struct tags to enforce API contract compliance at the type level, avoiding manual JSON construction while maintaining zero external dependencies
vs alternatives: More type-safe than raw JSON construction or map-based approaches, with better IDE support and compile-time checking than dynamic JSON libraries, though less flexible for handling schema variations