negaresh 0.2.0__py3-none-any.whl

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.
negaresh/__init__.py ADDED
@@ -0,0 +1,4 @@
1
+ """negaresh: original Persian writing guidance and local checks."""
2
+
3
+ __version__ = "0.2.0"
4
+ SCHEMA_VERSION = "1.0"
negaresh/api.py ADDED
@@ -0,0 +1,260 @@
1
+ """Typed tool inputs and the five tool functions. No MCP imports here, so the
2
+ CLI and tests call exactly what the server calls."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import uuid
7
+ from typing import Any, Literal
8
+
9
+ from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
10
+
11
+ from . import SCHEMA_VERSION, __version__, mechanics, patches
12
+ from .corpus import load
13
+ from .search import search
14
+ from .textutil import revision_of
15
+
16
+ MAX_TEXT = 12000
17
+ ProfileId = Literal[
18
+ "academic", "professional", "journalistic", "general_nonfiction", "literary",
19
+ "conversational", "technical_instructional", "persuasive_marketing_social",
20
+ ]
21
+ Category = Literal["orthography", "punctuation", "grammar", "usage", "style", "terminology", "discourse", "integrity"]
22
+
23
+
24
+ class _Strict(BaseModel):
25
+ model_config = ConfigDict(extra="forbid", strict=True)
26
+
27
+
28
+ class Context(_Strict):
29
+ profile_id: ProfileId | None = Field(default=None, description="Kind of text. Sets which mechanical fixes are offered as automatic patches and which checks are off.")
30
+ formality: Literal["formal", "neutral", "informal", "unspecified"] | None = Field(default=None, description="Informational only; does not change the checks.")
31
+ domain: str | None = Field(default=None, max_length=128, description="Informational only; does not change the checks.")
32
+ edit_level: Literal["proofreading", "copyediting", "substantive"] | None = Field(default=None, description="Informational only; does not change the checks.")
33
+
34
+
35
+ class Locator(_Strict):
36
+ """Find the patch's `before` text in the original by the text just before (prefix) and after (suffix) it."""
37
+ prefix: str | None = Field(default=None, max_length=128, description="Exact text immediately before `before`.")
38
+ suffix: str | None = Field(default=None, max_length=128, description="Exact text immediately after `before`.")
39
+
40
+
41
+ class SpanLocator(_Strict):
42
+ text: str = Field(min_length=1, max_length=2000, description="Exact protected text as it appears in the original.")
43
+ prefix: str | None = Field(default=None, max_length=128, description="Exact text immediately before it, if `text` occurs more than once.")
44
+ suffix: str | None = Field(default=None, max_length=128, description="Exact text immediately after it.")
45
+
46
+
47
+ class Span(_Strict):
48
+ """Give either start+end (code points) or locator. Not both."""
49
+ start: int | None = Field(default=None, ge=0, description="Start offset in Unicode code points.")
50
+ end: int | None = Field(default=None, ge=0, description="End offset in Unicode code points, exclusive.")
51
+ locator: SpanLocator | None = None
52
+ kind: str = Field(default="user", max_length=40)
53
+
54
+ @model_validator(mode="after")
55
+ def _one_form(self) -> "Span":
56
+ offsets = self.start is not None and self.end is not None
57
+ if offsets == (self.locator is not None) or (offsets and self.end < self.start): # type: ignore[operator]
58
+ raise ValueError("give exactly one of (start, end) or locator")
59
+ return self
60
+
61
+
62
+ class Patch(_Strict):
63
+ """Give either start+end (code points in the original) or locator. Not both."""
64
+ patch_id: str = Field(min_length=1, max_length=40, description="Your own unique ID for this patch.")
65
+ before: str = Field(max_length=4000, description="Exact original text to replace; empty for an insertion (then give offsets with start == end).")
66
+ after: str = Field(max_length=4000, description="Replacement text; empty for a deletion.")
67
+ start: int | None = Field(default=None, ge=0, description="Start offset of `before` in the original, in Unicode code points.")
68
+ end: int | None = Field(default=None, ge=0, description="End offset, exclusive. start + len(before) in code points.")
69
+ locator: Locator | None = None
70
+ rule_ids: list[str] = Field(default_factory=list, max_length=16, description="Rule IDs that justify the change, e.g. ORT-003.")
71
+ action_class: Literal["mechanical", "contextual", "style", "structure"] = "contextual"
72
+ explanation: str = Field(default="", max_length=600)
73
+
74
+ @model_validator(mode="after")
75
+ def _one_form(self) -> "Patch":
76
+ offsets = self.start is not None and self.end is not None
77
+ if offsets == (self.locator is not None):
78
+ raise ValueError("give exactly one of (start, end) or locator")
79
+ if self.locator is not None and not (self.locator.prefix or self.locator.suffix):
80
+ raise ValueError("a locator needs a prefix or a suffix")
81
+ return self
82
+
83
+
84
+ class SearchRulesInput(_Strict):
85
+ query: str = Field(min_length=1, max_length=512, description="Topic, word or phrase, in Persian or English.")
86
+ context_text: str | None = Field(default=None, max_length=4096, description="The sentence in question; searched only if the query finds nothing.")
87
+ context: Context | None = None
88
+ category: Category | None = None
89
+ limit: int = Field(default=5, ge=1, le=8)
90
+
91
+
92
+ class GetRuleInput(_Strict):
93
+ rule_id: str = Field(min_length=1, max_length=80, pattern=r"^[A-Za-z0-9._-]+$")
94
+
95
+
96
+ class GetProfileInput(_Strict):
97
+ profile_id: ProfileId | None = None
98
+
99
+
100
+ class CheckMechanicsInput(_Strict):
101
+ text: str = Field(min_length=1, max_length=MAX_TEXT)
102
+ context: Context | None = None
103
+ protected_spans: list[Span] = Field(default_factory=list, max_length=256)
104
+
105
+
106
+ class ValidatePatchesInput(_Strict):
107
+ text_revision: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
108
+ original_text: str | None = Field(default=None, max_length=MAX_TEXT)
109
+ patches: list[Patch] = Field(min_length=1, max_length=256)
110
+ protected_spans: list[Span] = Field(default_factory=list, max_length=256)
111
+ include_revised_text: bool = True
112
+
113
+
114
+ def envelope(status: str, data: Any = None, *, warnings: list[dict[str, Any]] | None = None,
115
+ truncated: bool = False, error: dict[str, Any] | None = None) -> dict[str, Any]:
116
+ return {
117
+ "schema_version": SCHEMA_VERSION, "package_version": __version__, "corpus_version": load().version,
118
+ "request_id": uuid.uuid4().hex[:12], "status": status, "warnings": warnings or [],
119
+ "truncated": truncated, "data": data, "error": error,
120
+ }
121
+
122
+
123
+ def _error(status: str, code: str, message: str, action: str) -> dict[str, Any]:
124
+ return envelope(status, error={"code": code, "message": message, "retryable": False, "suggested_action": action})
125
+
126
+
127
+ def _summary(rule: dict[str, Any]) -> dict[str, Any]:
128
+ keys = ("id", "title_fa", "title_en", "category", "severity", "action", "profiles", "guidance",
129
+ "exceptions", "evidence_class", "status")
130
+ out = {k: rule[k] for k in keys if k in rule}
131
+ out["citations"] = [f'{e["source"]}: {e["loc"]}' for e in rule.get("evidence", [])]
132
+ out["conflicts"] = rule.get("conflicts", [])
133
+ return out
134
+
135
+
136
+ def search_rules(args: SearchRulesInput) -> dict[str, Any]:
137
+ profile = args.context.profile_id if args.context else None
138
+ hits = search(args.query, category=args.category, profile_id=profile, limit=args.limit)
139
+ if not hits and args.context_text:
140
+ hits = search(args.context_text, category=args.category, profile_id=profile, limit=args.limit)
141
+ data = {
142
+ "backend": "in_memory_scan",
143
+ "results": [{**_summary(h["rule"]), "match_rationale": h["match_rationale"],
144
+ "applies_to_profile": h["applies_to_profile"]} for h in hits],
145
+ "returned_count": len(hits),
146
+ "coverage_note": "قاعده‌ای که بازیابی شده لزوماً بر متن شما صدق نمی‌کند؛ شرایط و استثناها را بخوانید. "
147
+ "نیافتن قاعده به معنای درست بودن عبارت نیست.",
148
+ }
149
+ return envelope("ok" if hits else "no_match", data)
150
+
151
+
152
+ def get_rule(args: GetRuleInput) -> dict[str, Any]:
153
+ corpus = load()
154
+ rule = corpus.rule(args.rule_id)
155
+ if rule is None:
156
+ tomb = corpus.tombstones.get(args.rule_id)
157
+ return envelope("ok", {"tombstone": tomb}) if tomb else envelope("no_match", {"rule": None})
158
+ sources = {e["source"]: corpus.sources.get(e["source"]) for e in rule.get("evidence", [])}
159
+ return envelope("ok", {"rule": rule, "sources": sources})
160
+
161
+
162
+ def get_profile(args: GetProfileInput) -> dict[str, Any]:
163
+ corpus = load()
164
+ if args.profile_id is None:
165
+ data = {
166
+ "variety": "Iranian standard Persian (fa-IR)",
167
+ "profiles": [{"id": p["id"], "title_fa": p["title_fa"]} for p in corpus.profiles.values()],
168
+ "formality_values": ["formal", "neutral", "informal", "unspecified"],
169
+ "edit_levels": ["proofreading", "copyediting", "substantive"],
170
+ "rule_count": len(corpus.rules),
171
+ "categories": sorted({r["category"] for r in corpus.rules.values()}),
172
+ "limits": {"max_text_code_points": MAX_TEXT, "search_limit": 8, "held_texts": patches.MAX_HELD_TEXTS},
173
+ "review_status": "All rules are drafts. No qualified human editor has reviewed them yet.",
174
+ "sources": list(corpus.sources.values()),
175
+ }
176
+ return envelope("ok", data)
177
+ return envelope("ok", {"profile": corpus.profiles[args.profile_id]})
178
+
179
+
180
+ def check_mechanics(args: CheckMechanicsInput) -> dict[str, Any]:
181
+ spans, issues = patches.resolve_spans(args.text, [s.model_dump() for s in args.protected_spans])
182
+ if issues:
183
+ return envelope("invalid_input", {"span_issues": issues},
184
+ error={"code": "protected_span_unresolved", "message": "A protected span could not be resolved.",
185
+ "retryable": True, "suggested_action": "Fix the span locator or give exact offsets."})
186
+ patches.hold(args.text)
187
+ profile = args.context.profile_id if args.context else None
188
+ data = mechanics.check(args.text, profile_id=profile, protected_spans=spans)
189
+ return envelope("ok", data, truncated=data["findings_omitted"] > 0)
190
+
191
+
192
+ def validate_patches(args: ValidatePatchesInput) -> dict[str, Any]:
193
+ original = args.original_text
194
+ if original is None:
195
+ original = patches.held(args.text_revision)
196
+ if original is None:
197
+ return _error("needs_context", "text_not_held", "The server no longer holds this text.",
198
+ "Call check_mechanics again with the exact text, then retry with the new text_revision.")
199
+ elif revision_of(original) != args.text_revision:
200
+ return _error("invalid_input", "revision_mismatch",
201
+ "original_text does not match text_revision; the text was altered when it was re-sent.",
202
+ "Send only text_revision (omit original_text) after check_mechanics, or re-run check_mechanics.")
203
+ spans, span_issues = patches.resolve_spans(original, [s.model_dump() for s in args.protected_spans])
204
+ if span_issues:
205
+ return envelope("invalid_input", {"span_issues": span_issues},
206
+ error={"code": "protected_span_unresolved", "message": "A protected span could not be resolved.",
207
+ "retryable": True, "suggested_action": "Fix the span locator or give exact offsets."})
208
+ spans = [*spans, *mechanics.detect_protected(original)]
209
+ result = patches.validate(original, [p.model_dump() for p in args.patches], spans, set(load().rules), MAX_TEXT * 2)
210
+ if not args.include_revised_text:
211
+ result["revised_text"] = None
212
+ return envelope("ok", result)
213
+
214
+
215
+ TOOLS: dict[str, tuple[type[BaseModel], Any, str]] = {
216
+ "search_rules": (SearchRulesInput, search_rules,
217
+ "Search the Persian writing rule set (Iranian standard Persian) by topic, word or phrase, in Persian or English. "
218
+ "Use before changing spelling, spacing, grammar or usage you are not sure about. Returns rules with conditions, "
219
+ "exceptions and sources. A returned rule may not apply; no match does not mean the text is correct."),
220
+ "get_rule": (GetRuleInput, get_rule,
221
+ "Get one full rule by ID (for example ORT-002), with all examples, exceptions and source details. "
222
+ "Use after search_rules or when a finding cites a rule ID."),
223
+ "get_profile": (GetProfileInput, get_profile,
224
+ "Without arguments: list writing profiles, corpus scope, limits and review status. With profile_id: "
225
+ "conventions and preservation policy for that kind of text. Call once at the start of an editing task."),
226
+ "check_mechanics": (CheckMechanicsInput, check_mechanics,
227
+ "Run deterministic checks (M01-M16) on Persian text: Arabic letters, presentation forms, digits, punctuation "
228
+ "spacing and Latin marks, spaces, half-space (ZWNJ) misuse, half-space after «می/نمی» before common verb stems "
229
+ "and before «ها/تر/ترین», quotes, kashida, invisible characters, mixed ezafe marks, brackets, preferred spellings "
230
+ "(Academy and Samiee lists), listed expressions to replace (M15) and sentence-shape patterns typical of translated or machine Persian (M16, flags pointing to a rebuild rule). Returns findings with exact code-point offsets, "
231
+ "candidate patches with rule IDs, auto_patch_set (low-risk, non-overlapping fixes, ready for validate_patches) "
232
+ "and text_revision. Flags need judgement. Check complete_scan. It does not judge grammar, meaning or style, "
233
+ "and never changes the text."),
234
+ "validate_patches": (ValidatePatchesInput, validate_patches,
235
+ "Validate proposed edits against the exact original and return the rebuilt text. Pass text_revision from "
236
+ "check_mechanics (do not re-send the original). Each patch gives 'before', 'after' and either offsets or a "
237
+ "locator with adjacent prefix/suffix. Rejects stale, ambiguous, overlapping edits and edits that touch or "
238
+ "change protected spans (URLs, e-mail, code, given spans). Present the "
239
+ "returned revised_text as it is; do not retype it. Meaning is not assessed."),
240
+ }
241
+
242
+
243
+ def call(name: str, arguments: dict[str, Any] | None) -> tuple[dict[str, Any], bool]:
244
+ """Returns (envelope, is_error)."""
245
+ if name not in TOOLS:
246
+ return _error("invalid_input", "unknown_tool", f"Unknown tool: {name}", "Use one of: " + ", ".join(TOOLS)), True
247
+ model, fn, _ = TOOLS[name]
248
+ try:
249
+ args = model.model_validate(arguments or {})
250
+ except ValidationError as exc:
251
+ details = [{"field": ".".join(str(p) for p in e["loc"]), "problem": e["type"]} for e in exc.errors()[:12]]
252
+ env = _error("invalid_input", "argument_validation", "Arguments rejected. Unknown or mistyped fields are not ignored.",
253
+ "Correct the listed fields and call again.")
254
+ env["data"] = {"fields": details}
255
+ return env, True
256
+ try:
257
+ env = fn(args)
258
+ except Exception: # content-free failure; no text or traceback reaches the model
259
+ return _error("resource_unavailable", "internal_error", "Internal error.", "Retry once; if it repeats, report the request_id."), True
260
+ return env, env["error"] is not None and env["status"] not in ("needs_context",)
negaresh/cli.py ADDED
@@ -0,0 +1,85 @@
1
+ """Command line: serve (MCP over stdio), doctor, corpus-info, and two helpers
2
+ for use without an MCP host (check, search)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import asyncio
8
+ import json
9
+ import sqlite3 # noqa: F401 (not used; kept out of runtime paths)
10
+ import sys
11
+ from importlib import metadata
12
+
13
+ from . import SCHEMA_VERSION, __version__
14
+
15
+
16
+ def _out(obj: object) -> None:
17
+ sys.stdout.reconfigure(encoding="utf-8") # type: ignore[union-attr]
18
+ json.dump(obj, sys.stdout, ensure_ascii=False, indent=2)
19
+ sys.stdout.write("\n")
20
+
21
+
22
+ def _doctor() -> dict[str, object]:
23
+ from .corpus import load
24
+ info: dict[str, object] = {"package": __version__, "schema": SCHEMA_VERSION, "python": sys.version.split()[0]}
25
+ try:
26
+ info["mcp_sdk"] = metadata.version("mcp")
27
+ except metadata.PackageNotFoundError:
28
+ info["mcp_sdk"] = None
29
+ try:
30
+ corpus = load()
31
+ info.update(corpus_version=corpus.version, rules=len(corpus.rules), profiles=len(corpus.profiles),
32
+ variant_spellings=len(corpus.lexicon.get("variant_spellings", {})), search_backend="in_memory_scan",
33
+ healthy=True)
34
+ except Exception as exc:
35
+ info.update(healthy=False, problem=type(exc).__name__)
36
+ return info
37
+
38
+
39
+ def main(argv: list[str] | None = None) -> int:
40
+ parser = argparse.ArgumentParser(prog="negaresh")
41
+ parser.add_argument("--version", action="version", version=__version__)
42
+ sub = parser.add_subparsers(dest="cmd", required=True)
43
+ p_serve = sub.add_parser("serve", help="run the MCP server (stdio by default; --http for Streamable HTTP)")
44
+ p_serve.add_argument("--http", action="store_true", help="serve Streamable HTTP at /mcp instead of stdio")
45
+ p_serve.add_argument("--host", default="127.0.0.1")
46
+ p_serve.add_argument("--port", type=int, default=8000)
47
+ p_serve.add_argument("--allowed-host", action="append", default=[],
48
+ help="extra Host header to accept, such as a tunnel's domain (repeatable)")
49
+ p_serve.add_argument("--allow-any-host", action="store_true",
50
+ help="turn off Host header checks (only behind a proxy you control)")
51
+ sub.add_parser("doctor", help="print health and version metadata as JSON")
52
+ sub.add_parser("corpus-info", help="print corpus metadata as JSON")
53
+ p_check = sub.add_parser("check", help="run mechanical checks on a UTF-8 text file")
54
+ p_check.add_argument("file")
55
+ p_check.add_argument("--profile")
56
+ p_search = sub.add_parser("search", help="search the rules")
57
+ p_search.add_argument("query")
58
+ args = parser.parse_args(argv)
59
+
60
+ if args.cmd == "serve":
61
+ if args.http:
62
+ from .server import serve_http
63
+ asyncio.run(serve_http(args.host, args.port, args.allowed_host, args.allow_any_host))
64
+ else:
65
+ from .server import serve
66
+ asyncio.run(serve())
67
+ return 0
68
+ if args.cmd == "doctor":
69
+ info = _doctor()
70
+ _out(info)
71
+ return 0 if info.get("healthy") else 1
72
+ from . import api
73
+ if args.cmd == "corpus-info":
74
+ _out(api.call("get_profile", {})[0]["data"])
75
+ elif args.cmd == "check":
76
+ text = open(args.file, encoding="utf-8").read()
77
+ ctx = {"context": {"profile_id": args.profile}} if args.profile else {}
78
+ _out(api.call("check_mechanics", {"text": text, **ctx})[0])
79
+ elif args.cmd == "search":
80
+ _out(api.call("search_rules", {"query": args.query})[0])
81
+ return 0
82
+
83
+
84
+ if __name__ == "__main__":
85
+ raise SystemExit(main())
negaresh/corpus.py ADDED
@@ -0,0 +1,36 @@
1
+ """Read-only access to the packaged corpus bundle."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from dataclasses import dataclass
7
+ from functools import lru_cache
8
+ from importlib import resources
9
+ from typing import Any
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class Corpus:
14
+ version: str
15
+ rules: dict[str, dict[str, Any]]
16
+ profiles: dict[str, dict[str, Any]]
17
+ sources: dict[str, dict[str, Any]]
18
+ lexicon: dict[str, Any]
19
+ tombstones: dict[str, dict[str, Any]]
20
+
21
+ def rule(self, rule_id: str) -> dict[str, Any] | None:
22
+ return self.rules.get(rule_id)
23
+
24
+
25
+ @lru_cache(maxsize=1)
26
+ def load() -> Corpus:
27
+ raw = resources.files("negaresh").joinpath("data/corpus.json").read_text(encoding="utf-8")
28
+ data = json.loads(raw)
29
+ return Corpus(
30
+ version=data["corpus_version"],
31
+ rules={r["id"]: r for r in data["rules"]},
32
+ profiles={p["id"]: p for p in data["profiles"]},
33
+ sources={s["id"]: s for s in data["sources"]},
34
+ lexicon=data["lexicon"],
35
+ tombstones={t["id"]: t for t in data.get("tombstones", [])},
36
+ )