# Opik Optimizer

This guide will help you get started with contributing to the Agent Optimizer SDK, our tool for optimizing prompts and improving model performance.

Before you start, please review our general [Contribution Overview](https://www.comet.com/contributing/overview) and the [Contributor License Agreement (CLA)](https://github.com/comet-ml/opik/blob/main/CLA.md).

## Project Structure

The Agent Optimizer is located in the `sdks/opik_optimizer` directory. Here's an overview of the key components:

- `src/`: Main source code
- `benchmarks/`: Benchmarking tools and results
- `notebooks/`: Example notebooks and tutorials
- `tests/`: Test files
- `docs/`: Additional documentation
- `scripts/`: Utility scripts
- `setup.py`: Package configuration
- `requirements.txt`: Python dependencies

## Setup

::::steps{titleSize="h3"}
:::step{title="Create virtual environment"}
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```
:::

:::step{title="Install dependencies"}
```bash
cd sdks/opik_optimizer
pip install -r requirements.txt
pip install -e .
```
:::

:::step{title="Run tests"}
```bash
pytest tests/
```
:::
::::

## Development Workflow

::::steps{titleSize="h3"}
:::step{title="Create branch"}
Create a new branch for your changes
:::

:::step{title="Make changes"}
Make your changes
:::

:::step{title="Add tests"}
Add tests for new functionality
:::

:::step{title="Run tests"}
Run the test suite
:::

:::step{title="Run benchmarks"}
Run benchmarks if applicable
:::

:::step{title="Submit PR"}
Submit a pull request
:::
::::

## Testing

We use pytest for testing. When adding new features:

::::steps{titleSize="h3"}
:::step{title="Write unit tests"}
Write unit tests in the `tests/` directory
:::

:::step{title="Run tests"}
Ensure all tests pass with `pytest tests/`
:::
::::

## Benchmarking

The optimizer includes benchmarking tools to measure performance improvements:

::::steps{titleSize="h3"}
:::step{title="Run benchmarks"}
`bash cd benchmarks python run_benchmark.py `
:::

:::step{title="View results"}
View results in the `benchmark_results/` directory
:::

:::step{title="Add benchmarks"}
Add new benchmarks for new optimization strategies
:::
::::

## Documentation

When adding new features or making changes:

::::steps{titleSize="h3"}
:::step{title="Update README"}
Update the README.md
:::

:::step{title="Add docstrings"}
Add docstrings for new functions and classes
:::

:::step{title="Add examples"}
Include examples in the `notebooks/` directory
:::

:::step{title="Update docs"}
Update the main documentation if necessary. See the [Documentation Guide](/guides/contributing-guides-documentation) for details.
:::
::::

## Code Style

We follow PEP 8 guidelines. Before submitting a PR:

::::steps{titleSize="h3"}
:::step{title="Run linter"}
Run `flake8` to check for style issues
:::

:::step{title="Fix issues"}
Fix any linting errors
:::

:::step{title="Check style"}
Ensure your code follows Python best practices
:::
::::

## Pull Request Process

::::steps{titleSize="h3"}
:::step{title="Fork repository"}
Fork the repository
:::

:::step{title="Create branch"}
Create your feature branch
:::

:::step{title="Make changes"}
Make your changes
:::

:::step{title="Run checks"}
Run tests and benchmarks
:::

:::step{title="Submit PR"}
Submit a pull request
:::
::::

Your PR should:

- Have a clear description of the changes
- Include tests for new functionality
- Pass all CI checks
- Follow the project's coding standards
- Include benchmark results if applicable

## Notebooks and Examples

The `notebooks/` directory contains examples and tutorials. When adding new features:

::::steps{titleSize="h3"}
:::step{title="Create notebook"}
Create a new notebook demonstrating the feature
:::

:::step{title="Add explanations"}
Include clear explanations and comments
:::

:::step{title="Show usage"}
Show both basic and advanced usage
:::

:::step{title="Add comparisons"}
Add performance comparisons if relevant
:::
::::

## Need Help?

If you need help or have questions:

- Open an issue on GitHub
- Join our [Comet Chat](https://chat.comet.com) community
- Check the existing documentation and notebooks

***

_Remember to review our [Contributor License Agreement (CLA)](https://github.com/comet-ml/opik/blob/main/CLA.md) before contributing._

## Related pages

- [Documentation](./contributing-guides-documentation.md)
- [Local Development Setup](./contributing-guides-local-development.md)
- [Python SDK](./contributing-guides-python-sdk.md)
- [TypeScript SDK](./contributing-guides-typescript-sdk.md)
- [Frontend](./contributing-guides-frontend.md)
- [Backend](./contributing-guides-backend.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.