zettcode-engine 0.3.4__py3-none-any.whl

zettcode/processes.py

@@ -0,0 +1,126 @@
+"""Reading a running process's command line, so one of this program's own can be told from another program.
+
+A process id in a file anyone could have written is not a name: it can be stale, and the operating system reuses ids.
+So a process is acted on only after its command line has been read and recognised as ``python -m <module>`` — the one
+shape that makes it ours. This module is the part of that which does not know what a broker or a gateway is, shared by
+both so there is one spelling of it.
+
+It imports the standard library only (and not ``psutil``: the command line is readable with the tools the system
+already has), and it is a leaf, so a package that owns a process may use it without reaching into another's.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Any
+
+
+def command_line(pid: int) -> str | None:
+    """Return the command line of a running process, or ``None`` when it is gone or cannot be read.
+
+    Asked of the operating system, because a process id is not a name: ``ps`` on POSIX, PowerShell's process
+    table on Windows. Neither is guaranteed to exist, and not finding out is an answer the caller handles by
+    doing nothing.
+    """
+    if pid <= 0 or pid == os.getpid():
+        return None
+    if os.name == "nt":
+        command = [
+            "powershell",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            f"(Get-CimInstance Win32_Process -Filter 'ProcessId={int(pid)}').CommandLine",
+        ]
+    else:
+        command = ["ps", "-ww", "-o", "command=", "-p", str(int(pid))]  # -ww: no cut at the width of a terminal
+    try:
+        done = subprocess.run(command, capture_output=True, text=True, timeout=10, check=False)  # noqa: S603
+    except (OSError, subprocess.SubprocessError):
+        return None
+    text = done.stdout.strip()
+    return text if done.returncode == 0 and text else None
+
+
+def is_module_command(text: str, module: str) -> bool:
+    """Return whether a command line is a Python interpreter started with ``-m module`` and nothing else in the way.
+
+    The ``-m`` has to follow the interpreter directly (single-letter options such as ``-u`` may sit between), so
+    ``python -c "..." -m module`` and ``python script.py -m module`` — a different program with a flag that
+    happens to read the same — are not taken for it. The path to the interpreter may hold spaces, and on Windows
+    it is quoted.
+    """
+    # Before the interpreter there is only its path: a space followed by a dash would be an option of some other
+    # program (``sh -c python -m module`` is a shell, not the module).
+    pattern = rf"^(?:\S|\s(?!-))*?python[\d.]*(?:\.exe)?\"?\s+(?:-[A-Za-z]\s+)*-m\s+{re.escape(module)}(?:\s|$)"
+    return re.search(pattern, text, re.IGNORECASE) is not None
+
+
+def runs_module(pid: int, module: str) -> bool:
+    """Return whether the process is ``python -m module``: the one thing that makes it ours to end."""
+    text = command_line(pid)
+    return text is not None and is_module_command(text, module)
+
+
+def still_there(pid: int) -> bool:
+    """Return whether a process with that id exists, without signalling it.
+
+    This is the question that is left when a command line cannot be read: a process that is there but unreadable is
+    not the same as one that is gone, and ending (or replacing) the wrong one is worse than reporting the doubt.
+    On Windows ``os.kill(pid, 0)`` is not a probe — it terminates the process — so the process table is asked through
+    ``OpenProcess`` instead, and a handle that opens is asked for its exit code: a process that has ended but whose
+    object is still around answers with its exit code, not ``STILL_ACTIVE``. Only ``ERROR_INVALID_PARAMETER`` on the
+    open means "no such process"; a refusal for lack of rights, and any other failure, still counts as it being there.
+    """
+    if pid <= 0 or pid == os.getpid():
+        return False
+    if os.name == "nt":
+        import ctypes
+
+        kernel32 = _kernel32()
+        handle = kernel32.OpenProcess(0x1000, False, int(pid))  # PROCESS_QUERY_LIMITED_INFORMATION
+        if not handle:
+            # Only ERROR_INVALID_PARAMETER means there is no such process; a refusal for lack of rights, or any
+            # other failure, still counts as it being there.
+            return int(ctypes.get_last_error()) != 87  # type: ignore[attr-defined]
+        try:
+            code = ctypes.c_ulong(0)
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return True  # cannot tell: keep the doubt
+            return code.value == 259  # STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+#: Bound the first time a Windows process is asked about; ``None`` everywhere else.
+_KERNEL32: Any = None
+
+
+def _kernel32() -> Any:
+    """Return the one kernel32 binding, with the process calls typed once rather than per question."""
+    global _KERNEL32
+    if _KERNEL32 is None:
+        import ctypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+        kernel32.OpenProcess.argtypes = (ctypes.c_uint32, ctypes.c_int, ctypes.c_uint32)
+        kernel32.OpenProcess.restype = ctypes.c_void_p
+        kernel32.CloseHandle.argtypes = (ctypes.c_void_p,)
+        kernel32.GetExitCodeProcess.argtypes = (ctypes.c_void_p, ctypes.POINTER(ctypes.c_ulong))
+        kernel32.GetExitCodeProcess.restype = ctypes.c_int
+        _KERNEL32 = kernel32
+    return _KERNEL32
+
+
+__all__ = ["command_line", "is_module_command", "runs_module", "still_there"]

zettcode/prompt.py

@@ -0,0 +1,94 @@
+"""The parts of a user turn: text, ``@`` references, and the images placed among them.
+
+The composer splits a draft into these, so the shell resolves a reference without
+re-parsing the text, and the turn that reaches the model keeps each picture where its
+writer put it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from zettcode.mention import MentionRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class MentionPart:
+    """One ``@`` reference in a turn, kept as typed.
+
+    The composer splits a draft at these tokens, so the shell resolves them
+    without re-parsing the text and the editor can style them where they sit.
+    """
+
+    token: str
+    #: The words the model reads in the token's place, when it is not to see the token itself. ``None``
+    #: leaves the token as typed; the typed text is what the transcript and the store keep either way.
+    says: str | None = None
+
+
+#: One piece of a user turn, in the order it was written: a run of text, or the
+#: encoded bytes and media type of an image placed where that run ends.
+PromptPart: TypeAlias = str | MentionPart | tuple[bytes, str]
+
+
+def plain_text_part(part: PromptPart) -> str:
+    """Return the text one part contributes; an image contributes nothing."""
+    if isinstance(part, str):
+        return part
+    if isinstance(part, MentionPart):
+        return part.token
+    return ""
+
+
+def model_text_part(part: PromptPart) -> str:
+    """Return the text one part is to the model: a reference that was resolved reads as what it says."""
+    if isinstance(part, MentionPart) and part.says is not None:
+        return part.says
+    return plain_text_part(part)
+
+
+def mention_parts(parts: Sequence[PromptPart], mentions: MentionRegistry) -> tuple[PromptPart, ...]:
+    """Return a turn with each reference that has words of its own carrying them.
+
+    ``@work`` typed for a session that is running is not a word the model knows, so it is put in the
+    model's reading as ``session "work"`` and :func:`mention_hint` explains it. Anything else — a skill, a
+    file, a name nobody has — keeps the token as it was typed.
+    """
+    if not mentions.providers:
+        return tuple(parts)
+    resolved: list[PromptPart] = []
+    for part in parts:
+        says = mentions.rename_token(part.token) if isinstance(part, MentionPart) else None
+        resolved.append(MentionPart(part.token, says) if says is not None and isinstance(part, MentionPart) else part)
+    return tuple(resolved)
+
+
+def plain_text(parts: Sequence[PromptPart]) -> str:
+    """Return a turn as the reader typed it, with its ``@`` tokens back in place."""
+    return "".join(plain_text_part(part) for part in parts)
+
+
+def carries_image(parts: Sequence[PromptPart]) -> bool:
+    """Return whether one turn holds an image beside its text."""
+    return any(not isinstance(part, (str, MentionPart)) for part in parts)
+
+
+def mention_hint(parts: Sequence[PromptPart], mentions: MentionRegistry) -> str | None:
+    """Return the instructions a turn's ``@`` references contribute, if any.
+
+    ``None`` means nothing is appended: no provider is registered, the draft has
+    no reference, or every token is unknown — the model then reads exactly what
+    was typed. Each reference that resolves contributes one block, in the order
+    the tokens appear.
+    """
+    if not mentions.providers:
+        return None
+    hints = [
+        hint
+        for part in parts
+        if isinstance(part, MentionPart)
+        if (hint := mentions.expand_token(part.token)) is not None
+    ]
+    return "\n\n".join(hints) if hints else None

zettcode/providers.py

@@ -0,0 +1,215 @@
+"""Providers: the hosts a model can be reached at, described once so ``/config`` can offer them.
+
+A model entry needs an API (chat completions, Responses API, or Anthropic Messages API), an
+address, a token and a model id. For a well-known host the first two are the same for everyone, so a
+:class:`Provider` carries them and the reader only supplies the token and a model. A host nobody has
+described is ``custom``: the reader gives the address too.
+
+This module knows nothing about the shell, the terminal or ``zett-agent`` — a plugin imports it to
+describe a host of its own (``container.register_provider(Provider(...))``) and the configuration
+code imports it to turn a choice into a ``[[models]]`` entry.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from zettcode._compat import StrEnum
+
+
+class Api(StrEnum):
+    """The three request protocols one model entry can speak.
+
+    The value is the name a reader types (``--api responses``) and the word the picker shows, and a
+    member compares equal to that string, so it can be used wherever the text was.
+
+    Attributes:
+        CHAT: An OpenAI-compatible chat-completions endpoint; the default.
+        RESPONSES: The Responses API, on an OpenAI-compatible endpoint.
+        ANTHROPIC: Anthropic's Messages API, which is not OpenAI-compatible.
+    """
+
+    CHAT = "chat"
+    RESPONSES = "responses"
+    ANTHROPIC = "anthropic"
+
+    @property
+    def description(self) -> str:
+        """Return what the protocol is, in words, for the question that asks for one."""
+        return _DESCRIPTIONS[self]
+
+    @property
+    def keys(self) -> dict[str, object]:
+        """Return the ``[[models]]`` keys that select this protocol: none for chat, one for the others.
+
+        The three flags (``chat`` is the third) are alternatives, never layers, so a rewrite clears all of them before
+        it sets one. Chat completions is what an entry that sets none already is, so it needs no key; a reader who
+        picks it outright is given ``chat = true`` by the editor (see ``Draft.chat``), to say so in the file.
+        """
+        if self is Api.ANTHROPIC:
+            return {"anthropic": True}
+        if self is Api.RESPONSES:
+            return {"responses_api": True}
+        return {}
+
+    @classmethod
+    def parse(cls, text: str) -> Api:
+        """Return the protocol a reader typed, in any case; raise ``ValueError`` listing the choices."""
+        try:
+            return cls(text.strip().lower())
+        except ValueError:
+            raise ValueError(f"the api must be one of {', '.join(cls)}, not {text!r}") from None
+
+
+#: How each protocol is named beside a choice. The wording rule for everything a list shows next to a name — here,
+#: a provider's :attr:`~Provider.note`, and the notes of the other pickers — is a lower-case phrase with no
+#: leading article and no full stop; a proper noun (Responses API, Anthropic) keeps its capital.
+_DESCRIPTIONS = {
+    Api.CHAT: "chat completions",
+    Api.RESPONSES: "Responses API",
+    Api.ANTHROPIC: "Anthropic Messages API",
+}
+
+#: The flags a ``[[models]]`` entry sets to choose a protocol; every one is cleared before one is set. ``chat`` is
+#: among them because a file may spell the default out, and a rewrite to another protocol must not leave it behind.
+API_FLAG_KEYS = ("chat", "anthropic", "responses_api")
+
+#: What a provider is called when typed: lower case, so ``/config add deepseek`` has one spelling.
+NAME = re.compile(r"[a-z][a-z0-9_-]{0,31}\Z")
+
+#: The name that stands for "a host not described here"; it is not a provider, it is the absence of one.
+CUSTOM = "custom"
+
+
+@dataclass(frozen=True, slots=True)
+class Provider:
+    """One host a model can be reached at.
+
+    Attributes:
+        name: Identifier typed after ``/config add``; lower case letters, digits, ``-`` and ``_``.
+        label: What the picker shows.
+        api: Which request protocol the host speaks: ``chat``, ``responses`` or ``anthropic``.
+        base_url: The address the client appends its route to. ``None`` leaves it to the SDK's own
+            default, which is right for the vendor the SDK belongs to.
+        token_env: The environment variable the vendor's own tools read the token from, named in
+            the hint so a reader knows which key is wanted. It is never read from here.
+        models: Model ids worth suggesting. Left empty by the built-ins: a list of model names goes
+            stale faster than this program is released, so the reader types the one they mean.
+        multimodal: Whether models at this host take images, as the default for a new entry.
+        note: One line of help shown beside the provider in the picker: a lower-case phrase with no leading
+            article and no full stop, as every note in a list is (``chat completions``, ``local models``).
+            Left empty, the picker shows the protocol's own name.
+    """
+
+    name: str
+    label: str
+    api: Api = Api.CHAT
+    base_url: str | None = None
+    token_env: str | None = None
+    models: tuple[str, ...] = ()
+    multimodal: bool = False
+    note: str = ""
+
+    def __post_init__(self) -> None:
+        """Reject a description that could not produce a working entry."""
+        if not NAME.match(self.name):
+            raise ValueError(
+                f"Provider name {self.name!r} must be lower case letters, digits, '-' or '_', starting with a letter"
+            )
+        if self.name == CUSTOM:
+            raise ValueError(f"{CUSTOM!r} is reserved: it stands for a host that is not described")
+        if not self.label.strip():
+            raise ValueError(f"Provider {self.name!r} needs a label")
+        try:
+            object.__setattr__(self, "api", Api.parse(self.api))
+        except ValueError as error:
+            raise ValueError(f"Provider {self.name!r}: {error}") from None
+        if self.base_url is not None:
+            check_url(self.base_url, what=f"Provider {self.name!r} base_url")
+
+
+def check_url(value: str, *, what: str = "url") -> str:
+    """Return ``value`` trimmed if it is an http or https address, else raise ``ValueError``.
+
+    Args:
+        value: What the reader typed or a plugin declared.
+        what: How to name it in the error.
+    """
+    cleaned = value.strip()
+    parsed = urlparse(cleaned)
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        raise ValueError(f"{what} must be an http or https address such as https://api.example.com/v1")
+    return cleaned
+
+
+#: The hosts described out of the box. Each is an address and a protocol, nothing a reader could not
+#: find on the vendor's own page; none of them lists models (see :attr:`Provider.models`).
+BUILTIN_PROVIDERS: tuple[Provider, ...] = (
+    Provider(
+        "openai",
+        "OpenAI",
+        api=Api.CHAT,
+        base_url="https://api.openai.com/v1",
+        token_env="OPENAI_API_KEY",
+        note="chat completions; change the api later for Responses API",
+    ),
+    Provider(
+        "anthropic",
+        "Anthropic",
+        api=Api.ANTHROPIC,
+        base_url="https://api.anthropic.com",
+        token_env="ANTHROPIC_API_KEY",
+        note="Anthropic Messages API",
+    ),
+    Provider(
+        "deepseek",
+        "DeepSeek",
+        base_url="https://api.deepseek.com",
+        token_env="DEEPSEEK_API_KEY",
+        note="chat completions",
+    ),
+    Provider(
+        "openrouter",
+        "OpenRouter",
+        base_url="https://openrouter.ai/api/v1",
+        token_env="OPENROUTER_API_KEY",
+        note="chat completions; one key for many vendors, model ids look like vendor/name",
+    ),
+    Provider(
+        "groq",
+        "Groq",
+        base_url="https://api.groq.com/openai/v1",
+        token_env="GROQ_API_KEY",
+        note="chat completions",
+    ),
+    Provider(
+        "ollama",
+        "Ollama (local)",
+        base_url="http://localhost:11434/v1",
+        note="chat completions on this machine; no key is checked, any text will do for the token",
+    ),
+)
+
+
+def find_provider(name: str, providers: Iterable[Provider]) -> Provider | None:
+    """Return the provider called ``name`` (case does not matter), or ``None``."""
+    wanted = name.strip().lower()
+    return next((provider for provider in providers if provider.name == wanted), None)
+
+
+def merge_providers(*groups: Iterable[Provider]) -> tuple[Provider, ...]:
+    """Join provider lists in order; the first to claim a name keeps it.
+
+    A plugin that describes ``openai`` again does not replace the built-in: two hosts with one name
+    would make ``/config add openai`` ambiguous, and the one that was there first is the one a
+    reader has already seen.
+    """
+    merged: list[Provider] = []
+    for group in groups:
+        for provider in group:
+            if all(existing.name != provider.name for existing in merged):
+                merged.append(provider)
+    return tuple(merged)

zettcode/registry.py

@@ -0,0 +1,63 @@
+"""Named items merged from ordered providers.
+
+The shell keeps two catalogs a plugin may extend: the composer's slash commands
+and its ``@`` resources. Both merge the same way — providers in order, and the
+first provider to claim a name owns it — so both are one :class:`Registry` over
+one :class:`Provider` shape, and the builtins are providers like any other.
+
+A leaf with no imports of the project: the engine's ``@`` resources and the shell's commands both build on it.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Generic, TypeVar
+
+#: The kind of item a registry holds, such as a slash command.
+Item = TypeVar("Item")
+
+
+class Provider(Generic[Item], ABC):
+    """One source of named items a registry merges."""
+
+    @property
+    @abstractmethod
+    def items(self) -> Sequence[Item]:
+        """Return the items this provider contributes, in display order."""
+
+
+class Registry(Generic[Item]):
+    """Merge providers in order; the first provider to claim a name owns it."""
+
+    def __init__(self, providers: Sequence[Provider[Item]] = ()) -> None:
+        """Start from the given providers, most trusted first."""
+        self._providers = list(providers)
+
+    def register(self, provider: Provider[Item]) -> Provider[Item]:
+        """Append one provider and return it, for a caller that wants to keep it."""
+        self._providers.append(provider)
+        return provider
+
+    @property
+    def providers(self) -> tuple[Provider[Item], ...]:
+        """Return the providers in order."""
+        return tuple(self._providers)
+
+    def items(self) -> tuple[Item, ...]:
+        """Return the merged items, an earlier provider's name winning a clash."""
+        seen: set[str] = set()
+        merged: list[Item] = []
+        for provider in self._providers:
+            for item in provider.items:
+                name = getattr(item, "name", None)
+                if name is not None:
+                    if name in seen:
+                        continue
+                    seen.add(name)
+                merged.append(item)
+        return tuple(merged)
+
+    def find(self, name: str) -> Item | None:
+        """Return the item with this name, or ``None`` when nothing claims it."""
+        return next((item for item in self.items() if getattr(item, "name", None) == name), None)