phern 0.1.0__py3-none-any.whl

ph_app/__init__.py

@@ -0,0 +1,5 @@
+"""`ph_app` — the pH command line, and from Phase 2 the Textual TUI."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

ph_app/__main__.py

@@ -0,0 +1,15 @@
+"""`python -m ph_app` — the CLI, reachable without a console script.
+
+Exists for the daemon a UI starts on a person's behalf: `spawn_command` in
+`ph_app.cli` says why it must be *this* interpreter rather than whatever `phern`
+is on `PATH`.
+
+@module ph_app.__main__
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

ph_app/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Model adapters that speak real provider wires."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

ph_app/adapters/_http.py

@@ -0,0 +1,231 @@
+"""What every HTTP-streaming adapter shares: the client, the credential, the failure.
+
+The three wires pH speaks differ in message shape, in how usage is reported, and
+— since P7-03 — in how a file API is shaped. They do **not** differ in how a
+request is sent, how a secret reaches a header, or what an HTTP status means for
+retry, and when those were written twice the copies drifted (one overflow
+heuristic matched `max_tokens` anywhere in a body, turning a bad-request 400 into
+a compaction trigger). So they live here once.
+
+One `httpx.AsyncClient` per adapter, not per request: creating a client inside
+`stream()` pays a fresh TCP connect and TLS handshake on every model call and
+never reaches keep-alive or HTTP/2 multiplexing. The adapter's row disposes the
+client with its scope.
+
+@module ph_app.adapters._http
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Mapping
+from typing import Any
+
+import httpx
+
+from ph.cordis import Context
+from ph.keys import CREDENTIALS
+from ph.llm.adapter import LlmError
+from ph.llm.types import CONTEXT_WINDOW_EXCEEDED, FILE_EXPIRED, LlmFailure
+
+from .sse import iter_sse
+
+__all__ = ["HttpClient", "failure_from_status", "resolve_secret"]
+
+TIMEOUT = httpx.Timeout(600.0, connect=15.0)
+
+_STATUS_CODES = {429: "RATE_LIMIT", 401: "AUTHENTICATION", 403: "AUTHENTICATION", 529: "OVERLOADED"}
+
+
+def resolve_secret(ctx: Context, env_name: str, provider: str) -> str:
+    """Turn a credential *name* into its value — here, at the edge, and nowhere above (I-3).
+
+    The value goes into a local that goes out of scope with the request. Nothing
+    that travelled to get here held it.
+    """
+    credentials = ctx.get(CREDENTIALS)
+    if credentials is None:
+        raise LlmError("ctx.credentials is not mounted", "NO_CREDENTIALS")
+    secret = credentials.resolve(credentials.reference(env_name))
+    if secret is None:
+        raise LlmError(
+            f'{env_name} is not set, so provider "{provider}" cannot be called',
+            "MISSING_CREDENTIAL",
+        )
+    value: str = secret.reveal()
+    return value
+
+
+def failure_from_status(
+    status: int,
+    body: str,
+    *,
+    is_overflow: Callable[[str], bool],
+    is_missing_file: Callable[[str], bool] | None = None,
+) -> LlmError:
+    """Classify an HTTP error into the codes the retry policy routes on.
+
+    The wire-specific judgements are callbacks because each provider phrases them
+    differently, and both are expensive to get wrong in either direction: a missed
+    overflow retries forever, a false one compacts a conversation that fit.
+
+    `is_missing_file` is the second of them (P7-03), here rather than in an
+    adapter because a body classified once must not be re-read into a different
+    code further up — and because both wires have a file API, so the next one
+    inherits this instead of writing its own parser. Whether the missing file was
+    *ours* is a separate question only the caller can answer, and it answers it
+    against the code rather than the prose.
+    """
+    code = _STATUS_CODES.get(status, "SERVER_ERROR" if status >= 500 else "REQUEST_FAILED")
+    if is_missing_file is not None and is_missing_file(body):
+        code = FILE_EXPIRED
+    if is_overflow(body):
+        code = CONTEXT_WINDOW_EXCEEDED
+    detail = body[:400] or f"HTTP {status}"
+    return LlmError(
+        f"provider returned {status}: {detail}",
+        code,
+        LlmFailure(message=detail, code=code, status=status),
+    )
+
+
+class HttpClient:
+    """A lazily-created, long-lived `httpx.AsyncClient` with one streaming shape."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    def _get(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=TIMEOUT)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def post_multipart(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        field: str,
+        filename: str,
+        content: bytes,
+        mime: str,
+        is_overflow: Callable[[str], bool],
+        data: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """POST one file as multipart form data and return the parsed reply.
+
+        Here rather than in an adapter for `stream_sse`'s reason: a file API is
+        one more thing both wires have, and the status→code classification is
+        the part that must not be written twice. `Content-Type` is left to
+        `httpx`, which has to compute the multipart boundary anyway.
+
+        `data` is the form fields that ride beside the file. Anthropic's Files API
+        takes none; OpenAI's requires `purpose`, and without a way to send it the
+        second wire's uploader would have had to build its own request and inherit
+        none of the classification above (P7-03).
+        """
+        sending = {name: value for name, value in headers.items() if name != "Content-Type"}
+        response = await self._get().post(
+            url, headers=sending, files={field: (filename, content, mime)}, data=data or {}
+        )
+        if response.status_code >= 400:
+            raise failure_from_status(
+                response.status_code,
+                response.text,
+                is_overflow=is_overflow,
+            )
+        parsed: dict[str, Any] = response.json()
+        return parsed
+
+    async def post_raw(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any] | None = None,
+        content: bytes | None = None,
+        is_overflow: Callable[[str], bool],
+    ) -> tuple[dict[str, Any], Mapping[str, str]]:
+        """POST a JSON body or raw bytes; return `(parsed body, response headers)`.
+
+        The **headers** are why this exists and why it is not `post_multipart`
+        (P7-03). Google's Files API is a two-step resumable upload whose first
+        step answers with an empty body and the destination in
+        `X-Goog-Upload-URL`, and whose second step is the file's bytes with no
+        form encoding around them at all. Neither shape fits a multipart helper,
+        and both want the same status→code classification, which is the whole
+        reason this module exists.
+
+        A body that is not JSON comes back as `{}` rather than raising: the first
+        step of that upload legitimately returns nothing, and a helper that
+        insisted on JSON would make the caller catch a decode error to discover
+        success.
+        """
+        response = await self._get().post(url, headers=headers, json=json, content=content)
+        if response.status_code >= 400:
+            raise failure_from_status(response.status_code, response.text, is_overflow=is_overflow)
+        try:
+            parsed: dict[str, Any] = response.json()
+        except ValueError:
+            parsed = {}
+        return parsed, response.headers
+
+    async def get_json(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        is_overflow: Callable[[str], bool],
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """GET and parse — the poll half of an upload that finishes asynchronously.
+
+        `timeout` overrides `TIMEOUT` for one call, and exists for the caller
+        that is not waiting on a model: a *mount-time* probe inherits a ten
+        minute read budget otherwise, so a host that accepts the socket and then
+        stalls holds up plugin mount — and with it a TUI start and `phern doctor`.
+        A request whose answer nobody is blocked on keeps the generous default.
+        """
+        response = await self._get().get(
+            url,
+            headers=headers,
+            # httpx's own sentinel rather than a splat: "say nothing and take the
+            # client's" is a value here, and spreading a conditional dict past a
+            # keyword-typed signature is a hole the checker cannot see through.
+            timeout=httpx.Timeout(timeout) if timeout is not None else httpx.USE_CLIENT_DEFAULT,
+        )
+        if response.status_code >= 400:
+            raise failure_from_status(response.status_code, response.text, is_overflow=is_overflow)
+        parsed: dict[str, Any] = response.json()
+        return parsed
+
+    async def stream_sse(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+        is_overflow: Callable[[str], bool],
+        is_missing_file: Callable[[str], bool] | None = None,
+    ) -> AsyncIterator[tuple[str, dict[str, Any]]]:
+        """POST and yield `(event, payload)` for every JSON SSE payload.
+
+        A non-2xx response is raised as a classified `LlmError` before any
+        payload is yielded, so a consumer never sees a half-stream.
+        """
+        async with self._get().stream("POST", url, headers=headers, json=json) as response:
+            if response.status_code >= 400:
+                body = (await response.aread()).decode("utf-8", errors="replace")
+                raise failure_from_status(
+                    response.status_code,
+                    body,
+                    is_overflow=is_overflow,
+                    is_missing_file=is_missing_file,
+                )
+            async for event, payload in iter_sse(response):
+                if isinstance(payload, dict):
+                    yield event, payload

ph_app/adapters/_media.py

@@ -0,0 +1,181 @@
+"""Loading the bytes for media that is going out (P7-01).
+
+The sibling of `_http.py`, and all that is left here once `ph.llm.media` answers
+the *policy* question above every adapter: by the time a request reaches one, any
+`MediaBlock` still on it is one this route said it accepts, so there is nothing
+left to decide — only bytes to fetch and a wire shape to build, and the shape is
+the adapter's own.
+
+Also the *upload* half of that, once a second wire grew one (P7-03). `_http`'s
+own docstring is the argument: the two adapters differ in message shape and in
+how usage is reported, and they do **not** differ in what a dead file handle
+means — so `forget_named_handle` lives here rather than being the third copy of
+twelve lines whose bug would be invisible.
+
+What is *not* here is the route projection (`MediaRoute`, `resolved`), which the
+three adapters also share: its content is `ResolvedModel`'s field list, so it
+belongs beside that dataclass in `ph.llm` rather than in an application
+package — everything in this module needs `ctx.uploads`, the attachment store or
+`FILE_EXPIRED` semantics to mean anything, and that one needed none of them.
+
+@module ph_app.adapters._media
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Collection, Sequence
+
+from ph.cordis import Context
+from ph.keys import UPLOADS
+from ph.llm.adapter import LlmError
+from ph.llm.media import media_pointer_text
+from ph.llm.types import FILE_EXPIRED, AttachmentRef, Message, attachment_of
+from ph.seams.attachments import AttachmentStore
+from ph.seams.uploads import UploadRegistry
+
+__all__ = ["forget_named_handle", "load_handles", "load_media", "media_pointer"]
+
+log = logging.getLogger("ph_app.adapters.media")
+
+
+def forget_named_handle(
+    ctx: Context, error: LlmError, referenced: Sequence[str], *, provider: str
+) -> LlmError:
+    """Drop the one handle this failure named, or leave the failure alone (P7-03).
+
+    `_http` has already decided the provider is talking about a missing file; what
+    only an adapter knows is whether it is a file *we* sent. A `not_found` naming
+    no id of ours is somebody else's 404 — a stale route, a gateway — and retrying
+    it would be the "unknown failure billed twice" the retry policy exists to
+    refuse, so it goes back to the code it came with.
+
+    **The named handle, not every handle.** A first draft invalidated all of them
+    on a match, which on a request carrying twenty files threw away nineteen live
+    uploads to re-fetch one dead one.
+
+    Shared rather than copied because the *classification* is already shared:
+    `failure_from_status` takes each wire's phrases and answers one code, and this
+    is what a caller does with that code. A second adapter writing its own would
+    be free to disagree about which half of the check is load-bearing, which is
+    the half that keeps `FILE_EXPIRED` out of an infinite retry.
+    """
+    uploads = ctx.get(UPLOADS)
+    message = str(error.failure.message)
+    named = [handle for handle in referenced if handle in message]
+    if uploads is None or not named:
+        return (
+            LlmError(
+                message,
+                "REQUEST_FAILED",
+                error.failure.model_copy(update={"code": "REQUEST_FAILED"}),
+            )
+            if error.code == FILE_EXPIRED
+            else error
+        )
+    for handle in named:
+        uploads.invalidate_handle(provider, handle)
+    return error
+
+
+def media_pointer(attachment: AttachmentRef) -> dict[str, str]:
+    """The text block that stands in for media that could not be loaded.
+
+    Reached only on a race — `media-degrade` already checked the blob was there,
+    so arriving here means it went away between that check and this read. The
+    wording is `ph.llm.media`'s, so the model reads one sentence for one
+    situation however it was arrived at.
+    """
+    return {"type": "text", "text": media_pointer_text(attachment)}
+
+
+async def load_handles(
+    uploads: UploadRegistry | None,
+    messages: Sequence[Message],
+    *,
+    provider: str,
+    mimes: frozenset[str],
+    session_id: str | None = None,
+) -> dict[str, str]:
+    """Provider file ids for the attachments this route references rather than inlines.
+
+    Keyed by attachment id like `load_media`, and consulted first by the
+    renderer: an id present here is sent as a reference, absent as bytes. The
+    two maps rather than one union type because the fallback has to be silent and
+    total — an upload that fails for any reason leaves the id out and the
+    attachment goes inline, which is what every route did before this row.
+
+    `mimes` is the route's own list rather than "everything large": which formats
+    are worth a round trip is a fact about a provider's file API, and video is
+    the case where it is not a choice.
+    """
+    handles: dict[str, str] = {}
+    if uploads is None or not mimes:
+        return handles
+    for message in messages:
+        for block in message.content:
+            attachment = attachment_of(block)
+            if attachment is None or attachment.attachment_id in handles:
+                continue
+            if attachment.mime not in mimes:
+                continue
+            try:
+                handle = await uploads.handle_for(
+                    attachment, provider=provider, session_id=session_id
+                )
+            except Exception:
+                # Deliberately broad and deliberately not fatal: an upload is an
+                # optimisation, and a route that can take the bytes inline must
+                # not lose a turn because a file API was down.
+                log.warning(
+                    "ph_app.adapters: could not upload %s to %s; sending it inline",
+                    attachment.name or attachment.attachment_id,
+                    provider,
+                    exc_info=True,
+                )
+                continue
+            if handle is not None:
+                handles[attachment.attachment_id] = handle.handle
+    return handles
+
+
+async def load_media(
+    store: AttachmentStore | None,
+    messages: Sequence[Message],
+    *,
+    skip: Collection[str] = (),
+) -> dict[str, str]:
+    """Base64 for every attachment still on the request, keyed by id.
+
+    Absent from the map means the read failed after `media-degrade` had approved
+    it, which is a race rather than a policy outcome — the caller renders a
+    pointer either way, so one branch covers both.
+
+    Through `AttachmentStore.load_b64`, which encodes once per process: a media
+    block lives in derived history for the session's life, so re-encoding per
+    request is a cost paid on every step.
+
+    **`skip` is what makes an upload actually cheaper** (P7-03). Without it a
+    referenced file was still read and base64-encoded here and then discarded by
+    the renderer — so the wire payload shrank and nothing else did, while a
+    5.5 MB string sat in the store's encode cache for the life of the process.
+    Uploading is supposed to remove that work, not move it.
+    """
+    loaded: dict[str, str] = {}
+    if store is None:
+        return loaded
+    for message in messages:
+        for block in message.content:
+            attachment = attachment_of(block)
+            if attachment is None or attachment.attachment_id in loaded:
+                continue
+            if attachment.attachment_id in skip:
+                continue
+            try:
+                loaded[attachment.attachment_id] = await store.load_b64(attachment)
+            except OSError:
+                log.warning(
+                    "ph_app.adapters: could not read %s; sending a pointer",
+                    attachment.name or attachment.attachment_id,
+                )
+    return loaded