feat: Implement optimization code paths and functionality for initial release

packages/optimization/Makefile

@@ -19,9 +19,9 @@ test: install
 .PHONY: lint
 lint: #! Run type analysis and linting checks
 lint: install
-	uv run mypy src/ldai_optimization
-	uv run isort --check --atomic src/ldai_optimization
-	uv run pycodestyle src/ldai_optimization
+	uv run mypy src/ldai_optimizer
+	uv run isort --check --atomic src/ldai_optimizer
+	uv run pycodestyle src/ldai_optimizer
 
 .PHONY: build
 build: #! Build distribution files

packages/optimization/README.md

@@ -1,27 +1,127 @@
 # LaunchDarkly AI SDK — optimization
 
-[![Actions Status](https://github.com/launchdarkly/python-server-sdk-ai/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/launchdarkly/python-server-sdk-ai/actions/workflows/ci.yml)
-
-[![PyPI](https://img.shields.io/pypi/v/launchdarkly-server-sdk-ai-optimization.svg?maxAge=2592000)](https://pypi.org/project/launchdarkly-server-sdk-ai-optimization/)
-[![PyPI](https://img.shields.io/pypi/pyversions/launchdarkly-server-sdk-ai-optimization.svg)](https://pypi.org/project/launchdarkly-server-sdk-ai-optimization/)
+[![PyPI](https://img.shields.io/pypi/v/ldai_optimizer.svg?style=flat-square)](https://pypi.org/project/ldai_optimizer/)
 
 > [!CAUTION]
 > This package is in pre-release and not subject to backwards compatibility
 > guarantees. The API may change based on feedback.
 >
 > Pin to a specific minor version and review the [changelog](CHANGELOG.md) before upgrading.
 
-This package will provide helpers to run selected tools against the [LaunchDarkly API](https://apidocs.launchdarkly.com/) from SDK-based workflows. The public surface is not yet finalized; see [CHANGELOG.md](CHANGELOG.md) for updates.
+This package provides helpers for running iterative AI prompt optimization workflows from within LaunchDarkly SDK-based applications. It drives the optimization loop — generating candidate variations, evaluating them with judges, and optionally committing winners back to LaunchDarkly — while delegating all LLM calls to your own handler functions.
+
+## Requirements
+
+- Python `>=3.9`
+- A configured [LaunchDarkly server-side SDK](https://docs.launchdarkly.com/sdk/server-side/python) client
+- The [LaunchDarkly AI package](https://pypi.org/project/launchdarkly-server-sdk-ai/) (`launchdarkly-server-sdk-ai>=0.16.0`) — pulled in automatically as a dependency
+- **`LAUNCHDARKLY_API_KEY` environment variable** — required only when using `auto_commit=True` or `optimize_from_config`. Not needed for basic `optimize_from_options` runs without auto-commit.
+
+> [!NOTE]
+> **`LAUNCHDARKLY_API_KEY` is used exclusively for discrete LaunchDarkly REST API calls** (fetching configs, publishing results). It is never included in any LLM prompt and is never forwarded to your handler callbacks. All API calls made by this package are isolated; they have no access to your runtime environment beyond the key you explicitly provide via the environment variable.
 
 ## Installation
 
 ```bash
-pip install launchdarkly-server-sdk-ai-optimization
+pip install ldai_optimizer
 ```
 
-## Status
+## Quick Start
+
+### Basic optimization (`optimize_from_options`)
 
-- 3/24/26: Initial package creation
+No `LAUNCHDARKLY_API_KEY` required unless `auto_commit=True`.
+
+```python
+import ldclient
+from ldai import LDAIClient
+from ldai_optimizer import (
+    OptimizationClient,
+    OptimizationJudge,
+    OptimizationOptions,
+    OptimizationResponse,
+    LLMCallConfig,
+    LLMCallContext,
+)
+
+ldclient.set_config(ldclient.Config("sdk-your-sdk-key"))
+ld = LDAIClient(ldclient.get())
+client = OptimizationClient(ld)
+
+def handle_llm_call(
+    run_id: str,
+    config: LLMCallConfig,
+    context: LLMCallContext,
+    is_evaluation: bool,
+) -> OptimizationResponse:
+    # config.model, config.instructions, config.key are available
+    # context.user_input, context.current_variables are available
+    response = your_llm_client.chat(
+        model=config.model.name if config.model else "gpt-4o",
+        system=config.instructions,
+        user=context.user_input or "",
+    )
+    return OptimizationResponse(completion=response.text)
+
+result = await client.optimize_from_options(
+    OptimizationOptions(
+        agent_key="my-agent",
+        handle_agent_call=handle_llm_call,
+        judge_model="gpt-4o-mini",
+        judges={
+            "quality": OptimizationJudge(
+                acceptance_statement="The response is accurate and concise."
+            )
+        },
+        model_choices=["gpt-4o", "gpt-4o-mini"],
+        variable_choices=[{"user_id": "user-123"}],
+        user_input_choices=["What is my account balance?"],
+    )
+)
+```
+
+### Ground truth optimization
+
+```python
+from ldai_optimizer import GroundTruthOptimizationOptions, GroundTruthSample
+
+result = await client.optimize_from_options(
+    GroundTruthOptimizationOptions(
+        agent_key="my-agent",
+        handle_agent_call=handle_llm_call,
+        judge_model="gpt-4o-mini",
+        judges={
+            "accuracy": OptimizationJudge(
+                acceptance_statement="The response matches the expected answer."
+            )
+        },
+        model_choices=["gpt-4o", "gpt-4o-mini"],
+        ground_truth_responses=[
+            GroundTruthSample(
+                user_input="What is 2+2?",
+                ground_truth_response="4",
+            )
+        ],
+    )
+)
+```
+
+### Config-driven optimization (`optimize_from_config`)
+
+Requires `LAUNCHDARKLY_API_KEY`.
+
+```python
+from ldai_optimizer import OptimizationFromConfigOptions
+
+result = await client.optimize_from_config(
+    OptimizationFromConfigOptions(
+        config_key="my-optimization-config",
+        project_key="my-project",
+        handle_agent_call=handle_llm_call,
+        auto_commit=True,
+    )
+)
+```
 
 ## License
 

packages/optimization/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
-name = "launchdarkly-server-sdk-ai-optimization"
+name = "ldai_optimizer"
 version = "0.1.0"  # x-release-please-version
-description = "LaunchDarkly AI SDK optimization helpers"
+description = "LaunchDarkly AI tool — optimizer"
 authors = [{name = "LaunchDarkly", email = "dev@launchdarkly.com"}]
 license = {text = "Apache-2.0"}
 readme = "README.md"
@@ -21,6 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "launchdarkly-server-sdk-ai>=0.16.0",
+    "coolname>=2.0.0",
 ]
 
 [project.urls]
@@ -42,7 +43,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/ldai_optimization"]
+packages = ["src/ldai_optimizer"]
 
 [tool.mypy]
 python_version = "3.10"

packages/optimization/src/ldai_optimizer/__init__.py

@@ -0,0 +1,44 @@
+"""LaunchDarkly AI SDK — optimization.
+
+This package will provide helpers to run selected tools against the LaunchDarkly API from SDK-based workflows.
+"""
+
+from ldai.tracker import TokenUsage
+
+from ldai_optimizer.client import OptimizationClient
+from ldai_optimizer.dataclasses import (
+    AIJudgeCallConfig,
+    GroundTruthOptimizationOptions,
+    GroundTruthSample,
+    LLMCallConfig,
+    LLMCallContext,
+    OptimizationContext,
+    OptimizationFromConfigOptions,
+    OptimizationJudge,
+    OptimizationJudgeContext,
+    OptimizationOptions,
+    OptimizationResponse,
+    ToolDefinition,
+)
+from ldai_optimizer.ld_api_client import LDApiError
+
+__version__ = "0.0.0"
+
+__all__ = [
+    '__version__',
+    'AIJudgeCallConfig',
+    'GroundTruthOptimizationOptions',
+    'GroundTruthSample',
+    'LDApiError',
+    'LLMCallConfig',
+    'LLMCallContext',
+    'OptimizationClient',
+    'OptimizationContext',
+    'OptimizationFromConfigOptions',
+    'OptimizationJudge',
+    'OptimizationJudgeContext',
+    'OptimizationOptions',
+    'OptimizationResponse',
+    'TokenUsage',
+    'ToolDefinition',
+]