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.
- lingity-0.2.2/PKG-INFO +356 -0
- lingity-0.2.2/README.md +320 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/__init__.py +1 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/analyzer.py +148 -6
- {lingity-0.2.0 → lingity-0.2.2}/lingity/cli.py +112 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/critique.py +58 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/improve.py +217 -6
- {lingity-0.2.0 → lingity-0.2.2}/lingity/invariants.py +53 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/markdown.py +14 -3
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/architecture-review.v1.json +11 -2
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/local-service.v1.json +11 -2
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/product-strategy.v1.json +10 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/resume-review.v1.json +10 -1
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles/web-copy.v1.json +15 -2
- {lingity-0.2.0 → lingity-0.2.2}/lingity/profiles.py +4 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/anthropic_provider.py +24 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/base.py +56 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/openai_provider.py +17 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/analysis.schema.json +19 -1
- lingity-0.2.2/lingity/schemas/v1/critique.schema.json +329 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/profile.schema.json +15 -1
- lingity-0.2.2/lingity/schemas/v1/style-contract.schema.json +174 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/verdict.schema.json +24 -1
- lingity-0.2.2/lingity/styles/architecture-review.v1.json +91 -0
- lingity-0.2.2/lingity/styles/conservative-web-editor.v1.json +87 -0
- lingity-0.2.2/lingity/styles/local-service-guide.v1.json +87 -0
- lingity-0.2.2/lingity/styles/technical-writer.v1.json +122 -0
- lingity-0.2.2/lingity/styles.py +183 -0
- lingity-0.2.2/lingity.egg-info/PKG-INFO +356 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/SOURCES.txt +7 -0
- {lingity-0.2.0 → lingity-0.2.2}/pyproject.toml +2 -2
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_analysis.py +1 -0
- lingity-0.2.2/tests/test_cli.py +320 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_documentation.py +54 -0
- lingity-0.2.2/tests/test_improve.py +765 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_invariants.py +93 -2
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_local_service_profile.py +60 -1
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_product_strategy_profile.py +1 -1
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_provider_anthropic.py +57 -1
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_provider_openai.py +47 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_release.py +9 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_resume_review_profile.py +12 -4
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_schemas.py +9 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_scoring.py +2 -1
- lingity-0.2.2/tests/test_styles.py +142 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_web_copy_profile.py +106 -0
- lingity-0.2.0/PKG-INFO +0 -443
- lingity-0.2.0/README.md +0 -407
- lingity-0.2.0/lingity/schemas/v1/critique.schema.json +0 -153
- lingity-0.2.0/lingity.egg-info/PKG-INFO +0 -443
- lingity-0.2.0/tests/test_cli.py +0 -111
- lingity-0.2.0/tests/test_improve.py +0 -367
- {lingity-0.2.0 → lingity-0.2.2}/LICENSE +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/NOTICE +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/__main__.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/lexicon.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/models.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/morphology.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/nlp.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/__init__.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/providers/agent.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/py.typed +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/provider-challenge.schema.json +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/provider-proposal.schema.json +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/schemas/v1/verification.schema.json +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/scoring.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity/text.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/dependency_links.txt +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/entry_points.txt +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/requires.txt +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/lingity.egg-info/top_level.txt +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/setup.cfg +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_determinism.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_markdown.py +0 -0
- {lingity-0.2.0 → lingity-0.2.2}/tests/test_meaning_equivalence.py +0 -0
- {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.
|
lingity-0.2.2/README.md
ADDED
|
@@ -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.
|