jevguard-core 1.0.0__tar.gz

jevguard_core-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seb4ez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevguard_core-1.0.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: jevguard-core
+Version: 1.0.0
+Summary: Deterministic decision runtime, zero-token caching, and certainty calibrator for TypeSafe AI (Jev).
+Author: seb4ez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/seb4ez/jevguard
+Project-URL: Repository, https://github.com/seb4ez/jevguard.git
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# JevGuard: Deterministic Caching and Guardrails for TypeSafe AI (Jev)
+
+[![MCP Server](https://img.shields.io/badge/MCP_Server-jevguard--mcp-blue.svg)](https://github.com/seb4ez/jevguard-mcp)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9+-brightgreen.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Official Model Context Protocol (MCP) Server:** JevGuard includes an official, zero-dependency MCP server designed for autonomous AI agents in Google Antigravity, Cursor IDE, Claude Desktop, and Cline: **[seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**.
+
+JevGuard is an open-source Python library that provides local deterministic caching, state pruning, neutral escape injection, and calibration guardrails around TypeSafe AI's System One decision model. While upstream decision engines produce probabilistic outputs, JevGuard provides a strictly deterministic local layer: canonical JSON sorting, SHA-256 fingerprinting with volatile key masking, SQLite storage, and rule-based calibration checks using only the Python standard library.
+
+## Upstream Latency and Cache Performance (50 Live Verification Requests)
+
+The following benchmark report reflects 50 complete test requests executed against the official TypeSafe AI endpoint (`https://api.typesafe.ai/v1/systemone` using model `jev-latest`) from a development workstation. Latency comparisons contrast WAN roundtrips against local in-memory/SQLite cache lookups:
+
+![JevGuard Benchmark Results](benchmark_results.png)
+
+| Key Metric | Direct Upstream API | JevGuard Runtime | Empirical Advantage |
+| :--- | :--- | :--- | :--- |
+| **Verification Requests** | 50 live calls tested | 50 live calls tested | 100% transport pass rate across 5 test scenarios |
+| **Average Network Latency** | 784.53 ms | 735.88 ms (pruned) | State pruning reduces wire payload size |
+| **Deterministic Cache Hit** | 763.40 ms (144 tokens charged) | **0.099 ms** (**0 tokens**) | **Sub-millisecond retrieval (0.099 ms vs 763 ms WAN roundtrip); 0 tokens billed** |
+| **Out-of-Scope Protection** | Forced False Positive (`chargeback`) | `UNRESOLVED_OR_OTHER` | Neutral escape injection catches off-topic inputs |
+| **Uncertainty Calibration** | Raw unverified probabilities | `AMBIGUOUS_STATE` alert | Flags bimodal ties and low certainty |
+| **Local Runtime Overhead** | 0 ms | **0.024 ms** | Sub-millisecond execution using pure Python stdlib |
+
+## Why JevGuard
+
+TypeSafe AI's Jev model produces sub-second probabilistic evaluations over structured state. In production workflows, raw calls encounter three practical challenges:
+
+1. **Closed-World False Positives**: When categorical choice criteria lack a neutral fallback, the model distributes all probability across defined options. If an unhandled or off-topic input arrives, the model selects the closest available option.
+2. **Uncalibrated Ambiguity**: When inputs contain conflicting signals, probability distributions flatten. Selecting the top option without checking the runner-up margin leads to decisions made on low confidence.
+3. **Repeated Query Cost and Cache Misses**: Identical state checks inside agent loops consume network latency and token budgets. If payloads contain dynamic timestamps or request IDs, standard caches miss on every call.
+
+## Features
+
+- **Closed-World Escape Injection**: Detects categorical choice rules without a fallback and injects `UNRESOLVED_OR_OTHER`. Off-topic inputs route to this escape option instead of triggering forced choices.
+- **Strict Enum Support**: Set `closed_world=True` on `Choice` or `auto_inject_escapes=False` on the client when building strict enums where additional options must not be introduced.
+- **Certainty and Dispersion Heuristics**: Uses configurable operational defaults (top probability below 0.40 or top-to-runner-up margin below 0.15) to flag indecisive distributions as `AMBIGUOUS_STATE`.
+- **Volatile Metadata Masking**: Automatically ignores ephemeral fields (`timestamp`, `trace_id`, `request_id`, `nonce`) during SHA-256 fingerprinting, ensuring production cache hits across repeated queries.
+- **Sub-Millisecond Overhead**: Pure local CPU computation runs in under 0.20 ms (198 microseconds) per evaluation.
+- **Zero-Token SHA-256 Cache**: Hashes canonical sorted JSON. Identical requests return in under 1 millisecond with zero network overhead and zero token cost.
+- **Concurrent Batch and Async Support**: Built-in `batch_evaluate` with thread pooling and native `async_evaluate` for `asyncio` event loops.
+- **Resilient Network Retries**: Exponential backoff with jitter and `Retry-After` header parsing for HTTP 429 and 5xx server errors.
+- **Episodic SQLite Memory**: Records session interaction turns with transactional serialization and builds rolling summaries without retransmitting raw history.
+- **Zero Dependencies**: Pure Python 3.9+ standard library (`urllib`, `sqlite3`, `hashlib`, `json`, `threading`, `concurrent.futures`). No pip dependencies, no Node.js.
+
+## Installation
+
+Install locally with pip:
+
+```bash
+git clone https://github.com/seb4ez/jevguard.git
+cd jevguard
+pip install .
+```
+
+Or copy the `jevguard` directory directly into your project.
+
+Set your TypeSafe AI API key:
+
+```bash
+export TYPESAFE_API_KEY="your_typesafe_api_key"
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:TYPESAFE_API_KEY="your_typesafe_api_key"
+```
+
+## Quickstart
+
+```python
+from jevguard import JevGuardClient, Noul, Score, Choice
+
+client = JevGuardClient()
+
+state = {
+    "ticket_id": "INC-4091",
+    "customer_message": "Our payment gateway timed out during credit card settlement.",
+    "account_tier": "enterprise",
+    "timestamp": 1726778900
+}
+
+questions = {
+    "is_billing": Noul(instructions="Does this ticket describe an invoice or payment issue?"),
+    "severity": Score(
+        instructions="Rate incident urgency",
+        criteria=["Low", "Medium", "High", "Critical"]
+    ),
+    "route": Choice(
+        instructions="Assign handling team",
+        criteria={
+            "database_team": "Database connection and replication issues",
+            "payment_support": "Gateway timeouts and transaction errors",
+            "frontend_ui": "CSS, rendering, and asset bundling issues"
+        }
+    )
+}
+
+response = client.evaluate(state, questions)
+
+print(response.nouls["is_billing"].noul)       # 0.96
+print(response.scores["severity"].score)       # 2.45
+print(response.choices["route"].choice)        # "payment_support"
+print(response.choices["route"].status)        # "CONFIDENT"
+```
+
+## Strict Closed-World Enums
+
+When building strict finite-state machines where unhandled options must not be injected:
+
+```python
+# Pass closed_world=True to prevent UNRESOLVED_OR_OTHER injection
+approval_choice = Choice(
+    instructions="Review status",
+    criteria={"APPROVED": "Request accepted", "REJECTED": "Request denied"},
+    closed_world=True
+)
+
+resp = client.evaluate(state, {"decision": approval_choice})
+```
+
+## Production Caching with Volatile Metadata
+
+JevGuard masks ephemeral fields during fingerprint computation so dynamic timestamps or trace IDs do not bust the cache:
+
+```python
+# First call (cold)
+resp1 = client.evaluate({"query": "Check balance", "timestamp": 1726778900, "trace_id": "t-1"}, questions)
+
+# Second call 10 seconds later with new timestamp and trace_id hits local cache
+resp2 = client.evaluate({"query": "Check balance", "timestamp": 1726778910, "trace_id": "t-2"}, questions)
+
+print(resp2.cached)                             # True
+print(resp2.telemetry["latency_total_ms"])      # 0.10 ms
+print(resp2.telemetry["tokens_saved"])          # 159 tokens
+```
+
+> Note: Volatile masking operates on structured dictionary keys (for example `{"timestamp": 123}`). If dynamic timestamps are embedded inside raw unstructured strings (for example `{"log": "2026-09-19T22:00:00Z error"}`), the SHA-256 fingerprint will change. To ensure cache hits, extract dynamic timestamps and request IDs into distinct dictionary keys in `state`.
+
+## Concurrent Batch and Async Execution
+
+```python
+# Synchronous parallel batch evaluation
+items = [
+    (state_1, questions),
+    (state_2, questions),
+    (state_3, questions)
+]
+results = client.batch_evaluate(items, max_workers=5)
+
+# Native asynchronous execution in asyncio event loops (no manual thread wrapping required)
+import asyncio
+
+async def main():
+    res = await client.async_evaluate(state, questions)
+    print(res.choices["route"].choice)
+
+asyncio.run(main())
+```
+
+## Examples
+
+Runnable demonstration scripts are included in the `examples/` directory:
+
+```bash
+# 1. SRE Incident Triage: State pruning and multi-question evaluation
+python examples/01_sre_incident_triage.py
+
+# 2. Strict Finite State Machine: Enforcing closed_world=True with zero escapes
+python examples/02_strict_finite_state_machine.py
+
+# 3. High-Throughput Batch & Caching: Thread pool evaluation and volatile key masking
+python examples/03_high_throughput_batch_caching.py
+```
+
+## Official Model Context Protocol (MCP) Server
+
+JevGuard provides an official, zero-dependency MCP server for AI coding assistants (Google Antigravity, Cursor IDE, Claude Desktop, LibreChat, and Cline):
+
+* **Repository**: **[seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**
+* **Architecture**: 100% Python standard library over JSON-RPC 2.0 stdio with SQLite WAL concurrency and transparent `:memory:` degradation.
+* **Autonomous Agent Tools**:
+  - `evaluate_command_safety`: Evaluates shell commands for destructive actions (`ALLOW_AUTONOMOUS`, `REQUIRE_HUMAN_APPROVAL`, `DENY_DESTRUCTIVE`).
+  - `verify_code_patch`: Evaluates git diffs for security regressions, broken syntax, or critical system impact under strict, balanced, or permissive risk tolerances.
+  - `evaluate_decision`: Evaluates architectural decisions from a list of options with automatic neutral escape injection (`UNRESOLVED_OR_OTHER`) and dispersion gap calibration.
+  - `jevguard_evaluate`: Low-level deterministic evaluation pipeline with state pruning and zero-token caching.
+  - `jevguard_calibrate`: Standalone certainty and probability dispersion calibrator (`AMBIGUOUS_STATE`).
+  - `jevguard_prune_state`: Sanitizes complex state payloads and collapses duplicate whitespace.
+  - `jevguard_cache_fingerprint`: Computes canonical SHA-256 fingerprints with volatile key masking.
+
+### Quick Setup for AI Coding Environments
+
+#### Cursor IDE (`.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "jevguard": {
+      "command": "python",
+      "args": ["-m", "jevguard_mcp.server"],
+      "env": {
+        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "jevguard": {
+      "command": "python",
+      "args": ["-m", "jevguard_mcp.server"],
+      "env": {
+        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
+      }
+    }
+  }
+}
+```
+
+For complete MCP server documentation, empirical benchmark reports, and installation guides, visit the dedicated repository: **[github.com/seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**.
+
+## Testing & Verification
+
+Run the 21 formal subsystem certification tests:
+
+```bash
+python test_suite_21.py
+```
+
+This suite validates all 5 core subsystems under production conditions:
+1. State Pruner & Normalization (Tests 1 to 5)
+2. Closed-World Optimizer (Tests 6 to 9)
+3. Calibration & Dispersion Engine (Tests 10 to 13)
+4. Volatile Masking & Zero-Token Cache (Tests 14 to 17)
+5. Resilience, Batch & Async Transport (Tests 18 to 21)
+
+Run the 30 comprehensive regression and concurrency tests:
+
+```bash
+python test_jevguard.py
+```
+
+Run the microsecond CPU latency audit:
+
+```bash
+python benchmark.py
+```
+
+Run the live upstream comparative test (requires `TYPESAFE_API_KEY`):
+
+```bash
+python run_live_certification_tests.py
+```
+
+## Project Status and Validation Transparency
+
+JevGuard is an independent, community-driven open-source project (v1.0.0) built strictly with the Python standard library. Initial implementation and test suites were developed iteratively using AI-assisted engineering and local unit test validation.
+
+Key design caveats:
+- The local runtime (canonicalization, hashing, state pruning, and calibration checks) is deterministic, whereas the remote TypeSafe AI / Jev service produces probabilistic classifications.
+- Default calibration thresholds (such as top probability below 0.40 or margin below 0.15) represent operational heuristics for tie and uncertainty detection rather than parameters fitted on a specific domain corpus. Users can configure them according to their domain risk tolerance.
+- We welcome external peer review, empirical validation on production datasets, and community contributions.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

jevguard_core-1.0.0/README.md

@@ -0,0 +1,271 @@
+# JevGuard: Deterministic Caching and Guardrails for TypeSafe AI (Jev)
+
+[![MCP Server](https://img.shields.io/badge/MCP_Server-jevguard--mcp-blue.svg)](https://github.com/seb4ez/jevguard-mcp)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9+-brightgreen.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Official Model Context Protocol (MCP) Server:** JevGuard includes an official, zero-dependency MCP server designed for autonomous AI agents in Google Antigravity, Cursor IDE, Claude Desktop, and Cline: **[seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**.
+
+JevGuard is an open-source Python library that provides local deterministic caching, state pruning, neutral escape injection, and calibration guardrails around TypeSafe AI's System One decision model. While upstream decision engines produce probabilistic outputs, JevGuard provides a strictly deterministic local layer: canonical JSON sorting, SHA-256 fingerprinting with volatile key masking, SQLite storage, and rule-based calibration checks using only the Python standard library.
+
+## Upstream Latency and Cache Performance (50 Live Verification Requests)
+
+The following benchmark report reflects 50 complete test requests executed against the official TypeSafe AI endpoint (`https://api.typesafe.ai/v1/systemone` using model `jev-latest`) from a development workstation. Latency comparisons contrast WAN roundtrips against local in-memory/SQLite cache lookups:
+
+![JevGuard Benchmark Results](benchmark_results.png)
+
+| Key Metric | Direct Upstream API | JevGuard Runtime | Empirical Advantage |
+| :--- | :--- | :--- | :--- |
+| **Verification Requests** | 50 live calls tested | 50 live calls tested | 100% transport pass rate across 5 test scenarios |
+| **Average Network Latency** | 784.53 ms | 735.88 ms (pruned) | State pruning reduces wire payload size |
+| **Deterministic Cache Hit** | 763.40 ms (144 tokens charged) | **0.099 ms** (**0 tokens**) | **Sub-millisecond retrieval (0.099 ms vs 763 ms WAN roundtrip); 0 tokens billed** |
+| **Out-of-Scope Protection** | Forced False Positive (`chargeback`) | `UNRESOLVED_OR_OTHER` | Neutral escape injection catches off-topic inputs |
+| **Uncertainty Calibration** | Raw unverified probabilities | `AMBIGUOUS_STATE` alert | Flags bimodal ties and low certainty |
+| **Local Runtime Overhead** | 0 ms | **0.024 ms** | Sub-millisecond execution using pure Python stdlib |
+
+## Why JevGuard
+
+TypeSafe AI's Jev model produces sub-second probabilistic evaluations over structured state. In production workflows, raw calls encounter three practical challenges:
+
+1. **Closed-World False Positives**: When categorical choice criteria lack a neutral fallback, the model distributes all probability across defined options. If an unhandled or off-topic input arrives, the model selects the closest available option.
+2. **Uncalibrated Ambiguity**: When inputs contain conflicting signals, probability distributions flatten. Selecting the top option without checking the runner-up margin leads to decisions made on low confidence.
+3. **Repeated Query Cost and Cache Misses**: Identical state checks inside agent loops consume network latency and token budgets. If payloads contain dynamic timestamps or request IDs, standard caches miss on every call.
+
+## Features
+
+- **Closed-World Escape Injection**: Detects categorical choice rules without a fallback and injects `UNRESOLVED_OR_OTHER`. Off-topic inputs route to this escape option instead of triggering forced choices.
+- **Strict Enum Support**: Set `closed_world=True` on `Choice` or `auto_inject_escapes=False` on the client when building strict enums where additional options must not be introduced.
+- **Certainty and Dispersion Heuristics**: Uses configurable operational defaults (top probability below 0.40 or top-to-runner-up margin below 0.15) to flag indecisive distributions as `AMBIGUOUS_STATE`.
+- **Volatile Metadata Masking**: Automatically ignores ephemeral fields (`timestamp`, `trace_id`, `request_id`, `nonce`) during SHA-256 fingerprinting, ensuring production cache hits across repeated queries.
+- **Sub-Millisecond Overhead**: Pure local CPU computation runs in under 0.20 ms (198 microseconds) per evaluation.
+- **Zero-Token SHA-256 Cache**: Hashes canonical sorted JSON. Identical requests return in under 1 millisecond with zero network overhead and zero token cost.
+- **Concurrent Batch and Async Support**: Built-in `batch_evaluate` with thread pooling and native `async_evaluate` for `asyncio` event loops.
+- **Resilient Network Retries**: Exponential backoff with jitter and `Retry-After` header parsing for HTTP 429 and 5xx server errors.
+- **Episodic SQLite Memory**: Records session interaction turns with transactional serialization and builds rolling summaries without retransmitting raw history.
+- **Zero Dependencies**: Pure Python 3.9+ standard library (`urllib`, `sqlite3`, `hashlib`, `json`, `threading`, `concurrent.futures`). No pip dependencies, no Node.js.
+
+## Installation
+
+Install locally with pip:
+
+```bash
+git clone https://github.com/seb4ez/jevguard.git
+cd jevguard
+pip install .
+```
+
+Or copy the `jevguard` directory directly into your project.
+
+Set your TypeSafe AI API key:
+
+```bash
+export TYPESAFE_API_KEY="your_typesafe_api_key"
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:TYPESAFE_API_KEY="your_typesafe_api_key"
+```
+
+## Quickstart
+
+```python
+from jevguard import JevGuardClient, Noul, Score, Choice
+
+client = JevGuardClient()
+
+state = {
+    "ticket_id": "INC-4091",
+    "customer_message": "Our payment gateway timed out during credit card settlement.",
+    "account_tier": "enterprise",
+    "timestamp": 1726778900
+}
+
+questions = {
+    "is_billing": Noul(instructions="Does this ticket describe an invoice or payment issue?"),
+    "severity": Score(
+        instructions="Rate incident urgency",
+        criteria=["Low", "Medium", "High", "Critical"]
+    ),
+    "route": Choice(
+        instructions="Assign handling team",
+        criteria={
+            "database_team": "Database connection and replication issues",
+            "payment_support": "Gateway timeouts and transaction errors",
+            "frontend_ui": "CSS, rendering, and asset bundling issues"
+        }
+    )
+}
+
+response = client.evaluate(state, questions)
+
+print(response.nouls["is_billing"].noul)       # 0.96
+print(response.scores["severity"].score)       # 2.45
+print(response.choices["route"].choice)        # "payment_support"
+print(response.choices["route"].status)        # "CONFIDENT"
+```
+
+## Strict Closed-World Enums
+
+When building strict finite-state machines where unhandled options must not be injected:
+
+```python
+# Pass closed_world=True to prevent UNRESOLVED_OR_OTHER injection
+approval_choice = Choice(
+    instructions="Review status",
+    criteria={"APPROVED": "Request accepted", "REJECTED": "Request denied"},
+    closed_world=True
+)
+
+resp = client.evaluate(state, {"decision": approval_choice})
+```
+
+## Production Caching with Volatile Metadata
+
+JevGuard masks ephemeral fields during fingerprint computation so dynamic timestamps or trace IDs do not bust the cache:
+
+```python
+# First call (cold)
+resp1 = client.evaluate({"query": "Check balance", "timestamp": 1726778900, "trace_id": "t-1"}, questions)
+
+# Second call 10 seconds later with new timestamp and trace_id hits local cache
+resp2 = client.evaluate({"query": "Check balance", "timestamp": 1726778910, "trace_id": "t-2"}, questions)
+
+print(resp2.cached)                             # True
+print(resp2.telemetry["latency_total_ms"])      # 0.10 ms
+print(resp2.telemetry["tokens_saved"])          # 159 tokens
+```
+
+> Note: Volatile masking operates on structured dictionary keys (for example `{"timestamp": 123}`). If dynamic timestamps are embedded inside raw unstructured strings (for example `{"log": "2026-09-19T22:00:00Z error"}`), the SHA-256 fingerprint will change. To ensure cache hits, extract dynamic timestamps and request IDs into distinct dictionary keys in `state`.
+
+## Concurrent Batch and Async Execution
+
+```python
+# Synchronous parallel batch evaluation
+items = [
+    (state_1, questions),
+    (state_2, questions),
+    (state_3, questions)
+]
+results = client.batch_evaluate(items, max_workers=5)
+
+# Native asynchronous execution in asyncio event loops (no manual thread wrapping required)
+import asyncio
+
+async def main():
+    res = await client.async_evaluate(state, questions)
+    print(res.choices["route"].choice)
+
+asyncio.run(main())
+```
+
+## Examples
+
+Runnable demonstration scripts are included in the `examples/` directory:
+
+```bash
+# 1. SRE Incident Triage: State pruning and multi-question evaluation
+python examples/01_sre_incident_triage.py
+
+# 2. Strict Finite State Machine: Enforcing closed_world=True with zero escapes
+python examples/02_strict_finite_state_machine.py
+
+# 3. High-Throughput Batch & Caching: Thread pool evaluation and volatile key masking
+python examples/03_high_throughput_batch_caching.py
+```
+
+## Official Model Context Protocol (MCP) Server
+
+JevGuard provides an official, zero-dependency MCP server for AI coding assistants (Google Antigravity, Cursor IDE, Claude Desktop, LibreChat, and Cline):
+
+* **Repository**: **[seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**
+* **Architecture**: 100% Python standard library over JSON-RPC 2.0 stdio with SQLite WAL concurrency and transparent `:memory:` degradation.
+* **Autonomous Agent Tools**:
+  - `evaluate_command_safety`: Evaluates shell commands for destructive actions (`ALLOW_AUTONOMOUS`, `REQUIRE_HUMAN_APPROVAL`, `DENY_DESTRUCTIVE`).
+  - `verify_code_patch`: Evaluates git diffs for security regressions, broken syntax, or critical system impact under strict, balanced, or permissive risk tolerances.
+  - `evaluate_decision`: Evaluates architectural decisions from a list of options with automatic neutral escape injection (`UNRESOLVED_OR_OTHER`) and dispersion gap calibration.
+  - `jevguard_evaluate`: Low-level deterministic evaluation pipeline with state pruning and zero-token caching.
+  - `jevguard_calibrate`: Standalone certainty and probability dispersion calibrator (`AMBIGUOUS_STATE`).
+  - `jevguard_prune_state`: Sanitizes complex state payloads and collapses duplicate whitespace.
+  - `jevguard_cache_fingerprint`: Computes canonical SHA-256 fingerprints with volatile key masking.
+
+### Quick Setup for AI Coding Environments
+
+#### Cursor IDE (`.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "jevguard": {
+      "command": "python",
+      "args": ["-m", "jevguard_mcp.server"],
+      "env": {
+        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "jevguard": {
+      "command": "python",
+      "args": ["-m", "jevguard_mcp.server"],
+      "env": {
+        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
+      }
+    }
+  }
+}
+```
+
+For complete MCP server documentation, empirical benchmark reports, and installation guides, visit the dedicated repository: **[github.com/seb4ez/jevguard-mcp](https://github.com/seb4ez/jevguard-mcp)**.
+
+## Testing & Verification
+
+Run the 21 formal subsystem certification tests:
+
+```bash
+python test_suite_21.py
+```
+
+This suite validates all 5 core subsystems under production conditions:
+1. State Pruner & Normalization (Tests 1 to 5)
+2. Closed-World Optimizer (Tests 6 to 9)
+3. Calibration & Dispersion Engine (Tests 10 to 13)
+4. Volatile Masking & Zero-Token Cache (Tests 14 to 17)
+5. Resilience, Batch & Async Transport (Tests 18 to 21)
+
+Run the 30 comprehensive regression and concurrency tests:
+
+```bash
+python test_jevguard.py
+```
+
+Run the microsecond CPU latency audit:
+
+```bash
+python benchmark.py
+```
+
+Run the live upstream comparative test (requires `TYPESAFE_API_KEY`):
+
+```bash
+python run_live_certification_tests.py
+```
+
+## Project Status and Validation Transparency
+
+JevGuard is an independent, community-driven open-source project (v1.0.0) built strictly with the Python standard library. Initial implementation and test suites were developed iteratively using AI-assisted engineering and local unit test validation.
+
+Key design caveats:
+- The local runtime (canonicalization, hashing, state pruning, and calibration checks) is deterministic, whereas the remote TypeSafe AI / Jev service produces probabilistic classifications.
+- Default calibration thresholds (such as top probability below 0.40 or margin below 0.15) represent operational heuristics for tie and uncertainty detection rather than parameters fitted on a specific domain corpus. Users can configure them according to their domain risk tolerance.
+- We welcome external peer review, empirical validation on production datasets, and community contributions.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

jevguard_core-1.0.0/jevguard/__init__.py

@@ -0,0 +1,63 @@
+"""
+JevGuard - High-Performance Deterministic Runtime for TypeSafe AI / Jev.
+Provides closed-world optimization, certainty calibration, state pruning,
+zero-token deterministic caching, and episodic session memory.
+"""
+
+from .models import (
+    Question,
+    Noul,
+    Score,
+    Choice,
+    NoulAnswer,
+    ScoreAnswer,
+    ChoiceAnswer,
+    EvaluationResponse,
+    EvaluationResult
+)
+from .client import JevGuardClient
+from .optimizer import StatePruner, QuestionOptimizer, ESCAPE_OPTION_KEY
+from .calibrator import ResponseCalibrator, CertaintyCalibrator
+from .cache import DeterministicCache, SemanticCache
+from .memory import EpisodicMemory
+from .exceptions import (
+    JevGuardError,
+    JevGuardConfigError,
+    JevGuardNetworkError,
+    JevGuardTimeoutError,
+    JevGuardHTTPError,
+    JevGuardAuthenticationError,
+    JevGuardRateLimitError,
+    JevGuardServerError
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "JevGuardClient",
+    "Question",
+    "Noul",
+    "Score",
+    "Choice",
+    "NoulAnswer",
+    "ScoreAnswer",
+    "ChoiceAnswer",
+    "EvaluationResponse",
+    "EvaluationResult",
+    "StatePruner",
+    "QuestionOptimizer",
+    "ResponseCalibrator",
+    "CertaintyCalibrator",
+    "DeterministicCache",
+    "SemanticCache",
+    "EpisodicMemory",
+    "ESCAPE_OPTION_KEY",
+    "JevGuardError",
+    "JevGuardConfigError",
+    "JevGuardNetworkError",
+    "JevGuardTimeoutError",
+    "JevGuardHTTPError",
+    "JevGuardAuthenticationError",
+    "JevGuardRateLimitError",
+    "JevGuardServerError"
+]