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/PROVENANCE.md

@@ -0,0 +1,49 @@
+## Verifying SDK build provenance with GitHub artifact attestations
+
+LaunchDarkly uses [GitHub artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages.
+
+LaunchDarkly publishes provenance about our SDK package builds using [GitHub's `actions/attest` action](https://github.com/actions/attest). These attestations are stored in GitHub's attestation API and can be verified using the [GitHub CLI](https://cli.github.com/).
+
+To verify build provenance attestations, we recommend using the [GitHub CLI `attestation verify` command](https://cli.github.com/manual/gh_attestation_verify). Example usage for verifying SDK packages is included below:
+
+<!-- x-release-please-start-version -->
+```
+# Set the version of the library to verify
+VERSION=0.1.0
+```
+<!-- x-release-please-end -->
+
+```
+# Download package from PyPI
+$ pip download --only-binary=:all: launchdarkly-ai-optimizer==${VERSION}
+
+# Verify provenance using the GitHub CLI
+$ gh attestation verify launchdarkly_ai_optimizer-${VERSION}-py3-none-any.whl --owner launchdarkly
+```
+
+Below is a sample of expected output.
+
+```
+Loaded digest sha256:... for file://launchdarkly_ai_optimizer-0.1.0-py3-none-any.whl
+Loaded 1 attestation from GitHub API
+
+The following policy criteria will be enforced:
+- Predicate type must match:................ https://slsa.dev/provenance/v1
+- Source Repository Owner URI must match:... https://github.com/launchdarkly
+- Subject Alternative Name must match regex: (?i)^https://github.com/launchdarkly/
+- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
+
+✓ Verification succeeded!
+
+The following 1 attestation matched the policy criteria
+
+- Attestation #1
+  - Build repo:..... launchdarkly/python-server-sdk-ai
+  - Build workflow:. .github/workflows/release-please.yml
+  - Signer repo:.... launchdarkly/python-server-sdk-ai
+  - Signer workflow: .github/workflows/release-please.yml
+```
+
+For more information, see [GitHub's documentation on verifying artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds#verifying-artifact-attestations-with-the-github-cli).
+
+**Note:** These instructions do not apply when building our libraries from source.

packages/optimization/README.md

@@ -1,27 +1,129 @@
 # 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(
+                threshold=1.0,
+                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(
+                threshold=1.0,
+                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 = "launchdarkly-ai-optimizer"
 version = "0.1.0"  # x-release-please-version
-description = "LaunchDarkly AI SDK optimization helpers"
+description = "LaunchDarkly AI tool — Optimization"
 authors = [{name = "LaunchDarkly", email = "dev@launchdarkly.com"}]
 license = {text = "Apache-2.0"}
 readme = "README.md"
@@ -42,7 +42,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',
+]

packages/optimization/src/ldai_optimizer/_slug_words.py

@@ -0,0 +1,74 @@
+"""Word lists for slug generation.
+
+Adjectives and nouns curated from the coolname package's word files
+(Apache-2.0 licensed).  Used by generate_slug() to produce
+``adjective-noun`` variation keys (e.g. ``blazing-lobster``).
+
+640 × 454 possible combinations from the full coolname corpus would be
+overkill; ~100 × ~100 = ~10 000 combinations is sufficient given that
+_commit_variation already appends a hex suffix on collisions.
+"""
+
+_ADJECTIVES: tuple = (
+    # appearance / texture
+    "blazing", "bouncy", "brawny", "chubby", "curvy", "elastic", "ethereal",
+    "fluffy", "foamy", "furry", "fuzzy", "glaring", "hairy", "hissing",
+    "icy", "luminous", "lumpy", "misty", "noisy", "quiet", "quirky",
+    "radiant", "roaring", "ruddy", "shaggy", "shiny", "silent", "silky",
+    "singing", "skinny", "smooth", "soft", "spicy", "spiked", "sticky",
+    "tall", "venomous", "warm", "winged", "wooden",
+    # personality / disposition
+    "adorable", "amazing", "amiable", "calm", "charming", "cute",
+    "dainty", "easygoing", "elegant", "famous", "friendly", "funny",
+    "graceful", "gracious", "happy", "hilarious", "jolly", "jovial",
+    "kind", "laughing", "lovely", "mellow", "neat", "nifty", "noble",
+    "popular", "pretty", "refreshing", "spiffy", "stylish", "sweet",
+    "tactful", "whimsical",
+    # character / trait
+    "adventurous", "ambitious", "audacious", "bold", "brave", "cheerful",
+    "curious", "daring", "determined", "eager", "enthusiastic", "faithful",
+    "fearless", "fierce", "generous", "gentle", "gleeful", "grateful",
+    "hopeful", "humble", "intrepid", "lively", "loyal", "merry",
+    "mysterious", "optimistic", "passionate", "polite", "proud", "rebel",
+    "relaxed", "reliable", "resolute", "romantic", "sincere", "spirited",
+    "stalwart", "thankful", "upbeat", "valiant", "vigorous", "vivacious",
+    "zealous", "zippy",
+    # quality / impressiveness
+    "ancient", "awesome", "brilliant", "classic", "dazzling", "fabulous",
+    "fantastic", "glorious", "legendary", "magnificent", "majestic",
+    "marvellous", "miraculous", "phenomenal", "remarkable", "splendid",
+    "wonderful",
+    # size
+    "colossal", "enormous", "gigantic", "huge", "massive", "tiny",
+    "towering",
+)
+
+_NOUNS: tuple = (
+    # common mammals
+    "badger", "bat", "bear", "beaver", "bison", "bobcat", "buffalo",
+    "capybara", "cheetah", "chipmunk", "coyote", "dingo", "dormouse",
+    "elephant", "ermine", "ferret", "fox", "gazelle", "gibbon", "gorilla",
+    "groundhog", "hamster", "hare", "hedgehog", "hippo", "horse",
+    "hyena", "jaguar", "kangaroo", "koala", "leopard", "lion", "lynx",
+    "mammoth", "marmot", "meerkat", "mongoose", "monkey", "moose",
+    "otter", "panda", "panther", "porcupine", "puma", "rabbit",
+    "raccoon", "rhinoceros", "seal", "skunk", "sloth", "squirrel",
+    "tiger", "walrus", "weasel", "whale", "wolf", "wombat",
+    "wolverine", "zebra",
+    # birds
+    "condor", "crane", "crow", "dove", "eagle", "falcon", "flamingo",
+    "hawk", "heron", "hummingbird", "kingfisher", "macaw", "magpie",
+    "ostrich", "owl", "parrot", "peacock", "pelican", "penguin",
+    "phoenix", "puffin", "raven", "robin", "sparrow", "starling",
+    "stork", "swan", "toucan", "vulture",
+    # reptiles / amphibians / fish
+    "cobra", "crocodile", "gecko", "iguana", "jellyfish", "lobster",
+    "narwhal", "octopus", "orca", "python", "rattlesnake", "salmon",
+    "seahorse", "shark", "snake", "squid", "tortoise", "turtle",
+    "viper",
+    # legendary / breed
+    "basilisk", "chimera", "chupacabra", "dragon", "griffin",
+    "kraken", "pegasus", "unicorn", "wyvern",
+    "beagle", "bulldog", "collie", "corgi", "dalmatian", "husky",
+    "labrador", "poodle", "rottweiler",
+)