hermes-jev-compact 0.1.0__tar.gz

hermes_jev_compact-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Runtime data (secrets, credentials, logs — NEVER commit)
+**/data/
+**/sockets/
+*.tmp
+*.lock
+!**/uv.lock
+
+# Environment
+.env
+.env.*
+
+# Hermes runtime (if symlinked from install)
+*.log
+node_modules
+
+# Local Hermes session artifacts (never commit)
+.hermes/

hermes_jev_compact-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [Unreleased]
+
+### Fixed
+
+- Bug-hunt wave (5 review agents, all findings verified before fixing):
+  - UTF-16-unit parity in the estimator/truncate/abridge — emoji-heavy text
+    was under-counted ~2x vs the TS reference.
+  - TS `_compact_call` port: `key=value` per entry with raw strings (was
+    whole-object JSON).
+  - 25% minimum-reduction rule enforced in-engine (TS `reductionRatio`):
+    low-value Jev passes fall back to the deterministic prune.
+  - Duplicate tool-result ids skip scoring (was: last-row-wins collapse
+    while pruning every row sharing the id).
+  - Out-of-order pairs (result before its call) are never candidates; the
+    validity gate rejects them plus malformed top-level rows.
+  - Multimodal text parts are flattened into state (host `_part_text`
+    parity); image/file parts contribute nothing instead of voiding the row.
+  - Multimodal assistant rows survive call-stripping (were dropped as
+    "payload-empty").
+  - `apply_decisions_openai` fails closed on duplicate/conflicting decision
+    input instead of last-wins.
+  - Transport: base URLs with query strings join correctly, fragments
+    refused, empty userinfo refused, malformed URLs raise JevError,
+    timeout must be finite + positive, NaN/Infinity bodies rejected,
+    `noul` answers range-checked to [0,1], status code is the authority
+    over the legacy `ok` flag.
+  - Engine inherits host `quiet_mode` / `protect_last_n`; `keep_threshold`
+    clamped to [0,1]; question-token cache bounded (4096 entries, tuple
+    keys); `register()` latches only after success.
+
+### Changed
+
+- Generic System One endpoint: settings are now `base_url` / `api_key_env`
+  (defaults `https://api.typesafe.ai/v1` / `TYPESAFE_API_KEY`) and `jev_model`
+  defaults to `jev-latest`. Works with TypeSafe's API or any router relaying
+  the same `{model, state, questions}` shape. The old `conduit_*` keys and
+  `CONDUIT_NEXUS_API_KEY` default are gone (pre-release rename — no
+  migration).
+- Transport hardening: redirects refused, response bodies capped at 1 MiB,
+  upstream error bodies no longer echoed into logs.
+
+## [0.1.0] - 2026-09-18
+
+### Added
+
+- Initial release: `JevContextCompressor(ContextCompressor)` engine `jev`.
+- Single-seam override of `_prune_old_tool_results`: Jev keep/drop scoring
+  via `/v1/systemone`, validity-checked, with built-in fallback on every
+  failure mode (transport, validation, timeout, cancel, missing key).
+- Port of fast-jev-compaction state shaping (estimator, fit stages,
+  questions, decisions, batching) with parity tests.
+- Deterministic demote still runs after a Jev pass
+  (dedup/args/images/stubs).

hermes_jev_compact-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheEpTic
+
+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.

hermes_jev_compact-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: hermes-jev-compact
+Version: 0.1.0
+Summary: Jev-powered smart tool-prune context engine for Hermes Agent (any OpenAI-style System One endpoint)
+Project-URL: Homepage, https://github.com/TheEpTic/hermes-plugins
+Project-URL: Repository, https://github.com/TheEpTic/hermes-plugins
+Project-URL: Issues, https://github.com/TheEpTic/hermes-plugins/issues
+Project-URL: Changelog, https://github.com/TheEpTic/hermes-plugins/blob/main/hermes-jev-compact/CHANGELOG.md
+Author-email: TheEpTic <nexus@eptic.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,compaction,context,hermes,jev,plugin,systemone
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == 'dev'
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hermes-jev-compact
+
+Smarter context compression for Hermes Agent: stale tool calls are scored by
+[TypeSafe Jev](https://docs.typesafe.ai/) — a fast decision model built for
+exactly this kind of keep-or-drop judgment — instead of being pruned by age
+alone. What Jev says still matters stays; the dead weight goes.
+
+Opt-in per profile (`context.engine: jev`). Worst case is exactly the built-in
+behavior: any Jev failure — transport, validation, timeout, cancel, missing
+key — falls back to the inherited deterministic prune.
+
+## why
+
+The built-in compressor prunes old tool results blindly: beyond the protected
+tail, everything is truncated by position. That is safe, but it throws away
+results the conversation still depends on (a test failure three turns back, the
+file listing that motivated the current edit) while keeping verbose output
+nobody will ever reference again.
+
+Jev fixes the targeting. For every stale tool call/result unit it answers two
+calibrated questions — *does the call still matter? does its full output still
+matter?* — against the whole conversation as state. The result:
+
+- **fewer broken continuations** — results the next step actually needs survive
+  compression instead of being truncated by age.
+- **smaller contexts** — high-confidence dead weight (passing test logs,
+  superseded listings, retried commands) is dropped entirely, not kept as
+  stubs.
+- **cheap judgments, not LLM summaries** — Jev returns probabilities in
+  ~70–500 ms at a fraction of a cent per prune; no generative model is
+  consulted during the prune path.
+
+## how it works
+
+`JevContextCompressor` subclasses the built-in `ContextCompressor` and
+overrides exactly one seam — `_prune_old_tool_results` (full-compression
+phase 1). The hot proactive path (`prune_tool_results_only`, documented
+deterministic/no-LLM) is untouched: it bypasses Jev entirely.
+
+One prune, end to end:
+
+1. **Candidates.** Paired tool call + result before the prune boundary, above
+   the char floor. Never candidates: system rows, index 0, the protected
+   tail, unpaired calls, unusable result shapes (bytes/numbers), duplicate or
+   out-of-order pairs (ambiguous address — fail closed).
+2. **State.** The whole transcript with result bodies replaced by short notes
+   (`ok, 9000 chars (omitted)`) is fitted into `max_state_tokens` through a
+   shrink ladder: cap call inputs → abridge long texts → collapse old texts →
+   compact old calls → drop text-only rows → merge call runs. Pinned rows
+   (index 0 + recent tail) shrink last.
+3. **Questions.** Two `noul` (yes/no probability) questions per call — *keep
+   the call? keep its full result?* — batched into `max_request_tokens` and
+   asked sequentially (so cancellation stops between asks).
+4. **Decisions.** `keep` / `drop_result` (truncate to a head + marker) /
+   `drop_call` (remove result rows, strip the call). Pinned calls always keep.
+5. **Commit gates.** Output is validity-checked (no orphans either way, no
+   duplicates, no out-of-order pairs, clean row shapes) and must shrink the
+   transcript by ≥25% (TS `reductionRatio` rule) — otherwise the deterministic
+   prune runs instead. The deterministic demote passes (dedup, arg truncation,
+   image retire, stubs) still run after a Jev pass, so nothing the built-in
+   compressor did is lost.
+
+State shaping is a port of
+[tamara/fast-jev-compaction](https://github.com/tamara/fast-jev-compaction)
+(MIT) — see THIRD_PARTY_NOTICES.md. Deliberate divergences from upstream:
+sequential batches (cancellation), OpenAI row adaptation, and the 25% rule
+enforced in-engine rather than by the caller.
+
+## install
+
+Works with any System One-compatible endpoint. TypeSafe's own API is the
+reference: get a key at
+[console.typesafe.ai](https://console.typesafe.ai/settings/keys), put it in
+`~/.hermes/.env` as `TYPESAFE_API_KEY`. Self-hosted routers relaying the same
+`{model, state, questions}` shape work too — just point `base_url` at them.
+
+```bash
+/path/to/hermes-python -m pip install hermes-jev-compact
+hermes plugins enable hermes-jev-compact --no-allow-tool-override
+```
+
+Then opt in per profile and `/reset`:
+
+```yaml
+context:
+  engine: jev
+plugins:
+  entries:
+    hermes-jev-compact:
+      settings:
+        base_url: https://api.typesafe.ai/v1   # any POST {base}/systemone endpoint
+        api_key_env: TYPESAFE_API_KEY              # env var holding the key
+        jev_model: jev-latest
+        keep_threshold: 0.5        # noul >= this keeps the unit
+        max_state_tokens: 25000    # transcript budget per request
+        max_request_tokens: 30000  # state + questions budget
+        truncate_head_chars: 300   # kept head of a dropped result
+        request_timeout_s: 30
+        min_result_chars: 8000     # results below this never become candidates
+```
+
+`compressor` (default) bypasses plugins entirely; `jev` only activates when
+named. To disable: `hermes config set context.engine compressor` (and
+optionally `hermes plugins disable hermes-jev-compact`), then `/reset`.
+
+## observability
+
+Per-agent counters live on the compressor: `jev_calls` (requests made),
+`jev_pruned_units` (units dropped/truncated), `jev_fallbacks` (times the
+built-in prune ran instead). A successful pass logs its score/drop counts and
+fit stage; every fallback logs its reason.
+
+## development
+
+```bash
+uv sync --extra dev --locked
+uv run pytest
+uv run black --check src tests
+uv run mypy src
+```

hermes_jev_compact-0.1.0/README.md

@@ -0,0 +1,120 @@
+# hermes-jev-compact
+
+Smarter context compression for Hermes Agent: stale tool calls are scored by
+[TypeSafe Jev](https://docs.typesafe.ai/) — a fast decision model built for
+exactly this kind of keep-or-drop judgment — instead of being pruned by age
+alone. What Jev says still matters stays; the dead weight goes.
+
+Opt-in per profile (`context.engine: jev`). Worst case is exactly the built-in
+behavior: any Jev failure — transport, validation, timeout, cancel, missing
+key — falls back to the inherited deterministic prune.
+
+## why
+
+The built-in compressor prunes old tool results blindly: beyond the protected
+tail, everything is truncated by position. That is safe, but it throws away
+results the conversation still depends on (a test failure three turns back, the
+file listing that motivated the current edit) while keeping verbose output
+nobody will ever reference again.
+
+Jev fixes the targeting. For every stale tool call/result unit it answers two
+calibrated questions — *does the call still matter? does its full output still
+matter?* — against the whole conversation as state. The result:
+
+- **fewer broken continuations** — results the next step actually needs survive
+  compression instead of being truncated by age.
+- **smaller contexts** — high-confidence dead weight (passing test logs,
+  superseded listings, retried commands) is dropped entirely, not kept as
+  stubs.
+- **cheap judgments, not LLM summaries** — Jev returns probabilities in
+  ~70–500 ms at a fraction of a cent per prune; no generative model is
+  consulted during the prune path.
+
+## how it works
+
+`JevContextCompressor` subclasses the built-in `ContextCompressor` and
+overrides exactly one seam — `_prune_old_tool_results` (full-compression
+phase 1). The hot proactive path (`prune_tool_results_only`, documented
+deterministic/no-LLM) is untouched: it bypasses Jev entirely.
+
+One prune, end to end:
+
+1. **Candidates.** Paired tool call + result before the prune boundary, above
+   the char floor. Never candidates: system rows, index 0, the protected
+   tail, unpaired calls, unusable result shapes (bytes/numbers), duplicate or
+   out-of-order pairs (ambiguous address — fail closed).
+2. **State.** The whole transcript with result bodies replaced by short notes
+   (`ok, 9000 chars (omitted)`) is fitted into `max_state_tokens` through a
+   shrink ladder: cap call inputs → abridge long texts → collapse old texts →
+   compact old calls → drop text-only rows → merge call runs. Pinned rows
+   (index 0 + recent tail) shrink last.
+3. **Questions.** Two `noul` (yes/no probability) questions per call — *keep
+   the call? keep its full result?* — batched into `max_request_tokens` and
+   asked sequentially (so cancellation stops between asks).
+4. **Decisions.** `keep` / `drop_result` (truncate to a head + marker) /
+   `drop_call` (remove result rows, strip the call). Pinned calls always keep.
+5. **Commit gates.** Output is validity-checked (no orphans either way, no
+   duplicates, no out-of-order pairs, clean row shapes) and must shrink the
+   transcript by ≥25% (TS `reductionRatio` rule) — otherwise the deterministic
+   prune runs instead. The deterministic demote passes (dedup, arg truncation,
+   image retire, stubs) still run after a Jev pass, so nothing the built-in
+   compressor did is lost.
+
+State shaping is a port of
+[tamara/fast-jev-compaction](https://github.com/tamara/fast-jev-compaction)
+(MIT) — see THIRD_PARTY_NOTICES.md. Deliberate divergences from upstream:
+sequential batches (cancellation), OpenAI row adaptation, and the 25% rule
+enforced in-engine rather than by the caller.
+
+## install
+
+Works with any System One-compatible endpoint. TypeSafe's own API is the
+reference: get a key at
+[console.typesafe.ai](https://console.typesafe.ai/settings/keys), put it in
+`~/.hermes/.env` as `TYPESAFE_API_KEY`. Self-hosted routers relaying the same
+`{model, state, questions}` shape work too — just point `base_url` at them.
+
+```bash
+/path/to/hermes-python -m pip install hermes-jev-compact
+hermes plugins enable hermes-jev-compact --no-allow-tool-override
+```
+
+Then opt in per profile and `/reset`:
+
+```yaml
+context:
+  engine: jev
+plugins:
+  entries:
+    hermes-jev-compact:
+      settings:
+        base_url: https://api.typesafe.ai/v1   # any POST {base}/systemone endpoint
+        api_key_env: TYPESAFE_API_KEY              # env var holding the key
+        jev_model: jev-latest
+        keep_threshold: 0.5        # noul >= this keeps the unit
+        max_state_tokens: 25000    # transcript budget per request
+        max_request_tokens: 30000  # state + questions budget
+        truncate_head_chars: 300   # kept head of a dropped result
+        request_timeout_s: 30
+        min_result_chars: 8000     # results below this never become candidates
+```
+
+`compressor` (default) bypasses plugins entirely; `jev` only activates when
+named. To disable: `hermes config set context.engine compressor` (and
+optionally `hermes plugins disable hermes-jev-compact`), then `/reset`.
+
+## observability
+
+Per-agent counters live on the compressor: `jev_calls` (requests made),
+`jev_pruned_units` (units dropped/truncated), `jev_fallbacks` (times the
+built-in prune ran instead). A successful pass logs its score/drop counts and
+fit stage; every fallback logs its reason.
+
+## development
+
+```bash
+uv sync --extra dev --locked
+uv run pytest
+uv run black --check src tests
+uv run mypy src
+```

hermes_jev_compact-0.1.0/SECURITY.md

@@ -0,0 +1,38 @@
+# Security
+
+## trust boundary
+
+Jev requests carry the conversation history with tool result bodies replaced
+by short notes (`ok, N chars (omitted)`); message text is abridged to fit the
+state budget, and call arguments are included (truncated per the fit stage).
+Prompt the operator before enabling on sessions carrying secrets outside the
+trust boundary of the Jev endpoint.
+
+Any OpenAI-style `POST {base_url}/systemone` endpoint works; TypeSafe's own
+API (https://api.typesafe.ai/v1) is the reference. Self-hosted routers keep
+the data in-house — point `base_url` at them.
+
+## key handling
+
+- The Jev API key is read at prune-call time via
+  `agent.secret_scope.get_secret()` (profile-scope aware, multiplex
+  fail-closed) and never cached on the engine instance or written to config.
+  The shared plugin singleton never retains it (stripped in `__init__`,
+  excluded from `__deepcopy__`); only per-agent copies hold the host chat key
+  the summary path needs, exactly like the built-in compressor.
+- The transport refuses redirects, embedded credentials, non-HTTP schemes,
+  and cleartext HTTP off loopback — a misconfigured `base_url` fails closed
+  to the built-in prune instead of sending the bearer key somewhere
+  surprising.
+- Upstream error bodies and raw transport exceptions are never echoed into
+  logs (status category only); response bodies are capped at 1 MiB.
+
+## lossiness
+
+Pruning is lossy by design (same as the built-in compressor). Dropped tool
+results are unrecoverable; dropped calls can be re-run by the agent.
+
+## reporting
+
+Report vulnerabilities to the repository owner; do not open public issues
+with sensitive details.

hermes_jev_compact-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# Third-party notices
+
+## fast-jev-compaction
+
+State shaping, estimator, batching, questions, and decision logic in
+`hermes_jev_compact/shaping.py` and `hermes_jev_compact/pruner.py` are ported
+from [tamaratran/fast-jev-compaction](https://github.com/tamaratran/fast-jev-compaction)
+(© 2025), used under the MIT License:
+
+```
+MIT License
+
+Copyright (c) 2025
+
+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.
+```

hermes_jev_compact-0.1.0/llms.txt

@@ -0,0 +1,39 @@
+# hermes-jev-compact
+
+Smarter context compression for Hermes Agent (opt-in `context.engine: jev`):
+stale tool call/result units are scored by TypeSafe Jev (keep / truncate /
+drop by calibrated probability) instead of being pruned by age alone.
+Any failure falls back to the built-in deterministic prune.
+
+## install
+
+```bash
+/path/to/hermes-python -m pip install hermes-jev-compact
+hermes plugins enable hermes-jev-compact --no-allow-tool-override
+```
+
+Then set `context.engine: jev` and `/reset`. `compressor` bypasses plugins;
+`jev` only activates when named. Disable with
+`hermes config set context.engine compressor` + `/reset`.
+
+## requires
+
+- a System One endpoint at `base_url` (default `https://api.typesafe.ai/v1`;
+  key from https://console.typesafe.ai/settings/keys)
+- client key in `~/.hermes/.env` under `api_key_env` (default `TYPESAFE_API_KEY`)
+
+## settings
+
+`plugins.entries.hermes-jev-compact.settings`: `base_url`, `api_key_env`,
+`jev_model` (`jev-latest`), `keep_threshold` (0.5), `max_state_tokens` (25000),
+`max_request_tokens` (30000), `truncate_head_chars` (300), `request_timeout_s`
+(30), `min_result_chars` (8000).
+
+## behavior
+
+Overrides only `_prune_old_tool_results` on the built-in compressor (the hot
+proactive path bypasses Jev — deterministic/no-LLM contract kept). Candidates
+are paired call+result units before the prune boundary; Jev scores two `noul`
+questions per unit against the fitted transcript; output must pass structural
+validity AND shrink ≥25% or the built-in prune runs instead. Counters
+`jev_calls` / `jev_pruned_units` / `jev_fallbacks` on the compressor.

hermes_jev_compact-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hermes-jev-compact"
+version = "0.1.0"
+description = "Jev-powered smart tool-prune context engine for Hermes Agent (any OpenAI-style System One endpoint)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "TheEpTic", email = "nexus@eptic.me" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+]
+
+keywords = ["hermes", "agent", "plugin", "context", "compaction", "jev", "systemone"]
+
+[project.urls]
+Homepage = "https://github.com/TheEpTic/hermes-plugins"
+Repository = "https://github.com/TheEpTic/hermes-plugins"
+Issues = "https://github.com/TheEpTic/hermes-plugins/issues"
+Changelog = "https://github.com/TheEpTic/hermes-plugins/blob/main/hermes-jev-compact/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "black==26.5.1",
+    "mypy==2.3.0",
+    "pytest==9.0.3",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hermes_jev_compact"]
+
+[project.entry-points."hermes_agent.plugins"]
+hermes-jev-compact = "hermes_jev_compact"
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["agent.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short --strict-markers"
+pythonpath = ["src"]

hermes_jev_compact-0.1.0/src/hermes_jev_compact/__init__.py

@@ -0,0 +1,88 @@
+"""hermes-jev-compact — Jev-powered smart tool-prune context engine for Hermes.
+
+A ContextCompressor subclass named ``jev`` that scores stale tool call/result
+units with TypeSafe Jev (any OpenAI-style ``POST {base_url}/systemone``
+endpoint — TypeSafe's own API at https://api.typesafe.ai/v1 is the reference)
+and keeps/drops them by probability, falling back to the built-in
+deterministic prune on any failure.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as distribution_version
+from typing import Any
+
+try:
+    __version__ = distribution_version("hermes-jev-compact")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+__all__ = ["__version__", "register"]
+
+logger = logging.getLogger(__name__)
+
+_registered: bool = False
+
+
+def _setting(ctx: Any, key: str, default: Any) -> Any:
+    """One typed coercion for ctx settings; garbage in → default out."""
+    try:
+        value = ctx.get_config(key, default)
+    except Exception:
+        return default
+    if isinstance(value, bool):
+        # bool coerces to everything (int(True) == 1); a bool setting is
+        # never what a str/int/float knob wants, so reject it outright.
+        return default
+    if isinstance(default, str):
+        return value.strip() if isinstance(value, str) and value.strip() else default
+    try:
+        out = type(default)(value)
+    except (TypeError, ValueError):
+        return default
+    if isinstance(out, float) and not math.isfinite(out):
+        return default
+    return out
+
+
+def _build_engine(ctx: Any) -> Any:
+    from .engine import _JEV_KNOBS, JevContextCompressor
+
+    knobs = {attr: _setting(ctx, key, default) for attr, key, default in _JEV_KNOBS}
+    # Host policy the built-in constructor would receive (agent_init.py:1856+):
+    # the plugin singleton is built at register() time, so read the same
+    # config roots directly. Without this the jev engine logs in quiet mode
+    # and guards the wrong tail size on the fallback/proactive paths.
+    base: dict[str, Any] = {}
+    try:
+        from hermes_cli.config import load_config_readonly  # type: ignore[import-not-found]
+
+        cfg = load_config_readonly() or {}
+        agent_cfg = cfg.get("agent", {}) if isinstance(cfg, dict) else {}
+        comp_cfg = cfg.get("compression", {}) if isinstance(cfg, dict) else {}
+        if isinstance(agent_cfg, dict) and isinstance(agent_cfg.get("quiet_mode"), bool):
+            base["quiet_mode"] = agent_cfg["quiet_mode"]
+        if isinstance(comp_cfg, dict) and comp_cfg.get("protect_last_n") is not None:
+            try:
+                base["protect_last_n"] = max(0, int(comp_cfg["protect_last_n"]))
+            except (TypeError, ValueError):
+                pass
+    except Exception:
+        pass
+    return JevContextCompressor(model="jev-latest", **base, **knobs)
+
+
+def register(ctx: Any) -> None:
+    """Register the ``jev`` context engine (config-only singleton, no secrets)."""
+    global _registered
+    if _registered:
+        logger.debug("hermes-jev-compact: already registered, skipping")
+        return
+    ctx.register_context_engine(_build_engine(ctx))
+    # Only latch AFTER success: a failed registration must not permanently
+    # disable retries (a second plugin wins the single-engine slot instead —
+    # the host rejects it with a warning, same as any double-register).
+    _registered = True
+    logger.info("hermes-jev-compact loaded (engine: jev)")