puremethod 0.1.0__py3-none-any.whl

app/model_search.py

@@ -0,0 +1,252 @@
+"""Finding model servers and their models (08-app.md §3 `POST /llm-servers/search`, Onboarding
+step 1; KB-036). Runs in a worker task: an SSH search decrypts the machine's keys (INV-2).
+
+Targets:
+- this computer: OpenAI-compatible servers on 127.0.0.1 at the known ports and any added;
+- an SSH machine: the same ports, first directly at the machine's address, then over SSH
+  channels on its loopback address (no listening port is opened); a server found only over
+  SSH is `via_ssh`;
+- a URL: with or without `/v1`, https before http; a 401 asks for a key; known hosted
+  providers serving open models are named, and their price is asked for.
+
+A port counts only if `GET /v1/models` answers with a model list. Models a server forwards to
+a hosted service (Ollama cloud models) are marked not local."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from typing import Any, Protocol
+from urllib.parse import urlsplit
+
+import httpx
+import paramiko
+
+from app import ssh_chain
+from app.addresses import private_address
+from app.settings import Mode
+
+KNOWN_PORTS = (11434, 1234, 8000, 8080, 30000)  # Ollama, LM Studio, vLLM, llama.cpp, SGLang
+TIMEOUT_S = 4.0
+MAX_BODY = 4 * 1024 * 1024
+# Hosted services that serve open-weights models through an OpenAI-compatible API.
+PROVIDERS = {"openrouter.ai": "OpenRouter", "api.together.xyz": "Together",
+             "api.groq.com": "Groq", "api.deepinfra.com": "DeepInfra",
+             "api.fireworks.ai": "Fireworks", "api.mistral.ai": "Mistral",
+             "api.cerebras.ai": "Cerebras", "integrate.api.nvidia.com": "NVIDIA NIM"}
+
+
+@dataclass
+class Model:
+    id: str
+    context_length: int | None = None  # as served, where the server says
+    local: bool = True
+
+
+@dataclass
+class Server:
+    endpoint: dict[str, Any]  # {"type": "local"|"via_ssh"|"base_url", ...}
+    kind: str | None = None
+    provider: str | None = None  # a known hosted provider
+    needs_key: bool = False
+    encrypted: bool = True
+    models: list[Model] = field(default_factory=list)
+
+
+@dataclass
+class Result:
+    servers: list[Server] = field(default_factory=list)
+    problems: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class Fetch(Protocol):
+    def __call__(self, method: str, path: str, body: Any = None
+                 ) -> tuple[int, Any]: ...
+
+
+def _direct(base: str, key: str = "") -> Fetch:
+    """HTTP to `base` (scheme://host:port), JSON in and out."""
+    headers = {"Authorization": f"Bearer {key}"} if key else {}
+
+    def fetch(method: str, path: str, body: Any = None) -> tuple[int, Any]:
+        try:
+            r = httpx.request(method, base + path, json=body, headers=headers,
+                              timeout=TIMEOUT_S, follow_redirects=False)
+        except (httpx.HTTPError, OSError):
+            return 0, None
+        try:
+            return r.status_code, r.json()
+        except ValueError:
+            return r.status_code, None
+    return fetch
+
+
+def _over_ssh(transport: paramiko.Transport, port: int) -> Fetch:
+    """HTTP/1.0 over a `direct-tcpip` channel to 127.0.0.1:`port` on the machine."""
+    def fetch(method: str, path: str, body: Any = None) -> tuple[int, Any]:
+        data = json.dumps(body).encode() if body is not None else b""
+        head = (f"{method} {path} HTTP/1.0\r\nHost: 127.0.0.1:{port}\r\n"
+                f"Content-Type: application/json\r\nContent-Length: {len(data)}\r\n\r\n")
+        try:
+            ch = transport.open_channel("direct-tcpip", ("127.0.0.1", port), ("127.0.0.1", 0),
+                                        timeout=TIMEOUT_S)
+        except (paramiko.SSHException, OSError, EOFError):
+            return 0, None
+        try:
+            ch.settimeout(TIMEOUT_S)
+            ch.sendall(head.encode() + data)
+            raw = b""
+            while len(raw) < MAX_BODY:
+                chunk = ch.recv(65536)
+                if not chunk:
+                    break
+                raw += chunk
+        except (OSError, paramiko.SSHException, EOFError):
+            return 0, None
+        finally:
+            ch.close()
+        top, _, payload = raw.partition(b"\r\n\r\n")
+        parts = top.split(b" ", 2)
+        try:
+            status = int(parts[1])
+        except (IndexError, ValueError):
+            return 0, None
+        try:
+            return status, json.loads(payload)
+        except ValueError:
+            return status, None
+    return fetch
+
+
+def _models(fetch: Fetch) -> tuple[int, list[dict[str, Any]] | None]:
+    status, body = fetch("GET", "/v1/models")
+    if status == 200 and isinstance(body, dict) and isinstance(body.get("data"), list):
+        return status, [m for m in body["data"] if isinstance(m, dict) and m.get("id")]
+    return status, None
+
+
+def describe(fetch: Fetch, endpoint: dict[str, Any]) -> Server | None:
+    """The server behind `fetch`, or None if it is not an OpenAI-compatible model server."""
+    status, listed = _models(fetch)
+    if status == 401:
+        return Server(endpoint=endpoint, needs_key=True)
+    if listed is None:
+        return None
+    server = Server(endpoint=endpoint)
+    version_status, _ = fetch("GET", "/api/version")
+    if version_status == 200:  # Ollama
+        server.kind = "ollama"
+        _, ps = fetch("GET", "/api/ps")
+        loaded = {m.get("name"): m.get("context_length")
+                  for m in (ps or {}).get("models", []) if isinstance(m, dict)}
+        for m in listed:
+            mid = str(m["id"])
+            cloud = mid.endswith(":cloud") or "-cloud" in mid
+            ctx = loaded.get(mid)
+            server.models.append(Model(mid, ctx if isinstance(ctx, int) else None, not cloud))
+        return server
+    for m in listed:
+        ctx = m.get("max_model_len")
+        if isinstance(ctx, int):
+            server.kind = "vllm"
+        server.models.append(Model(str(m["id"]), ctx if isinstance(ctx, int) else None))
+    if server.kind is None:
+        s, props = fetch("GET", "/props")
+        n_ctx = ((props or {}).get("default_generation_settings") or {}).get("n_ctx") \
+            if s == 200 and isinstance(props, dict) else None
+        if isinstance(n_ctx, int):
+            server.kind = "llama.cpp"
+            for model in server.models:
+                model.context_length = n_ctx
+        elif fetch("GET", "/api/v0/models")[0] == 200:
+            server.kind = "lmstudio"
+    return server
+
+
+def search_this_computer(ports: list[int]) -> Result:
+    result = Result()
+    for port in dict.fromkeys([*KNOWN_PORTS, *ports]):
+        found = describe(_direct(f"http://127.0.0.1:{port}"), {"type": "local", "port": port})
+        if found is not None:
+            result.servers.append(found)
+    return result
+
+
+def search_machine(machine_id: str, hops: list[dict[str, Any]], ports: list[int],
+                   private_key: Callable[[str], str], mode: Mode) -> Result:
+    """`hops` ends with the machine itself (its jump hosts first)."""
+    result = Result()
+    target = hops[-1]
+    host = str(target["host"])
+    seen: set[int] = set()
+    ports = list(dict.fromkeys([*KNOWN_PORTS, *ports]))
+    # Directly at the machine's address first; never a private address in hosted mode.
+    if not (mode == "hosted" and private_address(host)):
+        shown = f"[{host}]" if ":" in host else host
+        for port in ports:
+            base = f"http://{shown}:{port}"
+            found = describe(_direct(base), {"type": "base_url", "base_url": f"{base}/v1"})
+            if found is not None:
+                found.encrypted = private_address(host)  # plain http: fine on a private net
+                result.servers.append(found)
+                seen.add(port)
+    try:
+        chain = ssh_chain.connect(hops, private_key)
+    except (ssh_chain.HopFailed, paramiko.SSHException, OSError, EOFError) as exc:
+        result.problems.append(f"over SSH: {exc}")
+        return result
+    try:
+        transport = chain.client.get_transport()
+        if transport is None:
+            result.problems.append(f"over SSH: {host} gave no transport")
+            return result
+        for port in ports:
+            if port in seen:
+                continue
+            found = describe(_over_ssh(transport, port),
+                             {"type": "via_ssh", "machine": machine_id, "remote_port": port})
+            if found is not None:
+                result.servers.append(found)
+    finally:
+        chain.close()
+    return result
+
+
+def normalize(url: str) -> list[str]:
+    """Base URLs to try for what the user typed: with `/v1`, https before http."""
+    text = url.strip().rstrip("/")
+    if "://" not in text:
+        candidates = [f"https://{text}", f"http://{text}"]
+    else:
+        candidates = [text]
+    out = []
+    for c in candidates:
+        out.append(c if c.endswith("/v1") else f"{c}/v1")
+    return out
+
+
+def search_url(url: str, key: str, mode: Mode) -> Result:
+    result = Result()
+    for base in normalize(url):
+        parts = urlsplit(base)
+        host = parts.hostname or ""
+        if not host or parts.scheme not in ("http", "https"):
+            result.problems.append(f"{url!r} is not a web address")
+            return result
+        if mode == "hosted" and private_address(host):  # INV-11
+            result.problems.append(f"{host} is not a public address; hosted puremethod does "
+                                   "not call it. Use an SSH machine instead")
+            return result
+        root = base[: -len("/v1")]
+        found = describe(_direct(root, key), {"type": "base_url", "base_url": base})
+        if found is not None:
+            found.provider = PROVIDERS.get(host)
+            found.encrypted = parts.scheme == "https" or private_address(host)
+            result.servers.append(found)
+            return result
+    result.problems.append(f"no OpenAI-compatible model server answers at {url}")
+    return result

app/outputs.py

@@ -0,0 +1,77 @@
+"""Where delivered outputs are read from (08-app.md §3 Downloads, KB-021).
+
+`LocalOutputs` is the self-hosted store: the bundle directory `loop` recorded in the run's
+final `run.status`, which must lie inside the output root. Hosted mode adds an object-storage
+store with the same methods."""
+
+from __future__ import annotations
+
+import tarfile
+import tempfile
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Protocol
+
+from app.readonly import ReadOnlyLedger
+
+PAPER = Path("paper") / "main.pdf"
+STALE_S = 3600.0
+
+
+class OutputStore(Protocol):
+    def paper(self, ledger_run_id: str, bundle_ref: str) -> Path | None: ...
+    def bundle_archive(self, ledger_run_id: str, bundle_ref: str, name: str) -> Path | None: ...
+
+
+def bundle_ref(ledger: ReadOnlyLedger, ledger_run_id: str) -> str | None:
+    """The bundle recorded by the last `run.status` with status `delivered`, if any."""
+    ref = None
+    for e in ledger.entries(ledger_run_id, types=["run.status"]):
+        if e.payload.get("status") == "delivered" and e.payload.get("bundle"):
+            ref = str(e.payload["bundle"])
+    return ref
+
+
+class LocalOutputs:
+    def __init__(self, output_root: Path, tmp_dir: Path, *,
+                 clock: Callable[[], float] = time.time) -> None:
+        self._root = output_root.resolve()
+        self._tmp = tmp_dir
+        self._clock = clock
+
+    def _dir(self, ledger_run_id: str, bundle_ref: str) -> Path | None:
+        """Inside this run's own output directory, which `loop` writes bundles under
+        (03-loop.md §5), never just anywhere under the shared root (review finding 8)."""
+        run_dir = (self._root / ledger_run_id).resolve()
+        path = Path(bundle_ref).resolve()
+        inside = run_dir.is_relative_to(self._root) and path.is_relative_to(run_dir)
+        if not inside or not path.is_dir():
+            return None
+        return path
+
+    def paper(self, ledger_run_id: str, bundle_ref: str) -> Path | None:
+        d = self._dir(ledger_run_id, bundle_ref)
+        if d is None:
+            return None
+        pdf = (d / PAPER).resolve()
+        return pdf if pdf.is_relative_to(d) and pdf.is_file() else None
+
+    def bundle_archive(self, ledger_run_id: str, bundle_ref: str, name: str) -> Path | None:
+        """A `.tar.gz` of the bundle in a temporary file; the caller deletes it. Symlinks in
+        the bundle are stored as links, never followed. Archives an interrupted download left
+        behind are removed after an hour (review finding 9)."""
+        d = self._dir(ledger_run_id, bundle_ref)
+        if d is None:
+            return None
+        self._tmp.mkdir(parents=True, exist_ok=True)
+        for old in self._tmp.glob("bundle-*.tar.gz"):
+            try:
+                if self._clock() - old.stat().st_mtime > STALE_S:
+                    old.unlink()
+            except OSError:
+                pass  # another request is removing or sending it
+        fd, path = tempfile.mkstemp(prefix="bundle-", suffix=".tar.gz", dir=self._tmp)
+        with open(fd, "wb") as fh, tarfile.open(fileobj=fh, mode="w:gz") as tar:
+            tar.add(d, arcname=f"{name}-bundle", recursive=True)
+        return Path(path)

app/paths.py

@@ -0,0 +1,93 @@
+"""Self-hosted default locations (08-app.md §4 Storage, KB-025): data in
+`<user data dir>/puremethod/data`, the master key in `<user config dir>/puremethod/master.key`.
+The key file is never inside the data directory. `PM_DATA_DIR`, `PM_MASTER_KEY` and
+`PM_MASTER_KEY_FILE` override these (app.settings)."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import os
+import secrets
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+import platformdirs
+
+APP = "puremethod"
+KEY_BYTES = 32
+
+
+def default_data_dir() -> Path:
+    return Path(platformdirs.user_data_dir(APP, appauthor=False)) / "data"
+
+
+def default_key_file() -> Path:
+    return Path(platformdirs.user_config_dir(APP, appauthor=False)) / "master.key"
+
+
+class KeyFileExists(Exception):
+    pass
+
+
+def create_key_file(path: Path) -> None:
+    """Writes a new random 32-byte key, base64, readable only by the current user (08 §5
+    step 3). The key is written and restricted under a temporary name, then moved into place
+    without overwriting, so a failure never leaves an unrestricted key at `path`, and an
+    existing key is never replaced (losing it makes stored credentials unreadable)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        raise KeyFileExists(str(path))
+    tmp = path.with_name(f".{path.name}.{secrets.token_hex(4)}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(base64.b64encode(os.urandom(KEY_BYTES)) + b"\n")
+        restrict_to_user(tmp)
+        if sys.platform == "win32":
+            os.rename(tmp, path)  # fails if `path` exists
+        else:
+            os.link(tmp, path)  # fails if `path` exists; rename would overwrite
+    except FileExistsError:
+        raise KeyFileExists(str(path)) from None
+    finally:
+        with contextlib.suppress(OSError):
+            tmp.unlink()
+
+
+def _system32(exe: str) -> str:
+    """A Windows tool by its full path: PATH may hold another `whoami` (Git's, say)."""
+    return str(Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32" / exe)
+
+
+def _user_sid() -> str:
+    """The current user's SID, from the process token (not from environment variables)."""
+    out = subprocess.run([_system32("whoami.exe"), "/user", "/fo", "csv", "/nh"],  # noqa: S603
+                         capture_output=True, text=True, check=True).stdout
+    sid = out.strip().rsplit(",", 1)[-1].strip('"')
+    if not sid.startswith("S-1-"):
+        raise OSError("cannot read the current user's SID")
+    return sid
+
+
+def restrict_to_user(path: Path) -> None:
+    """POSIX: mode 0600. Windows: drop inherited entries and grant the current user alone,
+    since a file under AppData inherits SYSTEM and Administrators."""
+    if sys.platform != "win32":
+        os.chmod(path, 0o600)
+        return
+    # Fixed arguments as a list, no shell; the path is ours.
+    subprocess.run([_system32("icacls.exe"), str(path), "/inheritance:r", "/grant:r",  # noqa: S603
+                    f"*{_user_sid()}:F"], check=True, capture_output=True)
+
+
+def is_restricted(path: Path) -> bool:
+    """For `puremethod doctor`: is the key file readable by the current user only?"""
+    if sys.platform != "win32":
+        return stat.S_IMODE(path.stat().st_mode) & 0o077 == 0
+    out = subprocess.run([_system32("icacls.exe"), str(path)], capture_output=True,  # noqa: S603
+                         text=True, check=False).stdout
+    entries = [ln for ln in out.splitlines() if "(" in ln and ":" in ln]
+    return len(entries) == 1 and "(I)" not in out

app/readonly.py

@@ -0,0 +1,70 @@
+"""What the API process may do with the ledger and `loop` (08-app.md INV-2, INV-3, INV-7).
+
+`ReadOnlyLedger` exposes the read interface of `04-ledger.md` §3 only; any other attribute
+raises. `status_loop` builds a `Loop` that can answer `status` but whose client factories
+and credential lookup all refuse, so the API process never builds a client or decrypts."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from typing import Any, NoReturn
+
+from ledger import ChainReport, Entry, Ledger, RunState, SpendSummary
+from loop import Loop, RunStatus
+
+READS = frozenset({"entries", "get_artifact", "state", "spend", "verify"})
+
+
+class LedgerWriteRefused(PermissionError):
+    pass
+
+
+class ReadOnlyLedger:
+    """Also serializes reads: the API's request threads, event streams and the supervisor
+    share one ledger connection, and a SQLite connection is not safe for concurrent use."""
+
+    def __init__(self, ledger: Ledger) -> None:
+        self._ledger = ledger
+        self._lock = threading.Lock()
+
+    def entries(self, run_id: str, types: Iterable[str] | None = None,
+                refs: Iterable[str] | None = None,
+                since_seq: int | None = None) -> Iterator[Entry]:
+        with self._lock:
+            got = list(self._ledger.entries(run_id, types=types, refs=refs, since_seq=since_seq))
+        return iter(got)
+
+    def get_artifact(self, run_id: str, digest: str) -> bytes:
+        with self._lock:
+            return self._ledger.get_artifact(run_id, digest)
+
+    def state(self, run_id: str) -> RunState:
+        with self._lock:
+            return self._ledger.state(run_id)
+
+    def spend(self, run_id: str) -> SpendSummary:
+        with self._lock:
+            return self._ledger.spend(run_id)
+
+    def verify(self, run_id: str) -> ChainReport:
+        with self._lock:
+            return self._ledger.verify(run_id)
+
+    def __getattr__(self, name: str) -> NoReturn:
+        raise LedgerWriteRefused(f"the API reads the ledger only (INV-3): {name}")
+
+
+def _refuse(*_: Any, **__: Any) -> NoReturn:
+    raise LedgerWriteRefused("the API process builds no clients and reads no credentials")
+
+
+def status_loop(ledger: ReadOnlyLedger, output_root: Path) -> Loop:
+    return Loop(ledger, _refuse, llm=_refuse, executor=_refuse,  # type: ignore[arg-type]
+                purescholar=_refuse, puretrace=_refuse, credentials=_refuse,
+                output_root=output_root)
+
+
+def status_of(loop: Loop, ledger_run_id: str) -> RunStatus:
+    return loop.status(ledger_run_id)