agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/harness/backends/vertex_gemini.py

@@ -0,0 +1,457 @@
+"""A harness backend that runs stages on Gemini through Vertex AI, on Google's ADK.
+
+The Agent Development Kit is Google's counterpart to the Claude Agent SDK: it owns the agentic
+loop, executes tools, and holds session history, the way this harness expects a backend to. We
+adapt at the same seam as the Claude backend and nothing more: a ``ToolSpec`` becomes an ADK
+tool through ADK's own extension point (``BaseTool`` with an explicit declaration), and ADK's
+event stream is translated into the neutral reply vocabulary. The loop itself is not ours.
+
+The Gemini 3.x models this exists for are served from the ``global`` endpoint only, which is
+why ``ALK_VERTEX_LOCATION`` defaults to ``global`` rather than to a region. Regional Vertex
+deployments of older models can point it elsewhere.
+
+Read, Glob and Grep come from files.py when a stage grants them. AskUserQuestion is not
+implemented here yet: unattended runs never use it, and an attended run on this backend simply
+proceeds without the option, which is said out loud in the session rather than hidden.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from datetime import date
+from typing import Any, AsyncIterator
+
+from .base import (
+    FILE_TOOLS,
+    Call,
+    ModelReply,
+    Say,
+    SessionOpened,
+    SessionSpec,
+    StageDone,
+    ToolReturned,
+    ToolSpec,
+    qualified,
+)
+from .files import file_tools
+
+DEFAULT_MODEL = "gemini-3.7-flash"
+
+_TERMINAL_SAVE_TOOLS = frozenset(
+    {
+        "mcp__world__save_world",
+        "mcp__provision__save_environment",
+        "mcp__scenarios__save_scenarios",
+        # Source-data review is another persisted authoring boundary.  Its handler only
+        # succeeds after every scenario was reviewed and at least one executable invariant
+        # was declared.  Letting ADK take another turn after that success can burn the entire
+        # call budget and turn a completed review into a spurious validation failure.
+        "mcp__source_data__finish_review",
+    }
+)
+
+# Vertex list pricing per 1M tokens: (input, output, the day this pair was last checked against
+# the platform's litellm model table). An unknown or stale model reports no cost rather than a
+# wrong one, and shows up in `unpriced_turns`.
+PRICES_PER_MILLION = {
+    "gemini-3.8-flash": (0.75, 3.75, "2026-12-31"),
+    "gemini-3.7-flash": (0.75, 3.75, "2026-12-31"),
+    "gemini-3.6-flash": (0.75, 3.75, "2026-12-31"),
+    "gemini-3.5-transcribe-preview": (2.5, 12, "2026-12-31"),
+    "gemini-3.5-transcribe-live-preview": (3.5, 21, "2026-12-31"),
+    "gemini-3.5-flash-lite": (0.3, 2.5, "2026-12-31"),
+    "gemini-3.5-flash": (1.5, 9, "2026-12-31"),
+    "gemini-3.1-pro-preview-customtools": (2, 12, "2026-12-31"),
+    "gemini-3.1-pro-preview": (2, 12, "2026-12-31"),
+    "gemini-3.1-flash-lite-preview": (0.25, 1.5, "2026-12-31"),
+    "gemini-3.1-flash-lite-image": (0.25, 1.5, "2026-12-31"),
+    "gemini-3.1-flash-lite": (0.25, 1.5, "2026-12-31"),
+    "gemini-3.1-flash-image-preview": (0.5, 3, "2026-12-31"),
+    "gemini-3.1-flash-image": (0.5, 3, "2026-12-31"),
+    "gemini-3-pro-preview": (2, 12, "2026-12-31"),
+    "gemini-3-pro-image-preview": (2, 12, "2026-12-31"),
+    "gemini-3-pro-image": (2, 12, "2026-12-31"),
+    "gemini-3-flash-preview": (0.5, 3, "2026-12-31"),
+}
+
+_PYTHON_TYPES = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+# The keys Vertex's Schema type accepts. JSON Schema carries more; anything else is dropped
+# rather than passed through, because an unknown key fails declaration validation and takes
+# the whole stage down before its first turn.
+_SCHEMA_KEYS = (
+    "description",
+    "enum",
+    "format",
+    "items",
+    "maximum",
+    "maxItems",
+    "minimum",
+    "minItems",
+    "nullable",
+    "pattern",
+    "properties",
+    "required",
+    "type",
+    "anyOf",
+)
+
+
+def _gemini_schema(schema: Any) -> dict[str, Any]:
+    """A JSON Schema fragment as Vertex's Schema dialect.
+
+    The real difference is nullability: JSON Schema says ``"type": ["string", "null"]``,
+    Vertex says ``"type": "string", "nullable": true``. Everything Vertex does not know is
+    dropped, recursively, so a tool schema written for the loosest backend still declares.
+    """
+    if not isinstance(schema, dict):
+        return {"type": "string"}
+    cleaned: dict[str, Any] = {}
+    for key, value in schema.items():
+        if key not in _SCHEMA_KEYS:
+            continue
+        if key == "type" and isinstance(value, list):
+            bare = [entry for entry in value if entry != "null"]
+            cleaned["type"] = bare[0] if bare else "string"
+            if "null" in value:
+                cleaned["nullable"] = True
+        elif key == "properties" and isinstance(value, dict):
+            cleaned["properties"] = {
+                name: _gemini_schema(inner) for name, inner in value.items()
+            }
+        elif key == "items":
+            cleaned["items"] = _gemini_schema(value)
+        elif key == "anyOf" and isinstance(value, list):
+            cleaned["anyOf"] = [_gemini_schema(inner) for inner in value]
+        elif key == "enum" and isinstance(value, list):
+            # Vertex enums are strings; None inside one is JSON Schema's way of saying
+            # nullable, and everything else is stringified the way the model will echo it.
+            cleaned["enum"] = [str(entry) for entry in value if entry is not None]
+            if None in value:
+                cleaned["nullable"] = True
+        else:
+            cleaned[key] = value
+    # Vertex refuses an array that does not say what it holds. JSON Schema treats items as
+    # optional, and most such arrays here carry row-shaped dicts, so an open object is the
+    # faithful default.
+    if cleaned.get("type") == "array" and "items" not in cleaned:
+        cleaned["items"] = {"type": "object"}
+    return cleaned
+
+
+def _json_schema(schema: Any) -> dict[str, Any]:
+    """The tool's schema as Vertex-safe schema, whichever shorthand it was declared in."""
+    if isinstance(schema, dict) and (
+        "properties" in schema or schema.get("type") == "object"
+    ):
+        return _gemini_schema(schema)
+    if isinstance(schema, dict):
+        return {
+            "type": "object",
+            "properties": {
+                name: (
+                    {"type": "array", "items": {"type": "object"}}
+                    if kind is list
+                    else {"type": _PYTHON_TYPES.get(kind, "string")}
+                )
+                for name, kind in schema.items()
+            },
+            "required": list(schema),
+        }
+    return {"type": "object", "properties": {}}
+
+
+def _project() -> str:
+    named = os.environ.get("GOOGLE_CLOUD_PROJECT")
+    if named:
+        return named
+    credentials = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
+    if credentials:
+        try:
+            with open(credentials, encoding="utf-8") as handle:
+                found = json.load(handle).get("project_id", "")
+            if found:
+                return found
+        except (OSError, ValueError):
+            pass
+    # Application Default Credentials already carry a project on a machine that has run
+    # ``gcloud auth application-default login`` or that runs on Google infrastructure. Asking
+    # for it again as an environment variable is a setting the operator does not need to know.
+    try:
+        import google.auth
+
+        _, discovered = google.auth.default()
+        if discovered:
+            return str(discovered)
+    except Exception:  # noqa: BLE001 - fall through to the explicit instruction below
+        pass
+    raise RuntimeError(
+        "no GCP project named; run 'gcloud auth application-default login', or set "
+        "GOOGLE_CLOUD_PROJECT, or point GOOGLE_APPLICATION_CREDENTIALS at a service-account file"
+    )
+
+
+def _location() -> str:
+    return os.environ.get("ALK_VERTEX_LOCATION", "global").strip() or "global"
+
+
+def _flattened(result: Any) -> str:
+    content = result.get("content") if isinstance(result, dict) else None
+    if isinstance(content, list):
+        return "\n".join(
+            part.get("text", "") for part in content if isinstance(part, dict)
+        )
+    return content if isinstance(content, str) else str(result)
+
+
+def _successful_terminal_save(name: str, response: Any) -> bool:
+    """Whether a tool response proves this authoring stage has persisted its final output.
+
+    Save tools deliberately reject incomplete work with ``is_error`` so the model can repair and
+    retry. Once one succeeds, another model turn can only rewrite already-valid output or burn the
+    stage budget; the persisted artifact is the stage's actual completion boundary.
+    """
+    return bool(
+        name in _TERMINAL_SAVE_TOOLS
+        and isinstance(response, dict)
+        and not response.get("is_error")
+    )
+
+
+def _spec_tool(name: str, spec: ToolSpec) -> Any:
+    """A ToolSpec as an ADK tool, through ADK's own extension point.
+
+    ``BaseTool`` with an explicit ``_get_declaration`` is how ADK says a tool whose contract
+    is defined elsewhere should be wrapped; the handler runs unchanged and ADK owns calling
+    it, retrying the turn, and feeding the result back.
+    """
+    from google.adk.tools import BaseTool
+    from google.genai import types
+
+    class SpecTool(BaseTool):
+        def __init__(self) -> None:
+            super().__init__(name=name, description=spec.description)
+
+        def _get_declaration(self) -> Any:
+            return types.FunctionDeclaration(
+                name=name,
+                description=spec.description,
+                parameters=_json_schema(spec.input_schema),
+            )
+
+        async def run_async(self, *, args: dict[str, Any], tool_context: Any) -> Any:
+            return await spec.handler(args)
+
+    return SpecTool()
+
+
+class VertexGeminiSession:
+    """One ADK-run conversation with Gemini; ADK holds the history across turns."""
+
+    def __init__(self, spec: SessionSpec, model: str) -> None:
+        self._spec = spec
+        self._model = model
+        self._runner: Any = None
+        self._pending: str | None = None
+        self.session_id = f"gemini-{uuid.uuid4().hex[:12]}"
+
+    def _tools(self) -> list[Any]:
+        # ASK_TOOL is deliberately absent: unattended runs never call it, and declaring a tool
+        # this backend cannot answer would cost the model a turn finding that out.
+        offered: list[Any] = []
+        wanted = {name for name in self._spec.builtins if name in FILE_TOOLS}
+        offered.extend(
+            _spec_tool(spec.name, spec)
+            for spec in file_tools(self._spec.cwd)
+            if spec.name in wanted
+        )
+        for server_name, server in self._spec.servers.items():
+            offered.extend(
+                _spec_tool(qualified(server_name, spec.name), spec)
+                for spec in server.tools
+            )
+        return offered
+
+    async def start(self) -> None:
+        from google.adk.agents import LlmAgent
+        from google.adk.runners import Runner
+        from google.adk.sessions import InMemorySessionService
+        from google.genai import types
+
+        # ADK builds its Vertex client from the environment, the same way the Claude backend
+        # passes provider env through its options.
+        os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
+        os.environ["GOOGLE_CLOUD_PROJECT"] = _project()
+        os.environ["GOOGLE_CLOUD_LOCATION"] = _location()
+        # static_instruction, not instruction: the skills are full of literal JSON braces,
+        # and ADK templates {placeholders} in `instruction` from session state. Static
+        # content is sent verbatim and is what ADK context-caches.
+        agent = LlmAgent(
+            name=self.session_id.replace("-", "_"),
+            model=self._model,
+            static_instruction=types.Content(
+                role="user", parts=[types.Part(text=self._spec.system_prompt)]
+            ),
+            tools=self._tools(),
+        )
+        sessions = InMemorySessionService()
+        await sessions.create_session(
+            app_name="alk-harness", user_id="stage", session_id=self.session_id
+        )
+        self._runner = Runner(
+            agent=agent, app_name="alk-harness", session_service=sessions
+        )
+
+    async def stop(self) -> None:
+        if self._runner is not None:
+            await self._runner.close()
+            self._runner = None
+
+    async def send(self, message: str) -> None:
+        if self._runner is None:
+            raise RuntimeError("session is not open")
+        self._pending = message
+
+    async def replies(self) -> AsyncIterator[Any]:
+        from google.adk.agents.run_config import RunConfig
+        from google.genai import types
+
+        if self._runner is None or self._pending is None:
+            raise RuntimeError("nothing to reply to; send a message first")
+        yield SessionOpened(session_id=self.session_id)
+        message = types.Content(role="user", parts=[types.Part(text=self._pending)])
+        self._pending = None
+        turns = 0
+        tokens_in = 0
+        tokens_out = 0
+        tokens_cached = 0
+        settled = False
+        terminal_save_succeeded = False
+        try:
+            async for event in self._runner.run_async(
+                user_id="stage",
+                session_id=self.session_id,
+                new_message=message,
+                run_config=RunConfig(max_llm_calls=max(self._spec.max_turns, 1)),
+            ):
+                usage = getattr(event, "usage_metadata", None)
+                if usage is not None:
+                    tokens_in += usage.prompt_token_count or 0
+                    tokens_out += usage.candidates_token_count or 0
+                    tokens_cached += getattr(usage, "cached_content_token_count", 0) or 0
+                parts: list[Any] = []
+                returned: list[ToolReturned] = []
+                for part in (event.content.parts if event.content else []) or []:
+                    if getattr(part, "text", None):
+                        parts.append(Say(text=part.text))
+                    if getattr(part, "function_call", None):
+                        parts.append(
+                            Call(
+                                id=getattr(part.function_call, "id", None)
+                                or f"call-{uuid.uuid4().hex[:8]}",
+                                name=part.function_call.name or "",
+                                arguments=dict(part.function_call.args or {}),
+                            )
+                        )
+                    if getattr(part, "function_response", None):
+                        response = part.function_response.response
+                        response_name = part.function_response.name or ""
+                        terminal_save_succeeded = terminal_save_succeeded or (
+                            _successful_terminal_save(response_name, response)
+                        )
+                        returned.append(
+                            ToolReturned(
+                                id=getattr(part.function_response, "id", None) or "",
+                                text=_flattened(response),
+                                is_error=bool(
+                                    isinstance(response, dict)
+                                    and response.get("is_error")
+                                ),
+                            )
+                        )
+                if parts:
+                    turns += 1
+                    yield ModelReply(parts=parts, model=self._model)
+                for outcome in returned:
+                    yield outcome
+                if terminal_save_succeeded:
+                    settled = True
+                    break
+                if event.is_final_response():
+                    settled = True
+        except Exception as exc:
+            yield StageDone(
+                outcome="failed",
+                turns=turns,
+                cost_usd=self._cost(tokens_in, tokens_out),
+                tokens_in=tokens_in,
+                tokens_out=tokens_out,
+                tokens_cached=tokens_cached,
+                session_id=self.session_id,
+                models={self._model},
+                is_error=True,
+                api_error_status=getattr(exc, "code", None),
+                errors=[str(exc)[:400]],
+            )
+            return
+        # A stream that ends without a final response ran out of its call budget, which is
+        # not the same as the model having finished. Reported as success it reads as a stage
+        # that did its work, and a half-written suite comes back green.
+        yield StageDone(
+            outcome="success" if settled else "max_turns",
+            is_error=not settled,
+            turns=turns,
+            cost_usd=self._cost(tokens_in, tokens_out),
+            tokens_in=tokens_in,
+            tokens_out=tokens_out,
+            tokens_cached=tokens_cached,
+            session_id=self.session_id,
+            models={self._model},
+            errors=(
+                []
+                if settled
+                else [
+                    f"the stage spent its whole budget of {self._spec.max_turns} calls"
+                ]
+            ),
+        )
+
+    def _cost(self, tokens_in: int, tokens_out: int) -> float | None:
+        return priced(self._model, tokens_in, tokens_out)
+
+
+logger = logging.getLogger(__name__)
+
+
+def priced(model: str, tokens_in: int, tokens_out: int) -> float | None:
+    """What these tokens cost, or None where no price can be stood behind."""
+    prices = PRICES_PER_MILLION.get(model)
+    if prices is None:
+        return None
+    if len(prices) > 2 and date.today().isoformat() > str(prices[2]):
+        logger.warning(
+            "no current price for %s: the table's figures expired on %s", model, prices[2]
+        )
+        return None
+    return (tokens_in * prices[0] + tokens_out * prices[1]) / 1_000_000
+
+
+class VertexGeminiBackend:
+    name = "vertex-gemini"
+    default_model = DEFAULT_MODEL
+
+    def can_drive(self, model: str) -> bool:
+        return (model or "").lower().startswith("gemini")
+
+    def create(self, spec: SessionSpec) -> VertexGeminiSession:
+        return VertexGeminiSession(spec, model=spec.model or self.default_model)

fi/alk/harness/background_noise.py

@@ -0,0 +1,95 @@
+"""Choose the caller-side ambient noise a scenario should be heard through.
+
+A scenario that sets ``background_noise`` wants the agent to handle a caller phoning from somewhere
+real: a car, a street, an office. The clip is chosen here and handed to the voice engine, which
+mixes it under the simulated caller's audio.
+
+Two sources, in order. A run may point ``ALK_BACKGROUND_NOISE_CATALOG`` at a JSON file of clips
+(each with an ``environment`` tag and a ``url`` or ``path``); the catalog stays a local file so its
+asset locations are never committed here. When no catalog matches, a LiveKit builtin clip is used,
+which needs no external asset and always works.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+# LiveKit ships these; they are the reliable default when no custom catalog is configured.
+_BUILTIN_BY_ENVIRONMENT: dict[str, str] = {
+    "street": "CITY_AMBIENCE",
+    "transit": "CITY_AMBIENCE",
+    "vehicle": "CITY_AMBIENCE",
+    "outdoors": "FOREST_AMBIENCE",
+    "retail": "CROWDED_ROOM",
+    "office": "OFFICE_AMBIENCE",
+    "home": "OFFICE_AMBIENCE",
+}
+_DEFAULT_BUILTIN = "OFFICE_AMBIENCE"
+
+
+def enabled() -> bool:
+    """Whether any scenario may be heard through background noise on this run.
+
+    **On unless ``ALK_BACKGROUND_NOISE`` turns it off.** A real caller is somewhere, and an agent
+    tested only against studio silence has not been tested against its callers, so noise is what a
+    run should fall into rather than something it has to ask for. It was opt-in and every deployment
+    forgot: a switch nobody sets is a feature nobody has.
+
+    The tradeoff is real and is why an opt-out exists. Continuous ambience under the caller competes
+    with endpoint detection, and calls carrying it end a little earlier and on fewer turns. Set
+    ``ALK_BACKGROUND_NOISE=0`` (or ``off``, ``false``, ``no``) for a run that needs a clean line.
+
+    Permission, not compulsion: a scenario whose own ``background_noise`` says none stays silent
+    either way.
+    """
+    return os.environ.get("ALK_BACKGROUND_NOISE", "1").strip().lower() not in (
+        "0",
+        "off",
+        "false",
+        "no",
+    )
+
+
+def source_for(environment: str = "", seed: str = "") -> str:
+    """A background-noise source for a scenario.
+
+    Returns a ``url``/``path`` from the configured catalog when one matches the environment, else the
+    name of a LiveKit builtin clip. The choice is deterministic in ``seed`` so the same scenario
+    hears the same place across runs.
+    """
+    env = (environment or "").strip().lower()
+    catalog = os.environ.get("ALK_BACKGROUND_NOISE_CATALOG", "").strip()
+    if catalog and Path(catalog).is_file():
+        try:
+            entries = json.loads(Path(catalog).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            entries = []
+        if isinstance(entries, list) and entries:
+            pool = [
+                entry
+                for entry in entries
+                if str(entry.get("environment", "")).strip().lower() == env
+            ] or entries
+            chosen = pool[sum(ord(character) for character in (seed or env or "x")) % len(pool)]
+            located = str(chosen.get("url") or chosen.get("path") or "").strip()
+            if located:
+                return located
+    return _BUILTIN_BY_ENVIRONMENT.get(env, _DEFAULT_BUILTIN)
+
+
+def scenario_source(
+    background_noise, fixture, seed: str = ""
+) -> str:
+    """The noise source for one scenario, or "" when it should be heard in the clear.
+
+    The scenario names the place when it cares which one; otherwise the fixture says where the
+    caller is, and failing that any noise will do.
+    """
+    if not background_noise or not enabled():
+        return ""
+    environment = background_noise if isinstance(background_noise, str) else ""
+    if not environment and isinstance(fixture, dict):
+        environment = str(fixture.get("environment") or fixture.get("location") or "")
+    return source_for(environment, seed=seed)