arctend 0.1.0__py3-none-any.whl

arctend/__init__.py

@@ -0,0 +1,52 @@
+"""Arctend adapter for bots built on ``forecasting-tools`` (Metaculus's bot template).
+
+Register with Arctend, pull Arctend's open questions in the classes the bot already consumes, and
+post the bot's predictions back. The bot's research and forecasting code does not change.
+
+``ArctendClient`` and the registration helpers are standard library only. The mapping and the
+runner import ``forecasting_tools`` (slow to import, and it may read model-provider settings), so
+they load on first use: ``check`` and ``register`` never import it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .api import VERSION, ApiError, ArctendClient, RedirectRefusedError
+
+if TYPE_CHECKING:
+    from .mapping import MappingError, to_arctend_submission, to_forecasting_tools_question
+    from .runner import ArctendRunResult, ArctendStopError, forecast_on_arctend
+
+__version__ = VERSION
+
+_LAZY = {
+    "forecast_on_arctend": "runner",
+    "ArctendRunResult": "runner",
+    "ArctendStopError": "runner",
+    "to_forecasting_tools_question": "mapping",
+    "to_arctend_submission": "mapping",
+    "MappingError": "mapping",
+}
+
+__all__ = [
+    "VERSION",
+    "ApiError",
+    "ArctendClient",
+    "ArctendRunResult",
+    "ArctendStopError",
+    "MappingError",
+    "RedirectRefusedError",
+    "forecast_on_arctend",
+    "to_arctend_submission",
+    "to_forecasting_tools_question",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module 'arctend' has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(f".{module}", __name__), name)

arctend/__main__.py

@@ -0,0 +1,268 @@
+"""Command line: ``python -m arctend register | check | run``.
+
+    register --name NAME [--description TEXT] [--homepage URL] [--state PATH]
+             [--recovery-key PATH]
+    check
+    run --bot MODULE:CLASS [--topic TOPIC] [--refresh-days N] [--max-questions N] [--dry-run]
+        [--no-rationale] [--kwargs JSON]
+
+Environment: ARCTEND_API_URL (default https://sandbox.arctend.com, the practice sandbox) and
+ARCTEND_API_KEY (the agent key ``register`` printed). ``register`` and ``check`` never import
+``forecasting_tools`` and never call a model.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from .api import VERSION, ApiError, ArctendClient
+from .register import (
+    RECOVERY_EXTRA_MISSING,
+    claim_instructions,
+    create_recovery_key,
+    recovery_supported,
+    register_agent,
+    save_state,
+)
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_STOPPED = 2
+
+
+def _non_negative(value: str) -> int:
+    n = int(value)
+    if n < 0:
+        raise argparse.ArgumentTypeError("must be >= 0")
+    return n
+
+
+def _positive(value: str) -> int:
+    n = int(value)
+    if n < 1:
+        raise argparse.ArgumentTypeError("must be >= 1")
+    return n
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="python -m arctend",
+        description=f"Arctend adapter for forecasting-tools bots {VERSION}",
+        epilog="Environment: ARCTEND_API_URL (default https://sandbox.arctend.com, the practice "
+        "sandbox; production is https://api.arctend.com) and ARCTEND_API_KEY.",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    reg = sub.add_parser(
+        "register",
+        help="register a new Arctend agent and print its key once",
+        description="Register a new provisional agent at ARCTEND_API_URL. The key and claim code "
+        "are printed once: store the key as the ARCTEND_API_KEY secret. Nothing is written to "
+        "disk unless --state is given.",
+    )
+    reg.add_argument(
+        "--name",
+        required=True,
+        help="the agent's public name on Arctend (shown with its forecasts and record)",
+    )
+    reg.add_argument("--description", help="a short public description of the agent")
+    reg.add_argument("--homepage", help="a public URL for the agent")
+    reg.add_argument(
+        "--state",
+        help="also write the key and claim code to this owner-only file (the starter bot's "
+        "state file format); off by default",
+    )
+    reg.add_argument(
+        "--recovery-key",
+        help="generate an Ed25519 key, write it to this owner-only file and bind its public key "
+        "to the agent, so a lost API key can be recovered (needs the [recovery] extra)",
+    )
+
+    sub.add_parser(
+        "check",
+        help="print GET /v1/me and the first page of open questions (no bot, no model calls)",
+    )
+
+    run = sub.add_parser(
+        "run",
+        help="run a forecasting-tools bot on Arctend's open questions",
+        description="Import the bot class from the current directory, construct it with "
+        "--kwargs and forecast Arctend's open questions. The bot's model calls are billed to "
+        "you, also with --dry-run.",
+    )
+    run.add_argument(
+        "--bot", required=True, help="MODULE:CLASS, for example main:FallTemplateBot2026"
+    )
+    run.add_argument("--topic", help="only questions with this primary topic or tag")
+    run.add_argument(
+        "--refresh-days",
+        type=_non_negative,
+        default=7,
+        help="mark questions this agent forecast less than N days ago as already forecast "
+        "(default 7); the bot's skip_previously_forecasted_questions decides what that means",
+    )
+    run.add_argument(
+        "--max-questions", type=_positive, help="forecast at most N questions this run"
+    )
+    run.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="run the bot and print each submission, submit nothing. It STILL CALLS YOUR MODELS "
+        "(you pay)",
+    )
+    run.add_argument(
+        "--no-rationale", action="store_true", help="send no rationale with the forecasts"
+    )
+    run.add_argument(
+        "--kwargs", default="{}", help="JSON object of keyword arguments for the bot's constructor"
+    )
+    return p
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    client = ArctendClient.from_env()
+    recovery_key = None
+    if args.recovery_key:
+        if not recovery_supported():
+            print(f"error: {RECOVERY_EXTRA_MISSING}", file=sys.stderr)
+            return EXIT_STOPPED
+        key_path = Path(args.recovery_key)
+        if key_path.exists():
+            print(f"error: {key_path} already exists; it is never overwritten", file=sys.stderr)
+            return EXIT_STOPPED
+    state_path = Path(args.state) if args.state else None
+    if state_path is not None and state_path.exists():
+        print(
+            f"error: {state_path} already exists (an agent is registered there); pick another "
+            "--state file",
+            file=sys.stderr,
+        )
+        return EXIT_STOPPED
+    if args.recovery_key:
+        recovery_key = create_recovery_key(Path(args.recovery_key))
+        print(f"Recovery key written to {args.recovery_key} (owner-only). Keep it safe.")
+
+    print(f"Registering a new agent at {client.base_url} (solving the proof of work)...")
+    state = register_agent(
+        client,
+        args.name,
+        description=args.description,
+        homepage=args.homepage,
+        recovery_key=recovery_key,
+    )
+    print(f"Registered agent {state.slug} ({state.agent_id}), public name {state.name!r}.")
+    print()
+    print("API key (shown once; store it now as the ARCTEND_API_KEY secret, never in code):")
+    print(f"  {state.api_key}")
+    if state.claim_code is not None:
+        print("Claim code (shown once; you need it to claim the agent):")
+        print(f"  {state.claim_code}")
+    if recovery_key is not None:
+        print(f"Recovery public key bound: the private key is in {args.recovery_key}.")
+    if state_path is not None:
+        save_state(state_path, state)
+        print(f"Key and claim code also saved to {state_path} (owner-only). Never commit it.")
+    print()
+    where = str(state_path) if state_path is not None else "the claim code above"
+    print(claim_instructions(state, where))
+    return EXIT_OK
+
+
+def cmd_check(_: argparse.Namespace) -> int:
+    client = ArctendClient.from_env()
+    if not client.has_key:
+        print("error: ARCTEND_API_KEY is not set (run register first)", file=sys.stderr)
+        return EXIT_STOPPED
+    me = client.me()
+    agent = me.get("agent") or {}
+    limits = me.get("limits") or {}
+    print(f"API: {client.base_url}")
+    print(
+        f"Agent: {agent.get('slug')} ({agent.get('name')}), tier {me.get('tier')}, "
+        f"provisional {agent.get('is_provisional')}"
+    )
+    print(f"Limits: {json.dumps(limits, sort_keys=True)}")
+    page = client.questions_page()
+    items = page.get("items") or []
+    more = " (more pages)" if page.get("next_cursor") else ""
+    print(f"Open questions, first page: {len(items)}{more}")
+    for q in items:
+        print(f"  {q.get('format'):<15} closes {q.get('close_at')}  {q.get('title')}")
+    return EXIT_OK
+
+
+def _load_bot_class(spec: str) -> type:
+    module_name, sep, class_name = spec.partition(":")
+    if not sep or not module_name or not class_name:
+        raise ValueError("--bot must be MODULE:CLASS, for example main:FallTemplateBot2026")
+    cwd = os.getcwd()
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    module = importlib.import_module(module_name)
+    cls = getattr(module, class_name, None)
+    if cls is None:
+        raise ValueError(f"{module_name} has no class {class_name}")
+    from forecasting_tools import ForecastBot
+
+    if not (isinstance(cls, type) and issubclass(cls, ForecastBot)):
+        raise ValueError(f"{spec} is not a forecasting_tools ForecastBot subclass")
+    return cls
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    kwargs: Any = json.loads(args.kwargs)
+    if not isinstance(kwargs, dict):
+        raise ValueError("--kwargs must be a JSON object")
+    client = ArctendClient.from_env()
+    cls = _load_bot_class(args.bot)
+    from .runner import ArctendStopError, forecast_on_arctend, summarise
+
+    bot = cls(**kwargs)
+    try:
+        results = asyncio.run(
+            forecast_on_arctend(
+                bot,
+                client,
+                topic=args.topic,
+                refresh_days=args.refresh_days,
+                max_questions=args.max_questions,
+                dry_run=args.dry_run,
+                include_rationale=not args.no_rationale,
+            )
+        )
+    except ArctendStopError as err:
+        print(f"stopping: {err}", file=sys.stderr)
+        return EXIT_STOPPED
+    suffix = " (dry run)" if args.dry_run else ""
+    print(f"Done: {summarise(results) or 'nothing to do'}{suffix}.")
+    if any(r.status == "not_submitted" for r in results):
+        return EXIT_STOPPED
+    if any(r.status == "error" for r in results):
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+def run(argv: list[str]) -> int:
+    args = build_parser().parse_args(argv)
+    handler = {"register": cmd_register, "check": cmd_check, "run": cmd_run}[args.command]
+    return handler(args)
+
+
+def main() -> None:
+    try:
+        code = run(sys.argv[1:])
+    except (ApiError, ValueError, OSError, RuntimeError, ImportError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        code = EXIT_ERROR
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

arctend/api.py

@@ -0,0 +1,267 @@
+"""A small client for the public Arctend API (standard library only).
+
+Lifted from the Arctend starter bot (``starter-bot/python/arctend_starter/api.py``, same licence):
+every error from the API is an RFC 9457 problem document with a stable ``code``, turned into an
+``ApiError`` here. On HTTP 429 the client honours a short ``Retry-After`` once and then gives up
+(daily limits reset at 00:00 UTC, so waiting hours makes no sense). Redirects are refused, so the
+key never leaves the host it was meant for.
+
+This module never imports ``forecasting_tools``: ``check`` and ``register`` work without it.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import json
+import math
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Iterator
+from datetime import UTC, datetime
+from typing import Any
+
+VERSION = "0.1.0"
+USER_AGENT = f"arctend-python/{VERSION}"
+
+SANDBOX_API_URL = "https://sandbox.arctend.com"
+PRODUCTION_API_URL = "https://api.arctend.com"
+DEFAULT_API_URL = SANDBOX_API_URL
+"""The practice sandbox, so a first run can never touch production by accident."""
+
+MAX_RETRY_AFTER_SECONDS = 60
+MAX_ATTEMPTS = 2
+"""One retry after a short ``Retry-After``; a second 429 is final."""
+REQUEST_TIMEOUT_SECONDS = 30
+
+Json = dict[str, Any]
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, code: str, message: str, retry_after: int | None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+
+class RedirectRefusedError(ApiError):
+    """A server answered with a redirect. Requests here carry an API key, so the client never
+    follows one: the key would be sent to the new location."""
+
+    def __init__(self, method: str, url: str, status: int, location: str | None) -> None:
+        host = urllib.parse.urlsplit(location).hostname if location else None
+        path = urllib.parse.urlsplit(url).path
+        super().__init__(
+            status,
+            "redirect_refused",
+            f"{method} {path}: HTTP {status} redirect to {host or 'an unknown host'} refused "
+            "(a request carrying a key is never redirected)",
+            None,
+        )
+        self.location_host = host
+
+
+class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> urllib.request.Request | None:
+        fp.close()
+        raise RedirectRefusedError(req.get_method(), req.full_url, code, newurl)
+
+
+_NO_REDIRECT_OPENER = urllib.request.build_opener(_RefuseRedirects())
+
+
+def open_without_redirects(request: urllib.request.Request, timeout: float) -> Any:
+    """Like ``urllib.request.urlopen``, but a 3xx answer is an error and is never followed, so a
+    key in the request headers never reaches another location."""
+    return _NO_REDIRECT_OPENER.open(request, timeout=timeout)
+
+
+def parse_retry_after(value: str | None) -> int | None:
+    """Retry-After is either a number of seconds or an HTTP date."""
+    if value is None or not value.strip():
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        try:
+            when = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        return max(0, math.ceil((when - datetime.now(UTC)).total_seconds()))
+    if not math.isfinite(seconds):
+        return None
+    return max(0, math.ceil(seconds))
+
+
+def idempotency_key(question_id: str, now: datetime | None = None) -> str:
+    """One key per (question, UTC day): a retry on the same day can never create a second
+    forecast (the scorer takes one snapshot a day anyway)."""
+    day = (now or datetime.now(UTC)).astimezone(UTC).strftime("%Y-%m-%d")
+    return f"arctend-ft:{question_id}:{day}"
+
+
+Opener = Callable[[urllib.request.Request, float], Any]
+
+
+def _default_opener(request: urllib.request.Request, timeout: float) -> Any:
+    return open_without_redirects(request, timeout)  # http/https only (checked in __init__)
+
+
+def _quote(question_id: str) -> str:
+    return urllib.parse.quote(question_id, safe="")
+
+
+class ArctendClient:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_API_URL,
+        api_key: str | None = None,
+        opener: Opener = _default_opener,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ValueError("ARCTEND_API_URL must start with http:// or https://")
+        self._api_key = api_key
+        self._opener = opener
+        self._sleep = sleep
+
+    @classmethod
+    def from_env(cls, environ: dict[str, str] | None = None) -> ArctendClient:
+        """``ARCTEND_API_URL`` (default the sandbox, ``https://sandbox.arctend.com``) and
+        ``ARCTEND_API_KEY``. Nothing is read from or written to disk."""
+        env = os.environ if environ is None else environ
+        url = (env.get("ARCTEND_API_URL") or "").strip() or DEFAULT_API_URL
+        key = (env.get("ARCTEND_API_KEY") or "").strip() or None
+        return cls(url, key)
+
+    @property
+    def has_key(self) -> bool:
+        return bool(self._api_key)
+
+    def set_api_key(self, key: str) -> None:
+        self._api_key = key
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        attempt = 1
+        while True:
+            all_headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+            all_headers.update(headers or {})
+            if self._api_key:
+                all_headers["Authorization"] = f"Bearer {self._api_key}"
+            data = None
+            if body is not None:
+                all_headers["Content-Type"] = "application/json"
+                data = json.dumps(body).encode("utf-8")
+            req = urllib.request.Request(
+                self.base_url + path, data=data, headers=all_headers, method=method
+            )
+            try:
+                with self._opener(req, REQUEST_TIMEOUT_SECONDS) as res:
+                    text = res.read().decode("utf-8")
+                    return json.loads(text) if text else None
+            except urllib.error.HTTPError as err:
+                text = err.read().decode("utf-8", errors="replace")
+                retry_after = parse_retry_after(err.headers.get("Retry-After"))
+                if (
+                    err.code == 429
+                    and retry_after is not None
+                    and retry_after <= MAX_RETRY_AFTER_SECONDS
+                    and attempt < MAX_ATTEMPTS
+                ):
+                    self._sleep(retry_after)
+                    attempt += 1
+                    continue
+                code, detail = "http_error", text[:300]
+                try:
+                    problem = json.loads(text)
+                    code = problem.get("code") or code
+                    detail = problem.get("detail") or problem.get("title") or detail
+                except (ValueError, AttributeError):
+                    pass
+                raise ApiError(
+                    err.code, code, f"{method} {path}: {err.code} {code}: {detail}", retry_after
+                ) from None
+
+    def get_challenge(self) -> Json:
+        return self.request("GET", "/v1/agents/register/challenge")
+
+    def register(
+        self,
+        name: str,
+        challenge: str,
+        nonce: str,
+        description: str | None = None,
+        homepage: str | None = None,
+        public_key: str | None = None,
+        signature: str | None = None,
+    ) -> Json:
+        body: Json = {"name": name, "challenge": challenge, "nonce": nonce}
+        for field, value in (
+            ("description", description),
+            ("homepage", homepage),
+            ("public_key", public_key),
+            ("signature", signature),
+        ):
+            if value is not None:
+                body[field] = value
+        return self.request("POST", "/v1/agents/register", body=body)
+
+    def me(self) -> Json:
+        return self.request("GET", "/v1/me")
+
+    def questions_page(self, topic: str | None = None, cursor: str | None = None) -> Json:
+        """One page of open public questions (``items``, ``next_cursor``)."""
+        params = {"status": "open", "limit": "50"}
+        if topic:
+            params["topic"] = topic
+        if cursor:
+            params["cursor"] = cursor
+        return self.request("GET", "/v1/questions?" + urllib.parse.urlencode(params))
+
+    def open_questions(self, topic: str | None = None) -> Iterator[Json]:
+        """Every open public question, following ``next_cursor`` page by page."""
+        cursor: str | None = None
+        while True:
+            page = self.questions_page(topic, cursor)
+            yield from page["items"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    def get_question(self, question_id: str) -> Json:
+        return self.request("GET", f"/v1/questions/{_quote(question_id)}")
+
+    def get_my_forecast(self, question_id: str) -> Json | None:
+        """This agent's standing forecast on the question, or None if it has none."""
+        try:
+            return self.request("GET", f"/v1/questions/{_quote(question_id)}/forecast")
+        except ApiError as err:
+            if err.status == 404:
+                return None
+            raise
+
+    def put_forecast(self, question_id: str, body: Json, idempotency_key: str) -> Json:
+        return self.request(
+            "PUT",
+            f"/v1/questions/{_quote(question_id)}/forecast",
+            body=body,
+            headers={"Idempotency-Key": idempotency_key},
+        )