​
Local Development

Follow these instructions to set up the project locally for development:

​
Prerequisites

  • Java JDK 21+
  • Gradle (optional, as project includes Gradle Wrapper)
  • Docker (optional, for containerized setup)

​
Steps

  1. Clone the repository
git clone https://github.com/masaic-ai-platform/open-responses.git
cd open-responses
  1. Build the project
Use the Gradle Wrapper included in the project: 
./gradlew build
  1. Configure Environment Variables
Create or update the application.properties file with necessary configuration under src/main/resources: 
server.port: 8080
Set any additional configuration required by your project.
  1. Run the server
To start the server in development mode: 
./gradlew bootRun

​
Docker Setup (Optional)

Build and run the application using Docker: 
./gradlew build
docker build -t openresponses .
docker run -p 8080:8080 -d openresponses

​
Testing

Run the tests with: 
./gradlew test

​
Key Components

​
API Layer

The API layer is responsible for handling HTTP requests and responses. Key files include:
  • ResponsesController.kt: Handles requests to the /v1/responses endpoint
  • ResponsesInputItemsController.kt: Manages input items for responses

​
Service Layer

The service layer contains the business logic for the application:
  • ModelServiceClient.kt: Interface for model provider-specific implementations
  • ResponsesService.kt: Core service for handling responses
  • TelemetryService.kt: Service for collecting telemetry data

​
Storage Layer

The storage layer manages data persistence:
  • ResponseStore.kt: Interface for response storage
  • InMemoryResponseStore.kt: In-memory implementation
  • MongoDBResponseStore.kt: MongoDB implementation

​
Tool Integration

The tools package contains implementations for built-in tools:
  • BraveWebSearchTool.kt: Implementation of web search
  • GitHubTools.kt: GitHub integration tools
  • ClaudeThinkTool.kt: Claude’s think tool integration

​
Configuration

​
Application Properties

The main configuration files are:
  • application.properties: Default application configuration
  • application-otel.properties: OpenTelemetry configuration

​
API Testing

​
Using cURL

# Test the API with a simple request
curl --location 'http://localhost:6644/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": "openai@gpt-4o",
    "input": [
        {
            "role": "user",
            "content": "Hello, how are you?"
        }
    ]
}'

​
Debugging

​
Logs

By default, logs are written to the console. You can increase the log level by setting: 
logging.level.ai.masaic=DEBUG

​
Metrics and Health

The application exposes several endpoints for monitoring:
  • /actuator/health: Health check endpoint
  • /actuator/metrics: Metrics endpoint
  • /actuator/info: Application info

​
Contributing

We welcome contributions to OpenResponses! To contribute:
  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Add tests for your changes
  5. Run the tests (./gradlew test)
  6. Commit your changes (git commit -am 'Add my feature')
  7. Push to the branch (git push origin feature/my-feature)
  8. Create a new Pull Request
Please follow the Kotlin coding conventions for your code.

​
Troubleshooting

​
Common Issues

​
API Key Issues

If you’re having issues with API keys, ensure that:
  • The API key is correctly set in the Authorization header
  • The model provider header is correctly set
  • The API key has the necessary permissions

​
MongoDB Connection Issues

If using MongoDB and experiencing connection issues:
  • Verify the MongoDB URI is correct
  • Ensure MongoDB is running and accessible
  • Check that the database name is correct