How masaic-ai-platform/open-responses works
Project Type and Purpose
• The project is a full-stack API service built in Kotlin (using Gradle as a build system) that implements the OpenAI Responses API specification.
• Its purpose is to provide a standardized interface to multiple LLM providers, enabling developers to switch between models (including OpenAI, Groq, Claude, etc.) easily. It also supports built-in tools (such as web search and GitHub search) via a consistent API.
Main Components
a. API Gateway / Endpoint Layer:
– Represent the public API endpoint (e.g., routes like POST /v1/responses, GET /v1/responses/{responseId}) that receive incoming requests.
– This layer is implemented by the Controllers (such as PlaygroundController and ResponseController) under the controller package.
b. Controller Layer:
– This part should capture how incoming HTTP requests are routed into the system.
– Controllers are responsible for request validation, error handling (ExceptionHandler), and delegating work to the service layer.
c. Service Layer:
– Illustrate components like MasaicResponseService and related services that process requests and apply business logic.
– This layer bridges the controller with client integration and external calls to the LLM providers.
d. Client / Integration Layer:
– Include the API client implementations (e.g., MasaicOpenAiResponseServiceImpl, ChatCompletionConverter, ChatCompletionChunkConverter, etc.) that handle communication with external LLM providers.
– This layer manages conversions (MasaicParameterConverter) and streaming requests (MasaicStreamingService).
e. Configuration and Utility Systems:
– Show the configuration components (LoggingConfig, MetricsConfig, WebFluxConfig, ThreadPoolConfig) which set up the reactive web framework (likely Spring WebFlux) and manage logging, threading, metrics, etc.
– Include external configuration files (e.g., application.properties, logback-spring.xml) which configure the runtime behavior of the system.
f. Tools and MCP Integration:
– Represent the dedicated modules for tool support (in the “tool” and “tool/mcp” directories).
g. Data Models and Converters:
– Include components under the model packages that define shared data structures (Models.kt, ToolModels.kt, etc.) which are used to standardize API user input and outgoing responses.
– Data conversion utilities also appear here.
h. Test Infrastructure:
Relationships & Interactions
• An API Gateway or load balancer (if applicable) routes the request to a Controller in the API layer.
• The Controller validates and forwards the request to a Service component which contains business logic.
• The Service then interacts with Client/Integration components to make calls to external LLM providers and, if needed, the Tools modules for any tool-specific logic.
• Once processing is complete, response data is formatted (with converters/formatters) and sent back through the Controller to the client.
Architectural Patterns
• The design is modular, following principles of separation of concerns often seen in MVC-like architectures.
• Use of dependency inversion: Controllers call Services, and Services depend on client adapters to interface with external systems.
• Use of configuration management with a dedicated config package and externalized configuration files.
• Recognize that Spring Boot (or Spring WebFlux) is likely used for dependency injection, lifecycle management, and reactive processing.