ph-clm 0.9.0__tar.gz

ph_clm-0.9.0/.gitignore

@@ -0,0 +1,31 @@
+# Build and environment
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+jjt/
+w2/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+# Written by the guest's subprocess collectors and combined at the end of the
+# run; see `conftest.GUEST_COVERAGE_RC`.
+.coverage-guest*
+htmlcov/
+# Dropped at the repo root by pytest-textual-snapshot when a snapshot test
+# fails. The reference snapshots under `__snapshots__/` are the committed
+# expectation; this is the diff viewer for a run that did not match one.
+snapshot_report.html
+
+# Reference checkouts of the upstream projects this port reads from. Vendored
+# locally so the plans' citations are verifiable; never part of this repo.
+sources/
+
+# Local scratch
+.ph/
+*.local.yaml

ph_clm-0.9.0/LICENSE

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

ph_clm-0.9.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: ph-clm
+Version: 0.9.0
+Summary: pH plugin: the model edits its own context — tombstone, replace and rewrite sections of the surface, with the originals kept in the log.
+Project-URL: Homepage, https://github.com/chastabor/pH
+Project-URL: Repository, https://github.com/chastabor/pH
+Project-URL: Documentation, https://github.com/chastabor/pH/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/chastabor/pH/issues
+Author: Charles Tabor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,clm,context-management,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: ph-core==0.9.0
+Description-Content-Type: text/markdown
+
+# ph-clm
+
+*The model edits its own context: tombstone, replace and rewrite sections of what
+it sees, with every original kept in the log.*
+
+After [Context Language Models][clm]: a model keeps the context it works best with
+when it may edit that context itself. In pH an edit never rewrites the log. Each
+one is a surface `replace` — the mechanism compaction and paste offload already
+use — so the model's view changes, the log keeps the originals, and the person's
+transcript still shows the conversation they had.
+
+## Sections
+
+The model's context is cut into **sections** where no tool call is outstanding: a
+user message, an assistant reply, or an assistant message with every result it
+asked for. Each is named by the seq of its first event (`S412`), which never
+changes, so an id read on one call is good on the next.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `context_sections` | the map: each section's id, kind, size, and how much follows it |
+| `context_tombstone` | replace a run of sections with a one-line marker saying why |
+| `context_replace` | replace a run of sections with text the model wrote — a summary, or a rewrite |
+| `context_rewrite` | change one passage inside one section's tool output or reply |
+| `context_restore` | undo a section's latest edit, one level: a rewrite exactly, a removed or replaced run as the text it held |
+| `context_recall` | read back the originals a revised section stands for |
+| `context_diff` | a unified diff of a section against the originals it stands for, after the edits that led there |
+
+Every edit reports what it costs: a provider's prefix cache cannot serve anything
+after the first change, so the sections *after* an edit are read again once.
+
+## Readouts
+
+When a tool result takes the context past a share of its window, that result ends
+with one line giving the context's size and how to free space. Each share is reported
+once, and again only after an edit brings the context back below it. The shares are
+the `clm-context` row's `remindAt`, `[0.5, 0.75]` by default; `[]` turns readouts off.
+With compaction mounted, the last reminder comes `lastMargin` (0.2) below its trigger
+instead, 65% under the default 0.85, so the model has room to act before a summary is
+written for it. Under Code Mode the readout spells the call out, keywords and all.
+
+## The context file
+
+The `clm-mirror` row writes the model's context to a file in the agent's workspace
+scratch before each request, one `[[SECTION S<id>]]` block per section. The model
+edits it with whatever it already uses: `edit`, `sed`, Python in a cell. When the call
+that touched the file finishes, its changes land through the same editor the tools
+use, in one batch, before the call's result. The result carries the receipt.
+
+| in the file | becomes |
+|---|---|
+| a section deleted | a tombstone |
+| a tool result's text changed | that result rewritten in place |
+| a step's result lines removed | the step replaced by the text left |
+| a message's text changed | a replacement (a reply is rewritten in place) |
+| no section lines left | one replacement for everything editable |
+
+A revised section's header line says what it stands for. The text under it is only
+what the model may edit.
+
+A reorder, a damaged header, an edit to a protected section, or a file written before
+the context was last revised is refused. The call's result says why, and the file is
+rewritten.
+
+The file is a whole conversation, so it is kept private and short-lived:
+- its directory is 0700 and the file 0600;
+- it is deleted when the session leaves the store;
+- a link put in its place is replaced, never read through.
+
+Only an edit a tool call makes is applied. A file changed outside any call (in an
+editor, or by another process) is recorded as declined and rewritten before the next
+request.
+
+```bash
+phern --profile rlm-clm
+```
+
+[clm]: https://arxiv.org/abs/2609.37725

ph_clm-0.9.0/README.md

@@ -0,0 +1,80 @@
+# ph-clm
+
+*The model edits its own context: tombstone, replace and rewrite sections of what
+it sees, with every original kept in the log.*
+
+After [Context Language Models][clm]: a model keeps the context it works best with
+when it may edit that context itself. In pH an edit never rewrites the log. Each
+one is a surface `replace` — the mechanism compaction and paste offload already
+use — so the model's view changes, the log keeps the originals, and the person's
+transcript still shows the conversation they had.
+
+## Sections
+
+The model's context is cut into **sections** where no tool call is outstanding: a
+user message, an assistant reply, or an assistant message with every result it
+asked for. Each is named by the seq of its first event (`S412`), which never
+changes, so an id read on one call is good on the next.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `context_sections` | the map: each section's id, kind, size, and how much follows it |
+| `context_tombstone` | replace a run of sections with a one-line marker saying why |
+| `context_replace` | replace a run of sections with text the model wrote — a summary, or a rewrite |
+| `context_rewrite` | change one passage inside one section's tool output or reply |
+| `context_restore` | undo a section's latest edit, one level: a rewrite exactly, a removed or replaced run as the text it held |
+| `context_recall` | read back the originals a revised section stands for |
+| `context_diff` | a unified diff of a section against the originals it stands for, after the edits that led there |
+
+Every edit reports what it costs: a provider's prefix cache cannot serve anything
+after the first change, so the sections *after* an edit are read again once.
+
+## Readouts
+
+When a tool result takes the context past a share of its window, that result ends
+with one line giving the context's size and how to free space. Each share is reported
+once, and again only after an edit brings the context back below it. The shares are
+the `clm-context` row's `remindAt`, `[0.5, 0.75]` by default; `[]` turns readouts off.
+With compaction mounted, the last reminder comes `lastMargin` (0.2) below its trigger
+instead, 65% under the default 0.85, so the model has room to act before a summary is
+written for it. Under Code Mode the readout spells the call out, keywords and all.
+
+## The context file
+
+The `clm-mirror` row writes the model's context to a file in the agent's workspace
+scratch before each request, one `[[SECTION S<id>]]` block per section. The model
+edits it with whatever it already uses: `edit`, `sed`, Python in a cell. When the call
+that touched the file finishes, its changes land through the same editor the tools
+use, in one batch, before the call's result. The result carries the receipt.
+
+| in the file | becomes |
+|---|---|
+| a section deleted | a tombstone |
+| a tool result's text changed | that result rewritten in place |
+| a step's result lines removed | the step replaced by the text left |
+| a message's text changed | a replacement (a reply is rewritten in place) |
+| no section lines left | one replacement for everything editable |
+
+A revised section's header line says what it stands for. The text under it is only
+what the model may edit.
+
+A reorder, a damaged header, an edit to a protected section, or a file written before
+the context was last revised is refused. The call's result says why, and the file is
+rewritten.
+
+The file is a whole conversation, so it is kept private and short-lived:
+- its directory is 0700 and the file 0600;
+- it is deleted when the session leaves the store;
+- a link put in its place is replaced, never read through.
+
+Only an edit a tool call makes is applied. A file changed outside any call (in an
+editor, or by another process) is recorded as declined and rewritten before the next
+request.
+
+```bash
+phern --profile rlm-clm
+```
+
+[clm]: https://arxiv.org/abs/2609.37725

ph_clm-0.9.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ph-clm"
+version = "0.9.0"
+description = "pH plugin: the model edits its own context — tombstone, replace and rewrite sections of the surface, with the originals kept in the log."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Charles Tabor" }]
+keywords = ["agent", "llm", "context-management", "clm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# Nothing but the core: every edit is a surface `replace` ph-core already folds,
+# so a log written with this package opens and derives the same context on an
+# install without it.
+dependencies = ["ph-core==0.9.0"]
+
+[project.urls]
+Homepage = "https://github.com/chastabor/pH"
+Repository = "https://github.com/chastabor/pH"
+Documentation = "https://github.com/chastabor/pH/blob/main/docs/README.md"
+Issues = "https://github.com/chastabor/pH/issues"
+
+[project.entry-points."ph.bundles"]
+clm = "ph_clm:BUNDLE"
+
+[project.entry-points."ph.plugins"]
+clm-context = "ph_clm.tools:apply"
+clm-mirror = "ph_clm.mirror:apply"
+
+[tool.uv.sources]
+ph-core = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ph_clm"]

ph_clm-0.9.0/src/ph_clm/__init__.py

@@ -0,0 +1,27 @@
+"""pH's CLM bundle: the model manages its own context.
+
+After *Context Language Models* (Shao et al., 2026): a model keeps the context it
+works best with when it may edit that context itself. Here an edit is never a
+rewrite of the log. Every one is a surface `replace` ph-core already folds — a
+**tombstone** or a **replace** stands in for a run of whole sections, a
+**rewrite** changes one result or reply in place — so the model's view changes,
+the log keeps every original, and `transcript()` still shows the person what
+happened. `context_diff` and `context_recall` read the originals back, and
+`context_restore` undoes a section's latest edit.
+
+Ideas from the paper's harness and from `pi-clm`; no code from either — the CLM
+repository is CC BY-NC, and this package is MIT.
+
+@module ph_clm
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import kinds as kinds
+
+BUNDLE = Path(__file__).parent / "bundle.yaml"
+"""The rows the `clm` bundle layers over a profile."""
+
+__all__ = ["BUNDLE", "kinds"]

ph_clm-0.9.0/src/ph_clm/budget.py

@@ -0,0 +1,120 @@
+"""Context readouts: a line on a tool result when the context crosses a share of its
+window, so the model knows to edit before the provider's limit, or compaction, decides
+for it.
+
+**On the result, not beside it.** A readout rides on the tool result whose output
+crossed the threshold, appended in `tools/post-execute` as the context file's receipt
+is (pi-clm's `sizeTrailer` does the same). Everything the model is shown is logged
+(I3), and a notice message per threshold would be one more surface node to edit away.
+
+**Measured as compaction measures** (`TokenMeter.baseline`): the provider's count of
+the last request — system prompt and tool schemas included — moved by what the
+surface did since, plus the result about to be logged, against the window that request
+was routed with. A receipt's context figures are the same number. No window, no
+readouts: there is no share to report.
+
+**The last reminder comes a margin below compaction's trigger**, read from the engine
+(`CompactionSeam.trigger_fraction`), so the model always has room to act before a
+summary is written for it. A fixed last share did not: on a 16k slot, 75% left one
+file read before compaction's 85%, and a live run spent it on a malformed call and
+lost the sections it meant to edit to the summary (`Shares.of`).
+
+**Once per crossing, and again after an edit brings the context back down.** Per
+session, `Readouts` keeps how many thresholds the context had reached; a readout fires
+when a result raises that, and each reading sets it, so an edit that frees space lowers
+it and the next crossing is reported again. In memory: after a restart the first
+reading sets it without a readout, so a resumed session is not told again what it was
+told before the restart.
+
+@module ph_clm.budget
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+from ph.text import thousands
+
+__all__ = ["Readouts", "Shares"]
+
+
+@dataclass(frozen=True, slots=True)
+class Shares:
+    """The thresholds one reading is judged against, ascending, as shares of its
+    window — and the share at which compaction summarizes on its own, when an engine
+    says."""
+
+    thresholds: tuple[float, ...]
+    window: int
+    compacts_at: float | None
+
+    @classmethod
+    def of(
+        cls, remind_at: Sequence[float], margin: float, compacts_at: float | None, window: int
+    ) -> Shares:
+        """`remind_at`, with the last reminder moved to `margin` below compaction's
+        trigger: any configured share at or past that point gives way to it. Unchanged
+        with no engine, or a margin that would put it at or below zero; empty stays
+        empty, which is readouts off."""
+        shares = sorted(remind_at)
+        # Rounded, so 0.85 - 0.2 is the 0.65 it means rather than 0.6499999999999999.
+        last = None if compacts_at is None else round(compacts_at - margin, 6)
+        if shares and last is not None and last > 0:
+            shares = [*(share for share in shares if share < last), last]
+        return cls(tuple(shares), window, compacts_at)
+
+    def reached(self, tokens: int) -> int:
+        """How many thresholds `tokens` is at or past."""
+        return sum(1 for share in self.thresholds if tokens >= share * self.window)
+
+    def line(self, tokens: int, how: str) -> str:
+        """What a result carries when the context reached `tokens`: its size, what to
+        do, and when the next reminder comes — or that this is the last, and what
+        happens after it."""
+        level = self.reached(tokens)
+        share = tokens * 100 // self.window
+        head = f"[context: ~{thousands(tokens)} of {thousands(self.window)} tokens ({share}%)."
+        if level >= len(self.thresholds):
+            after = (
+                ""
+                if self.compacts_at is None
+                else f" At {round(self.compacts_at * 100)}% older context is summarized for you."
+            )
+            return f"{head} This is the last reminder: free space now — {how}.{after}]"
+        following = round(self.thresholds[level] * 100)
+        return (
+            f"{head} Free space when it suits you — {how}. "
+            f"The next reminder comes at {following}%.]"
+        )
+
+
+@dataclass(slots=True)
+class Readouts:
+    """Which thresholds each session's context has reached, and when that rises."""
+
+    _reached: dict[str, int] = field(default_factory=dict)
+
+    def crossed(
+        self, session_id: str, shares: Shares, before: int, most: int, measure: Callable[[], int]
+    ) -> int | None:
+        """When a result takes the context from `before` tokens to at most `most`: the
+        tokens after, if that reached a threshold this session had not; `None`
+        otherwise.
+
+        `measure` counts the tokens after exactly, and is asked only when the answer
+        needs it — when `most` could reach a threshold `before` had not, or when a
+        readout fires. Tokenizing a long result is the costly part, and most results
+        cross nothing.
+        """
+        floor = shares.reached(before)
+        known = self._reached.get(session_id, floor)
+        after = measure() if shares.reached(most) > floor else None
+        level = floor if after is None else shares.reached(after)
+        self._reached[session_id] = level
+        if level <= known:
+            return None
+        return measure() if after is None else after
+
+    def forget(self, session_id: str) -> None:
+        self._reached.pop(session_id, None)

ph_clm-0.9.0/src/ph_clm/bundle.yaml

@@ -0,0 +1,14 @@
+# ph-clm: the model edits its own context, over any profile.
+#
+# Two rows: the section map with its tools, and the context file. Every edit is a
+# surface `replace`, so compaction keeps working beside it — it summarizes the
+# surface, revisions included — and stays the backstop when a session outgrows
+# its window anyway.
+
+- id: clm-context
+  name: clm-context
+
+# The context as a file the model edits with its ordinary tools, read back after
+# each call and landed through the same editor the tools use (`CLM`).
+- id: clm-mirror
+  name: clm-mirror