Optim-Agent provides an LLM-driven framework for automating hyperparameter optimization. It targets engineers and researchers needing to tune configurable systems with measurable objectives, offering semantic understanding of parameters and auditable decision-making for efficient, intelligent optimization.

How It Works

The system leverages coding LLMs (Claude Code, Codex, OpenCode) to interpret parameter meanings and historical trial data. Agents propose configurations semantically, which Optim-Agent validates against a declared parameter space before execution. This approach prioritizes efficient exploration, especially when evaluations are costly, and ensures bounded, auditable optimization trajectories.

Quick Start & Requirements

• Installation: Install via pip (pip install optim-agent) or from source (pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"). Alternatively, use the skill installer ($skill-installer install https://github.com/Optim-Agent/optim-agent) or Claude/Codex plugins.
• Prerequisites: Requires an authenticated agent CLI (claude, codex, or opencode) on the system PATH.
• Links: Example usage and benchmark reproduction commands are provided within the README.

Highlighted Details

• Semantic Proposals: Agents reason over parameter context and observed outcomes, moving beyond anonymous coordinate tuning for potentially superior results.
• Small-Budget Leverage: Highly effective for expensive evaluations where classical surrogates lack sufficient data.
• Auditable Decisions: All study configurations, outcomes, states, and agent rationales are logged in JSON or SQLite for transparency.
• Bounded Execution: Agent proposals are validated against declared parameter spaces, with invalid outputs gracefully falling back to safe sampling.
• Performance Gains: Benchmarks demonstrate significant improvements in optimization tasks (e.g., math functions, image classification, RL) when using contextual LLM agents compared to traditional methods like TPE or Random search.

Maintenance & Community

Contributions are welcomed, with a request to open issues for significant changes before submitting pull requests. Specific community channels or active maintainer details are not detailed in the provided text.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license permits broad use, including commercial applications and linking with closed-source software.

Limitations & Caveats

OpenCode-hosted models do not currently support distributed computing within Optim-Agent; users should opt for single-process workflows or alternative backends for distributed runs. Pure-Python CPU-bound objectives may perform best in separate processes with shared SQLite storage due to GIL limitations when using max_concurrency within a single process. Agent errors trigger a fallback to safe sampling and do not prune trials.