asktheboard 0.2.0__py3-none-any.whl

asktheboard/__init__.py

@@ -0,0 +1,67 @@
+"""ask-the-board (OSS) -- a board of expert personas whose every decision is a
+pre-registered, time-anchored, reality-graded bet.
+
+BYOK (bring your own API key): you supply your own LLM key, you pay your own
+inference, the engine costs nothing to run at any scale. The durable asset is the
+accumulating, externally attested track record -- the board that keeps score,
+before the fact.
+"""
+
+from .model import (
+    BoardMinute,
+    IntegrityError,
+    Prediction,
+    Resolution,
+    SeatCall,
+    brier,
+)
+from .ledger import Ledger, SeatScore
+from .llm import LLMClient, NoProviderConfigured, require_client
+from .convene import ConveneError, Seat, convene
+from .http_client import HTTPLLMClient
+from .decision_types import (
+    CATALOG,
+    DecisionType,
+    UnknownDecisionType,
+    resolution_date_for,
+)
+from .roster import (
+    UnknownPanel,
+    UnknownSeat,
+    panel,
+    panel_names,
+    seat,
+    seat_slugs,
+    seats,
+)
+
+__all__ = [
+    "BoardMinute",
+    "Prediction",
+    "Resolution",
+    "SeatCall",
+    "IntegrityError",
+    "brier",
+    "Ledger",
+    "SeatScore",
+    "LLMClient",
+    "NoProviderConfigured",
+    "require_client",
+    "Seat",
+    "convene",
+    "ConveneError",
+    "HTTPLLMClient",
+    "DecisionType",
+    "CATALOG",
+    "UnknownDecisionType",
+    "resolution_date_for",
+    "seat",
+    "seats",
+    "panel",
+    "seat_slugs",
+    "panel_names",
+    "UnknownSeat",
+    "UnknownPanel",
+]
+
+__version__ = "0.2.0"

asktheboard/adr.py

@@ -0,0 +1,83 @@
+"""Render a BoardMinute as a git-committable Architecture Decision Record.
+
+The board-minute IS the artifact: a markdown ADR a user commits to their own
+repo. Git history then provides the external attestation of the anchor timestamp
+-- the thing a funded competitor cannot retroactively manufacture.
+"""
+
+from .model import BoardMinute
+
+
+def _pct(p: float) -> str:
+    return f"{round(p * 100)}%"
+
+
+def render_adr(minute: BoardMinute) -> str:
+    m = minute
+    if m.resolution is None:
+        status = f"Pre-registered (resolves {m.prediction.resolution_date.isoformat()})"
+    else:
+        verdict = "VINDICATED" if m.vindicated else "REFUTED"
+        status = f"Resolved {m.resolution.resolved_at.date().isoformat()} -- {verdict}"
+
+    lines: list[str] = []
+    lines.append(f"# ADR-{m.id}: {m.question}")
+    lines.append("")
+    lines.append(f"- **Status:** {status}")
+    lines.append(f"- **Anchored:** {m.created_at.isoformat()}")
+    lines.append(f"- **Resolution date:** {m.prediction.resolution_date.isoformat()}")
+    lines.append("")
+    lines.append("## Context (stated prior)")
+    lines.append("")
+    lines.append(m.prior.strip() or "_none recorded_")
+    lines.append("")
+    lines.append("## Decision")
+    lines.append("")
+    lines.append(m.decision.strip() or "_none recorded_")
+    lines.append("")
+    lines.append("## Pre-registered prediction")
+    lines.append("")
+    lines.append(f"> {m.prediction.statement.strip()}")
+    lines.append("")
+    lines.append(f"- **Board confidence:** {_pct(m.prediction.board_probability)} that this resolves TRUE")
+    lines.append(f"- **Resolves:** {m.prediction.resolution_date.isoformat()}")
+    lines.append("")
+    lines.append("## Board seats (dissent vector)")
+    lines.append("")
+    if m.seats:
+        resolved = m.resolution is not None
+        header = "| Seat | Stance | P(true) | "
+        sep = "|---|---|---|"
+        if resolved:
+            header += "Brier | "
+            sep += "---|"
+        header += "Rationale |"
+        sep += "---|"
+        lines.append(header)
+        lines.append(sep)
+        briers = m.seat_briers()
+        for s in m.seats:
+            row = f"| {s.seat} | {s.stance} | {_pct(s.probability)} | "
+            if resolved:
+                row += f"{briers[s.seat]:.3f} | "
+            row += f"{s.rationale.strip().replace(chr(10), ' ')} |"
+            lines.append(row)
+    else:
+        lines.append("_no seats recorded_")
+    lines.append("")
+
+    if m.resolution is not None:
+        o = "TRUE" if m.resolution.realized_outcome else "FALSE"
+        lines.append("## Resolution")
+        lines.append("")
+        lines.append(f"- **Realized outcome:** {o}")
+        lines.append(f"- **Board Brier:** {m.board_brier():.3f} (lower is better)")
+        winners = m.contrarian_winners()
+        if winners:
+            lines.append(f"- **Contrarian wins:** {', '.join(winners)} "
+                         f"(dissented and beat the consensus)")
+        if m.resolution.note.strip():
+            lines.append(f"- **Note:** {m.resolution.note.strip()}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

asktheboard/cli.py

@@ -0,0 +1,198 @@
+"""Local CLI: convene a board (BYOK), persist board-minutes, grade, and score seats.
+
+`create`/`resolve`/`score` need no network or key -- the foresight ledger runs
+entirely on local files. `convene` is the BYOK fan-out: it reads YOUR key
+(OPENAI_API_KEY) and runs the live LLM calls that *produce* a minute.
+
+Usage:
+  python -m asktheboard.cli convene --spec convene.json --model <m> [--base-url ...]
+  python -m asktheboard.cli create  --spec minute.json [--dir board-minutes]
+  python -m asktheboard.cli resolve --id <id> --outcome true|false [--note ...]
+  python -m asktheboard.cli score   [--dir board-minutes]
+"""
+
+import argparse
+import json
+import math
+import sys
+from pathlib import Path
+
+from .adr import render_adr
+from .convene import Seat, convene
+from .http_client import HTTPLLMClient
+from .ledger import Ledger
+from .model import BoardMinute
+from .roster import panel as roster_panel
+from .roster import panel_names, seat_slugs, seats as roster_seats
+
+
+def _store(dirpath: str) -> Path:
+    p = Path(dirpath)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _load_all(store: Path) -> list[BoardMinute]:
+    out = []
+    for f in sorted(store.glob("*.json")):
+        out.append(BoardMinute.from_dict(json.loads(f.read_text(encoding="utf-8"))))
+    return out
+
+
+def _save(store: Path, minute: BoardMinute) -> Path:
+    jpath = store / f"{minute.id}.json"
+    jpath.write_text(json.dumps(minute.to_dict(), indent=2), encoding="utf-8")
+    apath = store / f"{minute.id}.md"
+    apath.write_text(render_adr(minute), encoding="utf-8")
+    return apath
+
+
+def _resolve_seats(args: argparse.Namespace, spec: dict) -> list[Seat]:
+    """Seats from --seats > --panel > the spec's own seat list."""
+    if args.seats:
+        return roster_seats([s.strip() for s in args.seats.split(",") if s.strip()])
+    if args.panel:
+        return roster_panel(args.panel)
+    spec_seats = spec.get("seats")
+    if not spec_seats:
+        raise SystemExit(
+            "no seats: pass --seats <slugs> or --panel <name>, "
+            'or put a "seats" list in the spec'
+        )
+    return [Seat(name=s["name"], persona=s.get("persona", "")) for s in spec_seats]
+
+
+def cmd_convene(args: argparse.Namespace) -> int:
+    store = _store(args.dir)
+    spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
+    seats = _resolve_seats(args, spec)
+    client = HTTPLLMClient(model=args.model, base_url=args.base_url)
+    minute = convene(
+        id=spec["id"],
+        question=spec["question"],
+        prior=spec.get("prior", ""),
+        decision=spec["decision"],
+        statement=spec["statement"],
+        seats=seats,
+        client=client,
+        decision_type=spec.get("decision_type"),
+        resolution_date=_date_or_none(spec.get("resolution_date")),
+    )
+    adr = _save(store, minute)
+    print(f"convened {minute.id}: board P(true)={minute.prediction.board_probability:.2f}, "
+          f"{len(minute.seats)} seats, resolves "
+          f"{minute.prediction.resolution_date.isoformat()}")
+    print(f"  ADR -> {adr}")
+    return 0
+
+
+def _date_or_none(s):
+    from datetime import date
+    return date.fromisoformat(s) if s else None
+
+
+def cmd_roster(args: argparse.Namespace) -> int:
+    print("bundled seats:")
+    for slug in seat_slugs():
+        print(f"  {slug}")
+    print("\npanels:")
+    for name in panel_names():
+        members = ", ".join(s.name for s in roster_panel(name))
+        print(f"  {name:<10} {members}")
+    return 0
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    store = _store(args.dir)
+    spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
+    minute = BoardMinute.from_dict(spec)
+    adr = _save(store, minute)
+    print(f"created {minute.id}: pre-registered, resolves "
+          f"{minute.prediction.resolution_date.isoformat()}")
+    print(f"  ADR -> {adr}")
+    return 0
+
+
+def cmd_resolve(args: argparse.Namespace) -> int:
+    store = _store(args.dir)
+    jpath = store / f"{args.id}.json"
+    if not jpath.exists():
+        print(f"no such minute: {args.id}", file=sys.stderr)
+        return 1
+    minute = BoardMinute.from_dict(json.loads(jpath.read_text(encoding="utf-8")))
+    outcome = args.outcome.lower() in ("true", "t", "yes", "y", "1")
+    minute.resolve(outcome, note=args.note or "")
+    _save(store, minute)
+    verdict = "VINDICATED" if minute.vindicated else "REFUTED"
+    print(f"resolved {minute.id}: outcome={'TRUE' if outcome else 'FALSE'} -- {verdict}")
+    print(f"  board Brier {minute.board_brier():.3f}")
+    winners = minute.contrarian_winners()
+    if winners:
+        print(f"  contrarian wins: {', '.join(winners)}")
+    return 0
+
+
+def cmd_score(args: argparse.Namespace) -> int:
+    store = _store(args.dir)
+    ledger = Ledger()
+    ledger.extend(_load_all(store))
+    ranked = ledger.ranked_seats()
+    if not ranked:
+        print("no resolved minutes yet -- nothing to score")
+        return 0
+    print(f"{'seat':<16} {'n':>3} {'mean_brier':>11} {'wins':>5} {'losses':>7}")
+    print("-" * 46)
+    for sc in ranked:
+        mb = "n/a" if math.isnan(sc.mean_brier) else f"{sc.mean_brier:.3f}"
+        print(f"{sc.seat:<16} {sc.resolved_count:>3} {mb:>11} "
+              f"{sc.contrarian_wins:>5} {sc.contrarian_losses:>7}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="asktheboard", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    v = sub.add_parser("convene", help="BYOK: run the live LLM fan-out to produce a minute")
+    v.add_argument("--spec", required=True, help="path to the convene JSON spec")
+    v.add_argument("--model", required=True, help="model id (e.g. gpt-4o-mini)")
+    v.add_argument("--base-url", default="https://api.openai.com/v1",
+                   help="OpenAI-compatible API base URL")
+    v.add_argument("--seats", default="",
+                   help="comma-separated roster slugs (e.g. architect,skeptic); "
+                        "overrides the spec's seats")
+    v.add_argument("--panel", default="",
+                   help="a named panel from the bundled roster (e.g. tech); "
+                        "used if --seats is absent")
+    v.add_argument("--dir", default="board-minutes", help="store directory")
+    v.set_defaults(func=cmd_convene)
+
+    rb = sub.add_parser("roster", help="list the bundled seats and panels")
+    rb.set_defaults(func=cmd_roster)
+
+    c = sub.add_parser("create", help="pre-register a board-minute from a JSON spec")
+    c.add_argument("--spec", required=True, help="path to the minute JSON spec")
+    c.add_argument("--dir", default="board-minutes", help="store directory")
+    c.set_defaults(func=cmd_create)
+
+    r = sub.add_parser("resolve", help="grade a minute against reality")
+    r.add_argument("--id", required=True)
+    r.add_argument("--outcome", required=True, help="true|false")
+    r.add_argument("--note", default="")
+    r.add_argument("--dir", default="board-minutes")
+    r.set_defaults(func=cmd_resolve)
+
+    s = sub.add_parser("score", help="per-seat calibration over resolved minutes")
+    s.add_argument("--dir", default="board-minutes")
+    s.set_defaults(func=cmd_score)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

asktheboard/convene.py

@@ -0,0 +1,141 @@
+"""Live convening -- fan a decision across board seats and assemble a BoardMinute.
+
+This is the W1 fan-out: each seat answers *through the caller's LLMClient* (BYOK),
+returns its stance + probability + rationale on the pre-registered prediction, and
+the board's consensus probability is the mean of the seats' calls. The result is a
+fully-formed, graded-ready `BoardMinute` -- the integrity rules (no backfilling, no
+early grading, frozen anchor) are enforced by `model.py` on construction, so a
+convening cannot produce a dishonest minute.
+
+The engine still makes zero calls of its own: every token of inference runs on the
+client you pass. Swap in `HTTPLLMClient` for production, a fake for tests.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Optional, Sequence
+
+from .decision_types import resolution_date_for
+from .llm import LLMClient, require_client
+from .model import BoardMinute, Prediction, SeatCall
+
+
+class ConveneError(RuntimeError):
+    """Raised when a seat's answer cannot be parsed into a valid SeatCall."""
+
+
+@dataclass(frozen=True)
+class Seat:
+    """A board seat: a name plus the persona/expertise that shapes its system prompt."""
+
+    name: str
+    persona: str
+
+
+_SEAT_INSTRUCTION = (
+    "A decision is on the table and a falsifiable prediction has been registered.\n"
+    "Question: {question}\n"
+    "Board's decision: {decision}\n"
+    'Pre-registered prediction (resolves {resolution_date}): "{statement}"\n\n'
+    "Give YOUR independent call. Reply with ONLY a JSON object, no prose:\n"
+    '{{"stance": "affirm" | "dissent", "probability": <number 0..1>, '
+    '"rationale": "<one sentence>"}}\n'
+    '- "stance": "affirm" if you back the board\'s decision, "dissent" if you break from it.\n'
+    '- "probability": your own P(the prediction resolves TRUE), as a number in [0, 1].\n'
+    "- Be willing to dissent: a contrarian who is right is worth more than a chorus."
+)
+
+_JSON_RE = re.compile(r"\{.*\}", re.DOTALL)
+
+
+def _parse_seat_call(seat: str, raw: str) -> SeatCall:
+    """Parse one seat's raw completion into a validated SeatCall."""
+    text = raw.strip()
+    # Strip a ```json ... ``` fence if the model added one.
+    if text.startswith("```"):
+        text = text.strip("`")
+        text = text[4:] if text.lower().startswith("json") else text
+    try:
+        obj = json.loads(text)
+    except json.JSONDecodeError:
+        m = _JSON_RE.search(raw)
+        if not m:
+            raise ConveneError(f"seat {seat!r}: no JSON object in answer: {raw!r}")
+        try:
+            obj = json.loads(m.group(0))
+        except json.JSONDecodeError as e:
+            raise ConveneError(f"seat {seat!r}: unparseable JSON: {raw!r}") from e
+    if not isinstance(obj, dict):
+        raise ConveneError(f"seat {seat!r}: expected a JSON object, got {obj!r}")
+    try:
+        stance = str(obj["stance"]).strip().lower()
+        probability = float(obj["probability"])
+    except (KeyError, TypeError, ValueError) as e:
+        raise ConveneError(f"seat {seat!r}: missing/invalid stance|probability: {obj!r}") from e
+    rationale = str(obj.get("rationale", "")).strip()
+    try:
+        return SeatCall(seat=seat, stance=stance, probability=probability, rationale=rationale)
+    except ValueError as e:  # SeatCall enforces stance/probability domains
+        raise ConveneError(f"seat {seat!r}: {e}") from e
+
+
+def convene(
+    *,
+    id: str,
+    question: str,
+    prior: str,
+    decision: str,
+    statement: str,
+    seats: Sequence[Seat],
+    client: Optional[LLMClient],
+    resolution_date: Optional[date] = None,
+    decision_type: Optional[str] = None,
+    created_at: Optional[datetime] = None,
+) -> BoardMinute:
+    """Convene the board on a decision and return a pre-registered BoardMinute.
+
+    Provide the resolution horizon either directly (`resolution_date`) or by naming
+    a `decision_type` whose default horizon is applied from the anchor. Every seat
+    answers through `client` (BYOK); the board probability is the mean of their
+    calls. Raises NoProviderConfigured if `client` is None, ConveneError on an
+    unparseable seat answer, and IntegrityError if the horizon is in the past.
+    """
+    client = require_client(client)
+    if not seats:
+        raise ConveneError("convene requires at least one seat")
+    anchor = created_at or datetime.now()
+    if resolution_date is None:
+        if decision_type is None:
+            raise ConveneError("pass either resolution_date or decision_type")
+        resolution_date = resolution_date_for(decision_type, anchor.date())
+
+    calls: list[SeatCall] = []
+    for seat in seats:
+        prompt = _SEAT_INSTRUCTION.format(
+            question=question,
+            decision=decision,
+            statement=statement,
+            resolution_date=resolution_date.isoformat(),
+        )
+        raw = client.complete(prompt, system=f"You are {seat.name}. {seat.persona}")
+        calls.append(_parse_seat_call(seat.name, raw))
+
+    board_probability = sum(c.probability for c in calls) / len(calls)
+    prediction = Prediction(
+        statement=statement,
+        resolution_date=resolution_date,
+        board_probability=board_probability,
+    )
+    return BoardMinute(
+        id=id,
+        question=question,
+        prior=prior,
+        decision=decision,
+        prediction=prediction,
+        seats=calls,
+        created_at=anchor,
+    )

asktheboard/decision_types.py

@@ -0,0 +1,87 @@
+"""Decision-type catalog -- default resolution horizons that keep the loop honest.
+
+A board-minute is only foresight if its prediction has a date by which reality can
+grade it. Picking that date by hand every time is friction; worse, it lets an
+operator quietly stretch the horizon until any call looks right. The catalog fixes
+a sensible default horizon per decision class so the common case is one lookup and
+the dishonest case (a 5-year horizon on a library swap) stands out.
+
+Ordered short-latency first on purpose: the fastest-resolving decisions are how a
+fresh board accumulates a track record before anyone will trust a slow one. Seed
+the scoreboard with `library` calls; let the `architecture` bets ripen.
+
+No clock magic here -- `resolution_date()` takes the anchor explicitly so it stays
+pure and testable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+
+class UnknownDecisionType(KeyError):
+    """Raised when a decision-type key is not in the catalog."""
+
+
+@dataclass(frozen=True)
+class DecisionType:
+    """A class of decision with the default horizon over which it resolves."""
+
+    key: str
+    label: str
+    horizon_days: int
+    description: str
+
+    def resolution_date(self, anchor: date) -> date:
+        """The default date reality can grade a call of this type, given its anchor."""
+        return anchor + timedelta(days=self.horizon_days)
+
+
+# Short-latency first -> a new board earns signal fast on these, then ripens the
+# slower bets. Exactly the three the plan names; extend deliberately, not by reflex.
+_TYPES = (
+    DecisionType(
+        "library",
+        "Library / dependency choice",
+        90,
+        "Adopt, swap, or drop a library or dependency. Resolves within a quarter: "
+        "you know inside 90 days whether it held up in production.",
+    ),
+    DecisionType(
+        "migration",
+        "Migration / infrastructure change",
+        180,
+        "Move a datastore, platform, or pipeline. Half-year horizon: migrations "
+        "reveal their true cost over a couple of release cycles.",
+    ),
+    DecisionType(
+        "architecture",
+        "Architecture / design bet",
+        365,
+        "A structural design choice you will live with. Yearly horizon: the bill "
+        "for an architecture decision lands over the following year.",
+    ),
+)
+
+CATALOG: dict[str, DecisionType] = {t.key: t for t in _TYPES}
+
+
+def get(key: str) -> DecisionType:
+    """Look up a decision type by key, raising UnknownDecisionType if absent."""
+    try:
+        return CATALOG[key]
+    except KeyError:
+        raise UnknownDecisionType(
+            f"unknown decision type {key!r}; known: {', '.join(CATALOG)}"
+        ) from None
+
+
+def keys() -> list[str]:
+    """Catalog keys, short-latency first (insertion order)."""
+    return list(CATALOG)
+
+
+def resolution_date_for(key: str, anchor: date) -> date:
+    """Default resolution date for a decision of type `key` anchored at `anchor`."""
+    return get(key).resolution_date(anchor)

asktheboard/http_client.py

@@ -0,0 +1,67 @@
+"""A minimal, dependency-free OpenAI-compatible LLMClient (BYOK).
+
+Stdlib `urllib` only -- no `openai`, no `requests` -- so the open-source core stays
+zero-dependency and the BYOK promise is literal: you bring the key, you bring the
+endpoint, the engine bundles neither. Works against any OpenAI-compatible
+`/chat/completions` API (OpenAI, OpenRouter, Together, a local server) by setting
+`base_url` + `model`.
+
+This satisfies the `LLMClient` Protocol structurally; nothing imports a vendor SDK.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+
+class HTTPLLMClient:
+    """OpenAI-compatible chat client. Reads your key; pays your inference."""
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str | None = None,
+        base_url: str = "https://api.openai.com/v1",
+        timeout: float = 60.0,
+        temperature: float = 0.7,
+    ) -> None:
+        self.model = model
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "no API key: pass api_key= or set OPENAI_API_KEY. ask-the-board is "
+                "bring-your-own-key -- it ships no provider and no credentials."
+            )
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.temperature = temperature
+
+    def complete(self, prompt: str, *, system: str = "") -> str:
+        """POST a chat completion and return the assistant's text."""
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        payload = json.dumps(
+            {"model": self.model, "messages": messages, "temperature": self.temperature}
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:  # surface the provider's error body
+            body = e.read().decode("utf-8", "replace")
+            raise RuntimeError(f"LLM request failed ({e.code}): {body}") from e
+        return data["choices"][0]["message"]["content"]