arche-core 0.2.0a2__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.
Files changed (99) hide show
  1. arche/__init__.py +279 -0
  2. arche/_data/README.md +40 -0
  3. arche/_data/__init__.py +3 -0
  4. arche/_data/restcountries-v3.1-snapshot.json +1 -0
  5. arche/_models.py +151 -0
  6. arche/_types/__init__.py +48 -0
  7. arche/_version.py +15 -0
  8. arche/addr/__init__.py +42 -0
  9. arche/addr/_gazetteer/__init__.py +3 -0
  10. arche/addr/_gazetteer/cities.py +582 -0
  11. arche/addr/parse.py +633 -0
  12. arche/audit.py +141 -0
  13. arche/cli.py +474 -0
  14. arche/config.py +110 -0
  15. arche/credentials/__init__.py +67 -0
  16. arche/credentials/sd_jwt.py +458 -0
  17. arche/detect/__init__.py +53 -0
  18. arche/detect/_africa/__init__.py +3 -0
  19. arche/detect/_africa/ids.py +375 -0
  20. arche/detect/_africa/phones.py +764 -0
  21. arche/detect/_base.py +164 -0
  22. arche/detect/_llm/__init__.py +3 -0
  23. arche/detect/_money/__init__.py +3 -0
  24. arche/detect/_money/african.py +493 -0
  25. arche/detect/_names/__init__.py +3 -0
  26. arche/detect/_names/lexicon.py +760 -0
  27. arche/detect/digital_id/__init__.py +245 -0
  28. arche/detect/gh/__init__.py +3 -0
  29. arche/detect/gh/ids.py +127 -0
  30. arche/detect/gh/phones.py +40 -0
  31. arche/detect/gliner/__init__.py +3 -0
  32. arche/detect/ip/__init__.py +229 -0
  33. arche/detect/ke/__init__.py +3 -0
  34. arche/detect/ke/ids.py +114 -0
  35. arche/detect/ke/phones.py +40 -0
  36. arche/detect/locations/__init__.py +137 -0
  37. arche/detect/names/__init__.py +134 -0
  38. arche/detect/ng/__init__.py +3 -0
  39. arche/detect/ng/ids.py +205 -0
  40. arche/detect/ng/phones.py +59 -0
  41. arche/detect/phones.py +87 -0
  42. arche/detect/presidio/__init__.py +3 -0
  43. arche/detect/za/__init__.py +3 -0
  44. arche/detect/za/ids.py +146 -0
  45. arche/detect/za/phones.py +40 -0
  46. arche/doc/__init__.py +49 -0
  47. arche/doc/parse.py +176 -0
  48. arche/ensemble.py +917 -0
  49. arche/extract.py +589 -0
  50. arche/governance.py +345 -0
  51. arche/graph/__init__.py +37 -0
  52. arche/graph/audit.py +563 -0
  53. arche/graph/networkx_view.py +226 -0
  54. arche/ingest/__init__.py +31 -0
  55. arche/ingest/from_url.py +373 -0
  56. arche/jurisdictions/__init__.py +81 -0
  57. arche/jurisdictions/ghana.py +512 -0
  58. arche/jurisdictions/kenya.py +532 -0
  59. arche/jurisdictions/nigeria.py +560 -0
  60. arche/jurisdictions/restcountries.py +295 -0
  61. arche/jurisdictions/south_africa.py +520 -0
  62. arche/llm/__init__.py +103 -0
  63. arche/llm/extraction.py +308 -0
  64. arche/llm/providers.py +181 -0
  65. arche/locate.py +141 -0
  66. arche/models.py +341 -0
  67. arche/policy/__init__.py +43 -0
  68. arche/policy/_actions/__init__.py +3 -0
  69. arche/policy/_data/__init__.py +3 -0
  70. arche/policy/engine.py +402 -0
  71. arche/policy/statutes/GHANA-DPA.yaml +157 -0
  72. arche/policy/statutes/KENYA-DPA.yaml +167 -0
  73. arche/policy/statutes/NDPA-2023.yaml +253 -0
  74. arche/policy/statutes/POPIA.yaml +174 -0
  75. arche/protect.py +424 -0
  76. arche/py.typed +0 -0
  77. arche/resolve/__init__.py +80 -0
  78. arche/resolve/_matcher.py +668 -0
  79. arche/resolve/_relate.py +286 -0
  80. arche/resolve/classical.py +590 -0
  81. arche/resolve/places.py +875 -0
  82. arche/sign/__init__.py +96 -0
  83. arche/sign/envelope.py +208 -0
  84. arche/sign/jws.py +282 -0
  85. arche/sign/keys.py +260 -0
  86. arche/sign/workflow.py +401 -0
  87. arche/types.py +235 -0
  88. arche/workflow/__init__.py +40 -0
  89. arche/workflow/_dsar_templates.py +244 -0
  90. arche/workflow/_format.py +663 -0
  91. arche/workflow/_ingest.py +213 -0
  92. arche/workflow/_primitive.py +487 -0
  93. arche/workflow/_review.py +595 -0
  94. arche/workflow/dsar.py +347 -0
  95. arche/workflow/pipeline.py +887 -0
  96. arche_core-0.2.0a2.dist-info/METADATA +203 -0
  97. arche_core-0.2.0a2.dist-info/RECORD +99 -0
  98. arche_core-0.2.0a2.dist-info/WHEEL +4 -0
  99. arche_core-0.2.0a2.dist-info/licenses/LICENSE +190 -0
arche/__init__.py ADDED
@@ -0,0 +1,279 @@
1
+ # Copyright 2026 unpatterned.org
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """arche — the identity workflow framework.
5
+
6
+ African-first, globally pluggable. Compose detection, resolution, linking,
7
+ verification, and governance into production identity pipelines.
8
+
9
+ Lifecycle (five user-facing steps)::
10
+
11
+ Detect → Resolve → Link → Verify → Govern
12
+ arche. arche. arche- arche.sign + arche.policy +
13
+ detect resolve adapters arche.credentials arche.graph.audit
14
+ (v0.2.0a2:
15
+ arche.link)
16
+
17
+ Quickstart (v0.2, PRD §10.1)::
18
+
19
+ from arche import Pipeline
20
+
21
+ pipeline = Pipeline(
22
+ jurisdiction="NG",
23
+ statute="NDPA-2023",
24
+ )
25
+ result = pipeline.process(
26
+ "Customer Adesola Okonkwo, NIN 12345678901, phone 0803 555 7890."
27
+ )
28
+ print(result.redacted_text)
29
+ # -> "Customer NAME_..., NIN [NIN], phone PHONE_..."
30
+
31
+ Per-country detectors (PRD §6.1)::
32
+
33
+ from arche.detect.ng.ids import detect_nigerian_ids
34
+ from arche.detect.za.ids import detect_south_african_ids
35
+ from arche.detect.ng.phones import normalize_ng_phone, validate_ng_phone
36
+
37
+ Statute files (PRD §6.4)::
38
+
39
+ from arche.policy import load_statute, apply_policy, list_available_statutes
40
+ statute = load_statute("NDPA-2023") # or POPIA, KENYA-DPA, GHANA-DPA
41
+
42
+ Migration from v0.1: the legacy ``resolve()`` function still works through
43
+ the callable-module shim on ``arche.resolve`` (forwarding to
44
+ ``arche.workflow.pipeline.resolve``). ``Pipeline.process()`` is the v0.2
45
+ replacement and the recommended path for new code. The v0.1 surface is
46
+ removed in v0.3.
47
+ """
48
+
49
+ from __future__ import annotations
50
+
51
+ # ---------------------------------------------------------------------------
52
+ # v0.2.0a2 — places surface (eager)
53
+ # ---------------------------------------------------------------------------
54
+ # Added 2026-05-24 per docs/ceo-plans/2026-05-24-places-resolver.md §5 + §16.3.
55
+ # Eager because these are v0.2 primitives (no DeprecationWarning to defer).
56
+ from typing import TYPE_CHECKING
57
+
58
+ from ._version import __version__
59
+
60
+ # ---------------------------------------------------------------------------
61
+ # v0.2 PRD §10.1 surface (eager — the recommended public API)
62
+ # ---------------------------------------------------------------------------
63
+ from .workflow import Detection, Pipeline, Result
64
+
65
+ if TYPE_CHECKING:
66
+ from .resolve.places import PlaceResolver
67
+
68
+
69
+ def resolve_places(
70
+ text: str,
71
+ jurisdiction: str | None = None,
72
+ *,
73
+ resolver: PlaceResolver | None = None,
74
+ ):
75
+ """Resolve nearby places from a free-text query under jurisdictional law.
76
+
77
+ Returns a typed :class:`PlaceReport` with places, compliance block,
78
+ workflow trace, and ``save_receipt()`` for verifiable JWS audit.
79
+
80
+ Example::
81
+
82
+ from arche import resolve_places
83
+
84
+ report = resolve_places(
85
+ "My mum lives near St Thomas' Hospital in SW1 — find her a dentist."
86
+ )
87
+ for place in report.places:
88
+ print(place.name, place.distance_m, "m away")
89
+ report.save_receipt("audit.jws")
90
+
91
+ If ``jurisdiction`` is None, it's inferred from the text (UK postcodes,
92
+ country names, etc.). Raises :class:`JurisdictionInferenceError` if no
93
+ jurisdiction can be inferred — never silently defaults.
94
+
95
+ v0.1 ships with FIXTURES only by default. Set ``DEMO_LIVE_API=true`` env
96
+ to enable live OSM/NHS/openchargemap calls (stub in v0.1 — see spec §4.4).
97
+ """
98
+ from .resolve.places import _run_anchored
99
+ return _run_anchored(text=text, jurisdiction=jurisdiction, resolver=resolver)
100
+
101
+
102
+ def list_places(
103
+ category: str,
104
+ jurisdiction: str = "GB",
105
+ *,
106
+ near: str | None = None,
107
+ limit: int = 50,
108
+ cursor: str | None = None,
109
+ resolver: PlaceResolver | None = None,
110
+ ):
111
+ """Directory query: list every instance of `category` in `jurisdiction`.
112
+
113
+ Returns a typed :class:`PlaceDirectoryReport` with paginated results,
114
+ same compliance + trace shape as :func:`resolve_places`.
115
+
116
+ Example::
117
+
118
+ from arche import list_places
119
+
120
+ report = list_places(category="physiotherapy", jurisdiction="GB")
121
+ for clinic in report.results:
122
+ print(clinic.name, clinic.address)
123
+ if report.next_cursor:
124
+ more = list_places("physiotherapy", cursor=report.next_cursor)
125
+
126
+ Supported categories in v0.1: physiotherapy, dentist, ev_charger.
127
+ """
128
+ from .resolve.places import _run_directory
129
+ return _run_directory(
130
+ category=category, jurisdiction=jurisdiction,
131
+ near=near, limit=limit, cursor=cursor, resolver=resolver,
132
+ )
133
+
134
+ # ---------------------------------------------------------------------------
135
+ # v0.1 surface (lazy — PEP 562 __getattr__)
136
+ # ---------------------------------------------------------------------------
137
+ # The v0.1 names below remain importable as ``from arche import <name>`` for
138
+ # backward compatibility through the v0.2.x series. They are loaded on first
139
+ # access instead of at ``import arche`` time so that:
140
+ #
141
+ # 1. ``import arche`` stays silent (no DeprecationWarnings emitted by
142
+ # transitive shim modules: signal, enrich, audit, pipeline, etc.).
143
+ # 2. Cold-import time is minimised — PRD NFR-PERF-1 target <1000 ms.
144
+ # 3. The v0.2 ``__all__`` discipline is honoured: IDE auto-complete and
145
+ # ``from arche import *`` surface only the framework primitives.
146
+ #
147
+ # Each entry maps an exposed name to (submodule, attribute_name).
148
+
149
+ _LAZY: dict[str, tuple[str, str]] = {
150
+ # --- audit (v0.1 in-memory; v0.2 SQLite lives at arche.graph.audit) ----
151
+ "AuditEntry": (".audit", "AuditEntry"),
152
+ "AuditLog": (".audit", "AuditLog"),
153
+ "get_audit_log": (".audit", "get_audit_log"),
154
+ # --- config -----------------------------------------------------------
155
+ "configure": (".config", "configure"),
156
+ "get_config": (".config", "get_config"),
157
+ # --- ensemble ---------------------------------------------------------
158
+ "detect_sensitive_spans": (".ensemble", "detect_sensitive_spans"),
159
+ "extract_identity_evidence": (".ensemble", "extract_identity_evidence"),
160
+ "format_tagged_text": (".ensemble", "format_tagged_text"),
161
+ # --- extract / ingest -------------------------------------------------
162
+ "Entity": (".extract", "Entity"),
163
+ "extract": (".extract", "extract"),
164
+ "extract_text": (".workflow._ingest", "extract_text"),
165
+ # --- llm + locate -----------------------------------------------------
166
+ "LLMConfig": (".llm", "LLMConfig"),
167
+ "Location": (".locate", "Location"),
168
+ "locate": (".locate", "locate"),
169
+ # --- models (v2 pydantic surface) -------------------------------------
170
+ "IdentityEvidenceModel": (".models", "IdentityEvidenceModel"),
171
+ "IdentityRecordModel": (".models", "IdentityRecordModel"),
172
+ "JurisdictionProfileModel": (".models", "JurisdictionProfileModel"),
173
+ "MatchDecisionModel": (".models", "MatchDecisionModel"),
174
+ "SensitiveSpanModel": (".models", "SensitiveSpanModel"),
175
+ # --- match ------------------------------------------------------------
176
+ # Resolves to the real module (.resolve._matcher). The legacy
177
+ # `arche.match` deprecation shim was removed; `from arche import match`
178
+ # and friends route here directly.
179
+ "IdentityMatcher": (".resolve._matcher", "IdentityMatcher"),
180
+ "JurisdictionPriors": (".resolve._matcher", "JurisdictionPriors"),
181
+ "MatchScore": (".resolve._matcher", "MatchScore"),
182
+ "match": (".resolve._matcher", "match"),
183
+ # --- pipeline (v0.1 callables) ----------------------------------------
184
+ # Retargeted to .workflow.pipeline (real location); see note above.
185
+ # NOTE: `resolve_fhir` was removed in v0.2.0a3 along with the
186
+ # arche-adapters package — no FHIR surface in arche-core anymore.
187
+ "ArchePipeline": (".workflow.pipeline", "ArchePipeline"),
188
+ "IdentityGraph": (".workflow.pipeline", "IdentityGraph"),
189
+ "ResolutionResult": (".workflow.pipeline", "ResolutionResult"),
190
+ "detect": (".workflow.pipeline", "detect"),
191
+ "link": (".workflow.pipeline", "link"),
192
+ # --- relate -----------------------------------------------------------
193
+ # Resolves to the real module (.resolve._relate); the .relate shim was
194
+ # removed.
195
+ "EntityRelationship": (".resolve._relate", "EntityRelationship"),
196
+ "IdentityCluster": (".resolve._relate", "IdentityCluster"),
197
+ "extract_relationships": (".resolve._relate", "extract_relationships"),
198
+ "group_by_identity": (".resolve._relate", "group_by_identity"),
199
+ # --- protect ----------------------------------------------------------
200
+ "PIIDetection": (".protect", "PIIDetection"),
201
+ "detect_pii": (".protect", "detect_pii"),
202
+ "redact": (".protect", "redact"),
203
+ # --- resolve (also a callable package via _CallableResolveModule) -----
204
+ "ResolvedEntity": (".resolve", "ResolvedEntity"),
205
+ "resolve_entities": (".resolve", "resolve_entities"),
206
+ "resolve_identity_records": (".resolve", "resolve_identity_records"),
207
+ # --- review -----------------------------------------------------------
208
+ # Retargeted to .workflow._review (real location); see note above.
209
+ "ReviewCandidate": (".workflow._review", "ReviewCandidate"),
210
+ "ReviewQueue": (".workflow._review", "ReviewQueue"),
211
+ # --- visualize --------------------------------------------------------
212
+ # Resolves to the real module (.workflow._format); the .visualize shim
213
+ # was removed.
214
+ "evidence_to_csv": (".workflow._format", "evidence_to_csv"),
215
+ "evidence_to_html": (".workflow._format", "evidence_to_html"),
216
+ "format_evidence_table": (".workflow._format", "format_evidence_table"),
217
+ "format_summary": (".workflow._format", "format_summary"),
218
+ "format_table": (".workflow._format", "format_table"),
219
+ "print_table": (".workflow._format", "print_table"),
220
+ "to_csv": (".workflow._format", "to_csv"),
221
+ "to_dot": (".workflow._format", "to_dot"),
222
+ "to_graph_html": (".workflow._format", "to_graph_html"),
223
+ "to_html": (".workflow._format", "to_html"),
224
+ # --- types ------------------------------------------------------------
225
+ "IdentityEvidence": (".types", "IdentityEvidence"),
226
+ "IdentityRecord": (".types", "IdentityRecord"),
227
+ "JurisdictionProfile": (".types", "JurisdictionProfile"),
228
+ "MatchDecision": (".types", "MatchDecision"),
229
+ "SensitiveSpan": (".types", "SensitiveSpan"),
230
+ }
231
+
232
+
233
+ def __getattr__(name: str):
234
+ """PEP 562 lazy attribute access for the v0.1 backward-compat surface.
235
+
236
+ The v0.1 shim modules (signal, enrich, audit, pipeline, ...) emit
237
+ ``DeprecationWarning`` on import. Lazy-loading them defers those
238
+ warnings to first-use, so ``import arche`` itself remains silent.
239
+ """
240
+ target = _LAZY.get(name)
241
+ if target is None:
242
+ raise AttributeError(f"module 'arche' has no attribute {name!r}")
243
+ from importlib import import_module
244
+
245
+ module = import_module(target[0], package=__name__)
246
+ value = getattr(module, target[1])
247
+ # Cache on the package module so subsequent accesses skip __getattr__.
248
+ globals()[name] = value
249
+ return value
250
+
251
+
252
+ def __dir__() -> list[str]:
253
+ """Expose v0.1 names via auto-complete without forcing their import."""
254
+ return sorted(set(globals()) | _LAZY.keys())
255
+
256
+
257
+ # ---------------------------------------------------------------------------
258
+ # __all__: the recommended v0.2 PRD §10.1 surface.
259
+ # ---------------------------------------------------------------------------
260
+ # The v0.1 names listed in ``_LAZY`` above remain importable for backward
261
+ # compatibility but are intentionally absent from ``__all__`` so
262
+ # ``from arche import *`` and IDE auto-complete favour the v0.2 framework
263
+ # primitive. The v0.1 surface is removed in v0.3.
264
+ __all__ = [
265
+ # PRD §10.1 — the v0.2 framework primitive
266
+ "Pipeline",
267
+ "Result",
268
+ "Detection",
269
+ # Level 2 API kept in __all__ because it's the workhorse path
270
+ "detect",
271
+ "match",
272
+ "link",
273
+ "resolve",
274
+ # v0.2.0a2 — places (spec §5 + §16.3)
275
+ "resolve_places",
276
+ "list_places",
277
+ # Versioning
278
+ "__version__",
279
+ ]
arche/_data/README.md ADDED
@@ -0,0 +1,40 @@
1
+ # `arche/_data/` — Vendored data assets
2
+
3
+ This directory holds vendored data assets that ship with `arche-core`. Each
4
+ asset is documented below with source, version, fetch date, and license.
5
+
6
+ The data is loaded at module-import time (small, fast) and used to satisfy
7
+ lookups that would otherwise require network calls. The lightweight-by-default
8
+ commitment (BP §7) is the reason: `pip install arche-core` and any code path
9
+ that touches country metadata works fully offline.
10
+
11
+ ---
12
+
13
+ ## `restcountries-v3.1-snapshot.json`
14
+
15
+ | Field | Value |
16
+ |---|---|
17
+ | Source | https://restcountries.com/v3.1/all |
18
+ | Fields requested | `cca2,cca3,name,idd,currencies,languages,capital,region,subregion,borders` (10-field API limit) |
19
+ | Fetch date | 2026-05-20 |
20
+ | Countries | 250 (59 African) |
21
+ | File size | ~116 KB |
22
+ | Project license | restcountries.com → Mozilla Public License 2.0 (https://gitlab.com/restcountries/restcountries) |
23
+ | arche use | Phone calling-code prefixes (`+234` for NG, etc.), currency codes by country, language inference, jurisdiction borders fallback, region/subregion filtering |
24
+ | Refresh policy | Manual. Refresh quarterly or on confirmed data change. Run `scripts/refresh-restcountries.sh` (TODO) to re-fetch. |
25
+ | Consumer | `arche.jurisdictions.restcountries` |
26
+
27
+ **Why vendored:** The live API caps `fields` at 10, rate-limits aggressively,
28
+ and is centrally hosted. A production arche-core deployment in rural Ethiopia
29
+ or running offline on a field tablet cannot depend on it. The snapshot is
30
+ small enough to ship in the wheel and refresh on demand.
31
+
32
+ **Refresh command:**
33
+
34
+ ```bash
35
+ curl -sf "https://restcountries.com/v3.1/all?fields=cca2,cca3,name,idd,currencies,languages,capital,region,subregion,borders" \
36
+ -o packages/arche-core/src/arche/_data/restcountries-v3.1-snapshot.json
37
+ ```
38
+
39
+ After refreshing, bump the fetch date in this file and verify
40
+ `test_restcountries.py` still passes.
@@ -0,0 +1,3 @@
1
+ # Copyright 2026 unpatterned.org
2
+ # SPDX-License-Identifier: Apache-2.0
3
+