touchstone-compute 0.1.0__py3-none-any.whl

touchstone/__init__.py

@@ -0,0 +1,19 @@
+"""Touchstone — deterministic, verifiable text/code/measurement compute for AI agents.
+
+The open core: every function is deterministic (same input → same bytes) and reproduces
+a named published authority, so any answer can be re-executed and checked rather than
+trusted. The hosted suite (touchstone.locomot.io) adds a drand-anchored trust layer and
+signed pay-per-call receipts over x402.
+
+    from touchstone import units, citation, textdiff, proofreading, readability, syntax
+
+    units.compute(1, "nautical_mile", "meter")
+    citation.compute("apa", "book", authors="Anderson, Benedict",
+                     title="Imagined Communities", year=1983, publisher="Verso")
+
+Trust by re-execution, not reputation. github.com/savecharlie/touchstone
+"""
+from touchstone import units, citation, textdiff, proofreading, readability, syntax  # noqa: F401
+
+__version__ = "0.1.0"
+__all__ = ["units", "citation", "textdiff", "proofreading", "readability", "syntax"]

touchstone/citation.py

@@ -0,0 +1,532 @@
+"""citecore — deterministic citation formatter (APA 7, MLA 9, Chicago 17 author-date, BibTeX).
+
+The Touchstone thesis applied to writing: an LLM drafts the prose, WE assemble the
+citation correctly — element order, punctuation, italics, author-name inversion, the
+"& vs and" join, et-al. thresholds, date formatting — all of it deterministic and
+reproducible against published style-manual examples.
+
+HONEST BOUNDARY (this is the brand): we do NOT guess letter-case. Sentence-case vs
+title-case depends on proper-noun detection, which is not deterministic, so titles and
+container names are taken VERBATIM — the caller supplies the case the style wants. What
+we guarantee is the assembly: every comma, period, italic, and "et al." in the right
+place, every time, byte-for-byte against the authority. Pass `title_case=True` to apply
+the mechanical headline-case algorithm (Chicago/APA title rules) when you want it.
+
+Output renders the reference in three forms — `markdown` (italics as *...*), `html`
+(italics as <i>...</i>), and `plain` (no markers) — plus the `intext` citation.
+
+Authority-reproduced (see tests): APA Style / Scribbr, MLA Handbook 9 / SDSU LibGuide,
+The Chicago Manual of Style 17 author-date / Scribbr.
+
+Iris (Opus 4.8, 1M) + Ivy, Jun 29 2026.
+"""
+import re
+
+STYLES = ("apa", "mla", "chicago", "bibtex")
+TYPES = ("article", "book", "chapter", "web")
+
+# months MLA abbreviates (everything except May/June/July, which stay whole)
+_MLA_MONTH = {
+    "january": "Jan.", "february": "Feb.", "march": "Mar.", "april": "Apr.",
+    "may": "May", "june": "June", "july": "July", "august": "Aug.",
+    "september": "Sept.", "october": "Oct.", "november": "Nov.", "december": "Dec.",
+}
+# words left lowercase in headline (title) case unless first/last
+_LOWER = {"a", "an", "the", "and", "but", "or", "nor", "for", "so", "yet",
+          "as", "at", "by", "in", "of", "off", "on", "per", "to", "up", "via",
+          "vs", "with", "from", "into", "onto", "over"}
+
+
+# ---------------------------------------------------------------- helpers
+def _norm_authors(authors):
+    """Accept list of {family, given} dicts OR 'Family, Given' strings -> list of dicts."""
+    if authors is None:
+        return []
+    if isinstance(authors, dict):
+        authors = [authors]
+    if isinstance(authors, str):
+        # 'Family, Given; Family2, Given2'  OR a single 'Family, Given'
+        parts = [a.strip() for a in re.split(r"\s*;\s*", authors) if a.strip()]
+        authors = parts
+    out = []
+    for a in authors:
+        if isinstance(a, dict):
+            fam = (a.get("family") or a.get("last") or "").strip()
+            giv = (a.get("given") or a.get("first") or "").strip()
+        else:
+            s = str(a).strip()
+            if "," in s:
+                fam, giv = [x.strip() for x in s.split(",", 1)]
+            else:  # 'Given Family' -> split on last space
+                bits = s.rsplit(" ", 1)
+                if len(bits) == 2:
+                    giv, fam = bits[0].strip(), bits[1].strip()
+                else:
+                    fam, giv = s, ""
+        if fam or giv:
+            out.append({"family": fam, "given": giv})
+    return out
+
+
+def _initials(given):
+    """'Paul D.' -> 'P. D.'  ;  'Jean-Paul' -> 'J.-P.'  (APA style)."""
+    toks = [t for t in given.split() if t]
+    out = []
+    for t in toks:
+        parts = t.split("-")
+        out.append("-".join((p[0].upper() + ".") if p else "" for p in parts))
+    return " ".join(out)
+
+
+def _title_case(s):
+    """Mechanical headline (title) case per Chicago/APA: capitalize first & last word
+    and every word except short articles/conjunctions/prepositions in _LOWER."""
+    words = s.split()
+    n = len(words)
+    out = []
+    for i, w in enumerate(words):
+        bare = re.sub(r"[^A-Za-z]", "", w).lower()
+        if i == 0 or i == n - 1 or bare not in _LOWER:
+            # preserve all-caps acronyms; otherwise capitalize first letter
+            out.append(w if w[:1].isupper() and w[1:2].isupper() else _cap_first(w))
+        else:
+            out.append(w.lower())
+    return " ".join(out)
+
+
+def _cap_first(w):
+    for i, ch in enumerate(w):
+        if ch.isalpha():
+            return w[:i] + ch.upper() + w[i + 1:]
+    return w
+
+
+def _pages(p):
+    """Normalize a numeric range to an en-dash; otherwise verbatim."""
+    if not p:
+        return ""
+    p = str(p).strip()
+    m = re.match(r"^(\d+)\s*[-–—]\s*(\d+)$", p)
+    return f"{m.group(1)}–{m.group(2)}" if m else p
+
+
+def _period(s):
+    """Append a period unless the string already ends in sentence punctuation."""
+    s = s.rstrip()
+    return s if s[-1:] in ".!?" else s + "."
+
+
+def _quote(s):
+    """Quote a title, putting its terminal period inside the quotes (MLA/Chicago)."""
+    s = s.rstrip()
+    return f'"{s}"' if s[-1:] in ".!?" else f'"{s}."'
+
+
+def _oxford(items, conj="and"):
+    """['a'] -> 'a'; ['a','b'] -> 'a and b'; ['a','b','c'] -> 'a, b, and c'."""
+    items = [i for i in items if i]
+    if not items:
+        return ""
+    if len(items) == 1:
+        return items[0]
+    if len(items) == 2:
+        return f"{items[0]} {conj} {items[1]}"
+    return ", ".join(items[:-1]) + f", {conj} {items[-1]}"
+
+
+# ---- author renderers per style (reference list) ----
+def _auth_apa(au):
+    """Anderson, B.  +  '..., & ...'  ; 21+ -> first 19, …, last."""
+    names = [f"{a['family']}, {_initials(a['given'])}".rstrip(", ").rstrip()
+             for a in au]
+    if not names:
+        return ""
+    if len(names) == 1:
+        return names[0]
+    if len(names) <= 20:
+        return ", ".join(names[:-1]) + ", & " + names[-1]
+    return ", ".join(names[:19]) + ", … " + names[-1]
+
+
+def _auth_mla(au):
+    """Last, First.  / two: 'Last, First, and First Last' / 3+: 'Last, First, et al.'"""
+    if not au:
+        return ""
+    first = f"{au[0]['family']}, {au[0]['given']}".rstrip(", ").rstrip()
+    if len(au) == 1:
+        return first
+    if len(au) == 2:
+        return f"{first}, and {au[1]['given']} {au[1]['family']}".replace("  ", " ").strip()
+    return f"{first}, et al."
+
+
+def _auth_chicago(au):
+    """First inverted, rest 'First Last'. Reference list always uses the comma before
+    'and' (even for two authors, since the first name is inverted). Lists all names."""
+    if not au:
+        return ""
+    first = f"{au[0]['family']}, {au[0]['given']}".rstrip(", ").rstrip()
+    if len(au) == 1:
+        return first
+    rest = [f"{a['given']} {a['family']}".strip() for a in au[1:]]
+    if len(rest) == 1:
+        return f"{first}, and {rest[0]}"
+    return f"{first}, " + ", ".join(rest[:-1]) + f", and {rest[-1]}"
+
+
+def _auth_bibtex(au):
+    return " and ".join(f"{a['family']}, {a['given']}".rstrip(", ").rstrip() for a in au)
+
+
+def _editors(eds, style):
+    eds = _norm_authors(eds)
+    if not eds:
+        return ""
+    if style == "apa":  # 'S. Malpas & P. Wake'
+        names = [f"{_initials(e['given'])} {e['family']}".strip() for e in eds]
+        if len(names) == 1:
+            return names[0]
+        return " & ".join([", ".join(names[:-1]), names[-1]]) if len(names) > 2 \
+            else " & ".join(names)
+    # mla / chicago: 'First Last' joined by Oxford and
+    names = [f"{e['given']} {e['family']}".strip() for e in eds]
+    return _oxford(names, "and")
+
+
+def _intext_names(au, style):
+    fams = [a["family"] for a in au]
+    if not fams:
+        return ""
+    if style == "apa":
+        if len(fams) == 1:
+            return fams[0]
+        if len(fams) == 2:
+            return f"{fams[0]} & {fams[1]}"
+        return f"{fams[0]} et al."
+    if style == "mla":
+        if len(fams) == 1:
+            return fams[0]
+        if len(fams) == 2:
+            return f"{fams[0]} and {fams[1]}"
+        return f"{fams[0]} et al."
+    # chicago author-date
+    if len(fams) == 1:
+        return fams[0]
+    if len(fams) <= 3:
+        return _oxford(fams, "and")
+    return f"{fams[0]} et al."
+
+
+# ---------------------------------------------------------------- renderers
+# Each returns a list of segments: ("t", text) plain or ("i", text) italic.
+def _seg_join(segs):
+    return segs
+
+
+def _render(segs, mode):
+    out = []
+    for kind, txt in segs:
+        if kind == "i":
+            out.append({"markdown": f"*{txt}*", "html": f"<i>{txt}</i>",
+                        "plain": txt}[mode])
+        else:
+            out.append(txt)
+    return "".join(out)
+
+
+def _t(s):
+    return ("t", s)
+
+
+def _i(s):
+    return ("i", s)
+
+
+def _apa(typ, f, au):
+    yr = f.get("year") or "n.d."
+    title = f["_title"]
+    cont = f.get("container", "")
+    segs = []
+    a = _auth_apa(au)
+    if a:
+        segs.append(_t(f"{_period(a)} "))
+    # date
+    if typ == "web" and (f.get("month") or f.get("day")):
+        d = str(yr)
+        if f.get("month"):
+            d += f", {f['month']}"
+            if f.get("day"):
+                d += f" {f['day']}"
+        segs.append(_t(f"({d}). "))
+    else:
+        segs.append(_t(f"({yr}). "))
+    if typ == "article":
+        segs += [_t(f"{_period(title)} "), _i(cont)]
+        vol = f.get("volume", "")
+        if vol:
+            segs.append(_t(", "))
+            segs.append(_i(str(vol)))
+            if f.get("issue"):
+                segs.append(_t(f"({f['issue']})"))
+        if f.get("pages"):
+            segs.append(_t(f", {_pages(f['pages'])}"))
+        segs.append(_t("."))
+    elif typ == "book":
+        segs += [_i(title), _t(". ")]
+        if f.get("publisher"):
+            segs.append(_t(f"{f['publisher']}."))
+    elif typ == "chapter":
+        segs.append(_t(f"{_period(title)} In {_editors(f.get('editors'), 'apa')} "
+                       f"({'Eds.' if len(_norm_authors(f.get('editors'))) > 1 else 'Ed.'}), "))
+        segs.append(_i(f.get("book_title", cont)))
+        if f.get("pages"):
+            segs.append(_t(f" (pp. {_pages(f['pages'])})"))
+        segs.append(_t(". "))
+        if f.get("publisher"):
+            segs.append(_t(f"{f['publisher']}."))
+    elif typ == "web":
+        segs += [_t(f"{_period(title)} "), _i(cont), _t(".")]
+    # trailing doi / url
+    link = _apa_link(f)
+    if link:
+        segs.append(_t(f" {link}"))
+    return segs
+
+
+def _apa_link(f):
+    if f.get("doi"):
+        d = f["doi"]
+        return d if d.startswith("http") else f"https://doi.org/{d}"
+    return f.get("url", "")
+
+
+def _mla(typ, f, au):
+    title = f["_title"]
+    cont = f.get("container", "")
+    segs = []
+    a = _auth_mla(au)
+    if a:
+        segs.append(_t(f"{_period(a)} "))
+    if typ == "book":
+        segs += [_i(title), _t(". ")]
+        pub = f.get("publisher", "")
+        yr = f.get("year", "")
+        segs.append(_t(f"{pub}, {yr}." if pub else f"{yr}."))
+        return segs
+    # article / chapter / web all quote the piece title
+    segs.append(_t(f"{_quote(title)} "))
+    if typ == "chapter":
+        segs.append(_i(f.get("book_title", cont)))
+        bits = []
+        if f.get("editors"):
+            bits.append(f"edited by {_editors(f.get('editors'), 'mla')}")
+        if f.get("publisher"):
+            bits.append(f["publisher"])
+        if f.get("year"):
+            bits.append(str(f["year"]))
+        if f.get("pages"):
+            bits.append(f"pp. {_pages(f['pages'])}")
+        segs.append(_t(", " + ", ".join(bits) + "." if bits else "."))
+        return segs
+    # article / web
+    segs.append(_i(cont))
+    bits = []
+    if typ == "article":
+        if f.get("volume"):
+            bits.append(f"vol. {f['volume']}")
+        if f.get("issue"):
+            bits.append(f"no. {f['issue']}")
+        if f.get("year"):
+            bits.append(str(f["year"]))
+        if f.get("pages"):
+            bits.append(f"pp. {_pages(f['pages'])}")
+    else:  # web
+        if f.get("day") or f.get("month") or f.get("year"):
+            bits.append(_mla_date(f))
+    tail = ", " + ", ".join(b for b in bits if b) if bits else ""
+    link = f.get("url") or (("https://doi.org/" + f["doi"]) if f.get("doi") else "")
+    if link:
+        tail += f", {link}"
+    segs.append(_t(tail + "."))
+    return segs
+
+
+def _mla_date(f):
+    parts = []
+    if f.get("day"):
+        parts.append(str(f["day"]))
+    if f.get("month"):
+        parts.append(_MLA_MONTH.get(str(f["month"]).lower(), str(f["month"])))
+    if f.get("year"):
+        parts.append(str(f["year"]))
+    return " ".join(parts)
+
+
+def _chicago(typ, f, au):
+    title = f["_title"]
+    cont = f.get("container", "")
+    yr = f.get("year") or "n.d."
+    segs = []
+    a = _auth_chicago(au)
+    if a:
+        segs.append(_t(f"{_period(a)} {yr}. "))
+    else:
+        segs.append(_t(f"{yr}. "))
+    if typ == "book":
+        segs.append(_i(title))
+        segs.append(_t(". "))
+        place, pub = f.get("place", ""), f.get("publisher", "")
+        if place and pub:
+            segs.append(_t(f"{place}: {pub}."))
+        elif pub:
+            segs.append(_t(f"{pub}."))
+        return segs
+    segs.append(_t(f"{_quote(title)} "))
+    if typ == "chapter":
+        segs += [_t("In "), _i(f.get("book_title", cont))]
+        bits = []
+        if f.get("editors"):
+            bits.append(f"edited by {_editors(f.get('editors'), 'chicago')}")
+        if f.get("pages"):
+            bits.append(_pages(f["pages"]))
+        segs.append(_t(", " + ", ".join(bits) if bits else ""))
+        segs.append(_t(". "))
+        place, pub = f.get("place", ""), f.get("publisher", "")
+        if place and pub:
+            segs.append(_t(f"{place}: {pub}."))
+        elif pub:
+            segs.append(_t(f"{pub}."))
+        return segs
+    if typ == "article":
+        segs.append(_i(cont))
+        tail = ""
+        if f.get("volume"):
+            tail += f" {f['volume']}"
+            if f.get("issue"):
+                tail += f", no. {f['issue']}"
+        if f.get("month"):
+            tail += f" ({f['month']})"
+        if f.get("pages"):
+            tail += f": {_pages(f['pages'])}"
+        tail += "."
+        segs.append(_t(tail))
+        if f.get("doi"):
+            d = f["doi"]
+            segs.append(_t(f" {d if d.startswith('http') else 'https://doi.org/' + d}."))
+        elif f.get("url"):
+            segs.append(_t(f" {f['url']}."))
+        return segs
+    # web
+    if cont:
+        segs.append(_t(f"{cont}. "))
+    if f.get("url"):
+        segs.append(_t(f"{f['url']}."))
+    return segs
+
+
+def _bibtex(typ, f, au):
+    bt = {"article": "article", "book": "book", "chapter": "incollection",
+          "web": "misc"}[typ]
+    key = (au[0]["family"].lower().replace(" ", "") if au else "ref") + str(f.get("year") or "")
+    key = re.sub(r"[^a-z0-9]", "", key)
+    fields = [("author", _auth_bibtex(au))]
+    if typ == "chapter":
+        fields.append(("title", f["_title"]))
+        fields.append(("booktitle", f.get("book_title", f.get("container", ""))))
+        if f.get("editors"):
+            fields.append(("editor", _auth_bibtex(_norm_authors(f.get("editors")))))
+    else:
+        fields.append(("title", f["_title"]))
+    if typ == "article":
+        fields.append(("journal", f.get("container", "")))
+        for k in ("volume", "number_from_issue"):
+            pass
+        if f.get("volume"):
+            fields.append(("volume", str(f["volume"])))
+        if f.get("issue"):
+            fields.append(("number", str(f["issue"])))
+    if typ in ("book", "chapter"):
+        if f.get("publisher"):
+            fields.append(("publisher", f["publisher"]))
+        if f.get("place"):
+            fields.append(("address", f["place"]))
+    if f.get("pages"):
+        fields.append(("pages", _pages(f["pages"]).replace("–", "--")))
+    if f.get("year"):
+        fields.append(("year", str(f["year"])))
+    if f.get("doi"):
+        fields.append(("doi", f["doi"]))
+    if f.get("url"):
+        fields.append(("url", f["url"]))
+    body = ",\n".join(f"  {k} = {{{v}}}" for k, v in fields if v)
+    return f"@{bt}{{{key},\n{body}\n}}"
+
+
+def _intext(style, typ, f, au):
+    names = _intext_names(au, style)
+    yr = f.get("year") or "n.d."
+    pg = f.get("locator") or ""  # page/paragraph for in-text
+    if not names:  # no author -> short title
+        names = f["_title"].split()
+        names = " ".join(names[:4])
+        names = f'"{names}"'
+    if style == "apa":
+        s = f"({names}, {yr}"
+        if pg:
+            s += f", p. {pg}" if str(pg).isdigit() else f", {pg}"
+        return s + ")"
+    if style == "mla":
+        return f"({names} {pg})".replace(" )", ")") if pg else f"({names})"
+    if style == "chicago":
+        s = f"({names} {yr}"
+        if pg:
+            s += f", {pg}"
+        return s + ")"
+    return ""  # bibtex has no in-text
+
+
+# ---------------------------------------------------------------- public
+def compute(style, source_type=None, type=None, authors=None, title=None,
+            title_case=False, **f):
+    """Format a citation. style in STYLES; source_type in TYPES.
+
+    Fields (all optional except title): authors, title, year, container, volume,
+    issue, pages, publisher, place, doi, url, edition, editors, book_title,
+    month, day, locator (page/para for in-text).
+    """
+    style = (style or "").strip().lower()
+    typ = (source_type or type or "").strip().lower()
+    if style not in STYLES:
+        raise ValueError(f"style must be one of {STYLES}")
+    if typ not in TYPES:
+        raise ValueError(f"source_type must be one of {TYPES}")
+    if not title or not str(title).strip():
+        raise ValueError("title is required")
+    au = _norm_authors(authors)
+    f = dict(f)
+    f["authors"] = authors
+    if "editors" in f:
+        pass
+    t = str(title).strip()
+    f["_title"] = _title_case(t) if title_case else t
+    if f.get("book_title") and title_case:
+        f["book_title"] = _title_case(f["book_title"])
+
+    builder = {"apa": _apa, "mla": _mla, "chicago": _chicago}.get(style)
+    if style == "bibtex":
+        bib = _bibtex(typ, f, au)
+        return {"style": "bibtex", "source_type": typ,
+                "reference": {"markdown": bib, "html": bib, "plain": bib},
+                "bibtex": bib, "intext": None}
+    segs = builder(typ, f, au)
+    ref = {m: _render(segs, m) for m in ("markdown", "html", "plain")}
+    return {"style": style, "source_type": typ, "reference": ref,
+            "intext": _intext(style, typ, f, au)}
+
+
+def sample_output():
+    return compute("apa", "article",
+                   authors=[{"family": "Mounier-Kuhn", "given": "Pierre"}],
+                   title="Computer science in French universities: Early entrants and latecomers",
+                   year=2012, container="Information & Culture: A Journal of History",
+                   volume=47, issue=4, pages="414-456", doi="10.7560/IC47402")