comet-ml--opik/sdks/opik_optimizer/AGENTS.md

Repository Guidelines

Scope & Inheritance

• This file contains optimizer-specific guidance only.
• Follow ../../AGENTS.md for shared monorepo workflow, PR, and security policy.

Project Structure & Module Organization

sdks/opik_optimizer is a Python package with this main layout:

• src/opik_optimizer/: implementation modules (core optimizers, algorithms, datasets, metrics, utilities)
• src/opik_optimizer.egg-info/: packaging metadata generated by setuptools
• tests/: test suite split into tests/unit, tests/integration, and tests/e2e
• scripts/: helper scripts for benchmarks, data generation, and MCP/LLM framework examples
• docs/: long-form documentation and guides
• notebooks/: usage examples (including Colab-ready workflows)
• benchmarks/ + benchmark_results/: performance and experiment artifacts

Build, Test, and Development Commands

See also ../../AGENTS.md#build-test-and-development-commands for full monorepo commands.

• make setup-venv — create a local virtual environment at .venv
• make install-dev — install package + dev dependencies
• make test — run unit tests with coverage (excludes integration/e2e)
• make test-all — run unit, integration, and e2e tests
• make precommit — run pre-commit hooks on changed files in scope
• make build — build sdist and wheel (python setup.py sdist bdist_wheel)
• make clean — remove build artifacts and caches
• make modal-worker / make modal-coord / make modal-deploy — benchmark worker/coordinator deployment tasks

Coding Style & Naming Conventions

• Use 4-space indentation, full type hints for public APIs, and explicit names (avoid single-letter identifiers outside trivial contexts)
• Python style is enforced via Ruff and repo pre-commit hooks: trailing whitespace, import order, lint (E, F, I), and formatting
• Use snake_case for functions/variables, PascalCase for classes, and UPPER_CASE for constants
• Prefer minimal diffs; avoid large unrelated reformatting

Testing Guidelines

• Framework: pytest
• Test files: test_*.py
• Marker usage: integration for slower service-style tests, e2e for end-to-end flows
• Add unit tests for new behavior first; add integration/e2e only when cross-boundary behavior changes
• Keep API/config dependencies isolated in tests via fixtures/mocks when practical

Agent Contribution Workflow

• This module is part of the Opik monorepo; follow the shared workflow in ../../AGENTS.md#agent-contribution-workflow.
• Run relevant formatter and test commands in this file before requesting review.

Commit & Pull Request Guidelines

• Follow shared commit/PR policy in ../../AGENTS.md.
• Optimizer-specific convention: use SDK-tagged commit/PR titles when applicable and include test command summaries.

Security & Configuration Tips

• Follow shared security policy in ../../AGENTS.md.
• Optimizer-specific rule: use environment variables for provider keys and opik configure for remote-logging scenarios.