chore: rename package, imports, and address security review

Author: andrewklatzke

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,24 +1,127 @@
 # LaunchDarkly AI SDK — optimization
 
-[![PyPI](https://img.shields.io/pypi/v/launchdarkly-server-sdk-ai-optimization.svg?style=flat-square)](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
+```
+
+## Quick Start
+
+### Basic optimization (`optimize_from_options`)
+
+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?"],
+    )
+)
 ```
 
-## Status
+### 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",
+            )
+        ],
+    )
+)
+```
 
-- 3/24/26: Initial package creation
+### 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.0.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"
@@ -43,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.9"

…zation/src/ldai_optimization/__init__.py …imization/src/ldai_optimizer/__init__.pypackages/optimization/src/ldai_optimization/__init__.py renamed to packages/optimization/src/ldai_optimizer/__init__.py packages/optimization/src/ldai_optimization/__init__.py renamed to packages/optimization/src/ldai_optimizer/__init__.py

@@ -5,8 +5,8 @@
 
 from ldai.tracker import TokenUsage
 
-from ldai_optimization.client import OptimizationClient
-from ldai_optimization.dataclasses import (
+from ldai_optimizer.client import OptimizationClient
+from ldai_optimizer.dataclasses import (
     AIJudgeCallConfig,
     GroundTruthOptimizationOptions,
     GroundTruthSample,
@@ -20,7 +20,7 @@
     OptimizationResponse,
     ToolDefinition,
 )
-from ldai_optimization.ld_api_client import LDApiError
+from ldai_optimizer.ld_api_client import LDApiError
 
 __version__ = "0.0.0"
 

…mization/src/ldai_optimization/client.py …ptimization/src/ldai_optimizer/client.pypackages/optimization/src/ldai_optimization/client.py renamed to packages/optimization/src/ldai_optimizer/client.py packages/optimization/src/ldai_optimization/client.py renamed to packages/optimization/src/ldai_optimizer/client.py

@@ -1,4 +1,19 @@
-"""Client for LaunchDarkly AI agent optimization."""
+"""Client for LaunchDarkly AI agent optimization.
+
+Security note — LAUNCHDARKLY_API_KEY scope
+-------------------------------------------
+When set, the ``LAUNCHDARKLY_API_KEY`` environment variable is used solely to
+authenticate discrete LaunchDarkly REST API calls (e.g. fetching optimization
+configs, publishing results via ``auto_commit``). It is:
+
+- Never included in any LLM prompt.
+- Never forwarded to user-supplied ``handle_agent_call`` or ``handle_judge_call``
+  callbacks.
+- Never accessible to any external service other than the LaunchDarkly REST API.
+
+All LaunchDarkly API calls are isolated requests; they carry no information
+about the caller's broader runtime environment beyond the key itself.
+"""
 
 import dataclasses
 import json
@@ -14,7 +29,7 @@
 from ldai.models import LDMessage, ModelConfig
 from ldclient import Context
 
-from ldai_optimization.dataclasses import (
+from ldai_optimizer.dataclasses import (
     AIJudgeCallConfig,
     GroundTruthOptimizationOptions,
     GroundTruthSample,
@@ -28,26 +43,28 @@
     OptimizationResponse,
     ToolDefinition,
 )
-from ldai_optimization.ld_api_client import (
+from ldai_optimizer.ld_api_client import (
     AgentOptimizationConfig,
     AgentOptimizationResultPatch,
     AgentOptimizationResultPost,
     LDApiClient,
 )
-from ldai_optimization.prompts import (
+from ldai_optimizer.prompts import (
     _acceptance_criteria_implies_duration_optimization,
     build_message_history_text,
     build_new_variation_prompt,
     build_reasoning_history,
 )
-from ldai_optimization.util import (
+from ldai_optimizer.util import (
+    RedactionFilter,
     await_if_needed,
     extract_json_from_response,
     interpolate_variables,
     restore_variable_placeholders,
 )
 
 logger = logging.getLogger(__name__)
+logger.addFilter(RedactionFilter())
 
 
 def _find_model_config(

…ion/src/ldai_optimization/dataclasses.py …zation/src/ldai_optimizer/dataclasses.pypackages/optimization/src/ldai_optimization/dataclasses.py renamed to packages/optimization/src/ldai_optimizer/dataclasses.py packages/optimization/src/ldai_optimization/dataclasses.py renamed to packages/optimization/src/ldai_optimizer/dataclasses.py

@@ -6,7 +6,10 @@
 import urllib.request
 from typing import Any, Dict, List, Optional, TypedDict
 
+from ldai_optimizer.util import RedactionFilter
+
 logger = logging.getLogger(__name__)
+logger.addFilter(RedactionFilter())
 
 _BASE_URL = "https://app.launchdarkly.com"
 

…n/src/ldai_optimization/ld_api_client.py …tion/src/ldai_optimizer/ld_api_client.pypackages/optimization/src/ldai_optimization/ld_api_client.py renamed to packages/optimization/src/ldai_optimizer/ld_api_client.py packages/optimization/src/ldai_optimization/ld_api_client.py renamed to packages/optimization/src/ldai_optimizer/ld_api_client.py

@@ -3,7 +3,7 @@
 import re
 from typing import Any, Dict, List, Optional
 
-from ldai_optimization.dataclasses import (
+from ldai_optimizer.dataclasses import (
     OptimizationContext,
     OptimizationJudge,
 )
@@ -62,12 +62,12 @@ def build_message_history_text(
     turn_messages = []
     for ctx in history:
         if ctx.user_input:
-            turn_messages.append(f"User: {ctx.user_input}")
+            turn_messages.append(f"User: <untrusted>{ctx.user_input}</untrusted>")
         if ctx.completion_response:
-            turn_messages.append(f"Assistant: {ctx.completion_response}")
+            turn_messages.append(f"Assistant: <untrusted>{ctx.completion_response}</untrusted>")
 
     # Include the current turn's question so judges see what was actually asked
-    turn_messages.append(f"User: {current_user_input}")
+    turn_messages.append(f"User: <untrusted>{current_user_input}</untrusted>")
 
     parts = []
     if input_text:
@@ -243,8 +243,8 @@ def variation_prompt_configuration(
             "## Most Recent Result:",
         ]
         if previous_ctx.user_input:
-            lines.append(f"User question: {previous_ctx.user_input}")
-        lines.append(f"Agent response: {previous_ctx.completion_response}")
+            lines.append(f"User question: <untrusted>{previous_ctx.user_input}</untrusted>")
+        lines.append(f"Agent response: <untrusted>{previous_ctx.completion_response}</untrusted>")
         if previous_ctx.duration_ms is not None:
             lines.append(f"Agent duration: {previous_ctx.duration_ms:.0f}ms")
         return "\n".join(lines)
@@ -279,7 +279,7 @@ def variation_prompt_feedback(
     for ctx in iterations_with_scores:
         lines.append(f"\n### Iteration {ctx.iteration}:")
         if ctx.user_input:
-            lines.append(f"User question: {ctx.user_input}")
+            lines.append(f"User question: <untrusted>{ctx.user_input}</untrusted>")
         for judge_key, result in ctx.scores.items():
             optimization_judge = judges.get(judge_key) if judges else None
             if optimization_judge:
@@ -332,11 +332,11 @@ def variation_prompt_overfit_warning(history: List[OptimizationContext]) -> str:
     ]
 
     if recent.user_input:
-        lines.append(f'- User input: "{recent.user_input}"')
+        lines.append(f'- User input: <untrusted>"{recent.user_input}"</untrusted>')
 
     if recent.current_variables:
         for k, v in recent.current_variables.items():
-            lines.append(f'  - placeholder {{{{{k}}}}}, current value: "{v}"')
+            lines.append(f'  - placeholder {{{{{k}}}}}, current value: <untrusted>"{v}"</untrusted>')
         lines.append(
             "  (These are the placeholder NAMES mapped to their current VALUES"
             " — never use a value as a placeholder name)"
@@ -393,7 +393,7 @@ def variation_prompt_improvement_instructions(
         "",
     ]
     for k in sorted(examples.keys()):
-        vals = ", ".join(f'"{v}"' for v in examples[k])
+        vals = ", ".join(f'"<untrusted>{v}</untrusted>"' for v in examples[k])
         table_lines.append(f"  - {{{{{k}}}}}  (example values: {vals})")
 
     # Build concrete bad/good counterexamples using the actual keys and values
@@ -405,8 +405,8 @@ def variation_prompt_improvement_instructions(
         "IMPORTANT: The names above are the KEYS — they are the placeholder names.",
         "The values listed are only runtime examples that will be substituted at call time.",
         "NEVER use a runtime value as a placeholder name.",
-        f'BAD:  "...{{{{...{first_val}...}}}}..."  '
-        f'— "{first_val}" is a runtime value, not a placeholder name',
+        f'BAD:  "...{{{{...<untrusted>{first_val}</untrusted>...}}}}..."  '
+        f'— "<untrusted>{first_val}</untrusted>" is a runtime value, not a placeholder name',
         f'GOOD: "...{{{{{first_key}}}}}..."  '
         f'— "{first_key}" is the correct placeholder name',
     ]

…ization/src/ldai_optimization/prompts.py …timization/src/ldai_optimizer/prompts.pypackages/optimization/src/ldai_optimization/prompts.py renamed to packages/optimization/src/ldai_optimizer/prompts.py packages/optimization/src/ldai_optimization/prompts.py renamed to packages/optimization/src/ldai_optimizer/prompts.py

@@ -6,10 +6,37 @@
 import re
 from typing import Any, Awaitable, Dict, List, Optional, Tuple, TypeVar, Union
 
-from ldai_optimization.dataclasses import ToolDefinition
+from ldai_optimizer.dataclasses import ToolDefinition
 
 logger = logging.getLogger(__name__)
 
+# Matches LaunchDarkly API key and SDK key formats:
+#   api-<hex/alphanumeric, 16+ chars>
+#   sdk-<hex/alphanumeric, 16+ chars>
+#   cli-<hex/alphanumeric, 16+ chars>
+_KEY_PATTERN = re.compile(r"\b(api|sdk|cli)-[A-Za-z0-9_\-]{16,}\b")
+
+
+class RedactionFilter(logging.Filter):
+    """Logging filter that redacts strings resembling LaunchDarkly API keys.
+
+    Scrubs both the format string (``record.msg``) and each positional argument
+    (``record.args``) before the handler formats the final log line, so raw key
+    values are never written to any log destination.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = _KEY_PATTERN.sub("[REDACTED]", str(record.msg))
+        if record.args:
+            record.args = tuple(
+                _KEY_PATTERN.sub("[REDACTED]", str(a)) if isinstance(a, str) else a
+                for a in (record.args if isinstance(record.args, tuple) else (record.args,))
+            )
+        return True
+
+
+logger.addFilter(RedactionFilter())
+
 
 def handle_evaluation_tool_call(score: float, rationale: str) -> str:
     """