mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/costs.py

@@ -0,0 +1,161 @@
+"""Spend caps, the priced spend a run has observed (integer nanodollars until the public JSON boundary), the cost
+estimate before a Smart task and ``meter``, which puts every model call in the usage ledger."""
+
+import math
+import re
+import time
+import uuid
+
+from . import harness_api
+from .engines import OPENAI_SMART_MODEL, on_plan, provider_name, smart_model
+
+NANODOLLARS = 1_000_000_000
+
+
+def usd_to_nanodollars(value):
+    """Operator cap to integer nanodollars. None stays None (unenforced)."""
+    if value is None:
+        return None
+    if type(value) not in (int, float) or not math.isfinite(value) or value <= 0:
+        raise ValueError("Spend cap must be a positive USD amount")
+    return math.ceil(value * NANODOLLARS)
+
+
+class SpendLedger:
+    """Priced spend observed so far. Unpriced calls are counted, never zero-filled, so the total is never mistaken for a
+    billing record."""
+
+    def __init__(self):
+        self.cost_nanodollars = 0
+        self.priced_calls = 0
+        self.unpriced_calls = 0
+
+    def add_event(self, event):
+        """Fold one ``inference_finished`` event into the totals. Returns True if counted."""
+        if not isinstance(event, dict) or event.get("event") != "inference_finished":
+            return False
+        cost = event.get("cost_nanodollars")
+        if type(cost) is int and 0 <= cost <= 9_007_199_254_740_991:
+            self.cost_nanodollars += cost
+            self.priced_calls += 1
+        else:
+            self.unpriced_calls += 1
+        return True
+
+
+# What a Smart task costs, fitted on recorded runs of this loop on gpt-5.6-sol at list prices (27 Sep): the 152
+# iOSWorld runs of sol-a/b, ab6 and ab7 (research/iosworld-runs) and 32 app runs on simulator 4, split by task,
+# 70% to fit (app runs weighted 3x: they are the product) and 30% held out.
+# log(cost) = a + b·log(words in the request) + c·(apps it names, up to 6). Held out, the estimate is within 2x
+# of the actual cost on 46 of 56 runs (82%; the per-turn model it replaces managed 57% on the iOSWorld part),
+# median actual/estimate 0.78; on ab7-b1/b2 30 of 32 (was 11). On app runs it errs high: median 0.67, within
+# 2x on 16 of 32 (short tasks cost 1.7-14 cents for the same request). tests/smart_costs.json holds the runs
+# and test_engines pins the held-out rate.
+SMART_FIT = (-4.48, 0.615, 0.163)
+SMART_MAX_APPS = 6
+# The range around the estimate: halved to doubled holds about 80% of the recorded runs (10th and 90th
+# percentiles of actual/estimate: 0.50 and 1.94).
+SMART_SPREAD = 2.0
+# the answer put into a structure (the user's schema, or an automatic format): one small call
+SMART_STRUCTURE_USD = 0.004
+# The fit is sol's (OPENAI_SMART_MODEL), not SMART_CONFIG.model's; another model's tasks cost this multiple of sol's
+# on the same tasks, both at list prices (sol at $4/$20). Paired iOSWorld A/B, 16 never-run tasks, 28 Sep: Sonnet 5.5
+# $0.197 against sol's $0.291 a task (32 runs and 21; 95% CI of the difference -$0.143 to -$0.044), Opus 5.5 $0.297
+# (16 runs).
+SMART_COST_RATIO = {OPENAI_SMART_MODEL: 1.0, "claude-sonnet-5-5": 0.68, "claude-opus-5-5": 1.02,
+                    # Haiku 5.5 planning with code-checked steps cost 0.059-0.066 of Sonnet 5.5 on the same 16 tasks
+                    # (paired A/Bs on the phone, 9 Oct): 0.68 x 0.065. gpt-6.1-sol's list price is half sol's, and a
+                    # recorded turn cost 0.46 of sol's (9 Oct).
+                    "claude-haiku-5-5": 0.044, "gpt-6.1-sol": 0.46}
+
+
+def named_apps(goal, app_names=()):
+    """How many of ``app_names`` the request names (whole words, any case)."""
+    folded = " ".join(str(goal or "").split()).casefold()
+    return sum(1 for name in set(app_names) if len(name) > 2
+               and re.search(rf"\b{re.escape(name.casefold())}\b", folded))
+
+
+def smart_point(goal, app_names=()):
+    """The likeliest cost (USD) of a Smart task for ``goal``: longer requests that name more apps cost more."""
+    words = max(1, len(str(goal or "").split()))
+    a, b, c = SMART_FIT
+    return math.exp(a + b * math.log(words) + c * min(SMART_MAX_APPS, named_apps(goal, app_names)))
+
+
+def smart_estimate(goal, app_names=(), *, available=True, reason=None, structured=False, model=None):
+    model = model or smart_model()
+    if on_plan(model):
+        # Nothing per call: the run uses the person's plan allowance (``billing`` says so to the UI).
+        return {"available": available, "reason": reason, "model": model, "provider": provider_name(model),
+                "lowUsd": 0.0, "highUsd": 0.0, "billing": "plan"}
+    point = smart_point(goal, app_names) * SMART_COST_RATIO.get(model, 1.0) + (SMART_STRUCTURE_USD if structured else 0)
+    return {"available": available, "reason": reason, "model": model, "provider": provider_name(model),
+            "lowUsd": round(point / SMART_SPREAD, 4), "highUsd": round(point * SMART_SPREAD, 4)}
+
+
+def midpoint(estimate):
+    """The estimate's single figure: the geometric mean of its range."""
+    low, high = estimate["lowUsd"], estimate["highUsd"]
+    return round(math.sqrt(low * high), 4) if low > 0 and high > 0 else high
+
+
+def meter(client, emit, *, provider=None, purpose=None):
+    """Wrap ``client.complete`` so every model call emits inference_started / inference_finished with its
+    list-price cost (the usage ledger and the spend limits read those). A hedging client's losing twin is billed, so it
+    is a call of its own."""
+    from .model_clients import cost_usd
+    inner = client.complete
+    client.model_failed = False
+    provider = provider or getattr(client, "provider", None) or "openai"
+
+    def complete(messages, schema, **kwargs):
+        call_id = uuid.uuid4().hex[:16]
+        model = getattr(client, "model", "") or "unknown"
+        kind = purpose or ("planning" if "items" in (schema.get("properties") or {}) and "actions" not in (
+            schema.get("properties") or {}) else "decision")
+        meta = {"provider": provider, "call_id": call_id, "model": model, "purpose": kind}
+        if on_plan(model):
+            providers = harness_api.hooks().model_routes()
+            meta["plan"] = providers.plan_name(providers.get(providers.split(model)[0]))  # "On your Kimi Code plan"
+        emit({"event": "inference_started", **meta})
+        started = time.monotonic()
+        try:
+            out, usage = inner(messages, schema, **kwargs)
+        except Exception as error:
+            client.model_failed = True
+            emit({"event": "inference_finished", **meta, "success": False,
+                  "latency_ms": round((time.monotonic() - started) * 1000, 2), "usage": {},
+                  "error_type": type(error).__name__, "estimated_usd": None, "cost_nanodollars": None,
+                  "cost_basis": None})
+            raise
+        if kind != "planning":
+            # The task contract compiles alongside the first decision (the early decision): its success, which
+            # may land later, never hides that decision's failure.
+            client.model_failed = False
+        usage = usage or {}
+        finished(meta, usage, started)
+        return out, usage
+
+    def finished(meta, usage, started):
+        prompt, completion = int(usage.get("prompt_tokens", 0)), int(usage.get("completion_tokens", 0))
+        usd = cost_usd(meta["model"], usage)
+        basis = "plan" if on_plan(meta["model"]) else "published_rate"
+        emit({"event": "inference_finished", **meta, "success": True,
+              "latency_ms": round((time.monotonic() - started) * 1000, 2),
+              "usage": {"input_tokens": prompt, "output_tokens": completion, "total_tokens": prompt + completion,
+                        "cached_input_tokens": int(usage.get("cached_tokens", 0))},
+              "estimated_usd": usd, "cost_nanodollars": None if usd is None else round(usd * NANODOLLARS),
+              "cost_basis": None if usd is None else basis})
+
+    def hedged(usage):
+        meta = {"provider": provider, "call_id": uuid.uuid4().hex[:16],
+                "model": getattr(client, "model", "") or "unknown", "purpose": "hedge" if purpose is None
+                else f"{purpose}_hedge"}
+        emit({"event": "inference_started", **meta})
+        finished(meta, usage or {}, time.monotonic())
+
+    client.complete = complete
+    if hasattr(client, "on_hedge_usage"):
+        client.on_hedge_usage = hedged
+    return client

mobile_agent/decider_scope.py

@@ -0,0 +1,40 @@
+"""What a decision model may decide, as code (owner rule, 2026-10-09)."""
+
+from .task_policy import COMMIT_CONTROL, GUARD_WORDS, SHEET_OPENERS
+
+TARGET, CHECK, BRANCH = "target", "check", "branch"
+KINDS = (TARGET, CHECK, BRANCH)
+# Text, long presses (context menus hold commits), point taps, text macros and the run's endings are the planner's.
+NAVIGATION_OPS = frozenset({"TAP", "SWIPE_UP", "SWIPE_DOWN", "SWIPE_LEFT", "SWIPE_RIGHT", "DISMISS", "HOME",
+                            "LAUNCH_APP", "WAIT"})
+CHECK_TOPICS = frozenset({"settled", "toast", "popup", "screen_is", "item_visible", "evidence", "item_relevant",
+                          "item_ad"})
+# Roles that change a setting when tapped are never a decider's target.
+STATEFUL_ROLES = frozenset({"Switch", "Toggle", "Slider", "Stepper", "PickerWheel", "Picker"})
+
+
+class OutOfScope(ValueError):
+    """The decision model was asked, or answered, outside navigation and classification."""
+
+
+def commits(element):
+    """True when tapping ``element`` may commit something (or its label can't be read)."""
+    if element is None:
+        return True
+    label = " ".join((getattr(element, "label", "") or "").split()[:GUARD_WORDS])
+    if getattr(element, "role", "") in STATEFUL_ROLES or getattr(element, "editable", False):
+        return True
+    return bool(COMMIT_CONTROL.search(label)) and label.casefold() not in SHEET_OPENERS
+
+
+def admit(kind, *, op=None, topic=None):
+    """Raise OutOfScope unless a question of ``kind`` may go to a decision model."""
+    if kind not in KINDS:
+        raise OutOfScope(f"unknown decision kind {kind!r}")
+    if kind == TARGET:
+        if op not in NAVIGATION_OPS:
+            raise OutOfScope(f"{op} is the planner's: a decision model only navigates")
+    elif kind == CHECK:
+        if topic not in CHECK_TOPICS:
+            raise OutOfScope(f"check {topic!r} is not a state check a decision model may answer")
+

mobile_agent/decision_provider.py

@@ -0,0 +1,189 @@
+"""Decision models behind one seam: typed closed questions answered with probabilities, no text generated."""
+
+import base64
+import http.client
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+
+JEV_BASE_URL = "https://api.typesafe.ai/v1"
+
+# USD per 1M input tokens (output is free on both), read 2026-10-09.
+DECISION_PRICES = {"gpt-6-luna": 0.10, "jev-latest": 0.042}
+OPENAI_HOST = "api.openai.com"
+# A single choice question's option cap (Jev documents 255). OpenAI's is measured by bench/decide_gate.py.
+MAX_OPTIONS = 255
+
+
+@dataclass(frozen=True)
+class Question:
+    kind: str                     # "choice" | "yesno"
+    instructions: str
+    options: dict = field(default_factory=dict)   # choice: {value: description}
+
+    def __post_init__(self):
+        if self.kind not in ("choice", "yesno"):
+            raise ValueError(f"unknown question kind {self.kind!r}")
+        if self.kind == "choice" and not 2 <= len(self.options) <= MAX_OPTIONS:
+            raise ValueError("a choice needs 2 to 255 options")
+
+
+@dataclass(frozen=True)
+class Answer:
+    kind: str
+    choice: str = None            # choice: the winning value
+    probabilities: dict = field(default_factory=dict)
+    yes: float = None             # yesno: P(yes)
+    confidence: float = None
+
+    @property
+    def top(self):
+        """The winning probability (choice) or the probability of the answer given (yesno)."""
+        if self.kind == "choice":
+            return self.probabilities.get(self.choice)
+        return None if self.yes is None else max(self.yes, 1 - self.yes)
+
+
+def _prob(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 <= value <= 1:
+        raise ValueError("bad probability")
+    return float(value)
+
+
+def parse_choice(raw, options):
+    """An Answer for a choice, or None when it is malformed or names a value that was not offered."""
+    try:
+        probs = raw["probabilities"]
+        if isinstance(probs, list):
+            mapped = {item["value"]: item["probability"] for item in probs}
+            if len(mapped) != len(probs):
+                return None
+            probs = mapped
+        probs = {str(k): _prob(v) for k, v in probs.items()}
+        choice = str(raw["choice"])
+        if choice not in options or not set(probs) <= set(options) or abs(sum(probs.values()) - 1) > .03:
+            return None
+        if probs.get(choice, 0) < max(probs.values()) - 1e-6:
+            return None
+        confidence = raw.get("confidence")
+        return Answer("choice", choice=choice, probabilities=probs,
+                      confidence=_prob(confidence) if confidence is not None else None)
+    except (KeyError, TypeError, ValueError, AttributeError):
+        return None
+
+
+def parse_yesno(raw):
+    try:
+        value = raw.get("probability", raw.get("noul"))
+        return Answer("yesno", yes=_prob(value), confidence=_prob(raw["confidence"]) if "confidence" in raw else None)
+    except (KeyError, TypeError, ValueError, AttributeError):
+        return None
+
+
+class DecisionProvider:
+    name = "decision"
+    model = ""
+    sees_images = False
+
+    def __init__(self):
+        self.calls, self.input_tokens, self.latencies = 0, 0, []
+        self._lock = threading.Lock()
+
+    def ask(self, context, questions, image=None, timeout=20):
+        raise NotImplementedError
+
+    def _record(self, started, usage):
+        with self._lock:
+            self.calls += 1
+            self.input_tokens += int((usage or {}).get("input_tokens") or 0)
+            self.latencies.append(time.monotonic() - started)
+
+    @property
+    def cost_usd(self):
+        return self.input_tokens * DECISION_PRICES.get(self.model, 0.0) / 1e6
+
+
+class OpenAIDecisions(DecisionProvider):
+    name = "openai"
+    sees_images = True
+
+    def __init__(self, model="gpt-6-luna", key=None, host=OPENAI_HOST):
+        super().__init__()
+        self.model, self.host = model, host
+        self.key = key or os.environ.get("OPENAI_API_KEY", "")
+        if not self.key:
+            raise ValueError("OPENAI_API_KEY is not set")
+
+    def body(self, context, questions, image=None):
+        content = [{"type": "input_text", "text": context}]
+        if image is not None:
+            data = image if isinstance(image, str) else "data:image/jpeg;base64," + base64.b64encode(image).decode()
+            content.append({"type": "input_image", "image_url": data})
+        wire = []
+        for name, q in questions.items():
+            if q.kind == "choice":
+                wire.append({"type": "choice", "name": name, "instructions": q.instructions,
+                             "choices": [{"value": k, "description": v} for k, v in q.options.items()]})
+            else:
+                wire.append({"type": "predicate", "name": name, "instructions": q.instructions})
+        return {"model": self.model, "input": [{"role": "user", "content": content}], "questions": wire}
+
+    def ask(self, context, questions, image=None, timeout=20):
+        payload = json.dumps(self.body(context, questions, image)).encode()
+        started = time.monotonic()
+        connection = http.client.HTTPSConnection(self.host, timeout=timeout)
+        try:
+            connection.request("POST", "/v1/decisions", payload,
+                               {"Authorization": "Bearer " + self.key, "Content-Type": "application/json"})
+            response = connection.getresponse()
+            raw = response.read()
+        finally:
+            connection.close()
+        if response.status != 200:
+            raise RuntimeError(f"OpenAI decisions HTTP {response.status}: {raw[:300].decode(errors='replace')}")
+        data = json.loads(raw)
+        self._record(started, data.get("usage"))
+        by_name = {a.get("name"): a for a in data.get("answers") or () if isinstance(a, dict)}
+        return {name: (parse_choice(by_name.get(name), q.options) if q.kind == "choice"
+                       else parse_yesno(by_name.get(name))) if name in by_name else None
+                for name, q in questions.items()}
+
+
+class JevDecisions(DecisionProvider):
+    name = "jev"
+    sees_images = False
+
+    def __init__(self, model=None, key=None):
+        super().__init__()
+        from .http_pool import pooled_http
+        key = key or os.environ.get("TYPESAFE_API_KEY")
+        if not key:
+            raise ValueError("TYPESAFE_API_KEY is not set")
+        self.model = model or os.environ.get("TYPESAFE_MODEL", "jev-latest")
+        self.http = pooled_http(JEV_BASE_URL, key)
+
+    def ask(self, context, questions, image=None, timeout=20):
+        wire = {}
+        for name, q in questions.items():
+            if q.kind == "choice":
+                wire[name] = {"type": "choice", "criteria": dict(q.options), "instructions": q.instructions}
+            else:
+                wire[name] = {"type": "noul", "instructions": q.instructions}
+        started = time.monotonic()
+        response = self.http.request("POST", "/systemone", {"model": self.model, "state": {"context": context},
+                                                           "questions": wire}, timeout)
+        self._record(started, (response or {}).get("usage"))
+        answers = (response or {}).get("answers") or {}
+        return {name: (parse_choice(answers.get(name), q.options) if q.kind == "choice"
+                       else parse_yesno(answers.get(name))) if name in answers else None
+                for name, q in questions.items()}
+
+
+def provider(name, **kwargs):
+    if name == "openai":
+        return OpenAIDecisions(**kwargs)
+    if name == "jev":
+        return JevDecisions(**kwargs)
+    raise ValueError(f"unknown decision provider {name!r}")