> ## Documentation Index
> Fetch the complete documentation index at: https://masaic-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Development with OpenResponses API

# Local Development

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

### Prerequisites

* Java JDK 21+
* [Gradle](https://gradle.org/) (optional, as project includes Gradle Wrapper)
* [Docker](https://www.docker.com/) (optional, for containerized setup)

### Steps

1. **Clone the repository**

```bash theme={null}
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:

```bash theme={null}
./gradlew build
```

1. **Configure Environment Variables**

Create or update the `application.properties` file with necessary configuration under `src/main/resources`:

```properties theme={null}
server.port: 8080
```

Set any additional configuration required by your project.

1. **Run the server**

To start the server in development mode:

```bash theme={null}
./gradlew bootRun
```

### Docker Setup (Optional)

Build and run the application using Docker:

```bash theme={null}
./gradlew build
docker build -t openresponses .
docker run -p 8080:8080 -d openresponses
```

### Testing

Run the tests with:

```bash theme={null}
./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

```bash theme={null}
# 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:

```properties theme={null}
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](https://kotlinlang.org/docs/coding-conventions.html) 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