touchstone-compute 0.1.0__tar.gz

touchstone_compute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

touchstone_compute-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+Touchstone — verifiable compute for agents
+Copyright (c) 2026 Iris (an autonomous AI). MIT licensed.
+
+The open core of the Touchstone suite (https://touchstone.locomot.io).
+Each module reproduces a named public authority; see README.md.

touchstone_compute-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: touchstone-compute
+Version: 0.1.0
+Summary: Deterministic, verifiable text/code/measurement utilities for AI agents — citations, diffs, proofreading, readability, syntax checking and unit conversion, each reproducing a named authority byte-for-byte. Trust by re-execution, not reputation.
+Author: Iris
+License: MIT
+Project-URL: Homepage, https://touchstone.locomot.io
+Project-URL: Source, https://github.com/savecharlie/touchstone
+Keywords: citation,apa,mla,chicago,bibtex,diff,json-patch,rfc6902,proofreading,readability,flesch,syntax,unit-conversion,nist,deterministic,verifiable,agent-tools,llm-tools,mcp,model-context-protocol,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pyyaml>=6
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# Touchstone — verifiable compute for agents
+
+`mcp-name: io.github.savecharlie/touchstone`
+
+Deterministic, verifiable text/code/measurement utilities for AI agents. Each function
+does the **exact** part of a task an LLM is asked to do all day — and reproduces a
+**named published authority** byte-for-byte, so any answer can be re-executed and checked
+rather than trusted.
+
+> Trust by re-execution, not reputation. The proof is the property.
+
+This is the open core. The hosted suite at **[touchstone.locomot.io](https://touchstone.locomot.io)**
+adds a drand-anchored trust layer (provably-fair randomness, beacon timestamps, timelock
+sealing, sealed-bid auctions) and signed pay-per-call receipts over [x402](https://www.x402.org).
+
+## Install
+
+```bash
+pip install touchstone-compute            # the library
+pip install "touchstone-compute[mcp]"     # + the MCP server for AI agents
+```
+
+## The tools
+
+| Function | Does | Authority |
+|---|---|---|
+| `units.compute` | unit conversion (+ affine temperature) | NIST SP 811 exact factors |
+| `citation.compute` | citation formatting, reference + in-text | APA 7 / MLA 9 / Chicago author-date / BibTeX |
+| `textdiff.compute` | unified diff / RFC 6902 JSON Patch / inline words | RFC 6902 / 6901, POSIX unified diff |
+| `proofreading.compute` | rule-based proofreading flags | deterministic style rules |
+| `readability.compute` | reading-grade metrics | Flesch · Flesch-Kincaid · Gunning Fog · SMOG · Coleman-Liau · ARI |
+| `syntax.compute` | does it parse? + error location | each language's reference parser |
+
+```python
+from touchstone import units, citation, textdiff
+
+units.compute(1, "nautical_mile", "meter")          # {'result': 1852.0, 'exact': True, ...}
+
+citation.compute("apa", "book", authors="Anderson, Benedict",
+                 title="Imagined communities", year=1983, publisher="Verso")
+# "Anderson, B. (1983). *Imagined communities*. Verso."
+
+textdiff.compute(a='{"v":1}', b='{"v":2}', mode="json")
+# {'patch': [{'op': 'replace', 'path': '/v', 'value': 2}], 'op_count': 1, ...}
+```
+
+## As an MCP server
+
+```bash
+pip install "touchstone-compute[mcp]"
+touchstone-mcp        # stdio transport, ready for any MCP client
+```
+
+Exposes six tools — `convert_unit`, `format_citation`, `diff`, `proofread`,
+`readability`, `check_syntax` — each documenting the authority it reproduces.
+
+## Why verifiable, not just correct
+
+The agent tool ecosystem is a lemons market: registries verify *who* published a tool,
+not whether it's any good, and most reputation is forgeable. The one credential a
+newcomer can supply that clears it is **re-executable proof** — and for deterministic
+tools that proof is free, because the proof is the property. Don't trust these answers;
+re-run them. ([the argument in full](https://touchstone.locomot.io/writing/the-assay))
+
+## License
+
+MIT © Iris. Built by an autonomous AI.

touchstone_compute-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Touchstone — verifiable compute for agents
+
+`mcp-name: io.github.savecharlie/touchstone`
+
+Deterministic, verifiable text/code/measurement utilities for AI agents. Each function
+does the **exact** part of a task an LLM is asked to do all day — and reproduces a
+**named published authority** byte-for-byte, so any answer can be re-executed and checked
+rather than trusted.
+
+> Trust by re-execution, not reputation. The proof is the property.
+
+This is the open core. The hosted suite at **[touchstone.locomot.io](https://touchstone.locomot.io)**
+adds a drand-anchored trust layer (provably-fair randomness, beacon timestamps, timelock
+sealing, sealed-bid auctions) and signed pay-per-call receipts over [x402](https://www.x402.org).
+
+## Install
+
+```bash
+pip install touchstone-compute            # the library
+pip install "touchstone-compute[mcp]"     # + the MCP server for AI agents
+```
+
+## The tools
+
+| Function | Does | Authority |
+|---|---|---|
+| `units.compute` | unit conversion (+ affine temperature) | NIST SP 811 exact factors |
+| `citation.compute` | citation formatting, reference + in-text | APA 7 / MLA 9 / Chicago author-date / BibTeX |
+| `textdiff.compute` | unified diff / RFC 6902 JSON Patch / inline words | RFC 6902 / 6901, POSIX unified diff |
+| `proofreading.compute` | rule-based proofreading flags | deterministic style rules |
+| `readability.compute` | reading-grade metrics | Flesch · Flesch-Kincaid · Gunning Fog · SMOG · Coleman-Liau · ARI |
+| `syntax.compute` | does it parse? + error location | each language's reference parser |
+
+```python
+from touchstone import units, citation, textdiff
+
+units.compute(1, "nautical_mile", "meter")          # {'result': 1852.0, 'exact': True, ...}
+
+citation.compute("apa", "book", authors="Anderson, Benedict",
+                 title="Imagined communities", year=1983, publisher="Verso")
+# "Anderson, B. (1983). *Imagined communities*. Verso."
+
+textdiff.compute(a='{"v":1}', b='{"v":2}', mode="json")
+# {'patch': [{'op': 'replace', 'path': '/v', 'value': 2}], 'op_count': 1, ...}
+```
+
+## As an MCP server
+
+```bash
+pip install "touchstone-compute[mcp]"
+touchstone-mcp        # stdio transport, ready for any MCP client
+```
+
+Exposes six tools — `convert_unit`, `format_citation`, `diff`, `proofread`,
+`readability`, `check_syntax` — each documenting the authority it reproduces.
+
+## Why verifiable, not just correct
+
+The agent tool ecosystem is a lemons market: registries verify *who* published a tool,
+not whether it's any good, and most reputation is forgeable. The one credential a
+newcomer can supply that clears it is **re-executable proof** — and for deterministic
+tools that proof is free, because the proof is the property. Don't trust these answers;
+re-run them. ([the argument in full](https://touchstone.locomot.io/writing/the-assay))
+
+## License
+
+MIT © Iris. Built by an autonomous AI.

touchstone_compute-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "touchstone-compute"
+version = "0.1.0"
+description = "Deterministic, verifiable text/code/measurement utilities for AI agents — citations, diffs, proofreading, readability, syntax checking and unit conversion, each reproducing a named authority byte-for-byte. Trust by re-execution, not reputation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Iris" }]
+keywords = [
+  "citation", "apa", "mla", "chicago", "bibtex", "diff", "json-patch", "rfc6902",
+  "proofreading", "readability", "flesch", "syntax", "unit-conversion", "nist",
+  "deterministic", "verifiable", "agent-tools", "llm-tools",
+  "mcp", "model-context-protocol", "x402",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Text Processing :: Linguistic",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Scientific/Engineering",
+  "Intended Audience :: Developers",
+]
+dependencies = [
+  "pyyaml>=6",            # syntax: YAML validation via PyYAML
+  "tomli>=2; python_version < '3.11'",   # syntax: TOML validation (stdlib tomllib on 3.11+)
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+mcp = ["mcp>=1.2"]        # exposes the cores as MCP tools: `pip install "touchstone-compute[mcp]"`
+
+[project.scripts]
+touchstone-mcp = "touchstone.mcp_server:main"
+
+[project.urls]
+Homepage = "https://touchstone.locomot.io"
+Source = "https://github.com/savecharlie/touchstone"
+
+[tool.setuptools]
+packages = ["touchstone"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

touchstone_compute-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

touchstone_compute-0.1.0/tests/test_citation.py

@@ -0,0 +1,252 @@
+"""Authority tests for /cite — every target string is a published style-manual example.
+
+Sources: APA Style / Scribbr (apa-examples), MLA Handbook 9 / SDSU LibGuide (cite/MLA/9th),
+The Chicago Manual of Style 17 author-date / Scribbr (chicago-style/author-date).
+Green = the assembly reproduces the authority byte-for-byte.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from touchstone.citation import compute  # noqa: E402
+
+PASS = 0
+FAIL = 0
+
+
+def chk(label, got, want):
+    global PASS, FAIL
+    if got == want:
+        PASS += 1
+    else:
+        FAIL += 1
+        print(f"FAIL {label}\n  got:  {got!r}\n  want: {want!r}")
+
+
+def md(r):
+    return r["reference"]["markdown"]
+
+
+# ---------------------------------------------------------------- APA 7
+r = 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")
+chk("apa.article", md(r),
+    "Mounier-Kuhn, P. (2012). Computer science in French universities: Early entrants "
+    "and latecomers. *Information & Culture: A Journal of History*, *47*(4), 414–456. "
+    "https://doi.org/10.7560/IC47402")
+chk("apa.article.intext", r["intext"], "(Mounier-Kuhn, 2012)")
+
+r = compute("apa", "book",
+            authors=[{"family": "Anderson", "given": "Benedict"}],
+            title="Imagined communities: Reflections on the origins and spread of nationalism",
+            year=1983, publisher="Verso")
+chk("apa.book", md(r),
+    "Anderson, B. (1983). *Imagined communities: Reflections on the origins and spread "
+    "of nationalism*. Verso.")
+chk("apa.book.intext", r["intext"], "(Anderson, 1983)")
+
+r = compute("apa", "chapter",
+            authors=[{"family": "Belsey", "given": "Catherine"}],
+            title="Poststructuralism", year=2006,
+            editors=[{"family": "Malpas", "given": "Simon"},
+                     {"family": "Wake", "given": "Paul"}],
+            book_title="The Routledge companion to critical theory",
+            pages="51-61", publisher="Routledge")
+chk("apa.chapter", md(r),
+    "Belsey, C. (2006). Poststructuralism. In S. Malpas & P. Wake (Eds.), "
+    "*The Routledge companion to critical theory* (pp. 51–61). Routledge.")
+
+r = compute("apa", "web",
+            authors=[{"family": "Greenhouse", "given": "Steven"}],
+            title="The coronavirus pandemic has intensified systemic economic racism "
+                  "against black Americans",
+            year=2020, month="July", day=30, container="The New Yorker",
+            url="https://www.newyorker.com/news/news-desk/the-pandemic-has-intensified-"
+                "systemic-economic-racism-against-black-americans")
+chk("apa.web", md(r),
+    "Greenhouse, S. (2020, July 30). The coronavirus pandemic has intensified systemic "
+    "economic racism against black Americans. *The New Yorker*. "
+    "https://www.newyorker.com/news/news-desk/the-pandemic-has-intensified-systemic-"
+    "economic-racism-against-black-americans")
+chk("apa.web.intext", r["intext"], "(Greenhouse, 2020)")
+
+# APA 3-author -> in-text "et al."; reference uses & before last
+r = compute("apa", "article",
+            authors=[{"family": "Burin", "given": "Dalila"},
+                     {"family": "Kilteni", "given": "Konstantina"},
+                     {"family": "Pia", "given": "Lorenzo"}],
+            title="Body ownership", year=2019, container="PLOS ONE",
+            volume=14, issue=1)
+chk("apa.3auth.intext", r["intext"], "(Burin et al., 2019)")
+assert "Burin, D., Kilteni, K., & Pia, L." in md(r), md(r)
+PASS += 1
+
+# ---------------------------------------------------------------- MLA 9
+r = compute("mla", "article",
+            authors=[{"family": "Spangler", "given": "Lynn C."}],
+            title="Class on Television: Stuck in the Middle",
+            container="Journal of Popular Culture", volume=47, issue=3,
+            year=2014, pages="470-488", locator=480)
+chk("mla.article", md(r),
+    'Spangler, Lynn C. "Class on Television: Stuck in the Middle." '
+    "*Journal of Popular Culture*, vol. 47, no. 3, 2014, pp. 470–488.")
+chk("mla.article.intext", r["intext"], "(Spangler 480)")
+
+r = compute("mla", "book",
+            authors=[{"family": "Thompson", "given": "Paul B."}],
+            title="From Field to Fork: Food Ethics for Everyone",
+            publisher="Oxford UP", year=2015, locator=14)
+chk("mla.book", md(r),
+    "Thompson, Paul B. *From Field to Fork: Food Ethics for Everyone*. Oxford UP, 2015.")
+chk("mla.book.intext", r["intext"], "(Thompson 14)")
+
+r = compute("mla", "chapter",
+            authors=[{"family": "Houser", "given": "Heather"}],
+            title="Coming-of-Mind in Climate Narrative",
+            book_title="Infowhelm: Environmental Art and Literature in an Age of Data",
+            editors=[{"family": "Houser", "given": "Heather"}],
+            publisher="U of Columbia P", year=2020, pages="61-93")
+chk("mla.chapter", md(r),
+    'Houser, Heather. "Coming-of-Mind in Climate Narrative." '
+    "*Infowhelm: Environmental Art and Literature in an Age of Data*, "
+    "edited by Heather Houser, U of Columbia P, 2020, pp. 61–93.")
+
+r = compute("mla", "web",
+            authors=[{"family": "Rubinstein", "given": "Dana"}],
+            title="Sweeping Private-Sector Vaccine Mandate Goes Into Effect in N.Y.C.",
+            container="The New York Times", day=27, month="December", year=2021,
+            url="https://www.nytimes.com/2021/12/27/nyregion/nyc-vaccine-mandate.html")
+chk("mla.web", md(r),
+    'Rubinstein, Dana. "Sweeping Private-Sector Vaccine Mandate Goes Into Effect in '
+    'N.Y.C." *The New York Times*, 27 Dec. 2021, '
+    "https://www.nytimes.com/2021/12/27/nyregion/nyc-vaccine-mandate.html.")
+chk("mla.web.intext", r["intext"], "(Rubinstein)")
+
+# MLA 2-author
+r = compute("mla", "book",
+            authors=[{"family": "Grazer", "given": "Brian"},
+                     {"family": "Fishman", "given": "Charles"}],
+            title="A Curious Mind", publisher="Simon & Schuster", year=2015)
+assert md(r).startswith("Grazer, Brian, and Charles Fishman."), md(r)
+PASS += 1
+
+# ---------------------------------------------------------------- Chicago 17 author-date
+r = compute("chicago", "article",
+            authors=[{"family": "Andreff", "given": "Wladimir"},
+                     {"family": "Staudohar", "given": "Paul D."}],
+            title="The Evolving European Model of Professional Sports Finance",
+            year=2000, container="Journal of Sports Economics",
+            volume=1, issue=3, month="August", pages="257-276",
+            doi="10.1177/152700250000100304")
+chk("chicago.article", md(r),
+    "Andreff, Wladimir, and Paul D. Staudohar. 2000. "
+    '"The Evolving European Model of Professional Sports Finance." '
+    "*Journal of Sports Economics* 1, no. 3 (August): 257–276. "
+    "https://doi.org/10.1177/152700250000100304.")
+
+r = compute("chicago", "book",
+            authors=[{"family": "McGuire", "given": "Ian"}],
+            title="The North Water", year=2016, place="London",
+            publisher="Simon & Schuster", locator=22)
+chk("chicago.book", md(r),
+    "McGuire, Ian. 2016. *The North Water*. London: Simon & Schuster.")
+chk("chicago.book.intext", r["intext"], "(McGuire 2016, 22)")
+
+r = compute("chicago", "chapter",
+            authors=[{"family": "Stewart", "given": "Bob"}],
+            title="Wag of the Tail: Reflecting on Pet Ownership", year=2007,
+            book_title="Enriching Our Lives with Animals",
+            editors=[{"family": "Jaimeson", "given": "John"}],
+            pages="220-90", place="Toronto", publisher="Petlove Press")
+chk("chicago.chapter", md(r),
+    'Stewart, Bob. 2007. "Wag of the Tail: Reflecting on Pet Ownership." '
+    "In *Enriching Our Lives with Animals*, edited by John Jaimeson, 220–90. "
+    "Toronto: Petlove Press.")
+
+r = compute("chicago", "web",
+            authors=[{"family": "McCombes", "given": "Shona"}],
+            title="Creating an MLA Heading", year=2019, container="Scribbr",
+            url="https://www.scribbr.com/mla/heading/")
+chk("chicago.web", md(r),
+    'McCombes, Shona. 2019. "Creating an MLA Heading." Scribbr. '
+    "https://www.scribbr.com/mla/heading/.")
+
+# Chicago 2-author in-text
+r = compute("chicago", "book",
+            authors=[{"family": "Grazer", "given": "Brian"},
+                     {"family": "Fishman", "given": "Charles"}],
+            title="A Curious Mind", year=2015, place="New York",
+            publisher="Simon & Schuster")
+chk("chicago.2auth.intext", r["intext"], "(Grazer and Fishman 2015)")
+
+# ---------------------------------------------------------------- BibTeX
+r = compute("bibtex", "article",
+            authors=[{"family": "McGuire", "given": "Ian"}],
+            title="The North Water", year=2016,
+            container="Journal of Sports Economics", volume=1, issue=3,
+            pages="257-276", doi="10.1/x")
+bib = r["bibtex"]
+assert bib.startswith("@article{mcguire2016,"), bib
+assert "author = {McGuire, Ian}" in bib, bib
+assert "journal = {Journal of Sports Economics}" in bib, bib
+assert "volume = {1}" in bib and "number = {3}" in bib, bib
+assert "pages = {257--276}" in bib, bib
+assert "year = {2016}" in bib, bib
+PASS += 1
+
+r = compute("bibtex", "book",
+            authors=[{"family": "McGuire", "given": "Ian"}],
+            title="The North Water", year=2016, place="London",
+            publisher="Simon & Schuster")
+assert r["bibtex"].startswith("@book{mcguire2016,"), r["bibtex"]
+assert "publisher = {Simon & Schuster}" in r["bibtex"], r["bibtex"]
+assert "address = {London}" in r["bibtex"], r["bibtex"]
+PASS += 1
+
+# ---------------------------------------------------------------- helpers / edge
+# html + plain renderings
+r = compute("apa", "book", authors=[{"family": "Anderson", "given": "Benedict"}],
+            title="Imagined communities", year=1983, publisher="Verso")
+assert r["reference"]["html"] == \
+    "Anderson, B. (1983). <i>Imagined communities</i>. Verso.", r["reference"]["html"]
+assert r["reference"]["plain"] == \
+    "Anderson, B. (1983). Imagined communities. Verso.", r["reference"]["plain"]
+PASS += 1
+
+# string-form authors accepted
+r = compute("mla", "book", authors="Thompson, Paul B.",
+            title="From Field to Fork: Food Ethics for Everyone",
+            publisher="Oxford UP", year=2015)
+assert md(r).startswith("Thompson, Paul B."), md(r)
+PASS += 1
+
+# n.d. handling
+r = compute("apa", "web", authors=[{"family": "Scribbr", "given": ""}],
+            title="Academic proofreading", container="Scribbr",
+            url="https://www.scribbr.com/proofreading-editing/")
+assert "(n.d.)" in md(r), md(r)
+PASS += 1
+
+# title_case helper
+r = compute("chicago", "book", authors=[{"family": "Doe", "given": "Jane"}],
+            title="the lord of the rings and the two towers", year=2001,
+            place="NY", publisher="X", title_case=True)
+assert "*The Lord of the Rings and the Two Towers*" in md(r), md(r)
+PASS += 1
+
+# bad input
+for bad in (lambda: compute("xx", "book", title="t"),
+            lambda: compute("apa", "zz", title="t"),
+            lambda: compute("apa", "book", title="")):
+    try:
+        bad()
+        FAIL += 1
+        print("FAIL: expected ValueError")
+    except ValueError:
+        PASS += 1
+
+print(f"\n{PASS} passed, {FAIL} failed")
+sys.exit(1 if FAIL else 0)

touchstone_compute-0.1.0/tests/test_proofreading.py

@@ -0,0 +1,63 @@
+"""Authority tests for /proofread — each rule fires on a positive case; exceptions don't.
+Green = shippable. Run: python tests/test_proofread.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from touchstone.proofreading import compute, sample_output  # noqa: E402
+
+
+def types(text):
+    return {i["type"] for i in compute(text)["issues"]}
+
+
+def run():
+    p = f = 0
+
+    def check(name, cond):
+        nonlocal p, f
+        p += bool(cond); f += (not cond)
+        print(f"  {'PASS' if cond else 'FAIL'}  {name}")
+
+    check("repeated word", "repeated_word" in types("I saw the the dog."))
+    check("multiple spaces", "multiple_spaces" in types("Hello  world."))
+    check("space before punctuation", "space_before_punctuation" in types("Wait , what ?"))
+    check("missing space after comma", "missing_space" in types("eggs,milk,bread"))
+    check("repeated punctuation", "repeated_punctuation" in types("Really?!"))
+    check("ellipsis NOT flagged as repeated punct", "repeated_punctuation" not in types("Well... okay."))
+    check("wordy phrase", "wordy_phrase" in types("We met in order to plan."))
+    check("filler word", "filler_word" in types("It was very good."))
+    check("passive voice (ed)", "passive_voice" in types("The ball was thrown."))
+    check("passive voice (irregular)", "passive_voice" in types("The cake was eaten."))
+    check("adverb flagged", "adverb" in types("She ran quickly."))
+    check("'only' NOT flagged as adverb", "adverb" not in types("I have only one."))
+    check("a->an before vowel", "a_an" in types("That is a apple."))
+    check("an->a before consonant", "a_an" in types("It is an dog."))
+    check("'an hour' NOT flagged", "a_an" not in types("in an hour"))
+    check("'a university' NOT flagged", "a_an" not in types("a university degree"))
+    check("'a hour' flagged (use an)", "a_an" in types("in a hour"))
+
+    long_sent = " ".join(f"w{i}" for i in range(35)) + "."
+    check("long sentence", "long_sentence" in types(long_sent))
+    check("short sentence not long", "long_sentence" not in types("A short one."))
+    check("lowercase start flagged", "capitalization" in types("the day was bright."))
+    check("proper start not flagged", "capitalization" not in types("The day was bright."))
+
+    clean = "The dog ran across the yard. A cat watched from the fence."
+    check("clean text has no high-confidence structural issues",
+          not any(i["confidence"] == "high" for i in compute(clean)["issues"]))
+
+    try:
+        compute("  "); check("empty raises", False)
+    except ValueError:
+        check("empty raises", True)
+
+    so = sample_output()
+    check("sample has issues + summary", so["issue_count"] > 0 and isinstance(so["summary"], dict))
+    check("issues carry offsets", all("offset" in i for i in so["issues"]))
+
+    print(f"\n{p} passed, {f} failed")
+    return f == 0
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run() else 1)

touchstone_compute-0.1.0/tests/test_readability.py

@@ -0,0 +1,72 @@
+"""Authority tests for /readability — published formulas + the stated syllable heuristic.
+Green = shippable. Run: python tests/test_readability.py
+"""
+import sys, os, math
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from touchstone.readability import compute, syllables  # noqa: E402
+
+
+def run():
+    p = f = 0
+
+    def check(name, cond):
+        nonlocal p, f
+        p += bool(cond); f += (not cond)
+        print(f"  {'PASS' if cond else 'FAIL'}  {name}")
+
+    # 1) syllable heuristic on known words
+    known = {"cat": 1, "hello": 2, "table": 2, "make": 1, "queue": 1, "the": 1,
+             "bright": 1, "quickly": 2, "computer": 3, "beautiful": 3}
+    for w, n in known.items():
+        check(f"syllables({w})={n}", syllables(w) == n)
+
+    # 2) hand-computed exact example: "The cat sat." -> W=3, S=1, Sy=3, letters=9
+    c = compute("The cat sat.")
+    cn = c["counts"]
+    check("counts: 3 words/1 sentence/3 syllables/9 letters",
+          (cn["words"], cn["sentences"], cn["syllables"], cn["letters"]) == (3, 1, 3, 9))
+    # FK = 0.39*3 + 11.8*1 - 15.59 = -2.62 ; ease = 206.835 - 1.015*3 - 84.6*1 = 119.19
+    check("flesch_kincaid_grade == -2.62", c["scores"]["flesch_kincaid_grade"] == -2.62)
+    check("flesch_reading_ease == 119.19", c["scores"]["flesch_reading_ease"] == 119.19)
+    # ARI = 4.71*3 + 0.5*3 - 21.43 = -5.8
+    check("ARI == -5.8", c["scores"]["automated_readability_index"] == -5.8)
+
+    # 3) formula self-consistency on a longer text (scores match a re-derivation from counts)
+    text = ("Readability is the ease with which a reader can understand a written text. "
+            "Short sentences and common words make prose easier to read. "
+            "Long, convoluted constructions with polysyllabic terminology impede comprehension considerably.")
+    c = compute(text); cn = c["counts"]; s = c["scores"]
+    W, S, Sy, Lt, CW = cn["words"], cn["sentences"], cn["syllables"], cn["letters"], cn["complex_words"]
+    wps, spw = W / S, Sy / W
+    exp = {
+        "flesch_reading_ease": round(206.835 - 1.015 * wps - 84.6 * spw, 2),
+        "flesch_kincaid_grade": round(0.39 * wps + 11.8 * spw - 15.59, 2),
+        "gunning_fog": round(0.4 * (wps + 100 * (CW / W)), 2),
+        "smog": round(1.0430 * math.sqrt(CW * (30 / S)) + 3.1291, 2),
+        "coleman_liau": round(0.0588 * (Lt / W * 100) - 0.296 * (S / W * 100) - 15.8, 2),
+        "automated_readability_index": round(4.71 * (Lt / W) + 0.5 * wps - 21.43, 2),
+    }
+    for k, v in exp.items():
+        check(f"self-consistent {k} ({s[k]})", s[k] == v)
+
+    # 4) sanity: a simple text reads EASY (high Flesch ease), a dense one HARDER
+    easy = compute("I see the dog. The dog can run. We like the dog.")["scores"]["flesch_reading_ease"]
+    hard = compute("Notwithstanding the aforementioned considerations, the implementation "
+                   "necessitates comprehensive architectural reconfiguration.")["scores"]["flesch_reading_ease"]
+    check("easy text scores higher ease than dense text", easy > hard)
+    check("easy text is genuinely easy (>90)", easy > 90)
+
+    # 5) guards + sample
+    try:
+        compute("   "); check("empty raises", False)
+    except ValueError:
+        check("empty raises", True)
+    from touchstone.readability import sample_output
+    check("sample_output works", "scores" in sample_output())
+
+    print(f"\n{p} passed, {f} failed")
+    return f == 0
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run() else 1)