agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/_async_iterators.py

@@ -0,0 +1,79 @@
+"""Scoped async stream cleanup without changing its primary result or error.
+
+Optional ``aclose`` and close-only async contexts are handled here. This helper does
+not promise resource release after a failure, retry cleanup, detach a task,
+or suppress cancellation. External resources remain their Port owner's duty.
+"""
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import TypeVar
+
+_LOGGER = logging.getLogger(__name__)
+_T = TypeVar("_T")
+
+
+def _cleanup_warning(owner: str) -> None:
+    _LOGGER.warning(
+        "Async stream cleanup failed; resource release unconfirmed (%s)", owner,
+        extra={"event": "async_stream.cleanup_failed", "owner": owner},
+    )
+
+
+async def close_async_iterator(iterator: object, *, owner: str) -> None:
+    """Join a declared close operation, preserving the enclosing operation.
+
+    An AsyncIterator need not have ``aclose``. A close error must not erase a
+    sealed model response, replace a protocol rejection or turn cancellation
+    into an unrelated provider failure. The diagnostic deliberately contains
+    no exception message, traceback, provider data or credentials.
+    """
+    try:
+        close = getattr(iterator, "aclose", None)
+        if callable(close):
+            await close()
+    except Exception:
+        _cleanup_warning(owner)
+
+
+@asynccontextmanager
+async def owning_async_iterator(
+    iterator: AsyncIterator[_T], *, owner: str
+) -> AsyncIterator[AsyncIterator[_T]]:
+    try:
+        yield iterator
+    finally:
+        await close_async_iterator(iterator, owner=owner)
+
+
+async def _exit_context(
+    context: AbstractAsyncContextManager[_T], error: BaseException | None, *, owner: str
+) -> None:
+    try:
+        await context.__aexit__(
+            type(error) if error is not None else None,
+            error,
+            error.__traceback__ if error is not None else None,
+        )
+    except Exception:
+        _cleanup_warning(owner)
+
+
+@asynccontextmanager
+async def owning_async_context(
+    context: AbstractAsyncContextManager[_T], *, owner: str
+) -> AsyncIterator[_T]:
+    """Own a close-only response context; body/entry failures stay authoritative.
+
+    Used for HTTPX streaming responses, whose exit only closes the response.
+    This is not for transaction contexts or contexts that suppress body errors.
+    """
+    value = await context.__aenter__()
+    try:
+        yield value
+    except BaseException as error:
+        await _exit_context(context, error, owner=owner)
+        raise
+    else:
+        await _exit_context(context, None, owner=owner)

ksadk/_build_provenance.json

@@ -1 +1 @@
-{"schemaVersion":1,"sourceCommit":"8e37106d1faed44c2de8b7f72a0d8cd2f1fbddd5","sourceTree":"clean","version":"0.8.4"}
+{"schemaVersion":1,"sourceCommit":"867f7db34c697d5c927b6af618c11b14594cb53e","sourceTree":"clean","version":"0.8.6"}

ksadk/_model_anthropic.py

@@ -0,0 +1,49 @@
+"""Pure original-content decoding for client-executed Anthropic turns."""
+
+import copy
+
+
+def anthropic_content(value: object) -> list[dict]:
+    if not isinstance(value, list):
+        raise ValueError("Anthropic content must be an array")
+    for block in value:
+        if not isinstance(block, dict):
+            raise ValueError("Anthropic content requires typed blocks")
+        kind = block.get("type")
+        fields = {
+            "text": ("text",), "thinking": ("thinking", "signature"),
+            "redacted_thinking": ("data",), "tool_use": ("id", "name"),
+        }.get(kind)
+        if fields is None:
+            raise ValueError("unsupported Anthropic replay block")
+        if any(not isinstance(block.get(name), str) for name in fields):
+            raise ValueError("invalid Anthropic replay block field")
+        if kind == "tool_use" and (
+            not block["id"].strip() or not block["name"].strip()
+            or not isinstance(block.get("input"), dict)
+        ):
+            raise ValueError("invalid Anthropic tool block")
+    return copy.deepcopy(value)
+
+
+def anthropic_projection(content: list[dict], id_map: object = ()) -> tuple[str, list[dict]]:
+    """Separate visible/call facts while retaining the original replay elsewhere."""
+    blocks = anthropic_content(content)
+    text = "".join(block["text"] for block in blocks if block["type"] == "text")
+    calls = [{"call_id": block["id"], "name": block["name"], "arguments": block["input"]}
+             for block in blocks if block["type"] == "tool_use"]
+    originals = {call["call_id"] for call in calls}
+    if len(originals) != len(calls) or not isinstance(id_map, (tuple, list)):
+        raise ValueError("invalid original Anthropic tool identities")
+    mapped = {}
+    for pair in id_map:
+        if (not isinstance(pair, (tuple, list)) or len(pair) != 2
+                or any(not isinstance(value, str) or not value.strip() for value in pair)
+                or pair[0] not in originals or pair[0] in mapped):
+            raise ValueError("invalid Anthropic host identity projection")
+        mapped[pair[0]] = pair[1]
+    for call in calls:
+        call["call_id"] = mapped.get(call["call_id"], call["call_id"])
+    if len({call["call_id"] for call in calls}) != len(calls):
+        raise ValueError("colliding Anthropic host identities")
+    return text, calls

ksadk/_model_input.py

@@ -0,0 +1,86 @@
+"""Immutable provider input observations; no tool, replay or completion authority."""
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+
+from ksadk._model_json import load_model_json
+
+
+def transformations_json(value: object) -> str:
+    if not isinstance(value, list):
+        raise ValueError("input transformations must be an array")
+    for item in value:
+        if not isinstance(item, dict) or type(item.get("type")) is not str:
+            raise ValueError("input transformation requires a type")
+        for key in ("path", "reason"):
+            if item.get(key) is not None and type(item[key]) is not str:
+                raise ValueError("input transformation optional field must be text")
+    # Preserve unknown types, reasons and fields without interpreting them.
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+    )
+
+
+def provider_prefix_digest(payload: dict) -> str:
+    """Hash the actual outgoing request fields, not the API's per-block prefix.
+
+    Credentials and generation options aren't included. This exact-body proof
+    is deliberately not a reimplementation of the server's binding algorithm.
+    """
+    prefix = {key: payload[key] for key in ("system", "tools", "messages") if key in payload}
+    return hashlib.sha256(
+        json.dumps(
+            prefix, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+        ).encode()
+    ).hexdigest()
+
+
+@dataclass(frozen=True)
+class ProviderInputObservation:
+    transformations_json: str = field(repr=False)
+    provider_prefix_digest: str
+    source: str
+
+    def __post_init__(self):
+        if type(self.transformations_json) is not str:
+            raise ValueError("input observation requires immutable JSON")
+        transformations_json(load_model_json(self.transformations_json))
+        if (
+            type(self.provider_prefix_digest) is not str
+            or re.fullmatch(r"[0-9a-f]{64}", self.provider_prefix_digest) is None
+        ):
+            raise ValueError("input observation requires the actual request digest")
+        if self.source not in {"buffered", "message_start", "message_delta"}:
+            raise ValueError("input observation source is not a protocol boundary")
+
+
+def input_observation(fields: dict, payload: dict, source: str) -> ProviderInputObservation | None:
+    value = fields.get("input_transformations")
+    if value is None:
+        return None  # Absent/null is unknown; an explicit [] is a reported fact.
+    return ProviderInputObservation(
+        transformations_json(value), provider_prefix_digest(payload), source
+    )
+
+
+def transformation_summary(value: str) -> dict:
+    counts = {}
+    unknown = 0
+    for item in load_model_json(value):
+        kind, reason = item.get("type"), item.get("reason")
+        if (
+            kind == "thinking_dropped"
+            and reason
+            in {
+                "prefix_binding_mismatch",
+                "model_binding_mismatch",
+                "organization_binding_mismatch",
+            }
+        ) or (kind == "thinking_mismatch_allowed" and reason == "prefix_binding_mismatch"):
+            key = f"{kind}:{reason}"
+            counts[key] = counts.get(key, 0) + 1
+        else:
+            unknown += 1
+    return {"known_counts": counts, "unknown_count": unknown}

ksadk/_model_json.py

@@ -0,0 +1,40 @@
+"""Pure model JSON decoding without duplicate keys or non-finite numbers.
+
+Callers retain ownership of protocol classification and tool error receipts.
+This decoder never repairs input, coerces containers or records model text.
+"""
+
+import json
+import math
+
+
+class ModelJSONPolicyError(ValueError):
+    """Parsed JSON cannot identify one finite value; never reinterpret as text."""
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ModelJSONPolicyError("duplicate model JSON key")
+        result[key] = value
+    return result
+
+
+def _reject_constant(_value: str) -> object:
+    raise ModelJSONPolicyError("non-finite model JSON number")
+
+
+def _finite_float(value: str) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ModelJSONPolicyError("model JSON number overflow")
+    return number
+
+
+def load_model_json(value: str | bytes) -> object:
+    try:
+        return json.loads(value, object_pairs_hook=_unique_object,
+                          parse_constant=_reject_constant, parse_float=_finite_float)
+    except RecursionError:
+        raise ModelJSONPolicyError("model JSON nesting exceeds decoder capacity") from None

ksadk/_model_reasoning.py

@@ -0,0 +1,17 @@
+"""Pure Chat reasoning decoding; private protocol never becomes public text."""
+
+
+def chat_reasoning(message: dict) -> str:
+    """Normalize the supported alias without hiding invalid or conflicting data.
+
+    A missing/null field and an empty string both carry no text. Providers may
+    include an empty native field alongside the alias; two nonempty fields
+    must agree. This is decoding, independent of whether a host retains replay.
+    """
+    native, alias = message.get("reasoning_content"), message.get("reasoning")
+    for value in (native, alias):
+        if value is not None and not isinstance(value, str):
+            raise ValueError("invalid private reasoning field")
+    if native and alias and native != alias:
+        raise ValueError("conflicting private reasoning fields")
+    return native or alias or ""

ksadk/_model_refusal.py

@@ -0,0 +1,20 @@
+"""Typed provider refusal signals, independent of transport and retry policy."""
+
+
+def chat_refusal(value: object) -> bool:
+    if value is None:
+        return False
+    if type(value) is not str:
+        raise ValueError("invalid model refusal field")
+    return bool(value)
+
+
+def anthropic_refusal(details: object) -> bool:
+    if details is None:
+        return False
+    if not isinstance(details, dict) or details.get("type") != "refusal":
+        raise ValueError("unsupported model stop details")
+    for field in ("category", "explanation"):
+        if details.get(field) is not None and type(details[field]) is not str:
+            raise ValueError("invalid model stop details field")
+    return True

ksadk/_model_sse.py

@@ -0,0 +1,163 @@
+"""Shared byte framing for model SSE, independent of HTTP and provider schemas.
+
+Transport IDs and retry directives never authorize deduplication or retries.
+Only a blank line dispatches data. Model adapters reject unfinished data at EOF
+rather than treating a discarded terminal fragment as a complete response.
+"""
+
+import asyncio
+import codecs
+import math
+import re
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from ksadk._async_iterators import owning_async_iterator
+
+_LINE_END = re.compile(r"\r\n|\r|\n")
+
+
+class SSEFramingError(ValueError):
+    """A fixed diagnostic without provider bytes or credentials."""
+
+
+class ModelSSEIdleTimeout(TimeoutError):
+    """No nonempty model data arrived within the host's read interval."""
+
+
+@dataclass(frozen=True)
+class SSEFrame:
+    data: str
+    event: str = "message"
+    last_event_id: str = ""
+
+
+class _Framer:
+    def __init__(self) -> None:
+        self.parts: list[str] = []
+        self.data: list[str] = []
+        self.event = ""
+        self.last_event_id = ""
+        self.after_cr = False
+
+    def feed(self, text: str) -> Iterator[SSEFrame]:
+        if not text:
+            return
+        if self.after_cr:
+            if text.startswith("\n"):
+                text = text[1:]
+            self.after_cr = False
+        start = 0
+        for end in _LINE_END.finditer(text):
+            self.parts.append(text[start:end.start()])
+            line = "".join(self.parts)
+            self.parts.clear()
+            start = end.end()
+            self.after_cr = end.group() == "\r" and start == len(text)
+            frame = self._line(line)
+            if frame is not None:
+                yield frame
+        if start < len(text):
+            self.parts.append(text[start:])
+
+    def _line(self, line: str) -> SSEFrame | None:
+        if not line:
+            frame = (
+                SSEFrame("\n".join(self.data), self.event or "message", self.last_event_id)
+                if self.data else None
+            )
+            self.data.clear()
+            self.event = ""
+            return frame
+        if line.startswith(":"):
+            return None
+        name, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if name == "data":
+            self.data.append(value)
+        elif name == "event":
+            self.event = value
+        elif name == "id" and "\x00" not in value:
+            self.last_event_id = value
+        # Unknown fields and retry are transport controls, not model payloads.
+        return None
+
+    def finish(self) -> None:
+        pending = "".join(self.parts)
+        if self.data or pending == "data" or pending.startswith("data:"):
+            raise SSEFramingError("unfinished model SSE data")
+
+
+async def _decode(chunks: AsyncIterator[bytes], max_bytes: int) -> AsyncIterator[SSEFrame]:
+    decoder = codecs.getincrementaldecoder("utf-8-sig")("strict")
+    framer, total = _Framer(), 0
+    async for raw in chunks:
+        total += len(raw)
+        if total > max_bytes:
+            raise SSEFramingError("model SSE byte budget exceeded")
+        for frame in framer.feed(decoder.decode(raw)):
+            yield frame
+    for frame in framer.feed(decoder.decode(b"", final=True)):
+        yield frame
+    framer.finish()
+
+
+async def _idle_frames(
+    frames: AsyncIterator[SSEFrame], timeout: float | None,
+) -> AsyncIterator[SSEFrame]:
+    if timeout is None:
+        async for frame in frames:
+            yield frame
+        return
+    loop = asyncio.get_running_loop()
+    deadline = None
+    while True:
+        if deadline is None:
+            deadline = loop.time() + timeout
+        try:
+            # wait_for joins the cancelled read and also supports Python 3.10.
+            # The outer Effect owner handles a transport that refuses to join.
+            frame = await asyncio.wait_for(anext(frames), max(0, deadline - loop.time()))
+        except StopAsyncIteration:
+            if loop.time() >= deadline:
+                raise ModelSSEIdleTimeout("model stream idle timeout") from None
+            return
+        except asyncio.TimeoutError:
+            if loop.time() < deadline:
+                raise  # Preserve an unrelated timeout raised by the byte source.
+            raise ModelSSEIdleTimeout("model stream idle timeout") from None
+        if loop.time() >= deadline:
+            # A read may swallow cancellation and return a late frame or EOF.
+            raise ModelSSEIdleTimeout("model stream idle timeout")
+        yield frame
+        if frame.data.strip():
+            # Time spent by the consumer is not provider idle time. Private
+            # reasoning/tool data counts; comments and blank data do not.
+            deadline = None
+
+
+@asynccontextmanager
+async def model_sse_frames(
+    chunks: AsyncIterator[bytes], *, max_bytes: int, idle_timeout_seconds: float | None = None,
+) -> AsyncIterator[AsyncIterator[SSEFrame]]:
+    """Join local iterators on EOF, terminal return, rejection and cancellation.
+
+    UTF-8 is deliberately strict: replacing corrupt bytes inside JSON changes
+    model facts. Byte limits belong to the adapter; no transport is opened here.
+    The existing HTTP response owner remains responsible for external resources.
+    """
+    if type(max_bytes) is not int or max_bytes <= 0:
+        raise ValueError("model SSE needs a positive byte budget")
+    if idle_timeout_seconds is not None and (
+        type(idle_timeout_seconds) not in {int, float}
+        or not math.isfinite(idle_timeout_seconds) or idle_timeout_seconds <= 0
+    ):
+        raise ValueError("model SSE needs a positive idle interval")
+    decoded = _decode(chunks, max_bytes)
+    iterator = _idle_frames(decoded, idle_timeout_seconds)
+    async with owning_async_iterator(chunks, owner="model_sse.bytes"):
+        async with owning_async_iterator(decoded, owner="model_sse.decode"):
+            async with owning_async_iterator(iterator, owner="model_sse.frames"):
+                yield iterator

ksadk/_process.py

@@ -0,0 +1,83 @@
+"""Small process-group lifecycle helpers shared by local runtime backends."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+
+
+def starts_new_process_group() -> bool:
+    return os.name == "posix"
+
+
+def terminate_process_group(
+    process: subprocess.Popen[object],
+    *,
+    grace_seconds: float = 0.2,
+    reap_seconds: float = 1.0,
+) -> str | None:
+    """Stop a process and its descendants, then reap the direct child.
+
+    The caller must have created the process with ``start_new_session=True`` on
+    POSIX. The bounded waits intentionally avoid ``communicate()`` because a
+    surviving descendant may keep inherited output descriptors open.
+    """
+
+    errors: list[str] = []
+    if os.name == "posix":
+        _signal_group(process.pid, signal.SIGTERM, errors)
+        deadline = time.monotonic() + max(grace_seconds, 0)
+        while time.monotonic() < deadline and _group_exists(process.pid):
+            # Reap an exited group leader before probing again. On Darwin an
+            # unreaped leader can make a now-empty group appear present and a
+            # subsequent killpg report EPERM.
+            process.poll()
+            time.sleep(0.01)
+        process.poll()
+        if _group_exists(process.pid):
+            _signal_group(process.pid, signal.SIGKILL, errors)
+    elif process.poll() is None:
+        try:
+            process.terminate()
+        except ProcessLookupError:
+            pass
+        except Exception as exc:  # pragma: no cover - platform/runtime specific
+            errors.append(type(exc).__name__)
+
+    try:
+        process.wait(timeout=max(reap_seconds, 0.01))
+    except subprocess.TimeoutExpired:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+        except Exception as exc:  # pragma: no cover - platform/runtime specific
+            errors.append(type(exc).__name__)
+        try:
+            process.wait(timeout=max(reap_seconds, 0.01))
+        except subprocess.TimeoutExpired:
+            errors.append("process_reap_timeout")
+    except Exception as exc:  # pragma: no cover - platform/runtime specific
+        errors.append(type(exc).__name__)
+    return ",".join(dict.fromkeys(errors)) or None
+
+
+def _signal_group(pid: int, sig: signal.Signals, errors: list[str]) -> None:
+    try:
+        os.killpg(pid, sig)
+    except ProcessLookupError:
+        pass
+    except Exception as exc:  # pragma: no cover - platform/runtime specific
+        errors.append(type(exc).__name__)
+
+
+def _group_exists(pid: int) -> bool:
+    try:
+        os.killpg(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:  # pragma: no cover - cannot inspect another owner
+        return True

ksadk/_str_enum.py

@@ -0,0 +1,17 @@
+"""String-valued enums on all supported Python versions (including 3.10)."""
+
+try:
+    from enum import StrEnum
+except ImportError:  # Python 3.10
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        __str__ = str.__str__
+        __format__ = str.__format__
+
+        @staticmethod
+        def _generate_next_value_(name, start, count, last_values):
+            return name.lower()
+
+
+__all__ = ["StrEnum"]