lingity 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. lingity-0.2.2/PKG-INFO +356 -0
  2. lingity-0.2.2/README.md +320 -0
  3. {lingity-0.2.0 → lingity-0.2.2}/lingity/__init__.py +1 -1
  4. {lingity-0.2.0 → lingity-0.2.2}/lingity/analyzer.py +148 -6
  5. {lingity-0.2.0 → lingity-0.2.2}/lingity/cli.py +112 -1
  6. {lingity-0.2.0 → lingity-0.2.2}/lingity/critique.py +58 -1
  7. {lingity-0.2.0 → lingity-0.2.2}/lingity/improve.py +217 -6
  8. {lingity-0.2.0 → lingity-0.2.2}/lingity/invariants.py +53 -1
  9. {lingity-0.2.0 → lingity-0.2.2}/lingity/markdown.py +14 -3
  10. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/architecture-review.v1.json +11 -2
  11. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/local-service.v1.json +11 -2
  12. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/product-strategy.v1.json +10 -1
  13. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/resume-review.v1.json +10 -1
  14. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/web-copy.v1.json +15 -2
  15. {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles.py +4 -0
  16. {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/anthropic_provider.py +24 -0
  17. {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/base.py +56 -0
  18. {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/openai_provider.py +17 -0
  19. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/analysis.schema.json +19 -1
  20. lingity-0.2.2/lingity/schemas/v1/critique.schema.json +329 -0
  21. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/profile.schema.json +15 -1
  22. lingity-0.2.2/lingity/schemas/v1/style-contract.schema.json +174 -0
  23. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/verdict.schema.json +24 -1
  24. lingity-0.2.2/lingity/styles/architecture-review.v1.json +91 -0
  25. lingity-0.2.2/lingity/styles/conservative-web-editor.v1.json +87 -0
  26. lingity-0.2.2/lingity/styles/local-service-guide.v1.json +87 -0
  27. lingity-0.2.2/lingity/styles/technical-writer.v1.json +122 -0
  28. lingity-0.2.2/lingity/styles.py +183 -0
  29. lingity-0.2.2/lingity.egg-info/PKG-INFO +356 -0
  30. {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/SOURCES.txt +7 -0
  31. {lingity-0.2.0 → lingity-0.2.2}/pyproject.toml +2 -2
  32. {lingity-0.2.0 → lingity-0.2.2}/tests/test_analysis.py +1 -0
  33. lingity-0.2.2/tests/test_cli.py +320 -0
  34. {lingity-0.2.0 → lingity-0.2.2}/tests/test_documentation.py +54 -0
  35. lingity-0.2.2/tests/test_improve.py +765 -0
  36. {lingity-0.2.0 → lingity-0.2.2}/tests/test_invariants.py +93 -2
  37. {lingity-0.2.0 → lingity-0.2.2}/tests/test_local_service_profile.py +60 -1
  38. {lingity-0.2.0 → lingity-0.2.2}/tests/test_product_strategy_profile.py +1 -1
  39. {lingity-0.2.0 → lingity-0.2.2}/tests/test_provider_anthropic.py +57 -1
  40. {lingity-0.2.0 → lingity-0.2.2}/tests/test_provider_openai.py +47 -0
  41. {lingity-0.2.0 → lingity-0.2.2}/tests/test_release.py +9 -0
  42. {lingity-0.2.0 → lingity-0.2.2}/tests/test_resume_review_profile.py +12 -4
  43. {lingity-0.2.0 → lingity-0.2.2}/tests/test_schemas.py +9 -0
  44. {lingity-0.2.0 → lingity-0.2.2}/tests/test_scoring.py +2 -1
  45. lingity-0.2.2/tests/test_styles.py +142 -0
  46. {lingity-0.2.0 → lingity-0.2.2}/tests/test_web_copy_profile.py +106 -0
  47. lingity-0.2.0/PKG-INFO +0 -443
  48. lingity-0.2.0/README.md +0 -407
  49. lingity-0.2.0/lingity/schemas/v1/critique.schema.json +0 -153
  50. lingity-0.2.0/lingity.egg-info/PKG-INFO +0 -443
  51. lingity-0.2.0/tests/test_cli.py +0 -111
  52. lingity-0.2.0/tests/test_improve.py +0 -367
  53. {lingity-0.2.0 → lingity-0.2.2}/LICENSE +0 -0
  54. {lingity-0.2.0 → lingity-0.2.2}/NOTICE +0 -0
  55. {lingity-0.2.0 → lingity-0.2.2}/lingity/__main__.py +0 -0
  56. {lingity-0.2.0 → lingity-0.2.2}/lingity/lexicon.py +0 -0
  57. {lingity-0.2.0 → lingity-0.2.2}/lingity/models.py +0 -0
  58. {lingity-0.2.0 → lingity-0.2.2}/lingity/morphology.py +0 -0
  59. {lingity-0.2.0 → lingity-0.2.2}/lingity/nlp.py +0 -0
  60. {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/__init__.py +0 -0
  61. {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/agent.py +0 -0
  62. {lingity-0.2.0 → lingity-0.2.2}/lingity/py.typed +0 -0
  63. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/provider-challenge.schema.json +0 -0
  64. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/provider-proposal.schema.json +0 -0
  65. {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/verification.schema.json +0 -0
  66. {lingity-0.2.0 → lingity-0.2.2}/lingity/scoring.py +0 -0
  67. {lingity-0.2.0 → lingity-0.2.2}/lingity/text.py +0 -0
  68. {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/dependency_links.txt +0 -0
  69. {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/entry_points.txt +0 -0
  70. {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/requires.txt +0 -0
  71. {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/top_level.txt +0 -0
  72. {lingity-0.2.0 → lingity-0.2.2}/setup.cfg +0 -0
  73. {lingity-0.2.0 → lingity-0.2.2}/tests/test_determinism.py +0 -0
  74. {lingity-0.2.0 → lingity-0.2.2}/tests/test_markdown.py +0 -0
  75. {lingity-0.2.0 → lingity-0.2.2}/tests/test_meaning_equivalence.py +0 -0
  76. {lingity-0.2.0 → lingity-0.2.2}/tests/test_morphology.py +0 -0
lingity-0.2.2/PKG-INFO ADDED
@@ -0,0 +1,356 @@
1
+ Metadata-Version: 2.4
2
+ Name: lingity
3
+ Version: 0.2.2
4
+ Summary: Deterministic governed text analysis
5
+ Author: phrocker
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/phrocker/lingitylingity
8
+ Project-URL: Repository, https://github.com/phrocker/lingitylingity
9
+ Project-URL: Issues, https://github.com/phrocker/lingitylingity/issues
10
+ Keywords: linguistics,readability,governance,nlp,deterministic
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Text Processing :: Linguistic
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ License-File: NOTICE
22
+ Requires-Dist: jsonschema<5,>=4.23
23
+ Requires-Dist: markdown-it-py<4,>=3
24
+ Requires-Dist: nltk<4,>=3.9
25
+ Requires-Dist: spacy<3.9,>=3.8
26
+ Provides-Extra: dev
27
+ Requires-Dist: mypy<2,>=1.13; extra == "dev"
28
+ Requires-Dist: pytest<9,>=8.3; extra == "dev"
29
+ Requires-Dist: trove-classifiers>=2024.10.0; extra == "dev"
30
+ Requires-Dist: types-jsonschema<5,>=4.23; extra == "dev"
31
+ Provides-Extra: release
32
+ Requires-Dist: lingity[dev]; extra == "release"
33
+ Requires-Dist: build<2,>=1.2; extra == "release"
34
+ Requires-Dist: twine<7,>=5; extra == "release"
35
+ Dynamic: license-file
36
+
37
+ # Lingity
38
+
39
+ Lingity provides deterministic, governed analysis and rewrite validation for
40
+ English Markdown or plain text written by people or language models. Use it
41
+ when readability may improve but facts, identifiers, quantities, modality,
42
+ negation, citations, ownership, and governance status must not change.
43
+
44
+ The local `analyze` and `verify` commands make no network or LLM calls.
45
+ Rewriting commands can use a host agent or an explicitly configured provider,
46
+ but deterministic code remains the authority that accepts or rejects a
47
+ candidate.
48
+
49
+ ## Prerequisites and installation
50
+
51
+ Lingity is not yet published to a package index. Install it from a clone with
52
+ Python 3.11 or later:
53
+
54
+ ```text
55
+ python -m pip install .
56
+ python -m pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
57
+ python -m nltk.downloader wordnet omw-1.4
58
+ ```
59
+
60
+ All three commands are required. The spaCy model must be exactly
61
+ `en_core_web_sm` 3.8.0; do not substitute
62
+ `python -m spacy download en_core_web_sm`, which can resolve a different
63
+ version. WordNet and `omw-1.4` are corpus data and must be downloaded
64
+ separately.
65
+
66
+ Lingity fails closed when these prerequisites are wrong or absent.
67
+ `LinguisticModelError` names the model installation command, and
68
+ `WordNetDataError` names the corpus command. Analysis never downloads data or
69
+ quietly falls back to a different model or rule.
70
+
71
+ ## Run the first analysis
72
+
73
+ 1. Analyze a document with a profile:
74
+
75
+ ```text
76
+ lingity analyze review.md --profile architecture-review
77
+ ```
78
+
79
+ The command writes a deterministic, schema-valid JSON artifact to standard
80
+ output. Redirect it when you want to verify or retain it:
81
+
82
+ ```text
83
+ lingity analyze review.md --profile architecture-review > analysis.json
84
+ ```
85
+
86
+ 2. Verify the artifact:
87
+
88
+ ```text
89
+ lingity verify analysis.json
90
+ ```
91
+
92
+ `verify` validates the schema and hashes, resolves the recorded profile, and
93
+ replays the analysis. An altered artifact, unavailable profile, different
94
+ parser pipeline, or non-reproducible result fails explicitly.
95
+
96
+ The artifact contains located findings, the attributed Human Readability Index,
97
+ protected-element manifests, source and profile hashes, ingest coverage, and
98
+ the pinned linguistic model identity. The same source, profile, analyzer, model,
99
+ and parser produce the same result.
100
+
101
+ ## Choose a profile
102
+
103
+ Five profiles ship:
104
+
105
+ | Profile | Use it for |
106
+ | --- | --- |
107
+ | `architecture-review` | Recommendations, ADR summaries, findings, risks, and review decisions. |
108
+ | `product-strategy` | Need statements, value propositions, positioning, and go-to-market plans. |
109
+ | `web-copy` | Landing pages, product descriptions, and job listings. |
110
+ | `resume-review` | Resume and CV accomplishment bullets. |
111
+ | `local-service` | Location-specific pages for trades and local services. |
112
+
113
+ Profiles are versioned analysis policy, not interchangeable labels. They set
114
+ different weights, thresholds, vocabulary, and genre rules. For example,
115
+ `product-strategy` requires a responsible actor, `resume-review` recognizes the
116
+ implied first-person subject of accomplishment bullets, and `local-service`
117
+ distinguishes trade terms from generic promotional language.
118
+
119
+ Run the same document under another profile only when that profile matches the
120
+ document's purpose:
121
+
122
+ ```text
123
+ lingity analyze strategy.md --profile product-strategy
124
+ ```
125
+
126
+ See [DESIGN.md](DESIGN.md) for profile rationale, threshold behavior, scoring,
127
+ parser boundaries, and rule details.
128
+
129
+ ## Rewrite a document
130
+
131
+ Lingity separates proposal generation from acceptance. A model may propose a
132
+ rewrite; only deterministic checks decide whether to accept it.
133
+
134
+ ### Create a critique
135
+
136
+ ```text
137
+ lingity critique review.md --output brief.json
138
+ lingity critique review.md --profile architecture-review --style technical-writer --output styled-brief.json
139
+ ```
140
+
141
+ `critique` ranks defects and records the elements a rewrite may not change.
142
+ Add `--style` to include a versioned style contract and deterministic provider
143
+ instructions. Omitting `--style` preserves the unstyled brief behavior.
144
+
145
+ ### Judge one candidate
146
+
147
+ ```text
148
+ lingity judge review.md --candidate rewrite.md --profile architecture-review
149
+ ```
150
+
151
+ A candidate is accepted only when protected meaning is equivalent, the Human
152
+ Readability Index strictly improves, no new high-severity finding appears, the
153
+ profile's readable-word growth budget is met, and no semantic-drift challenge
154
+ raises material doubt. A higher score never compensates for changed meaning.
155
+
156
+ Every rejection reports its reasons and a `protected_delta` so the next edit can
157
+ restore named elements instead of guessing:
158
+
159
+ ```text
160
+ $ lingity judge source.txt --candidate shorter.txt
161
+ accepted False 70.46 -> 89.50
162
+ reason: protected meaning is changed: 9 protected element(s) dropped
163
+ MISSING quantity:count:2
164
+ MISSING governance:term:ratify
165
+ MISSING order:sequence:earlier=require closure evidence govern recommendation;later=target architecture return human decision
166
+ ...
167
+ ```
168
+
169
+ When no candidate qualifies, Lingity returns the source unchanged with the
170
+ rejection reasons. It never accepts a regression, tie, unresolved meaning
171
+ comparison, or candidate that drops a protected claim.
172
+
173
+ ### Run the bounded improvement loop
174
+
175
+ ```text
176
+ lingity improve review.md --provider subagent --candidate rewrite.md
177
+ lingity improve review.md --provider anthropic --model <model> --style technical-writer
178
+ ```
179
+
180
+ `improve` feeds each rejection into the next critique until a candidate is
181
+ accepted or the bounded run ends. `--style` passes the contract to an API
182
+ provider. The `subagent` provider serves candidates written before the loop
183
+ runs, so it rejects `--style`; give the host agent `lingity critique --style`
184
+ instead. The copy-ready editing prompt for writing one candidate is in
185
+ [`docs/conservative-editing-prompt.md`](docs/conservative-editing-prompt.md).
186
+
187
+ To drive the whole loop from an agent harness such as Claude Code, follow
188
+ [`docs/agent-harness.md`](docs/agent-harness.md). It covers the critique, judge,
189
+ and repair steps, how to read a verdict, a copy-ready system prompt, and a
190
+ Claude Code skill in [`skills/lingity`](skills/lingity/SKILL.md).
191
+
192
+ Proposal providers are transports, never authorities:
193
+
194
+ - `subagent` is the default. It makes no network call and needs no API key. The
195
+ host agent writes a candidate and Lingity judges it.
196
+ - `openai` and `anthropic` make direct API calls. Credentials come only from
197
+ `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`; they are not accepted as arguments,
198
+ logged, or written to artifacts. These providers require `--model`; Lingity
199
+ has no default model.
200
+
201
+ A drift challenger can block acceptance but cannot clear a deterministic
202
+ failure. An unparseable challenge response is an error.
203
+
204
+ ### Exit codes
205
+
206
+ `critique`, `judge`, and `improve` use:
207
+
208
+ - `0`: success
209
+ - `1`: reasoned rejection
210
+ - `2`: error
211
+
212
+ This contract lets a host process branch on the exit code without parsing
213
+ human-readable output.
214
+
215
+ ## Choose a style contract
216
+
217
+ Four versioned JSON style contracts ship:
218
+
219
+ - `architecture-review`
220
+ - `conservative-web-editor`
221
+ - `local-service-guide`
222
+ - `technical-writer`
223
+
224
+ List and inspect them with:
225
+
226
+ ```text
227
+ lingity styles
228
+ lingity style technical-writer --format json
229
+ lingity style technical-writer --format prompt
230
+ ```
231
+
232
+ Style contracts guide proposal generation. They do not score rhetorical fit,
233
+ and `judge` remains style-independent. Profiles validate deterministic
234
+ readability and protected meaning; a profile score is not a style-contract fit
235
+ score. Optional style guidance never changes the acceptance gates.
236
+
237
+ See [`docs/style-contract-experiment.md`](docs/style-contract-experiment.md)
238
+ for the style-contract evaluation and examples.
239
+
240
+ ## Analysis and safety contract
241
+
242
+ Lingity's current workflow is:
243
+
244
+ ```text
245
+ source text
246
+ -> deterministic analysis
247
+ -> schema-valid analysis artifact
248
+ -> deterministic verification replay
249
+ ```
250
+
251
+ Rewrite validation adds a bounded proposal between analysis and deterministic
252
+ acceptance:
253
+
254
+ ```text
255
+ source text
256
+ -> deterministic analysis
257
+ -> bounded proposal
258
+ -> invariant validation
259
+ -> deterministic rescoring
260
+ -> semantic-drift challenge
261
+ -> accept, iterate, reject, or require human review
262
+ ```
263
+
264
+ The core guarantees are:
265
+
266
+ 1. The source text is immutable.
267
+ 2. Every score is reproducible from a versioned profile and analyzer.
268
+ 3. The runtime does not emit success-shaped fallback results.
269
+ 4. Protected facts, identifiers, quantities, modality, negation, citations,
270
+ ownership, and governance status must survive unchanged.
271
+ 5. A candidate must improve the configured thresholds without a hard-gate
272
+ violation.
273
+ 6. Semantic uncertainty is `needs_human`, not success.
274
+
275
+ The analyzer covers sentence load, morphology, noun stacking, agency, voice,
276
+ lexical clarity, structure, and redundancy. It reads Markdown prose blocks but
277
+ not fenced or indented code, tables, or thematic breaks. Inline-code identifiers
278
+ are protected. Findings include a rule ID, severity, source location, observed
279
+ value, threshold, and remediation.
280
+
281
+ The parser, linguistic model, profile, analyzer, and ingest coverage are part of
282
+ the hashed analysis contract. `verify` refuses incompatible inputs instead of
283
+ silently reanalyzing them. The exact dimensions, score formula, block-scoping
284
+ rules, CommonMark behavior, protected-meaning model, held-out corpus limits, and
285
+ provider protocols are documented in [DESIGN.md](DESIGN.md).
286
+
287
+ Additional background is available in the
288
+ [AgenticTuner comparison](docs/agentictuner-comparison.md) and the
289
+ [implementation plan](docs/implementation-plan.md).
290
+
291
+ ## Development
292
+
293
+ ```text
294
+ python -m pip install -e '.[dev]'
295
+ python -m pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
296
+ python -m nltk.downloader wordnet omw-1.4
297
+ python -m pytest
298
+ python -m mypy
299
+ python -m compileall -q lingity tests
300
+ ```
301
+
302
+ These are the commands CI runs, in this order, on Python 3.11 and 3.12 for every
303
+ push to `main` and every pull request; see `.github/workflows/ci.yml`. CI skips
304
+ the corpus download when its `~/nltk_data` cache is restored. Locally, rerunning
305
+ the download after the corpora are present is a no-op.
306
+
307
+ Use `python -m` so each tool runs under the interpreter where Lingity is
308
+ installed. Keep the extras spec quoted because `zsh` treats brackets as a glob.
309
+ `pytest` and `mypy` read their settings from `pyproject.toml`.
310
+
311
+ ## Prior art
312
+
313
+ The rule families follow:
314
+
315
+ - Femmer, Méndez Fernández, Wagner, Eder, *Rapid Quality Assurance with
316
+ Requirements Smells* (Journal of Systems and Software, 2017).
317
+ - INCOSE-TP-010-009, *Guide to Writing Requirements* (2019).
318
+ - U.S. Federal Plain Language Guidelines (PLAIN).
319
+
320
+ These sources inform the smell-detection, imperative, ambiguity,
321
+ quantification, actor-first, active-voice, and sentence-length rules. Lingity
322
+ adds attributed findings and governed-meaning rewrite gates.
323
+
324
+ ## License
325
+
326
+ Apache License 2.0. The full text is in [LICENSE](LICENSE), and [NOTICE](NOTICE)
327
+ carries the copyright statement and required section 4(d) attribution.
328
+
329
+ Lingity does not redistribute or declare its two data artifacts as
330
+ dependencies. Users download the `en_core_web_sm` spaCy model under the MIT
331
+ License and the NLTK WordNet corpus under the WordNet 3.0 License. `NOTICE`
332
+ records both.
333
+
334
+ ## Release
335
+
336
+ Publishing requires an authenticated `twine` configuration. Credentials are
337
+ resolved from `~/.pypirc`, the system keyring, or `TWINE_*` environment
338
+ variables; no credential is passed as an argument or written by the script.
339
+
340
+ Run:
341
+
342
+ ```text
343
+ python -m pip install -e ".[release]"
344
+ python scripts/release.py --repository testpypi --dry-run
345
+ python scripts/release.py --repository testpypi
346
+ python scripts/release.py --repository pypi
347
+ ```
348
+
349
+ `--repository` is required; there is no default. Use `--dry-run` to run every
350
+ check and build the artifacts without uploading.
351
+
352
+ The release script stops on an unclean working tree, failing guard test,
353
+ already-published version, direct URL dependency, missing license metadata,
354
+ unknown classifier, or unreachable index. Uploads cannot be undone and a
355
+ version cannot be reused, so an unavailable check is an error rather than an
356
+ assumed success.
@@ -0,0 +1,320 @@
1
+ # Lingity
2
+
3
+ Lingity provides deterministic, governed analysis and rewrite validation for
4
+ English Markdown or plain text written by people or language models. Use it
5
+ when readability may improve but facts, identifiers, quantities, modality,
6
+ negation, citations, ownership, and governance status must not change.
7
+
8
+ The local `analyze` and `verify` commands make no network or LLM calls.
9
+ Rewriting commands can use a host agent or an explicitly configured provider,
10
+ but deterministic code remains the authority that accepts or rejects a
11
+ candidate.
12
+
13
+ ## Prerequisites and installation
14
+
15
+ Lingity is not yet published to a package index. Install it from a clone with
16
+ Python 3.11 or later:
17
+
18
+ ```text
19
+ python -m pip install .
20
+ python -m pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
21
+ python -m nltk.downloader wordnet omw-1.4
22
+ ```
23
+
24
+ All three commands are required. The spaCy model must be exactly
25
+ `en_core_web_sm` 3.8.0; do not substitute
26
+ `python -m spacy download en_core_web_sm`, which can resolve a different
27
+ version. WordNet and `omw-1.4` are corpus data and must be downloaded
28
+ separately.
29
+
30
+ Lingity fails closed when these prerequisites are wrong or absent.
31
+ `LinguisticModelError` names the model installation command, and
32
+ `WordNetDataError` names the corpus command. Analysis never downloads data or
33
+ quietly falls back to a different model or rule.
34
+
35
+ ## Run the first analysis
36
+
37
+ 1. Analyze a document with a profile:
38
+
39
+ ```text
40
+ lingity analyze review.md --profile architecture-review
41
+ ```
42
+
43
+ The command writes a deterministic, schema-valid JSON artifact to standard
44
+ output. Redirect it when you want to verify or retain it:
45
+
46
+ ```text
47
+ lingity analyze review.md --profile architecture-review > analysis.json
48
+ ```
49
+
50
+ 2. Verify the artifact:
51
+
52
+ ```text
53
+ lingity verify analysis.json
54
+ ```
55
+
56
+ `verify` validates the schema and hashes, resolves the recorded profile, and
57
+ replays the analysis. An altered artifact, unavailable profile, different
58
+ parser pipeline, or non-reproducible result fails explicitly.
59
+
60
+ The artifact contains located findings, the attributed Human Readability Index,
61
+ protected-element manifests, source and profile hashes, ingest coverage, and
62
+ the pinned linguistic model identity. The same source, profile, analyzer, model,
63
+ and parser produce the same result.
64
+
65
+ ## Choose a profile
66
+
67
+ Five profiles ship:
68
+
69
+ | Profile | Use it for |
70
+ | --- | --- |
71
+ | `architecture-review` | Recommendations, ADR summaries, findings, risks, and review decisions. |
72
+ | `product-strategy` | Need statements, value propositions, positioning, and go-to-market plans. |
73
+ | `web-copy` | Landing pages, product descriptions, and job listings. |
74
+ | `resume-review` | Resume and CV accomplishment bullets. |
75
+ | `local-service` | Location-specific pages for trades and local services. |
76
+
77
+ Profiles are versioned analysis policy, not interchangeable labels. They set
78
+ different weights, thresholds, vocabulary, and genre rules. For example,
79
+ `product-strategy` requires a responsible actor, `resume-review` recognizes the
80
+ implied first-person subject of accomplishment bullets, and `local-service`
81
+ distinguishes trade terms from generic promotional language.
82
+
83
+ Run the same document under another profile only when that profile matches the
84
+ document's purpose:
85
+
86
+ ```text
87
+ lingity analyze strategy.md --profile product-strategy
88
+ ```
89
+
90
+ See [DESIGN.md](DESIGN.md) for profile rationale, threshold behavior, scoring,
91
+ parser boundaries, and rule details.
92
+
93
+ ## Rewrite a document
94
+
95
+ Lingity separates proposal generation from acceptance. A model may propose a
96
+ rewrite; only deterministic checks decide whether to accept it.
97
+
98
+ ### Create a critique
99
+
100
+ ```text
101
+ lingity critique review.md --output brief.json
102
+ lingity critique review.md --profile architecture-review --style technical-writer --output styled-brief.json
103
+ ```
104
+
105
+ `critique` ranks defects and records the elements a rewrite may not change.
106
+ Add `--style` to include a versioned style contract and deterministic provider
107
+ instructions. Omitting `--style` preserves the unstyled brief behavior.
108
+
109
+ ### Judge one candidate
110
+
111
+ ```text
112
+ lingity judge review.md --candidate rewrite.md --profile architecture-review
113
+ ```
114
+
115
+ A candidate is accepted only when protected meaning is equivalent, the Human
116
+ Readability Index strictly improves, no new high-severity finding appears, the
117
+ profile's readable-word growth budget is met, and no semantic-drift challenge
118
+ raises material doubt. A higher score never compensates for changed meaning.
119
+
120
+ Every rejection reports its reasons and a `protected_delta` so the next edit can
121
+ restore named elements instead of guessing:
122
+
123
+ ```text
124
+ $ lingity judge source.txt --candidate shorter.txt
125
+ accepted False 70.46 -> 89.50
126
+ reason: protected meaning is changed: 9 protected element(s) dropped
127
+ MISSING quantity:count:2
128
+ MISSING governance:term:ratify
129
+ MISSING order:sequence:earlier=require closure evidence govern recommendation;later=target architecture return human decision
130
+ ...
131
+ ```
132
+
133
+ When no candidate qualifies, Lingity returns the source unchanged with the
134
+ rejection reasons. It never accepts a regression, tie, unresolved meaning
135
+ comparison, or candidate that drops a protected claim.
136
+
137
+ ### Run the bounded improvement loop
138
+
139
+ ```text
140
+ lingity improve review.md --provider subagent --candidate rewrite.md
141
+ lingity improve review.md --provider anthropic --model <model> --style technical-writer
142
+ ```
143
+
144
+ `improve` feeds each rejection into the next critique until a candidate is
145
+ accepted or the bounded run ends. `--style` passes the contract to an API
146
+ provider. The `subagent` provider serves candidates written before the loop
147
+ runs, so it rejects `--style`; give the host agent `lingity critique --style`
148
+ instead. The copy-ready editing prompt for writing one candidate is in
149
+ [`docs/conservative-editing-prompt.md`](docs/conservative-editing-prompt.md).
150
+
151
+ To drive the whole loop from an agent harness such as Claude Code, follow
152
+ [`docs/agent-harness.md`](docs/agent-harness.md). It covers the critique, judge,
153
+ and repair steps, how to read a verdict, a copy-ready system prompt, and a
154
+ Claude Code skill in [`skills/lingity`](skills/lingity/SKILL.md).
155
+
156
+ Proposal providers are transports, never authorities:
157
+
158
+ - `subagent` is the default. It makes no network call and needs no API key. The
159
+ host agent writes a candidate and Lingity judges it.
160
+ - `openai` and `anthropic` make direct API calls. Credentials come only from
161
+ `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`; they are not accepted as arguments,
162
+ logged, or written to artifacts. These providers require `--model`; Lingity
163
+ has no default model.
164
+
165
+ A drift challenger can block acceptance but cannot clear a deterministic
166
+ failure. An unparseable challenge response is an error.
167
+
168
+ ### Exit codes
169
+
170
+ `critique`, `judge`, and `improve` use:
171
+
172
+ - `0`: success
173
+ - `1`: reasoned rejection
174
+ - `2`: error
175
+
176
+ This contract lets a host process branch on the exit code without parsing
177
+ human-readable output.
178
+
179
+ ## Choose a style contract
180
+
181
+ Four versioned JSON style contracts ship:
182
+
183
+ - `architecture-review`
184
+ - `conservative-web-editor`
185
+ - `local-service-guide`
186
+ - `technical-writer`
187
+
188
+ List and inspect them with:
189
+
190
+ ```text
191
+ lingity styles
192
+ lingity style technical-writer --format json
193
+ lingity style technical-writer --format prompt
194
+ ```
195
+
196
+ Style contracts guide proposal generation. They do not score rhetorical fit,
197
+ and `judge` remains style-independent. Profiles validate deterministic
198
+ readability and protected meaning; a profile score is not a style-contract fit
199
+ score. Optional style guidance never changes the acceptance gates.
200
+
201
+ See [`docs/style-contract-experiment.md`](docs/style-contract-experiment.md)
202
+ for the style-contract evaluation and examples.
203
+
204
+ ## Analysis and safety contract
205
+
206
+ Lingity's current workflow is:
207
+
208
+ ```text
209
+ source text
210
+ -> deterministic analysis
211
+ -> schema-valid analysis artifact
212
+ -> deterministic verification replay
213
+ ```
214
+
215
+ Rewrite validation adds a bounded proposal between analysis and deterministic
216
+ acceptance:
217
+
218
+ ```text
219
+ source text
220
+ -> deterministic analysis
221
+ -> bounded proposal
222
+ -> invariant validation
223
+ -> deterministic rescoring
224
+ -> semantic-drift challenge
225
+ -> accept, iterate, reject, or require human review
226
+ ```
227
+
228
+ The core guarantees are:
229
+
230
+ 1. The source text is immutable.
231
+ 2. Every score is reproducible from a versioned profile and analyzer.
232
+ 3. The runtime does not emit success-shaped fallback results.
233
+ 4. Protected facts, identifiers, quantities, modality, negation, citations,
234
+ ownership, and governance status must survive unchanged.
235
+ 5. A candidate must improve the configured thresholds without a hard-gate
236
+ violation.
237
+ 6. Semantic uncertainty is `needs_human`, not success.
238
+
239
+ The analyzer covers sentence load, morphology, noun stacking, agency, voice,
240
+ lexical clarity, structure, and redundancy. It reads Markdown prose blocks but
241
+ not fenced or indented code, tables, or thematic breaks. Inline-code identifiers
242
+ are protected. Findings include a rule ID, severity, source location, observed
243
+ value, threshold, and remediation.
244
+
245
+ The parser, linguistic model, profile, analyzer, and ingest coverage are part of
246
+ the hashed analysis contract. `verify` refuses incompatible inputs instead of
247
+ silently reanalyzing them. The exact dimensions, score formula, block-scoping
248
+ rules, CommonMark behavior, protected-meaning model, held-out corpus limits, and
249
+ provider protocols are documented in [DESIGN.md](DESIGN.md).
250
+
251
+ Additional background is available in the
252
+ [AgenticTuner comparison](docs/agentictuner-comparison.md) and the
253
+ [implementation plan](docs/implementation-plan.md).
254
+
255
+ ## Development
256
+
257
+ ```text
258
+ python -m pip install -e '.[dev]'
259
+ python -m pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
260
+ python -m nltk.downloader wordnet omw-1.4
261
+ python -m pytest
262
+ python -m mypy
263
+ python -m compileall -q lingity tests
264
+ ```
265
+
266
+ These are the commands CI runs, in this order, on Python 3.11 and 3.12 for every
267
+ push to `main` and every pull request; see `.github/workflows/ci.yml`. CI skips
268
+ the corpus download when its `~/nltk_data` cache is restored. Locally, rerunning
269
+ the download after the corpora are present is a no-op.
270
+
271
+ Use `python -m` so each tool runs under the interpreter where Lingity is
272
+ installed. Keep the extras spec quoted because `zsh` treats brackets as a glob.
273
+ `pytest` and `mypy` read their settings from `pyproject.toml`.
274
+
275
+ ## Prior art
276
+
277
+ The rule families follow:
278
+
279
+ - Femmer, Méndez Fernández, Wagner, Eder, *Rapid Quality Assurance with
280
+ Requirements Smells* (Journal of Systems and Software, 2017).
281
+ - INCOSE-TP-010-009, *Guide to Writing Requirements* (2019).
282
+ - U.S. Federal Plain Language Guidelines (PLAIN).
283
+
284
+ These sources inform the smell-detection, imperative, ambiguity,
285
+ quantification, actor-first, active-voice, and sentence-length rules. Lingity
286
+ adds attributed findings and governed-meaning rewrite gates.
287
+
288
+ ## License
289
+
290
+ Apache License 2.0. The full text is in [LICENSE](LICENSE), and [NOTICE](NOTICE)
291
+ carries the copyright statement and required section 4(d) attribution.
292
+
293
+ Lingity does not redistribute or declare its two data artifacts as
294
+ dependencies. Users download the `en_core_web_sm` spaCy model under the MIT
295
+ License and the NLTK WordNet corpus under the WordNet 3.0 License. `NOTICE`
296
+ records both.
297
+
298
+ ## Release
299
+
300
+ Publishing requires an authenticated `twine` configuration. Credentials are
301
+ resolved from `~/.pypirc`, the system keyring, or `TWINE_*` environment
302
+ variables; no credential is passed as an argument or written by the script.
303
+
304
+ Run:
305
+
306
+ ```text
307
+ python -m pip install -e ".[release]"
308
+ python scripts/release.py --repository testpypi --dry-run
309
+ python scripts/release.py --repository testpypi
310
+ python scripts/release.py --repository pypi
311
+ ```
312
+
313
+ `--repository` is required; there is no default. Use `--dry-run` to run every
314
+ check and build the artifacts without uploading.
315
+
316
+ The release script stops on an unclean working tree, failing guard test,
317
+ already-published version, direct URL dependency, missing license metadata,
318
+ unknown classifier, or unreachable index. Uploads cannot be undone and a
319
+ version cannot be reused, so an unavailable check is an error rather than an
320
+ assumed success.
@@ -5,4 +5,4 @@ from lingity.invariants import compare_protected
5
5
  from lingity.profiles import Profile, load_profile
6
6
 
7
7
  __all__ = ["Profile", "analyze_text", "compare_protected", "load_profile"]
8
- __version__ = "0.2.0"
8
+ __version__ = "0.2.2"