askround 0.1.0__py3-none-any.whl

askround/__init__.py

@@ -0,0 +1,3 @@
+"""askround: ask several AI assistants the same question and keep their answers."""
+
+__version__ = "0.1.0"

askround/__main__.py

@@ -0,0 +1,3 @@
+from askround.cli import main
+
+raise SystemExit(main())

askround/budget.py

@@ -0,0 +1,108 @@
+"""The person's budget: what askround may spend a day and a month, and what it has spent.
+
+askround spends money on the user's keys, and an agent with the MCP tools can run rounds
+on its own, in a loop. So the person sets a budget in askround's config file, which no
+MCP tool writes (law L5: the person, never the agent, sets the money):
+
+    # %APPDATA%\\askround\\config.toml on Windows, ~/.config/askround/config.toml
+    # elsewhere, or the file ASKROUND_CONFIG names
+    [budget]
+    day = 1.00      # USD
+    month = 10.00
+
+Every saved round adds its actual cost to a ledger, `spent.jsonl` beside the rounds. A
+run whose estimate would take the day's or the month's spending past the budget is not
+run: it is refused before any call, with the estimate, the spending so far and the
+budget, as a request for the person's approval. Only the person approves - with
+`--approve` on the command line, which the MCP tools do not offer - or raises the budget.
+Days and months are counted in UTC.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tomllib
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+LEDGER = "spent.jsonl"
+
+
+@dataclass(frozen=True)
+class Budget:
+    day: float | None = None
+    month: float | None = None
+
+
+def config_path() -> Path:
+    if os.environ.get("ASKROUND_CONFIG"):
+        return Path(os.environ["ASKROUND_CONFIG"])
+    if sys.platform == "win32" and os.environ.get("APPDATA"):
+        return Path(os.environ["APPDATA"]) / "askround" / "config.toml"
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "askround" / "config.toml"
+
+
+def load() -> Budget:
+    path = config_path()
+    if not path.is_file():
+        return Budget()
+    data = tomllib.loads(path.read_text(encoding="utf-8")).get("budget") or {}
+    return Budget(_amount(data.get("day")), _amount(data.get("month")))
+
+
+def _amount(value) -> float | None:
+    return float(value) if isinstance(value, int | float) and value >= 0 else None
+
+
+def record(out: Path, cost: float | None, question: str, now: datetime | None = None) -> None:
+    """Add a saved round's actual cost to the ledger (a cost the table cannot price is 0)."""
+    out.mkdir(parents=True, exist_ok=True)
+    moment = (now or datetime.now(UTC)).astimezone(UTC)
+    entry = {"at": moment.isoformat(), "cost": round(cost or 0.0, 6), "question": question[:120]}
+    with (out / LEDGER).open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def spent(out: Path, now: datetime | None = None) -> tuple[float, float]:
+    """USD spent today and this month, from the ledger."""
+    moment = (now or datetime.now(UTC)).astimezone(UTC)
+    day, month = moment.strftime("%Y-%m-%d"), moment.strftime("%Y-%m")
+    today = this_month = 0.0
+    path = out / LEDGER
+    if path.is_file():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            entry = json.loads(line)
+            if entry["at"][:7] == month:
+                this_month += entry["cost"]
+                if entry["at"][:10] == day:
+                    today += entry["cost"]
+    return round(today, 6), round(this_month, 6)
+
+
+def status(out: Path, now: datetime | None = None) -> dict:
+    """What has been spent against the budget; reported with every paid result."""
+    today, month = spent(out, now)
+    limits = load()
+    return {
+        "today": today,
+        "month": month,
+        "budget": {"day": limits.day, "month": limits.month},
+        "config": str(config_path()),
+    }
+
+
+def over(out: Path, estimate: float, now: datetime | None = None) -> str | None:
+    """Why this run would pass the budget, or None when it fits (or there is none)."""
+    limits = load()
+    today, month = spent(out, now)
+    if limits.day is not None and today + estimate > limits.day:
+        return f"today ${today:.4f} spent + ${estimate:.4f} estimated > the day's budget ${limits.day:.2f}"
+    if limits.month is not None and month + estimate > limits.month:
+        return f"this month ${month:.4f} spent + ${estimate:.4f} estimated > the month's budget ${limits.month:.2f}"
+    return None

askround/citations.py

@@ -0,0 +1,172 @@
+"""Which pages an answer cites, and which of them are the product's own.
+
+An answer's citations are the sources its provider reported (AR2) plus the links
+written in its text, one per page: URLs are normalised so the same page counts once
+(tracking parameters such as OpenAI's `utm_source=openai` and fragments dropped, the
+host lower-cased, `www.` removed). Gemini reports its sources as
+`vertexaisearch.cloud.google.com/grounding-api-redirect/...` links titled with the
+domain; askround reads the domain from the title rather than following each redirect,
+so a Gemini citation is known by its site, not its page.
+
+A product's places are the names given for it that contain a dot: a domain
+(`modelado.app`, which covers its subdomains) or a URL prefix
+(`github.com/alegauss/modelado`). A cited page on one of them is the product's, and is
+classified by kind - repository (GitHub, GitLab, Hugging Face, ...), store (Microsoft
+Store, Google Play, App Store, ...), docs (a `docs.` host or a `/docs` path) or site.
+Every other page is third-party, counted by domain, and attributed to a rival when the
+rival's name is in its address or title.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from askround import mention
+
+REDIRECT_HOSTS = ("vertexaisearch.cloud.google.com",)
+_TRACKING = re.compile(r"^(utm_\w+|ref|ref_src|fbclid|gclid)$", re.IGNORECASE)
+_LINK = re.compile(r"https?://[^\s)\]>\"'`]+")
+
+REPOSITORY_HOSTS = (
+    "github.com",
+    "gitlab.com",
+    "bitbucket.org",
+    "huggingface.co",
+    "sourceforge.net",
+)
+STORE_HOSTS = (
+    "apps.microsoft.com",
+    "microsoft.com/store",
+    "microsoft.com/p/",
+    "play.google.com",
+    "apps.apple.com",
+    "store.steampowered.com",
+    "itch.io",
+)
+
+
+@dataclass(frozen=True)
+class Cited:
+    url: str  # normalised; for a redirect, "https://<domain>/" read from its title
+    host: str
+    title: str = ""
+    redirect: bool = False
+
+
+def _host(netloc: str) -> str:
+    host = netloc.lower().split("@")[-1].split(":")[0]
+    return host[4:] if host.startswith("www.") else host
+
+
+def normalise(url: str, title: str = "") -> Cited | None:
+    parts = urlsplit(url.strip().rstrip(".,;"))
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        return None
+    host = _host(parts.netloc)
+    if host in REDIRECT_HOSTS:
+        domain = _host(title.strip()) if "." in title else ""
+        if not domain:
+            return None
+        return Cited(f"https://{domain}/", domain, title, redirect=True)
+    query = urlencode([(k, v) for k, v in parse_qsl(parts.query) if not _TRACKING.match(k)])
+    path = parts.path.rstrip("/") or "/"
+    return Cited(urlunsplit(("https", host, path, query, "")), host, title)
+
+
+def cited(answer) -> list[Cited]:
+    """The answer's pages: its reported sources, then the links in its text."""
+    pages: dict[str, Cited] = {}
+    for source in answer.sources:
+        page = normalise(source.url, source.title)
+        if page:
+            pages.setdefault(page.url, page)
+    for link in _LINK.findall(answer.text):
+        page = normalise(link)
+        if page:
+            pages.setdefault(page.url, page)
+    return list(pages.values())
+
+
+def places(names: list[str]) -> list[str]:
+    """The product's own places among its names: "modelado.app", "github.com/x/y"."""
+    return [
+        n.lower().removeprefix("https://").removeprefix("http://").removeprefix("www.").rstrip("/")
+        for n in names
+        if "." in n
+    ]
+
+
+def _address(page: Cited) -> str:
+    rest = urlsplit(page.url).path
+    return f"{page.host}{'' if rest == '/' else rest}"
+
+
+def owns(place: str, page: Cited) -> bool:
+    if "/" not in place:
+        return page.host == place or page.host.endswith("." + place)
+    return (_address(page) + "/").lower().startswith(place + "/") or _address(page).lower() == place
+
+
+def kind(page: Cited) -> str:
+    address = _address(page).lower()
+    if any(address.startswith(h) or page.host == h for h in REPOSITORY_HOSTS):
+        return "repository"
+    if any(address.startswith(h) for h in STORE_HOSTS):
+        return "store"
+    if page.host.startswith("docs.") or "/docs" in address:
+        return "docs"
+    return "site"
+
+
+@dataclass
+class ProductCitations:
+    """How one provider's answers cited one product's pages."""
+
+    provider: str
+    answers: int = 0
+    citing: int = 0  # answers that cited at least one of the product's pages
+    kinds: dict[str, int] = field(default_factory=dict)  # kind -> answers citing it
+    pages: dict[str, int] = field(default_factory=dict)  # url -> answers citing it
+
+
+def product_citations(round_, names: list[str]) -> list[ProductCitations]:
+    own = places(names)
+    table: dict[str, ProductCitations] = {}
+    for r in round_.results:
+        row = table.setdefault(r.provider, ProductCitations(r.provider))
+        if r.answer is None:
+            continue
+        row.answers += 1
+        mine = [p for p in cited(r.answer) if any(owns(place, p) for place in own)]
+        if mine:
+            row.citing += 1
+        for k in {kind(p) for p in mine}:
+            row.kinds[k] = row.kinds.get(k, 0) + 1
+        for page in {p.url for p in mine}:
+            row.pages[page] = row.pages.get(page, 0) + 1
+    return list(table.values())
+
+
+def third_party(round_, products: list[list[str]], rival_names: list[str]) -> dict:
+    """Pages that are no product's own: answers citing each domain, and each rival's."""
+    own = [place for names in products for place in places(names)]
+    domains: dict[str, int] = {}
+    by_rival: dict[str, int] = {}
+    for r in round_.results:
+        if r.answer is None:
+            continue
+        pages = [p for p in cited(r.answer) if not any(owns(place, p) for place in own)]
+        for host in {p.host for p in pages}:
+            domains[host] = domains.get(host, 0) + 1
+        for rival in rival_names:
+            needle = mention.core(rival).lower()
+            squashed = needle.replace(" ", "")
+            if any(
+                squashed in _address(p).lower().replace("-", "") or needle in p.title.lower()
+                for p in pages
+            ):
+                by_rival[rival] = by_rival.get(rival, 0) + 1
+    ranked = dict(sorted(domains.items(), key=lambda kv: (-kv[1], kv[0])))
+    return {"domains": ranked, "rivals": by_rival}

askround/claims.py

@@ -0,0 +1,61 @@
+"""What a round's answers claim about one product, aggregated.
+
+The extraction pass (extract.py) reads every claim an answer makes about the products
+it names, as attribute and value with a verbatim quote. For one product, this groups
+them by attribute and value - so 'CPU only: Check build' in two answers is one line
+seen twice - with the providers that made each and the first verified quote as its
+passage. A claim whose quote is not in the answer is counted apart as unverified,
+never mixed with the ones that trace to their passage (law L4).
+
+Attributes are grouped case-insensitively and with whitespace collapsed; the spelling
+first seen is the one shown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from askround import mention
+from askround.provenance import answer_id, span
+
+
+@dataclass
+class ProductClaim:
+    attribute: str
+    value: str
+    answers: int = 0
+    providers: dict[str, int] = field(default_factory=dict)
+    quote: str = ""
+    unverified: int = 0
+    # each answer that made it: {"answer": "openai#2", "range": [start, end]}
+    found_in: list[dict] = field(default_factory=list)
+
+
+def _fold(text: str) -> str:
+    return " ".join(text.lower().split())
+
+
+def product_claims(round_, names: list[str]) -> list[ProductClaim]:
+    target = mention.pattern(names)
+    table: dict[tuple[str, str], ProductClaim] = {}
+    for r in round_.results:
+        answer = r.answer
+        if answer is None or not answer.claims:
+            continue
+        seen: set[tuple[str, str]] = set()
+        for claim in answer.claims:
+            if not target.search(claim.product):
+                continue
+            k = (_fold(claim.attribute), _fold(claim.value))
+            row = table.setdefault(k, ProductClaim(claim.attribute, claim.value))
+            if not claim.verified:
+                row.unverified += 1
+                continue
+            if k in seen:
+                continue
+            seen.add(k)
+            row.answers += 1
+            row.providers[r.provider] = row.providers.get(r.provider, 0) + 1
+            row.quote = row.quote or claim.quote
+            row.found_in.append({"answer": answer_id(r), "range": span(answer.text, claim.quote)})
+    return sorted(table.values(), key=lambda c: (-c.answers, _fold(c.attribute), _fold(c.value)))