second-read 0.1.1__py3-none-any.whl

second_read-0.1.1.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: second-read
+Version: 0.1.1
+Summary: Evidence-backed document review for Claude: fact-checks claims against the web and builds the strongest counter-argument, as an MCP server.
+Project-URL: Homepage, https://github.com/sbanthia92/second-read
+Project-URL: Repository, https://github.com/sbanthia92/second-read
+Project-URL: Issues, https://github.com/sbanthia92/second-read/issues
+Project-URL: Changelog, https://github.com/sbanthia92/second-read/releases
+Author: Shubham Banthia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,editing,fact-checking,llm,mcp,review
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing
+Requires-Python: <3.13,>=3.12
+Requires-Dist: anthropic>=1.10.0
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mcp>=2.2.0
+Requires-Dist: openai>=3.22.1
+Requires-Dist: pydantic>=2.13.5
+Description-Content-Type: text/markdown
+
+# Second Read
+
+Second Read reviews a draft the way a careful editor would, and shows its
+sources. You give it an article, a blog post or a design doc. It returns one
+report:
+
+- **Facts checked against the web.** Each claim is looked up, and every
+  "this is wrong" comes with the page that says so.
+- **The strongest counter-case.** A devil's advocate builds the best argument
+  against your piece from sources it retrieves.
+- **Copy edits.** Grammar and clarity fixes that keep your voice.
+- **Originality notes.** Sentences that closely match text found online.
+
+It runs as an [MCP](https://modelcontextprotocol.io) server with one tool,
+`review_document`, so you can ask for a review from Claude Code or Claude
+Desktop. It also has a command-line tool. It runs on your machine with **your
+own API keys**; nothing is sent to the author of this project.
+
+A finding looks like this:
+
+> **Factual error** — "Mjällby clinched the title on 20 October 2025 by winning
+> 2-0 at IFK Göteborg, with two games to spare"
+>
+> The date, the 2-0 score and the opponent are confirmed. ESPN and Flashscore
+> both say three rounds were left (27 of 30 played), so "two games to spare" is
+> wrong.
+
+## What you need
+
+- [uv](https://docs.astral.sh/uv/) (it installs Python 3.12 for you).
+- An [Anthropic](https://platform.claude.com) API key: `ANTHROPIC_API_KEY`.
+- A [Tavily](https://tavily.com) search key: `TAVILY_API_KEY`.
+
+### Getting your keys
+
+You need two keys. Each takes a couple of minutes: sign up, create a key, copy
+it.
+
+| Key | Where to get it |
+| --- | --- |
+| `ANTHROPIC_API_KEY` | Sign in at <https://platform.claude.com>, add credit under Billing, then create a key under **API keys** (<https://platform.claude.com/settings/keys>) |
+| `TAVILY_API_KEY` | Sign up at <https://app.tavily.com>; the key is shown on the dashboard |
+
+The Anthropic key is pay-as-you-go: reviews fail with a clear message if the
+account has no credit. Keep keys out of chats and out of version control; put
+them in the MCP client's `env` block or in a `.env` file as shown below.
+
+A review of a 700-word article takes about two minutes and uses roughly
+150,000–180,000 tokens on your model key (about $0.60–$1.20 at Anthropic's
+list prices in October 2026) plus about 30 searches.
+
+## Install: Claude Code
+
+```sh
+claude mcp add second-read \
+  -e ANTHROPIC_API_KEY=your-key \
+  -e TAVILY_API_KEY=your-key \
+  -- uvx --from git+https://github.com/sbanthia92/second-read secondread-mcp
+```
+
+Start Claude Code with a longer tool timeout, because a review takes minutes:
+
+```sh
+MCP_TOOL_TIMEOUT=600000 claude
+```
+
+Then ask: "Use second-read to review this draft", and paste the text or give a
+public URL.
+
+## Install: Claude Desktop
+
+Add this to `claude_desktop_config.json` (on macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`), then restart
+the app. If Claude Desktop cannot find `uvx`, use its full path (`which uvx`).
+
+```json
+{
+  "mcpServers": {
+    "second-read": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/sbanthia92/second-read", "secondread-mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your-key",
+        "TAVILY_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+To try it without keys, replace the `env` block with
+`{"SECONDREAD_FAKE": "1"}`. Demo mode returns placeholder findings and makes
+no model calls.
+
+## Command line
+
+```sh
+git clone https://github.com/sbanthia92/second-read && cd second-read
+cp .env.example .env        # then put your keys in .env
+uv run secondread review path/to/draft.md --profile opinion > report.md
+```
+
+Progress prints to the terminal; the report goes to `report.md`. Use
+`--profile design_doc` for technical design docs, or leave the profile out to
+let the tool decide. A URL works in place of a file path.
+
+## The tool
+
+`review_document` takes:
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `content` | one of `content` / `url` | The draft as text or markdown (up to 20,000 words) |
+| `url` | one of `content` / `url` | A public web page to fetch and review |
+| `profile` | no | `auto` (default), `opinion` or `design_doc` |
+| `focus` | no | A steer, e.g. "check the financial figures" |
+
+It returns the report as markdown and sends progress updates while it works.
+
+The report has these sections: a verdict line; **Must fix** (factual errors and
+claims the sources do not back); **Could not verify** (claims it found no
+adequate source for, which is not the same as wrong); **Strongest
+counter-case**; **Should fix** (structure); **Polish** (copy edits);
+**Originality notes**; and an appendix listing every claim with its verdict and
+sources.
+
+## Settings
+
+Set these in the MCP client's `env` block, in the environment, or in a `.env`
+file (the server reads `.env` from its working directory, or the file named by
+`SECONDREAD_ENV_FILE`).
+
+| Variable | Purpose |
+| --- | --- |
+| `ANTHROPIC_API_KEY` | Anthropic model key |
+| `TAVILY_API_KEY` | Web search key |
+| `SECONDREAD_MODEL_CHEAP`, `_MID`, `_STRONG` | Override the model used for each tier |
+| `SECONDREAD_MAX_WORDS` | Document size cap (default 20000) |
+| `SECONDREAD_FAKE=1` | Demo mode: no keys, no model calls |
+
+## What leaves your machine
+
+- **Your document** goes to Anthropic, under your key and their terms.
+- **Search queries** built from your document's claims, and up to eight
+  sentences quoted exactly for the originality check, go to Tavily.
+- **Web pages** named in search results are fetched directly from your machine.
+  The fetcher refuses private and local network addresses.
+
+Nothing is stored after the review finishes, and nothing is sent anywhere
+else. Keys are read from your environment and are never logged.
+
+## How well it works
+
+Measured on a small test in October 2026: four articles with planted errors
+that cannot be caught from memory (recent results, exact figures), one run
+each, compared with asking the same model to "review this and argue the other
+side" in a single prompt.
+
+| | Single prompt | Second Read |
+| --- | --- | --- |
+| Planted wrong facts caught (19) | 7 | 13 |
+| ...with a cited source | 0 | 13 |
+| Weak arguments rebutted (4) | 2 | 4 |
+| Borrowed sentences caught (3) | 3 | 1 |
+| Tokens per article | about 5,000 | about 136,000 |
+
+Second Read earns its cost on claims that need looking up: recent events,
+exact figures, and details a model cannot know from memory. Every finding
+names its source, so you can check it in one click.
+
+Getting the most from it:
+
+- Open the cited source before acting on a "factual error". The report links
+  the page and quotes the passage it relied on.
+- Search results change, so two runs on the same draft can differ slightly.
+- The originality check is a heuristic: it flags close matches found online.
+- Sources are web pages; PDFs are not read.
+
+## How it works
+
+An orchestrator runs specialist agents and settles their disagreements:
+
+1. A **claim extractor** splits the document into its thesis, supporting
+   claims and checkable facts.
+2. In parallel: a **fact-checker** researches each fact in a bounded loop
+   (search, fetch, read, assess; at most three rounds per claim); a **devil's
+   advocate** gathers counter-evidence; a **copy editor**; for articles, an
+   **originality checker**; and, for design docs, a **structure reviewer**.
+3. A reaction round: a verified fact the devil's advocate disputes is
+   re-checked, and the two argue once over the most important disagreements.
+4. Fixed rules settle what is left (for example, a grammar fix on a sentence
+   flagged as wrong is dropped), findings are ranked, and the report is written.
+
+`DESIGN.md` has the full design. `ARCHITECTURE.md` describes the shared types.
+
+## Development
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
+```
+
+Tests run offline with fakes. Tests that call real providers are marked `live`
+and skipped by default (`uv run pytest -m live`). The evaluation harness and
+its 40 seeded documents are in `eval/` (see `eval/README.md`); running it
+against real providers spends money on your keys.
+
+## Status
+
+The local MCP server and command-line tool work. A hosted version (sign in,
+add a key once, get the report by email) is designed in `DESIGN.md` but not
+built.
+
+## License
+
+MIT. See `LICENSE`.

second_read-0.1.1.dist-info/RECORD

@@ -0,0 +1,95 @@
+secondread/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secondread/pipeline.py,sha256=6gETxqfrs19BxWVrylqP9zwqo_XI8z-jrAnrRDqSXgM,2380
+secondread/registry.py,sha256=jRRDjqTP5FnUmHNRaCZAfntGLOJ7bf3C8XnZuhUGKTQ,9054
+secondread/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secondread/agents/copyedit/__init__.py,sha256=5PtZpcLs3YoFCoaT1yByeFImOV56Wc9cbnBqEW_-iSE,413
+secondread/agents/copyedit/agent.py,sha256=RvOkutqik-diKvQVNtwbth_pf_RFZNn90Hj9YGB34sg,9823
+secondread/agents/copyedit/prompts.py,sha256=dqxXYNwYnPLx7soJGVl3gn1OTpUV3hH3iP8f8iIrFGg,4920
+secondread/agents/copyedit/text.py,sha256=m-VIsjMfLq5ajLERJlqAGyFfhY7LbQlTgqwMJEu1Xrw,8422
+secondread/agents/devils_advocate/__init__.py,sha256=n8JNFnOdldvl4Y9Sma_YxeNh02jQF8Rc5NPRkoWVRNM,600
+secondread/agents/devils_advocate/agent.py,sha256=Khm2ZUJwftpWoLdcXDpiL_W-dulQc6tDckxvInZ01ak,25499
+secondread/agents/devils_advocate/prompts.py,sha256=Q7Gb2P_P6YgS5wnOnPcw97ZgxcoUPWnzeEs9Hw-L1to,10969
+secondread/agents/devils_advocate/schemas.py,sha256=PTG22TP70R9s_iJp7vK2utrR3n8Ve1q60GFeOrzoLBc,2475
+secondread/agents/devils_advocate/text.py,sha256=1fLDWTi0gwyqjzJRF_AEV6JrWFQeKRAphIBmPxi8ypE,4751
+secondread/agents/extractor/__init__.py,sha256=MhkB9fpu_Ynytxoy_wGBHIWarXBhASIvNjWsLa1CmUk,608
+secondread/agents/extractor/agent.py,sha256=5pRTa5YMsiUg7Xx8Tktafh04_psEVYu07YRVF_wn4XY,12003
+secondread/agents/extractor/chunks.py,sha256=rPSeqjCezMRJCJPOys2kL7oQiwo3hiaAeGaM81gqCvQ,1692
+secondread/agents/extractor/prompts.py,sha256=njA0VckeYcLRXYYMbPhHxYuyJCkAP7ZyisXPmkt_e5Q,4896
+secondread/agents/extractor/spans.py,sha256=wv9eqnyeK6sCEYQa6lOOuxhrp5OtSAOIVhMJ-xWqrm4,5652
+secondread/agents/factcheck/__init__.py,sha256=9Ysiqf2par4WEXAx2HVUYJ13Lk5708LkZL4IDFU2lPw,509
+secondread/agents/factcheck/agent.py,sha256=u3__NuNKsP1PrvFn5mqFYj_RgqlNcocs4JcctFrbnAk,10395
+secondread/agents/factcheck/prompts.py,sha256=m7bMivMfDohQ4jUJ4C4CgChnY4UD0AEGMBw1Sntjqsk,11489
+secondread/agents/factcheck/research.py,sha256=hCWfe33bG7UryDtSjIO-ekLmAp9IDXdlA8DLyWkswIo,30678
+secondread/agents/factcheck/schemas.py,sha256=rz9yChibT-ASJLopr6VA3xO-nD3NXcW6sNLWsRbFN7c,4235
+secondread/agents/factcheck/sources.py,sha256=rTb7a_wqMuOKqpRg7E1qdvH9eHUYiGAcqDG08aW_2Kc,10009
+secondread/agents/originality/__init__.py,sha256=BxpkJ8r4zxxbz569gU21gN_oMyRk0pBTJJSFopBGjAY,813
+secondread/agents/originality/agent.py,sha256=f3y2oZH7xwyG6LlRTgEq_xwQOmMrcoGWw-Sgr-mxIWI,10625
+secondread/agents/originality/sentences.py,sha256=XUGbY2kQv8qd8JWiKnoooo0SZ5k2lW9iuYXh3-YaRxI,12015
+secondread/agents/originality/similarity.py,sha256=CbsA3YYSaw2DAvUflkbFZMrzpXsN6pq0r5IgSuvzpCs,3947
+secondread/agents/structure/__init__.py,sha256=hGKKm8_lZfAZuHk97-1hDWejchjYfw9dFUc6WIqySsE,594
+secondread/agents/structure/agent.py,sha256=Cv6mC-OhSGTsfocoJGKYKA9AyNawefiJFONLeoUmlXY,11096
+secondread/agents/structure/prompts.py,sha256=E_sqLyjJBJMdVaixr_YFxxwUR3TagayJoJr3SvqWTlM,6816
+secondread/cli/__init__.py,sha256=uFcPDK9Aj4xH8epXMoXKzrH3g8JXYJkHHhyJDozilLA,203
+secondread/cli/__main__.py,sha256=SXMMPEDxXLTpA0MGWG2fQ_h1xDajxsREybeVxr5zrCI,113
+secondread/cli/envfile.py,sha256=kb7NHuRiUoiEF27ACl9n5-kuq5UqfyURvzyT8Qwh81c,2719
+secondread/cli/errors.py,sha256=kARoCvhEClX9pI6t6SMQlTiWhDdKc5lDK1yUJbiZDwM,3778
+secondread/cli/main.py,sha256=5eD5z1Wgq0tSan9uH_ksHu5dwdX7w6nRsL5WBcbHVEM,11108
+secondread/contracts/__init__.py,sha256=6JmVJvFbpb48sNjrvfcgn9aUXUUfL284abyAJVoNM_g,2388
+secondread/contracts/errors.py,sha256=3mns7OPECQlxfqG_ATYpTiSPMYt3jtOjDAI85zBN4mE,1683
+secondread/contracts/interfaces.py,sha256=_32gMrAzVmXuZqzr8qaAaAv_15edov3CLivCKVuh_HA,9679
+secondread/contracts/models.py,sha256=Kl-2VZel3chf1IfUOnSOdSWr1jxx1dN8ZQVU9FLjR4A,24049
+secondread/mcp_local/README.md,sha256=J_WjBZR-T9AGZ1ptr-nArf2WvfqN2-IG_CjPy7Kyhxw,3298
+secondread/mcp_local/__init__.py,sha256=FvM6WTqAs38XjOnNxum-aQ3vplb4plszNxYz7xfducY,953
+secondread/mcp_local/__main__.py,sha256=_bx-F6huhy6WQa_tjKh2_M36CQwP35QUr2pXOdkBb30,151
+secondread/mcp_local/demo.py,sha256=mVKqtU2cgvv4T5Yox1XlBCrqgLQpSsgy4a5_Q4n2ffQ,3963
+secondread/mcp_local/errors.py,sha256=QZDw_xdUdo6IVLyslbiVapgCHlKi7naZ216pHeQR3a8,3843
+secondread/mcp_local/main.py,sha256=YN2D5ubsqNFiyYsFi-PkFYhUtPim3ZMbcFXxW5r2R-0,3002
+secondread/mcp_local/progress.py,sha256=shmLqQrk45hxftj0Ly9SCl-CGUJsvxrE9M8wiAYogwI,3326
+secondread/mcp_local/server.py,sha256=0yJZBwlVywGKolbPVc0UTqBXd-NcYwtvOuXuprnXPWs,7348
+secondread/mcp_local/wiring.py,sha256=mnMVfNbXMWEwUUu6u2T8x4eyp9pMfTtB7OrC1PBFI8c,7951
+secondread/orchestrator/__init__.py,sha256=UALnVwzpQyQEfeaM59BxErvueURh0dwrDaYQqtYCXMo,1691
+secondread/orchestrator/assemble.py,sha256=AhiuoPns5AA6AmMqfRu_GDDMno56RRSbg9sTI79YbAw,5060
+secondread/orchestrator/authwatch.py,sha256=0BQRiyABQ-vWQUnU5b710C1--Qva-0jV5TmBOZwq_Vc,2443
+secondread/orchestrator/classify.py,sha256=OIVpV3xekuCT3AYTJhVYeGF6sT9-f1xfkSIcIrpiT3U,2812
+secondread/orchestrator/conflicts.py,sha256=SmGA3qs_czH_wlqK10vOXcJjMSPPTaU512rrR5mSo3E,15597
+secondread/orchestrator/labels.py,sha256=qYFfUCHI-whyEo1qWV5ZyuWiWs7hJ7evxg6Ki6ahoUA,1204
+secondread/orchestrator/orchestrator.py,sha256=xV78CWKx088y1EvriBzgZJO0aOXAaONTqNIM9b3jjNk,23599
+secondread/orchestrator/planning.py,sha256=bZ16ro9k-xVfs4FzK8NkFDpZ4kPhE_OegHGwOJtbhUQ,8772
+secondread/orchestrator/progress.py,sha256=nmZh3CO4VjyqD7PwnKbIgBR6TGQTto8nyir7pcKXscg,4208
+secondread/orchestrator/prompts.py,sha256=g_zrHwwzrCuIqpNAabkxiRNoie41TyrJG3OrvcBQZ6Q,5274
+secondread/orchestrator/reactions.py,sha256=4BahoyfcM33GPmM2QVUtQQvEEcY9kYOgDiYEjJL0sb8,5551
+secondread/orchestrator/registry.py,sha256=2EyZNvRcpHzxFh62_TrB2uoHz3cEk-lLVQQ3pLpaMOE,2011
+secondread/orchestrator/schemas.py,sha256=vC6cVild9tkzv2Ljwrl_I4wMrQM9itvHyvuTDiYJWGk,1258
+secondread/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secondread/providers/fetch/__init__.py,sha256=o7r8k9MUzxZneeNPZZk3FjXRDCRl0UaW6T5mXgSQYVI,794
+secondread/providers/fetch/extract.py,sha256=sHxAuIkKcXn9bpB5avZlsYFK7ITaeesSloKzx_Y2h6Q,4162
+secondread/providers/fetch/fetcher.py,sha256=ZQFtuUTpxgzXECUgX9xciw0CHk_ggHFgQVXdO5mi4Jk,9440
+secondread/providers/fetch/guarded.py,sha256=jJ5OXIIFGxoC11UeWTTLYZiZi9z_-xLUs4_8cvl4TNE,4192
+secondread/providers/fetch/ssrf.py,sha256=ZJzk8m8Qutvu2HJDNXr_eiD8FJmAXDM4BENj3nXkpuA,7409
+secondread/providers/llm/__init__.py,sha256=jEfd7HZ9rEXg299eG0MUcHrYS_z3JB3ymEPLd-D8uSI,1416
+secondread/providers/llm/_common.py,sha256=yDvwatqwfKbEEGaqAXYiDUL4nZYGnvTmmzCoSJS6eEY,8826
+secondread/providers/llm/anthropic_client.py,sha256=2aLvJoxl8L9YNR68jxxMb3Khb0Bj67G4FMONgRDluQ0,12124
+secondread/providers/llm/config.py,sha256=LBTsjX2uT1Ed1K5Gxb0zdrUQkILGYewGcLLWcfe0TvI,3021
+secondread/providers/llm/openai_client.py,sha256=6c3L1V6FHWzZAnK8UOOfroUdLC3xKNOVOlW4UHQDmxs,8389
+secondread/providers/search/__init__.py,sha256=6O3Q6kNyHLobR123p5GvbOplBWLhI_poGJWB-vIhRGs,1659
+secondread/providers/search/base.py,sha256=2vW3KEVj2xSiWWv8YkMU5_FQuWfUx8Go9BTHudgT2Hw,7576
+secondread/providers/search/brave.py,sha256=BPj8__NoOANiizYYoIEhd4fzCte9AYvDlaBFlUuxBsQ,1703
+secondread/providers/search/config.py,sha256=V17cdSXJyHNhLv_rdq_PZFp4FeQ_IWTxpb2T3nbS8vo,2242
+secondread/providers/search/exa.py,sha256=j_LcLcVLLlCr47U_PRULdI9sSQFuvBcLQ8QcImi8Lh0,2036
+secondread/providers/search/retry.py,sha256=M7s6A7RNoRXGkCAUugwEji0Sci5XGbD_lRLVBy50nVs,2168
+secondread/providers/search/tavily.py,sha256=qVn-3xRIr8A-Cd6_bl5fz_kFRsC_CrR_DzojVtvebuY,1827
+secondread/report/__init__.py,sha256=qmpB7yHsqq3ElsDbbmAQ0TQSu3s3dtjnKFSpQi5ky9w,1039
+secondread/report/email.py,sha256=PFs0wnYFOKPzAOkue6i3gPzIik4iEvBi2_yiJKj-ujU,1391
+secondread/report/html.py,sha256=8_jDt8b5BeQawa-grr7kzcGGVZcCyNdEAVac6_MvgmQ,1390
+secondread/report/markdown.py,sha256=8VDkRBRsQauaY2LEbfLX405N7kIBLDR6So53KcDPdb8,6770
+secondread/report/text.py,sha256=RKp66smYnDD5-02OPwevFxPXfnr_nmi7xbs9mLvKr2o,5521
+secondread/report/view.py,sha256=OeLDQ_ENJEtW9xkFNA5f2o1I5zDK8frAs6WtMMzQ6Mw,13252
+secondread/report/templates/email.html.j2,sha256=btoKzbpTgQXHHcii5NX3YfbjGKk91ZA6BDwzHWuUit4,6807
+secondread/testing/__init__.py,sha256=BnrCBfoNSE8O3tcaDaGvtQFbe30a-w4SPS7kNkTgy6E,78
+secondread/testing/fakes.py,sha256=aBSW-b95Q1Dl5FsV5vw3g38AE42uFKD-iWuopVzOk_o,14738
+secondread/testing/samples.py,sha256=E49tHPEmOGfOBcbWH2BOVSA-F3UfKpLVtfihGCzX9zU,11362
+second_read-0.1.1.dist-info/METADATA,sha256=s98olonzRSgLTT9xFNcoI12j8T5VR0J4I2xGWpkB3NY,9397
+second_read-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+second_read-0.1.1.dist-info/entry_points.txt,sha256=zT967noGnSdcioRQKz5hn65E_cYH1CK9Iky9L_hA2Sg,144
+second_read-0.1.1.dist-info/licenses/LICENSE,sha256=OkeCCajJ31d8eQ3UY-3mLFaby5_uy1gXV0yVqFOkaZQ,1072
+second_read-0.1.1.dist-info/RECORD,,

second_read-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

second_read-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+second-read = secondread.mcp_local.main:main
+secondread = secondread.cli:main
+secondread-mcp = secondread.mcp_local.main:main

second_read-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubham Banthia
+
+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.

secondread/agents/copyedit/__init__.py

@@ -0,0 +1,10 @@
+"""Copy editor agent.
+
+Line-level grammar, clarity and concision suggestions, each a
+``Severity.STYLE`` finding with a span into the document and a suggestion.
+"""
+
+from secondread.agents.copyedit.agent import CopyEditAgent, EditOutcome
+from secondread.agents.copyedit.prompts import TAG_EDIT, CopyEditOutput, ProposedEdit
+
+__all__ = ["TAG_EDIT", "CopyEditAgent", "CopyEditOutput", "EditOutcome", "ProposedEdit"]

secondread/agents/copyedit/agent.py

@@ -0,0 +1,261 @@
+"""The copy editor agent.
+
+Asks a cheap-tier model for line-level edits (verbatim quote plus
+replacement), locates each quote in the original text and returns one
+``Severity.STYLE`` finding per located edit. Every finding has a span that is
+valid for the document, and ``document.text[span.start:span.end]`` is the
+quoted passage (matched exactly, or modulo whitespace, quote-mark, dash and
+case normalization). Edits that cannot be located, are no-ops, overlap an
+earlier edit or are too large to be line edits are dropped and counted in
+``AgentResult.notes``. The agent never mutates the ledger.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from pydantic import ValidationError
+
+from secondread.agents.copyedit.prompts import (
+    TAG_EDIT,
+    CopyEditOutput,
+    ProposedEdit,
+    build_messages,
+)
+from secondread.agents.copyedit.text import Chunk, TextLocator, split_into_chunks
+from secondread.contracts.errors import BudgetExceeded, ProviderError
+from secondread.contracts.interfaces import LLMResponse, ModelTier, ReviewContext
+from secondread.contracts.models import (
+    AgentName,
+    AgentResult,
+    Finding,
+    ProgressEvent,
+    ProgressStep,
+    Severity,
+    Span,
+    Usage,
+    new_id,
+)
+
+log = logging.getLogger(__name__)
+
+DEFAULT_MAX_CHUNK_CHARS = 8_000
+"""Characters of document per copy-edit call (~2k tokens)."""
+
+DEFAULT_MAX_EDITS = 80
+"""Cap on edits kept per document (in document order)."""
+
+MAX_QUOTE_CHARS = 400
+"""Longer quotes are rewrites, not line edits, and are dropped."""
+
+_PROMPT_OVERHEAD_TOKENS = 700
+_OUTPUT_ALLOWANCE_TOKENS = 1_500
+
+
+def estimate_tokens(text: str, style_guide: str | None = None) -> int:
+    """Rough token estimate for one copy-edit call over ``text``."""
+    guide = len(style_guide or "")
+    return (len(text) + guide) // 4 + _PROMPT_OVERHEAD_TOKENS + _OUTPUT_ALLOWANCE_TOKENS
+
+
+@dataclass
+class EditOutcome:
+    """Result of ``edit``: findings plus drop counts for notes and tests."""
+
+    findings: list[Finding] = field(default_factory=list)
+    unlocated: int = 0
+    no_ops: int = 0
+    oversized: int = 0
+    overlapping: int = 0
+    truncated: int = 0
+    usage: Usage = field(default_factory=Usage)
+    error: str | None = None
+
+    def notes(self) -> list[str]:
+        """Human-readable notes (counts only, never document text)."""
+        notes: list[str] = []
+        if self.unlocated:
+            notes.append(
+                f"{self.unlocated} copy edit(s) quoted text not found in the document "
+                "and were dropped"
+            )
+        if self.no_ops:
+            notes.append(f"{self.no_ops} copy edit(s) that changed nothing were dropped")
+        if self.oversized:
+            notes.append(f"{self.oversized} copy edit(s) too large for a line edit were dropped")
+        if self.overlapping:
+            notes.append(f"{self.overlapping} overlapping copy edit(s) were dropped")
+        if self.truncated:
+            notes.append(f"{self.truncated} copy edit(s) omitted over the cap")
+        return notes
+
+
+class CopyEditAgent:
+    """Line-level grammar, clarity and concision suggestions with spans.
+
+    Implements the ``Agent`` protocol with ``name == AgentName.COPYEDIT``.
+    Uses ``ctx.style_guide`` when present. Long documents are processed in
+    chunks of ``max_chunk_chars``. Never raises for provider or budget
+    failures: returns the edits found so far with ``AgentResult.error`` set.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_chunk_chars: int = DEFAULT_MAX_CHUNK_CHARS,
+        max_edits: int = DEFAULT_MAX_EDITS,
+        model_tier: ModelTier = ModelTier.CHEAP,
+    ) -> None:
+        if max_chunk_chars <= 0 or max_edits <= 0:
+            raise ValueError("max_chunk_chars and max_edits must be positive")
+        self.max_chunk_chars = max_chunk_chars
+        self.max_edits = max_edits
+        self.model_tier = model_tier
+
+    @property
+    def name(self) -> str:
+        """``AgentName.COPYEDIT``."""
+        return AgentName.COPYEDIT
+
+    async def run(self, ctx: ReviewContext) -> AgentResult:
+        """Copy-edit the document and return ``STYLE`` findings."""
+        self._emit(ctx, "Copy editing", 0.0)
+        outcome = await self.edit(ctx)
+        message = f"Copy editing done: {len(outcome.findings)} suggestion(s)"
+        if outcome.error:
+            message += " (stopped early)"
+        self._emit(ctx, message, 100.0)
+        log.info(
+            "copyedit: %d edits, %d unlocated, error=%s",
+            len(outcome.findings),
+            outcome.unlocated,
+            bool(outcome.error),
+        )
+        return AgentResult(
+            agent=self.name,
+            findings=outcome.findings,
+            usage=outcome.usage,
+            error=outcome.error,
+            notes=outcome.notes(),
+        )
+
+    async def edit(self, ctx: ReviewContext) -> EditOutcome:
+        """Run copy editing over every chunk and post-process the edits."""
+        doc = ctx.document
+        outcome = EditOutcome()
+        chunks = [c for c in split_into_chunks(doc.text, self.max_chunk_chars) if c.text.strip()]
+        taken: list[Span] = []
+        for i, chunk in enumerate(chunks, start=1):
+            if len(chunks) > 1:
+                self._emit(
+                    ctx,
+                    f"Copy editing part {i} of {len(chunks)}",
+                    100.0 * (i - 1) / len(chunks),
+                )
+            try:
+                response = await self._call(ctx, chunk, i, len(chunks))
+            except BudgetExceeded as exc:
+                outcome.error = f"budget exhausted: {exc}"
+                break
+            except ProviderError as exc:
+                outcome.error = f"copy edit failed: {exc}"
+                break
+            outcome.usage = outcome.usage + response.usage
+            parsed = _parse(response)
+            if parsed is None:
+                outcome.error = outcome.error or "copy edit returned malformed output"
+                continue
+            locator = TextLocator(chunk.text)
+            for item in parsed.edits:
+                finding = self._to_finding(ctx, item, chunk, locator, taken, outcome)
+                if finding is not None:
+                    outcome.findings.append(finding)
+
+        outcome.findings.sort(key=lambda f: f.span.start if f.span else 0)
+        if len(outcome.findings) > self.max_edits:
+            outcome.truncated = len(outcome.findings) - self.max_edits
+            outcome.findings = outcome.findings[: self.max_edits]
+        for f in outcome.findings:  # invariant: every finding has a valid span
+            if f.span is None or not f.span.is_valid_for(doc.text):  # pragma: no cover
+                raise AssertionError("copy-edit finding without a valid span")
+        return outcome
+
+    # -- steps -------------------------------------------------------------
+
+    async def _call(self, ctx: ReviewContext, chunk: Chunk, part: int, parts: int) -> LLMResponse:
+        ctx.meter.require_tokens(estimate_tokens(chunk.text, ctx.style_guide))
+        response = await ctx.llm.complete(
+            build_messages(
+                chunk.text,
+                part=part,
+                parts=parts,
+                style_guide=ctx.style_guide,
+                focus=ctx.focus,
+            ),
+            schema=CopyEditOutput,
+            model_tier=self.model_tier,
+            tag=TAG_EDIT,
+            temperature=0.0,
+        )
+        ctx.meter.charge(response.usage)
+        return response
+
+    def _to_finding(
+        self,
+        ctx: ReviewContext,
+        item: ProposedEdit,
+        chunk: Chunk,
+        locator: TextLocator,
+        taken: list[Span],
+        outcome: EditOutcome,
+    ) -> Finding | None:
+        quote = item.quote.strip()
+        if len(quote) > MAX_QUOTE_CHARS or len(item.suggestion) > 2 * MAX_QUOTE_CHARS:
+            outcome.oversized += 1
+            return None
+        # Trimming is not allowed: the suggestion replaces exactly the quote,
+        # so a span that silently drops punctuation would corrupt the edit.
+        located = locator.locate(quote, allow_trim=False)
+        if located is None:
+            outcome.unlocated += 1
+            return None
+        spans = [Span(start=s.start + chunk.start, end=s.end + chunk.start) for s in located.spans]
+        # A repeated quote maps to its first occurrence not already edited.
+        span = next((s for s in spans if not any(s.overlaps(t) for t in taken)), None)
+        if span is None:
+            outcome.overlapping += 1
+            return None
+        original = span.text_of(ctx.document.text)
+        suggestion = item.suggestion.strip()
+        if suggestion == original.strip():
+            outcome.no_ops += 1
+            return None
+        taken.append(span)
+        reason = item.reason.strip() or "Suggested wording change."
+        return Finding(
+            id=new_id("find"),
+            agent=self.name,
+            severity=Severity.STYLE,
+            span=span,
+            message=f"{item.category.capitalize()}: {reason}",
+            suggestion=suggestion,
+            claim_ids=[e.claim.id for e in ctx.ledger.claims_overlapping(span)],
+        )
+
+    def _emit(self, ctx: ReviewContext, message: str, percent: float) -> None:
+        try:
+            ctx.emit_progress(
+                ProgressEvent(step=ProgressStep.REVIEWING, message=message, percent=percent)
+            )
+        except Exception:  # progress must never break the review
+            log.warning("copyedit: progress callback raised", exc_info=True)
+
+
+def _parse(response: LLMResponse) -> CopyEditOutput | None:
+    if isinstance(response.parsed, CopyEditOutput):
+        return response.parsed
+    try:
+        return CopyEditOutput.model_validate_json(response.text)
+    except ValidationError:
+        return None