overheard 0.0.2__py3-none-any.whl

overheard/__init__.py

@@ -0,0 +1,3 @@
+"""Overheard: an AI voicemail console that catches what busy humans miss."""
+
+__version__ = "0.0.2"

overheard/adapters/backend/base.py

@@ -0,0 +1,11 @@
+"""The case-system seam: the mock reads the seeded database; a real system of record replaces it later."""
+
+from typing import Protocol
+
+from overheard.data.models import Case
+
+
+class CaseBackend(Protocol):
+    def case(self, case_id: str) -> Case | None: ...
+    def by_phone(self, phone: str) -> list[Case]: ...
+    def search(self, text: str) -> list[Case]: ...

overheard/adapters/backend/mock.py

@@ -0,0 +1,45 @@
+"""The mock case system, over the seeded database."""
+
+import json
+import re
+import sqlite3
+
+from overheard.data.models import Case
+
+
+def _digits(s: str) -> str:
+    return re.sub(r"\D", "", s or "")
+
+
+class MockCaseBackend:
+    def __init__(self, con: sqlite3.Connection):
+        self.con = con
+
+    def _case(self, row) -> Case:
+        return Case(id=row["id"], name=row["name"], phone=row["phone"], status=row["status"], region=row["region"],
+                    lang=row["lang"], payments=json.loads(row["payments"]), docs=json.loads(row["docs"]),
+                    lastAction=row["last_action"], team=row["team"])
+
+    def case(self, case_id: str) -> Case | None:
+        cid = case_id.upper().replace(" ", "")
+        if not cid.startswith("FBS-"):
+            cid = "FBS-" + _digits(cid)
+        row = self.con.execute("SELECT * FROM cases WHERE id = ?", (cid,)).fetchone()
+        return self._case(row) if row else None
+
+    def by_phone(self, phone: str) -> list[Case]:
+        want = _digits(phone)[-10:]
+        rows = self.con.execute("SELECT * FROM cases").fetchall() if want else []
+        return [self._case(r) for r in rows if _digits(r["phone"])[-10:] == want]
+
+    def search(self, text: str) -> list[Case]:
+        """Name, phone or case number, the way an agent types into the lookup box."""
+        text = text.strip()
+        if not text:
+            return []
+        if _digits(text) and len(_digits(text)) >= 6:
+            found = self.by_phone(text) if len(_digits(text)) >= 10 else []
+            c = self.case(text)
+            return found + ([c] if c and c not in found else [])
+        rows = self.con.execute("SELECT * FROM cases WHERE name LIKE ? ORDER BY name LIMIT 20", (f"%{text}%",))
+        return [self._case(r) for r in rows]

overheard/app.py

@@ -0,0 +1,22 @@
+"""The FastAPI app: the API under /api, and the front end (static files) at /."""
+
+from importlib.resources import files
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from overheard import __version__
+from overheard.config import Settings
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or Settings()
+    app = FastAPI(title="Overheard", version=__version__)
+    app.state.settings = settings
+
+    @app.get("/api/health")
+    async def health() -> dict:
+        return {"ok": True, "version": __version__, "llm_mode": settings.llm_mode}
+
+    app.mount("/", StaticFiles(directory=str(files("overheard") / "static"), html=True), name="static")
+    return app

overheard/cli.py

@@ -0,0 +1,48 @@
+"""The `overheard` command: serve, seed, record, batch-label."""
+
+import argparse
+import sys
+
+from overheard import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="overheard", description="An AI voicemail console demo.")
+    parser.add_argument("--version", action="version", version=f"overheard {__version__}")
+    sub = parser.add_subparsers(dest="command")
+    serve = sub.add_parser("serve", help="run the console (API and front end) in one process")
+    serve.add_argument("--host")
+    serve.add_argument("--port", type=int)
+    sub.add_parser("seed", help="generate the synthetic day and archive into the database")
+    sub.add_parser("record", help="run the live LLM over the day and save its responses for replay")
+    sub.add_parser("batch-label", help="label a sample of the archive with the live LLM")
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        import uvicorn
+
+        from overheard.app import create_app
+        from overheard.config import Settings
+
+        settings = Settings()
+        host, port = args.host or settings.host, args.port or settings.port
+        print(f"Overheard {__version__} on http://{host}:{port}  (LLM mode: {settings.llm_mode})")
+        uvicorn.run(create_app(settings), host=host, port=port, log_level="warning")
+        return 0
+    if args.command == "seed":
+        from overheard.config import Settings
+        from overheard.data.generator import seed
+
+        settings = Settings()
+        counts = seed(settings.db_path, settings.seed)
+        print(f"seeded {settings.db_path} (seed {settings.seed}): " + ", ".join(f"{v:,} {k}" for k, v in counts.items()))
+        return 0
+    if args.command in ("record", "batch-label"):
+        print(f"overheard {args.command}: not built yet (this is an early release)", file=sys.stderr)
+        return 2
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

overheard/config.py

@@ -0,0 +1,21 @@
+"""Settings, from OVERHEARD_* environment variables."""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="OVERHEARD_")
+
+    llm_mode: Literal["mock", "live", "record", "replay"] = "mock"
+    llm_base_url: str | None = None
+    llm_api_key: SecretStr | None = None
+    llm_model: str | None = None
+    llm_timeout: float = 60.0
+    db_path: Path = Path("overheard.db")
+    seed: int = 2026
+    host: str = "127.0.0.1"
+    port: int = 8000

overheard/data/db.py

@@ -0,0 +1,50 @@
+"""SQLite: the seeded day, the case system, and the archive. Nested lists (payments, docs) are stored as JSON."""
+
+import json
+import sqlite3
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE voicemails (id TEXT PRIMARY KEY, received_at TEXT, caller_id TEXT, duration_sec INTEGER, lang TEXT,
+                         script TEXT, truth TEXT);
+CREATE TABLE cases (id TEXT PRIMARY KEY, name TEXT, phone TEXT, status TEXT, region TEXT, lang TEXT, payments TEXT,
+                    docs TEXT, last_action TEXT, team TEXT);
+CREATE INDEX cases_phone ON cases (phone);
+CREATE TABLE events (id TEXT PRIMARY KEY, date TEXT, type TEXT, name TEXT, description TEXT);
+CREATE TABLE contacts (id TEXT PRIMARY KEY, case_id TEXT, at TEXT, channel TEXT, root_cause TEXT, lang TEXT, region TEXT,
+                       handle_min REAL, resolved INTEGER, days_to_resolve INTEGER, text TEXT, promise TEXT);
+CREATE INDEX contacts_case ON contacts (case_id);
+CREATE INDEX contacts_cause ON contacts (root_cause, at);
+CREATE TABLE kb_articles (id TEXT PRIMARY KEY, title TEXT, body TEXT, topics TEXT);
+CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT);
+"""
+
+
+def connect(path: Path | str) -> sqlite3.Connection:
+    con = sqlite3.connect(path)
+    con.row_factory = sqlite3.Row
+    return con
+
+
+def create(path: Path | str) -> sqlite3.Connection:
+    """A fresh database at `path` (an existing one is replaced)."""
+    path = Path(path)
+    if path.exists():
+        path.unlink()
+    con = connect(path)
+    con.executescript(SCHEMA)
+    return con
+
+
+def dump_digest(con: sqlite3.Connection) -> str:
+    """A digest of every row, for checking that the same seed gives the same data."""
+    import hashlib
+
+    h = hashlib.sha256()
+    for line in con.iterdump():
+        h.update(line.encode())
+    return h.hexdigest()
+
+
+def j(value) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True)

overheard/data/events.py

@@ -0,0 +1,23 @@
+"""The events calendar that drives the archive's volume: each event adds calls about one driver, peaking at its
+start and fading over `days`. The planted signals Mode 3 should recover are marked."""
+
+# (id, date, type, name, description, driver it drives, extra contacts per day at the start, days it lasts)
+EVENTS = [
+    ("ev-portal-40", "2023-09-12", "release", "Portal release 4.0", "New sign-in page", "portal-sign-in-failure", 3.0, 5),
+    ("ev-cola-24", "2024-01-08", "mailing", "Cost-of-living letters 2024", "Annual adjustment notices", "cola-letter", 4.0, 20),
+    ("ev-income-rule", "2024-01-22", "policy", "Monthly income reporting rule", "Income must be reported monthly", "income-reporting-question", 3.0, 60),
+    ("ev-portal-41", "2024-04-16", "release", "Portal release 4.1", "Document upload redesign", "portal-navigation", 3.0, 6),
+    # PLANTED: the confusing letter. Mailed twice a year; each mailing drives a large, slow-fading excess.
+    ("ev-22b-1", "2024-06-03", "mailing", "Form 22-B re-verification letter (1st mailing)", "Re-verify address and income within 30 days", "form-22b-confusion", 9.0, 50),
+    ("ev-1099-quiet", "2024-10-01", "policy", "Tax form vendor change", "1099s produced by a new vendor", "tax-form-1099", 0.25, 110),
+    ("ev-22b-2", "2024-12-02", "mailing", "Form 22-B re-verification letter (2nd mailing)", "Re-verify address and income within 30 days", "form-22b-confusion", 9.0, 50),
+    ("ev-cola-25", "2025-01-06", "mailing", "Cost-of-living letters 2025", "Annual adjustment notices", "cola-letter", 4.0, 20),
+    # PLANTED: the weak signal that grew: a trickle of missing-1099 calls from October, then a spike in late January.
+    ("ev-1099-spike", "2025-01-27", "mailing", "1099 tax forms mailed", "Annual tax forms", "tax-form-1099", 8.0, 20),
+    # PLANTED: the big release that broke sign-in.
+    ("ev-portal-42", "2025-05-06", "release", "Portal release 4.2", "Two-step verification for sign-in", "portal-sign-in-failure", 30.0, 9),
+    ("ev-22b-3", "2025-06-02", "mailing", "Form 22-B re-verification letter (3rd mailing)", "Re-verify address and income within 30 days", "form-22b-confusion", 9.0, 50),
+    ("ev-22b-4", "2025-12-01", "mailing", "Form 22-B re-verification letter (4th mailing)", "Re-verify address and income within 30 days", "form-22b-confusion", 9.0, 50),
+    ("ev-cola-26", "2026-01-05", "mailing", "Cost-of-living letters 2026", "Annual adjustment notices", "cola-letter", 4.0, 20),
+    ("ev-payday-12", "2026-02-27", "payment-shift", "Payment date moves to the 12th", "March payments move from the 3rd to the 12th", "payment-date-shift", 6.0, 14),
+]

overheard/data/generator.py

@@ -0,0 +1,148 @@
+"""`overheard seed`: the hand-written day (seed_today.json) plus a three-year archive generated from a fixed seed.
+Same seed, same data. The archive's planted signals are in events.py and in the knobs below."""
+
+import json
+import math
+import random
+from datetime import date, timedelta
+from importlib.resources import files
+from pathlib import Path
+
+from overheard.data import db
+from overheard.data.events import EVENTS
+from overheard.data.templates import DOCS, DRIVERS, LANGUAGES, MONTHS
+
+START, END = date(2023, 3, 10), date(2026, 3, 9)         # the archive: three years up to the day before "today"
+LANGS = [("en", 0.80), ("es", 0.13), ("vi", 0.03), ("tl", 0.02), ("zh", 0.02)]
+REGIONS = [("CA", 12), ("TX", 10), ("FL", 8), ("NY", 7), ("PA", 5), ("OH", 5), ("IL", 5), ("GA", 4), ("NC", 4), ("MI", 4),
+           ("AZ", 3), ("WA", 3), ("TN", 3), ("KY", 2), ("MD", 2), ("NM", 2), ("NV", 2), ("OR", 2), ("MN", 2), ("ME", 1)]
+VOLUME = 1.35               # scales every driver and event alike: about 15,000 archive contacts
+LOOP_SHARE = 0.04            # PLANTED: callers stuck in a loop: 3-6 contacts on one issue, never resolved
+SLOW_LANG = "vi"             # PLANTED: slower, less often resolved service for one language
+BROKEN = {"appeal-status": 0.62, "claim-status": 0.35, "identity-check-hold": 0.45}   # PLANTED: promises broken
+FIRST = ["James", "Mary", "Robert", "Patricia", "John", "Jennifer", "Michael", "Linda", "David", "Elizabeth", "Maria",
+         "Jose", "Thi", "Van", "Nguyen", "Rosa", "Carlos", "Wei", "Mei", "Ana", "Luis", "Grace", "Samuel", "Ruth"]
+LAST = ["Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez",
+        "Nguyen", "Tran", "Le", "Santos", "Reyes", "Cruz", "Chen", "Wang", "Kim", "Patel", "Okafor", "Kowalski"]
+KB = [
+    ("kb-payment-dates", "When payments arrive", "Payments arrive on the 3rd; from March 2026, on the 12th.", ["payment-status", "payment-date-shift"]),
+    ("kb-direct-deposit", "Changing your bank account", "Send Form 14; changes take effect within 10 business days.", ["direct-deposit-change", "returned-deposit"]),
+    ("kb-address", "Changing your address", "Send Form 9 or update it in the portal; processed in 5 business days.", ["address-change", "temporary-address"]),
+    ("kb-portal-signin", "Signing in to the portal", "Use the code sent by text; codes expire after 10 minutes.", ["portal-sign-in-failure", "password-reset"]),
+    ("kb-documents", "Sending documents", "Mail documents to the address on your letter.", ["document-submission-method", "document-received-confirmation"]),
+    ("kb-cola", "Cost-of-living adjustments", "Amounts change each January; your letter shows the new amount.", ["cola-letter"]),
+    ("kb-overpayment", "Overpayment notices", "You can ask for a waiver or a repayment plan within 30 days.", ["overpayment-notice"]),
+    ("kb-appeals", "Appeals", "Appeals are decided in order received.", ["appeal-status"]),
+    # PLANTED gaps: no article explains Form 22-B re-verification, a fax number, or the 1099 vendor change.
+]
+
+
+def poisson(rng: random.Random, lam: float) -> int:
+    if lam <= 0:
+        return 0
+    if lam > 30:                                       # normal approximation for big days
+        return max(0, round(rng.gauss(lam, math.sqrt(lam))))
+    k, p, target = 0, 1.0, math.exp(-lam)
+    while True:
+        p *= rng.random()
+        if p <= target:
+            return k
+        k += 1
+
+
+def pick(rng: random.Random, weighted) -> str:
+    total = sum(w for _, w in weighted)
+    r, acc = rng.random() * total, 0.0
+    for value, w in weighted:
+        acc += w
+        if r <= acc:
+            return value
+    return weighted[-1][0]
+
+
+def say(rng: random.Random, phrasings: list[str]) -> str:
+    text = rng.choice(phrasings)
+    return text.format(month=rng.choice(MONTHS), amount=f"${rng.randint(4, 120) * 10}",
+                       doc=rng.choice(DOCS), language=rng.choice(list(LANGUAGES.values())))
+
+
+def seed(path: Path | str, seed_value: int = 2026) -> dict:
+    """Write the day and the archive to a fresh database at `path`. Returns counts."""
+    rng = random.Random(seed_value)
+    con = db.create(path)
+    today = json.loads((files("overheard.data") / "seed_today.json").read_text(encoding="utf-8"))
+    for v in today["voicemails"]:
+        con.execute("INSERT INTO voicemails VALUES (?,?,?,?,?,?,?)",
+                    (v["id"], v["receivedAt"], v["callerId"], v["durationSec"], v["lang"], v["script"], db.j(v["truth"])))
+    for c in today["cases"]:
+        con.execute("INSERT INTO cases VALUES (?,?,?,?,?,?,?,?,?,?)",
+                    (c["id"], c["name"], c["phone"], c["status"], c["region"], c["lang"], db.j(c["payments"]),
+                     db.j(c["docs"]), c["lastAction"], c["team"]))
+    for e in EVENTS:
+        con.execute("INSERT INTO events VALUES (?,?,?,?,?)", e[:5])
+    for k in KB:
+        con.execute("INSERT INTO kb_articles VALUES (?,?,?,?)", (k[0], k[1], k[2], db.j(k[3])))
+
+    # The archive's callers: a pool of cases, each with a language and region
+    callers = []
+    for i in range(6000):
+        lang, region = pick(rng, LANGS), pick(rng, REGIONS)
+        cid = f"FBS-{500000 + i}"
+        name = f"{rng.choice(FIRST)} {rng.choice(LAST)}"
+        phone = f"+1-{rng.randint(201, 989)}-555-{rng.randint(0, 9999):04d}"
+        callers.append((cid, lang, region))
+        con.execute("INSERT INTO cases VALUES (?,?,?,?,?,?,?,?,?,?)",
+                    (cid, name, phone, "active", region, lang, "[]", "[]", "archive", "general"))
+    drivers = {d[0]: d for d in DRIVERS}
+    events = [(date.fromisoformat(e[1]), e[5], e[6], e[7]) for e in EVENTS]
+    n, day = 0, START
+    while day <= END:
+        weekday = day.weekday()
+        if weekday < 5:                                  # the archive is weekday contacts
+            for dname, _team, weekly, handle, resolve_p, phrasings in DRIVERS:
+                lam = weekly / 5
+                for start, driver, peak, days in events:
+                    age = (day - start).days
+                    if driver == dname and 0 <= age < days:
+                        lam += peak * math.exp(-3.0 * age / days)
+                for _ in range(poisson(rng, lam * VOLUME)):
+                    n += 1
+                    cid, lang, region = rng.choice(callers)
+                    slow = lang == SLOW_LANG
+                    h = max(0.5, rng.gauss(handle * (1.35 if slow else 1.0), handle * 0.25))
+                    resolved = rng.random() < resolve_p - (0.15 if slow else 0.0)
+                    days_to = (rng.randint(1, 30) * (2 if slow else 1)) if resolved else None
+                    promise = None
+                    if rng.random() < 0.3:
+                        due = day + timedelta(days=rng.choice([5, 10, 14, 30]))
+                        kept = rng.random() >= BROKEN.get(dname, 0.08) if due <= END else None
+                        promise = {"text": f"Call back with an answer by {due.isoformat()}", "dueAt": due.isoformat(),
+                                   "kept": kept}
+                    at = f"{day.isoformat()}T{rng.randint(8, 16):02d}:{rng.randint(0, 59):02d}"
+                    con.execute("INSERT INTO contacts VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+                                (f"c{n:06d}", cid, at, pick(rng, [("voicemail", 3), ("phone", 6), ("web", 1)]), dname,
+                                 lang, region, round(h, 1), int(resolved), days_to, say(rng, phrasings),
+                                 db.j(promise) if promise else None))
+        day += timedelta(days=1)
+
+    # PLANTED: callers stuck in loops: the same unresolved issue, again and again
+    loops = 0
+    for cid, lang, region in rng.sample(callers, int(len(callers) * LOOP_SHARE)):
+        dname = rng.choice(["identity-check-hold", "appeal-status", "overpayment-notice", "form-22b-confusion"])
+        d = drivers[dname]
+        first = START + timedelta(days=rng.randint(0, (END - START).days - 120))
+        for k in range(rng.randint(3, 6)):
+            n += 1
+            loops += 1
+            at = first + timedelta(days=k * rng.randint(7, 21))
+            con.execute("INSERT INTO contacts VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+                        (f"c{n:06d}", cid, f"{at.isoformat()}T{rng.randint(8, 16):02d}:{rng.randint(0, 59):02d}",
+                         "phone", dname, lang, region, round(max(0.5, rng.gauss(d[3] * 1.2, 1.5)), 1), 0, None,
+                         say(rng, d[5]), None))
+    con.execute("INSERT INTO meta VALUES ('seed', ?)", (str(seed_value),))
+    con.execute("INSERT INTO meta VALUES ('today', ?)", (today["date"],))
+    con.commit()
+    counts = {"voicemails": len(today["voicemails"]), "cases": len(today["cases"]) + len(callers),
+              "contacts": n, "loop_contacts": loops, "events": len(EVENTS)}
+    con.close()
+    return counts

overheard/data/models.py

@@ -0,0 +1,96 @@
+"""The data model, shared by the API and the pipeline. Raw input, ground truth and (later) AI output are kept
+apart, so any mode can be re-run and any AI field scored against the truth."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+Obligation = Literal["congressional", "records", "legal", "welfare", "discrimination"]
+
+
+class Truth(BaseModel):
+    intent: str
+    urgency: int
+    rootCause: str
+    team: str
+    callerName: str | None = None
+    callbackNumber: str
+    caseId: str | None = None
+    caseNumberSaid: bool = True
+    group: str | None = None
+    obligations: list[Obligation] = []
+    resolvableBy: str | None = None
+    linkedTo: list[str] = []
+    callbackWindow: str | None = None
+    beliefMismatch: str | None = None
+    englishGist: str | None = None
+
+
+class Voicemail(BaseModel):
+    id: str
+    receivedAt: str
+    callerId: str
+    durationSec: int
+    lang: str
+    script: str
+    truth: Truth
+
+
+class Payment(BaseModel):
+    date: str
+    amount: float
+    status: str
+
+
+class Doc(BaseModel):
+    name: str
+    received: str | None = None
+
+
+class Case(BaseModel):
+    id: str
+    name: str
+    phone: str
+    status: str
+    region: str
+    lang: str = "en"
+    payments: list[Payment] = []
+    docs: list[Doc] = []
+    lastAction: str
+    team: str
+
+
+class Event(BaseModel):
+    id: str
+    date: str
+    type: Literal["mailing", "release", "policy", "payment-shift"]
+    name: str
+    description: str
+
+
+class Promise(BaseModel):
+    text: str
+    dueAt: str
+    kept: bool | None = None
+
+
+class Contact(BaseModel):
+    id: str
+    caseId: str
+    at: str
+    channel: Literal["voicemail", "phone", "web"]
+    rootCause: str
+    lang: str
+    region: str
+    handleMin: float
+    resolved: bool
+    daysToResolve: int | None = None
+    text: str
+    promise: Promise | None = None
+
+
+class KBArticle(BaseModel):
+    id: str
+    title: str
+    body: str
+    topics: list[str]