confoundsearch 0.1.0__py3-none-any.whl

confoundsearch/__init__.py

@@ -0,0 +1,72 @@
+"""ConfoundSearch: an agent that builds a confound graph as a Markov Decision Process."""
+
+from confoundsearch.data.corpus import Corpus, InMemoryCorpus
+from confoundsearch.data.es import ElasticsearchCorpus
+from confoundsearch.data.sources import OpenAlexCorpus, SemanticScholarCorpus
+from confoundsearch.errors import CorpusError, InvalidAction, LLMError, RemoteError
+from confoundsearch.interface.export import export_zip, save_export, to_share_data
+from confoundsearch.logic.actions import (
+    Action,
+    AddConfound,
+    AddEdge,
+    AttachPassage,
+    Merge,
+    Retrieve,
+    Stop,
+    enumerate_actions,
+)
+from confoundsearch.logic.audit import AuditedClient, AuditLog, AuditTrail, verify
+from confoundsearch.logic.episode import Step, Trajectory, run_episode
+from confoundsearch.logic.graph import Graph, Passage, Vertex
+from confoundsearch.logic.policy import EpsilonGreedy, LookaheadQ, Softmax
+from confoundsearch.logic.reward import phi, reward
+from confoundsearch.logic.state import State
+from confoundsearch.logic.transition import Environment, Judge
+from confoundsearch.model.llm import LLMJudge, LLMProposer, OpenAICompatibleClient, Proposer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Action",
+    "AddConfound",
+    "AddEdge",
+    "AttachPassage",
+    "AuditLog",
+    "AuditTrail",
+    "AuditedClient",
+    "Corpus",
+    "CorpusError",
+    "ElasticsearchCorpus",
+    "Environment",
+    "EpsilonGreedy",
+    "Graph",
+    "InMemoryCorpus",
+    "InvalidAction",
+    "Judge",
+    "LLMError",
+    "LLMJudge",
+    "LLMProposer",
+    "LookaheadQ",
+    "Merge",
+    "OpenAICompatibleClient",
+    "OpenAlexCorpus",
+    "Passage",
+    "Proposer",
+    "RemoteError",
+    "Retrieve",
+    "SemanticScholarCorpus",
+    "Softmax",
+    "State",
+    "Step",
+    "Stop",
+    "Trajectory",
+    "Vertex",
+    "enumerate_actions",
+    "export_zip",
+    "phi",
+    "reward",
+    "run_episode",
+    "save_export",
+    "to_share_data",
+    "verify",
+]

confoundsearch/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from confoundsearch.interface.cli import main
+
+sys.exit(main())

confoundsearch/data/__init__.py

@@ -0,0 +1,2 @@
+"""The data layer: where papers come from (a file, Elasticsearch, Semantic Scholar, OpenAlex), all behind the
+`Corpus` interface."""

confoundsearch/data/corpus.py

@@ -0,0 +1,36 @@
+"""The corpus D, behind a one-method protocol."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Protocol
+
+from confoundsearch.logic.graph import Passage, normalize
+
+
+class Corpus(Protocol):
+    def search(self, query: str, k: int) -> list[Passage]:
+        """Return up to k passages relevant to the query."""
+        ...
+
+
+class InMemoryCorpus:
+    """Ranks passages by how many query words they contain. Deterministic."""
+
+    def __init__(self, passages: Iterable[Passage]) -> None:
+        self.passages = tuple(passages)
+
+    @classmethod
+    def from_jsonl(cls, path: str | Path) -> InMemoryCorpus:
+        """One JSON object per line with `id` and `text`, and optionally `title` and `url`."""
+        rows = [json.loads(line) for line in Path(path).read_text().splitlines() if line.strip()]
+        return cls(Passage(str(r["id"]), r["text"], r.get("title", ""), r.get("url", "")) for r in rows)
+
+    def search(self, query: str, k: int) -> list[Passage]:
+        words = set(normalize(query).split())
+        scored = [(len(words & set(normalize(p.text).split())), p) for p in self.passages]
+        hits = [(n, p) for n, p in scored if n > 0]
+        hits.sort(key=lambda hit: (-hit[0], hit[1].id))
+        return [p for _, p in hits[: max(k, 0)]]

confoundsearch/data/es.py

@@ -0,0 +1,72 @@
+"""An Elasticsearch-backed corpus, over the plain REST API.
+
+Works with a local node or Elastic Cloud. Documents need a text field (default
+`abstract`) and may have `title`, `url` and `corpusid`, as in the Semantic
+Scholar index the paper's experiments use.
+
+    ElasticsearchCorpus("https://my-deployment.es.us-east-1.aws.elastic.cloud", api_key="...")
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from confoundsearch.errors import CorpusError, RemoteError
+from confoundsearch.http import Transport, urllib_transport
+from confoundsearch.logic.graph import Passage
+
+
+class ElasticsearchCorpus:
+    def __init__(
+        self,
+        url: str,
+        index: str = "papers",
+        api_key: str | None = None,
+        text_field: str = "abstract",
+        title_field: str = "title",
+        min_citations: int = 0,
+        timeout: float = 30.0,
+        transport: Transport = urllib_transport,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.index = index
+        self.api_key = api_key
+        self.text_field = text_field
+        self.title_field = title_field
+        self.min_citations = min_citations
+        self.timeout = timeout
+        self.transport = transport
+
+    def _query(self, query: str, k: int) -> dict[str, Any]:
+        match = {"multi_match": {"query": query, "fields": [f"{self.title_field}^2", self.text_field]}}
+        bool_query: dict[str, Any] = {"must": match, "filter": [{"exists": {"field": self.text_field}}]}
+        if self.min_citations:
+            bool_query["filter"].append({"range": {"citationcount": {"gte": self.min_citations}}})
+        return {"query": {"bool": bool_query}, "size": k}
+
+    def search(self, query: str, k: int) -> list[Passage]:
+        if k <= 0:
+            return []
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"ApiKey {self.api_key}"
+        body = json.dumps(self._query(query, k)).encode()
+        try:
+            raw = self.transport(f"{self.url}/{self.index}/_search", headers, body, self.timeout)
+        except RemoteError as err:
+            raise CorpusError(str(err)) from err
+        try:
+            hits = json.loads(raw)["hits"]["hits"]
+            return [self._passage(hit) for hit in hits]
+        except (ValueError, KeyError, TypeError) as err:
+            raise CorpusError(f"unexpected response: {raw[:200]!r}") from err
+
+    def _passage(self, hit: dict[str, Any]) -> Passage:
+        source = hit["_source"]
+        return Passage(
+            id=str(source.get("corpusid", hit["_id"])),
+            text=source[self.text_field],
+            title=source.get(self.title_field) or "",
+            url=source.get("url") or "",
+        )

confoundsearch/data/sources.py

@@ -0,0 +1,148 @@
+"""Paper sources that need no corpus of your own: Semantic Scholar's API and OpenAlex's.
+
+Both implement the same one-method `Corpus` protocol as the file and Elasticsearch corpora, so the agent
+does not know or care which it is searching. Only papers that have an abstract are returned, because an
+abstract is the passage the agent reads and cites.
+
+    SemanticScholarCorpus(api_key="...")      # a free key raises the rate limit; request one at S2_KEY_URL
+    OpenAlexCorpus(mailto="you@example.org")  # an email (or an api_key) puts you in OpenAlex's polite pool
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urlencode
+
+from confoundsearch.errors import CorpusError, RemoteError
+from confoundsearch.http import Transport, urllib_transport
+from confoundsearch.logic.graph import Passage
+
+MAX_PAGE = 100
+S2_KEY_URL = "https://www.semanticscholar.org/product/api"  # where to request a free Semantic Scholar API key
+
+
+def _get(transport: Transport, url: str, headers: Mapping[str, str], timeout: float, hint: str) -> Any:
+    try:
+        raw = transport(url, headers, None, timeout)
+    except RemoteError as err:
+        extra = f" {hint}" if "HTTP 429" in str(err) else ""
+        raise CorpusError(f"{err}{extra}") from err
+    try:
+        return json.loads(raw)
+    except ValueError as err:
+        raise CorpusError(f"unexpected response: {raw[:200]!r}") from err
+
+
+def _page_size(k: int) -> int:
+    """Ask for extra results, since some papers have no abstract and are dropped."""
+    return min(max(2 * k, k), MAX_PAGE)
+
+
+class SemanticScholarCorpus:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.semanticscholar.org/graph/v1",
+        timeout: float = 30.0,
+        transport: Transport = urllib_transport,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.transport = transport
+
+    def search(self, query: str, k: int) -> list[Passage]:
+        if k <= 0 or not query.strip():
+            return []
+        params = urlencode(
+            {
+                "query": query,
+                "limit": _page_size(k),
+                "fields": "title,abstract,url,year,citationCount,corpusId",
+            }
+        )
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        hint = (
+            f"Semantic Scholar is rate limiting you. Request a free API key at {S2_KEY_URL} "
+            "and set it as S2_KEY (or --s2-key); it raises the limit."
+        )
+        data = _get(self.transport, f"{self.base_url}/paper/search?{params}", headers, self.timeout, hint)
+        try:
+            papers = data.get("data") or []  # an empty result has no "data" at all
+            passages = [self._passage(p) for p in papers if p.get("abstract")]
+        except (AttributeError, KeyError, TypeError) as err:
+            raise CorpusError(f"unexpected response: {str(data)[:200]!r}") from err
+        return passages[:k]
+
+    @staticmethod
+    def _passage(paper: dict[str, Any]) -> Passage:
+        return Passage(
+            id=str(paper.get("corpusId") or paper["paperId"]),
+            text=paper["abstract"],
+            title=paper.get("title") or "",
+            url=paper.get("url") or "",
+        )
+
+
+def abstract_from_inverted_index(inverted: Mapping[str, list[int]]) -> str:
+    """OpenAlex stores an abstract as {word: [positions]}. Put the words back in order."""
+    placed = sorted((position, word) for word, positions in inverted.items() for position in positions)
+    return " ".join(word for _, word in placed)
+
+
+class OpenAlexCorpus:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        mailto: str | None = None,
+        base_url: str = "https://api.openalex.org",
+        timeout: float = 30.0,
+        transport: Transport = urllib_transport,
+    ) -> None:
+        self.api_key = api_key
+        self.mailto = mailto
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.transport = transport
+
+    def search(self, query: str, k: int) -> list[Passage]:
+        if k <= 0 or not query.strip():
+            return []
+        params = {
+            "search": query,
+            "per_page": _page_size(k),
+            "select": "id,title,abstract_inverted_index,doi,publication_year",
+        }
+        if self.api_key:
+            params["api_key"] = self.api_key
+        if self.mailto:
+            params["mailto"] = self.mailto
+        hint = (
+            "OpenAlex is rate limiting you; add an email (OPENALEX_EMAIL) or an API key (OPENALEX_API_KEY)."
+        )
+        data = _get(
+            self.transport,
+            f"{self.base_url}/works?{urlencode(params)}",
+            {"Accept": "application/json"},
+            self.timeout,
+            hint,
+        )
+        try:
+            works = data["results"]
+            passages = [self._passage(w) for w in works if w.get("abstract_inverted_index")]
+        except (KeyError, TypeError, AttributeError) as err:
+            raise CorpusError(f"unexpected response: {str(data)[:200]!r}") from err
+        return passages[:k]
+
+    @staticmethod
+    def _passage(work: dict[str, Any]) -> Passage:
+        return Passage(
+            id=work["id"].rsplit("/", 1)[-1],
+            text=abstract_from_inverted_index(work["abstract_inverted_index"]),
+            title=work.get("title") or "",
+            url=work.get("doi") or work["id"],
+        )

confoundsearch/dotenv.py

@@ -0,0 +1,21 @@
+"""Read settings from a `.env` file, so API keys need not be typed into a terminal."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_dotenv(path: Path) -> None:
+    """Put KEY=VALUE lines from `path` into the environment. Never overrides a variable already set."""
+    if not path.is_file():
+        return
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip().removeprefix("export ")
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        os.environ.setdefault(key.strip(), value)

confoundsearch/errors.py

@@ -0,0 +1,17 @@
+"""Exceptions shared across the package."""
+
+
+class InvalidAction(ValueError):
+    """An edit or action violates a graph invariant or the MDP's rules."""
+
+
+class RemoteError(RuntimeError):
+    """A remote HTTP service failed or returned something unusable."""
+
+
+class LLMError(RemoteError):
+    """An OpenAI-compatible endpoint failed or returned something unusable."""
+
+
+class CorpusError(RemoteError):
+    """The search backend failed or returned something unusable."""

confoundsearch/http.py

@@ -0,0 +1,26 @@
+"""One HTTP request (a POST with a body, or a GET without), using only the standard library."""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+
+from confoundsearch.errors import RemoteError
+
+Transport = Callable[[str, Mapping[str, str], bytes | None, float], bytes]
+
+
+def urllib_transport(url: str, headers: Mapping[str, str], body: bytes | None, timeout: float) -> bytes:
+    request = urllib.request.Request(
+        url, data=body, headers=dict(headers), method="GET" if body is None else "POST"
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310
+            data: bytes = response.read()
+            return data
+    except urllib.error.HTTPError as err:
+        detail = err.read().decode("utf-8", "replace")
+        raise RemoteError(f"HTTP {err.code} from {url}: {detail}") from err
+    except urllib.error.URLError as err:
+        raise RemoteError(f"could not reach {url}: {err.reason}") from err

confoundsearch/interface/__init__.py

@@ -0,0 +1 @@
+"""The interface layer: the web page and its backend, the command line, the JSON result, the agent skill."""

confoundsearch/interface/cli.py

@@ -0,0 +1,211 @@
+"""Command line: `confoundsearch serve` runs the interface and its backend,
+`confoundsearch run` runs one search and writes the standalone page.
+
+    confoundsearch serve --model gpt-4.1                     # the hosted index (ES_URL, ES_API_KEY)
+    confoundsearch serve --model gpt-4.1 --corpus openalex   # or semanticscholar, or --corpus-file F
+    confoundsearch run --iv "IT investment" --dv "firm performance" --corpus-file passages.jsonl
+    confoundsearch audit confoundsearch.logic.audit.jsonl     # check and read a run's audit trail
+    confoundsearch run --json ...                        # the result as JSON, for programs and agents
+    confoundsearch install-skill                         # add the Claude Code skill
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import sys
+from collections.abc import Sequence
+from importlib import resources
+from pathlib import Path
+
+from confoundsearch import __version__
+from confoundsearch.data.corpus import Corpus, InMemoryCorpus
+from confoundsearch.data.es import ElasticsearchCorpus
+from confoundsearch.data.sources import OpenAlexCorpus, SemanticScholarCorpus
+from confoundsearch.dotenv import load_dotenv
+from confoundsearch.interface.export import to_share_data
+from confoundsearch.interface.result import run_result
+from confoundsearch.interface.server import RunManager, make_server
+from confoundsearch.interface.ui import standalone_html
+from confoundsearch.logic.audit import AuditedClient, AuditLog, AuditTrail
+from confoundsearch.logic.episode import ActionSource, run_episode
+from confoundsearch.logic.policy import EpsilonGreedy, LookaheadQ
+from confoundsearch.logic.transition import Environment
+from confoundsearch.model.llm import OPENROUTER_URL, LLMJudge, LLMProposer, OpenAICompatibleClient, Proposer
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="confoundsearch", description=__doc__.split("\n\n")[0])
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    shared = argparse.ArgumentParser(add_help=False)
+    llm = shared.add_argument_group("language model (any OpenAI-compatible endpoint)")
+    llm.add_argument("--model", required=True)
+    llm.add_argument("--base-url", help="default: $OPENAI_BASE_URL or https://api.openai.com/v1")
+    llm.add_argument("--api-key", help="default: $OPENAI_API_KEY (with --openrouter: $OPENROUTER_API_KEY)")
+    llm.add_argument(
+        "--openrouter", action="store_true", help="use OpenRouter; --model is a slug like openai/gpt-4.1"
+    )
+    env = os.environ.get
+    papers = shared.add_argument_group("papers to search (default: the hosted Elasticsearch index)")
+    papers.add_argument(
+        "--corpus", choices=CORPORA, help="elasticsearch (default), semanticscholar, openalex, or file"
+    )
+    papers.add_argument("--corpus-file", type=Path, help="JSONL with id, text, and optionally title, url")
+    papers.add_argument("--es-url", default=env("ES_URL"), help="Elasticsearch endpoint (default: $ES_URL)")
+    papers.add_argument("--es-index", default="papers")
+    papers.add_argument("--es-api-key", default=env("ES_API_KEY"), help="default: $ES_API_KEY")
+    papers.add_argument(
+        "--s2-key", default=env("S2_KEY"), help="Semantic Scholar API key (optional; $S2_KEY)"
+    )
+    papers.add_argument(
+        "--openalex-key", default=env("OPENALEX_API_KEY"), help="OpenAlex API key ($OPENALEX_API_KEY)"
+    )
+    papers.add_argument(
+        "--openalex-email", default=env("OPENALEX_EMAIL"), help="email for OpenAlex ($OPENALEX_EMAIL)"
+    )
+
+    serve = commands.add_parser("serve", parents=[shared], help="serve the interface and its backend")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=7860)
+    serve.add_argument("--max-concurrent", type=int, default=2)
+    serve.add_argument("--audit-dir", type=Path, help="also write every run's audit trail to this folder")
+
+    run = commands.add_parser("run", parents=[shared], help="run one search and write the standalone page")
+    run.add_argument("--iv", required=True)
+    run.add_argument("--dv", required=True)
+    run.add_argument("--max-steps", type=int, default=40)
+    run.add_argument("--epsilon", type=float, default=0.1)
+    run.add_argument("--seed", type=int)
+    run.add_argument("--out", type=Path, default=Path("confoundsearch.html"))
+    run.add_argument("--audit", type=Path, help="where to write the audit trail (default: next to --out)")
+    run.add_argument(
+        "--json", action="store_true", help="print the result as JSON (and nothing else) to stdout"
+    )
+
+    audit = commands.add_parser("audit", help="check and read an audit trail written by a run")
+    audit.add_argument("file", type=Path, help="an audit trail (.jsonl)")
+    audit.add_argument(
+        "--json", action="store_true", help="print a machine-readable summary instead of the report"
+    )
+
+    skill = commands.add_parser("install-skill", help="install the Claude Code skill for ConfoundSearch")
+    skill.add_argument("--dir", type=Path, help="skills folder (default: ~/.claude/skills)")
+    skill.add_argument("--project", action="store_true", help="install into ./.claude/skills instead")
+    skill.add_argument("--force", action="store_true", help="overwrite a different SKILL.md")
+    skill.add_argument(
+        "--print", dest="show", action="store_true", help="print the skill instead of installing it"
+    )
+    return parser
+
+
+CORPORA = ("elasticsearch", "semanticscholar", "openalex", "file")
+
+
+def build_corpus(args: argparse.Namespace) -> Corpus:
+    """The papers to search. With nothing chosen, this is the hosted Elasticsearch index."""
+    kind = args.corpus or ("file" if args.corpus_file else "elasticsearch")
+    if args.corpus_file and kind != "file":
+        raise SystemExit("error: --corpus-file goes with --corpus file, not with another source")
+    if kind == "file":
+        if not args.corpus_file:
+            raise SystemExit("error: --corpus file needs --corpus-file PATH")
+        return InMemoryCorpus.from_jsonl(args.corpus_file)
+    if kind == "semanticscholar":
+        return SemanticScholarCorpus(args.s2_key)
+    if kind == "openalex":
+        return OpenAlexCorpus(args.openalex_key, args.openalex_email)
+    if not args.es_url:
+        raise SystemExit(
+            "error: the hosted Elasticsearch index needs ES_URL and ES_API_KEY (put them in a .env file), "
+            "or pick another source: --corpus semanticscholar, --corpus openalex, or --corpus-file PATH"
+        )
+    return ElasticsearchCorpus(args.es_url, args.es_index, args.es_api_key)
+
+
+def build_client(args: argparse.Namespace) -> OpenAICompatibleClient:
+    """The AI model. With --openrouter it is OpenRouter, using your own OPENROUTER_API_KEY."""
+    if not args.openrouter:
+        return OpenAICompatibleClient(args.model, base_url=args.base_url, api_key=args.api_key)
+    key = args.api_key or os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        raise SystemExit("error: --openrouter needs OPENROUTER_API_KEY (put it in a .env file) or --api-key")
+    return OpenAICompatibleClient(args.model, base_url=args.base_url or OPENROUTER_URL, api_key=key)
+
+
+def build_backend(args: argparse.Namespace) -> tuple[Environment, ActionSource]:
+    client = AuditedClient(build_client(args))
+    corpus = build_corpus(args)
+    return Environment(corpus, LLMJudge(client)), Proposer(LLMProposer(client))
+
+
+def skill_text() -> str:
+    return resources.files("confoundsearch.interface.skill").joinpath("SKILL.md").read_text(encoding="utf-8")
+
+
+def install_skill(args: argparse.Namespace) -> int:
+    """Copy the packaged SKILL.md to <skills folder>/confoundsearch/SKILL.md, where Claude Code finds it."""
+    text = skill_text()
+    if args.show:
+        print(text, end="")
+        return 0
+    default = Path.cwd() / ".claude" / "skills" if args.project else Path.home() / ".claude" / "skills"
+    target = (args.dir or default) / "confoundsearch" / "SKILL.md"
+    if target.exists():
+        if target.read_text(encoding="utf-8") == text:
+            print(f"already installed: {target}")
+            return 0
+        if not args.force:
+            print(f"error: {target} exists and differs; use --force to overwrite it", file=sys.stderr)
+            return 1
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+    print(f"installed {target}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    load_dotenv(Path.cwd() / ".env")  # before the parser reads its defaults from the environment
+    args = build_parser().parse_args(argv)
+    if args.command == "install-skill":
+        return install_skill(args)
+    if args.command == "audit":
+        trail = AuditTrail.load(args.file)
+        if args.json:
+            print(json.dumps({"file": str(args.file), **trail.to_dict()}, indent=2))
+        else:
+            print(trail.to_markdown(), end="")
+        return 0 if trail.intact and trail.complete else 1
+    env, proposer = build_backend(args)
+    if args.command == "serve":
+        server = make_server(
+            RunManager(env, proposer, args.max_concurrent, audit_dir=args.audit_dir), args.host, args.port
+        )
+        print(f"ConfoundSearch at http://{args.host}:{server.server_port}", file=sys.stderr)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            server.server_close()
+        return 0
+    policy = EpsilonGreedy(
+        LookaheadQ(env.preview), args.epsilon, random.Random(args.seed), explore_stop=False
+    )
+    audit_path = args.audit or args.out.with_name(f"{args.out.stem}.audit.jsonl")
+    with AuditLog(audit_path) as log:
+        trajectory = run_episode(env, policy, proposer, args.iv, args.dv, args.max_steps, audit=log)
+    args.out.write_text(standalone_html(to_share_data(trajectory.final)), encoding="utf-8")
+    if args.json:
+        print(json.dumps(run_result(trajectory, args.out, audit_path), indent=2))
+        return 0
+    graph = trajectory.final.graph
+    print(f"{len(trajectory.steps)} steps, {len(graph.connected())} connected, phi={trajectory.score:.3f}")
+    print(f"wrote {args.out}")
+    trail = trajectory.audit_trail()
+    chain = "intact" if trail.intact else "BROKEN"
+    print(f"audit trail {audit_path} ({len(trail.events)} events, hash chain {chain})")
+    return 0