alpha-engine-lib 0.40.1__tar.gz → 0.41.0__tar.gz

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.40.1
+Version: 0.41.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.40.1"
+version = "0.41.0"
 description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.40.1"
+__version__ = "0.41.0"

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/src/alpha_engine_lib/anthropic_payload.py

@@ -215,3 +215,95 @@ def build_messages_payload(
 
     validate_payload(payload)
     return payload
+
+
+def build_batches_request_params(
+    *,
+    custom_id: str,
+    model: str,
+    max_tokens: int,
+    user_content: str,
+    tools: list[dict] | None = None,
+    tool_choice: dict[str, Any] | None = None,
+    system_prompt: str | None = None,
+    cache_system: bool = False,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Construct one entry of the ``messages.batches.create`` ``requests`` array.
+
+    The Anthropic Batches API takes a list of ``{"custom_id", "params"}``
+    dicts, where each ``params`` value is a kwargs dict for an underlying
+    ``messages.create()`` call. This helper builds one such entry,
+    validating the embedded payload via :func:`validate_payload`.
+
+    Differs from :func:`build_messages_payload` along three axes the
+    judge-batch path requires:
+
+    1. **Optional system prompt.** Synchronous callers nearly always have
+       a static system prompt (the lib default caches it); judge batches
+       inject the entire rubric into the user message and have no system
+       block. Pass ``system_prompt=None`` (the default) to emit no
+       system block at all.
+    2. **No cache_control by default.** The Batches API discounts every
+       call 50% before prompt caching applies; the marginal value of
+       caching is small enough that the existing judge path opts out.
+       ``cache_system=False`` is the default for this reason; pass
+       ``cache_system=True`` explicitly if the system prompt is large
+       enough to benefit.
+    3. **Explicit tool_choice.** Forced tool calls (
+       ``{"type": "tool", "name": ...}``) are the dominant Batches use
+       case (structured-output via a known schema). Pass ``tool_choice``
+       directly rather than smuggling through ``extra``.
+
+    All :func:`validate_payload` invariants run against the embedded
+    ``params`` — including the server-tool ⊥ assistant-prefill check —
+    so a future Batches caller that mixes ``web_search`` with a
+    prefill won't reach Anthropic's HTTP 400.
+
+    Args:
+        custom_id: Per-request identifier returned in the batch result.
+            Caller-owned; must be unique within a batch.
+        model: Anthropic model identifier (e.g. ``"claude-haiku-4-5"``).
+        max_tokens: ``max_tokens`` for the embedded call.
+        user_content: The user-message content (typically the full
+            rendered rubric / prompt body, since batch calls usually
+            omit the system block).
+        tools: Optional list of tool specs.
+        tool_choice: Optional tool-choice spec (e.g.
+            ``{"type": "tool", "name": "RubricEvalLLMOutput"}`` to force
+            structured output via a specific tool).
+        system_prompt: Optional system-prompt text. When ``None`` (the
+            default), no ``system`` block is emitted.
+        cache_system: When ``True``, attach ``cache_control: ephemeral``
+            to the system block. Default ``False`` because Batches
+            already discounts 50% and the marginal cache value is small.
+            Ignored when ``system_prompt is None``.
+        extra: Optional dict merged into ``params`` after construction
+            (e.g. ``metadata``, ``stop_sequences``). Validation runs
+            AFTER the merge.
+
+    Returns:
+        ``{"custom_id": custom_id, "params": <validated kwargs dict>}``,
+        ready to splat into ``messages.batches.create(requests=[...])``.
+
+    Raises :exc:`PayloadInvariantError` on a known-incompatible shape.
+    """
+    params: dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [{"role": "user", "content": user_content}],
+    }
+    if system_prompt is not None:
+        system_block: dict[str, Any] = {"type": "text", "text": system_prompt}
+        if cache_system:
+            system_block["cache_control"] = {"type": "ephemeral"}
+        params["system"] = [system_block]
+    if tools:
+        params["tools"] = list(tools)
+    if tool_choice is not None:
+        params["tool_choice"] = tool_choice
+    if extra:
+        params.update(extra)
+
+    validate_payload(params)
+    return {"custom_id": custom_id, "params": params}

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/src/alpha_engine_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.40.1
+Version: 0.41.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.40.1 → alpha_engine_lib-0.41.0}/tests/test_anthropic_payload.py

@@ -30,6 +30,7 @@ from alpha_engine_lib.anthropic_payload import (
     DEFAULT_WEB_SEARCH_MAX_USES,
     SERVER_TOOL_PREFIXES,
     PayloadInvariantError,
+    build_batches_request_params,
     build_messages_payload,
     build_web_search_tool,
     validate_payload,
@@ -271,3 +272,119 @@ def test_build_messages_payload_morning_signal_replication():
     assert payload["tools"][0]["max_uses"] == 20
     assert len(payload["messages"]) == 1  # no assistant prefill
     assert opener in payload["messages"][0]["content"]
+
+
+# ── build_batches_request_params ─────────────────────────────────────────────
+
+
+_FORCE_TOOL_CHOICE = {"type": "tool", "name": "RubricEvalLLMOutput"}
+
+
+def _custom_tool_spec():
+    """A non-server-side tool — what the judge batch uses for structured output."""
+    return {
+        "name": "RubricEvalLLMOutput",
+        "description": "Emit the rubric eval payload as structured JSON.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"score": {"type": "integer"}},
+            "required": ["score"],
+        },
+    }
+
+
+def test_build_batches_request_params_judge_shape():
+    """Replicates the alpha-engine-research judge call shape: no system
+    prompt, custom tool, forced tool_choice, no caching. Locks the
+    minimal viable Batches request envelope the judge actually ships."""
+    req = build_batches_request_params(
+        custom_id="judge-abc-123",
+        model="claude-haiku-4-5",
+        max_tokens=2048,
+        user_content="Rubric prompt body here…",
+        tools=[_custom_tool_spec()],
+        tool_choice=_FORCE_TOOL_CHOICE,
+    )
+    assert req["custom_id"] == "judge-abc-123"
+    params = req["params"]
+    assert params["model"] == "claude-haiku-4-5"
+    assert params["max_tokens"] == 2048
+    assert params["messages"] == [{"role": "user", "content": "Rubric prompt body here…"}]
+    assert params["tools"] == [_custom_tool_spec()]
+    assert params["tool_choice"] == _FORCE_TOOL_CHOICE
+    # No system prompt by default — judge inlines rubric into user content.
+    assert "system" not in params
+
+
+def test_build_batches_request_params_with_system_prompt_no_cache_default():
+    """When a system prompt IS provided, it lands as a one-element system
+    array. Caching is OFF by default for batches per the docstring rationale."""
+    req = build_batches_request_params(
+        custom_id="x",
+        model="claude-sonnet-4-6",
+        max_tokens=256,
+        user_content="u",
+        system_prompt="You are a helpful assistant.",
+    )
+    sys_blocks = req["params"]["system"]
+    assert sys_blocks == [{"type": "text", "text": "You are a helpful assistant."}]
+    assert "cache_control" not in sys_blocks[0]
+
+
+def test_build_batches_request_params_with_system_prompt_cache_opt_in():
+    """``cache_system=True`` attaches ephemeral cache_control (the
+    opt-in path for batches with large repeated system prompts)."""
+    req = build_batches_request_params(
+        custom_id="x",
+        model="claude-sonnet-4-6",
+        max_tokens=256,
+        user_content="u",
+        system_prompt="Large repeated system prompt.",
+        cache_system=True,
+    )
+    assert req["params"]["system"][0]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_build_batches_request_params_validates_server_tool_prefill_invariant():
+    """The Batches builder honors the same server-tool ⊥ assistant-prefill
+    invariant as the sync builder — caught via ``extra`` smuggling."""
+    with pytest.raises(PayloadInvariantError):
+        build_batches_request_params(
+            custom_id="x",
+            model="claude-sonnet-4-6",
+            max_tokens=256,
+            user_content="u",
+            tools=[build_web_search_tool()],
+            extra={
+                "messages": [
+                    {"role": "user", "content": "hi"},
+                    {"role": "assistant", "content": "Y"},
+                ]
+            },
+        )
+
+
+def test_build_batches_request_params_no_system_no_tools_minimal():
+    """Minimal shape: only model + max_tokens + messages. Pins that
+    optional fields don't leak ``None`` keys into the payload."""
+    req = build_batches_request_params(
+        custom_id="x",
+        model="claude-haiku-4-5",
+        max_tokens=64,
+        user_content="ping",
+    )
+    params = req["params"]
+    assert set(params.keys()) == {"model", "max_tokens", "messages"}
+
+
+def test_build_batches_request_params_extra_merges_into_params():
+    """``extra`` keys merge into ``params`` (e.g. metadata for batch-side
+    observability). Validation still runs."""
+    req = build_batches_request_params(
+        custom_id="x",
+        model="claude-haiku-4-5",
+        max_tokens=64,
+        user_content="u",
+        extra={"metadata": {"user_id": "judge-v3"}},
+    )
+    assert req["params"]["metadata"] == {"user_id": "judge-v3"}