​

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:8080/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