maf-compaction 0.1.0__tar.gz

maf_compaction-0.1.0/LICENSE

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

maf_compaction-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: maf-compaction
+Version: 0.1.0
+Summary: Prompt-cache-aware compaction strategies for Microsoft Agent Framework: anchored trimming, tool-result records and user-turn summaries that keep the cached prefix intact.
+Keywords: compaction,context-window,prompt-cache,agent-framework,microsoft-agent-framework
+Author: SOKOLAI BV
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: agent-framework-core>=1.20.0,<1.21
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-compaction
+
+[![PyPI](https://img.shields.io/pypi/v/maf-compaction)](https://pypi.org/project/maf-compaction/) [![Python](https://img.shields.io/pypi/pyversions/maf-compaction)](https://pypi.org/project/maf-compaction/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE)
+
+> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafCompactionExperimentalWarning`.
+
+Compaction strategies for [Microsoft Agent Framework](https://aka.ms/AgentFramework) that are shaped around the provider's prompt cache. A prompt cache matches on an exact prefix, and every compaction rewrites history inside that prefix, so compaction breaks the cache by construction. The strategies here break it as rarely and as late as they can: they keep a fixed head and tail of the conversation verbatim, change only the band between them, and change it by rules that produce the same bytes on every later turn.
+
+This is an independent package. It is not affiliated with or endorsed by Microsoft.
+
+## What is in it
+
+| Strategy | What it does |
+|---|---|
+| `AnchoredCompactionStrategy` | Keeps the first and last groups of the conversation whole and shortens the oldest tool results between them, by position, so the compacted prefix is stable. |
+| `MinimumGainAnchoredCompactionStrategy` | The same, with a floor: a collapse that would save too little to repay the cache it invalidates is declined. |
+| `ToolResultAnchoredSummarizationCompactionStrategy` | Has the model write the facts from its tool results into a *record* through a recall tool, then drops the tool groups the record covers. Ships with `make_recall_tool`, `RecallGate` and `ToolResultRecallMiddleware`, which ask for the record at the right moment. |
+| `UserTurnAnchoredSummarizationCompactionStrategy` | Summarises the user's turns between a fixed head and tail with a summarizer client, in one of three modes. |
+| `ToolResultAndUserTurnAnchoredSummarizationCompactionStrategy` | Runs the two summarising strategies over one conversation, record phase first, with a bounded last-resort chain that merges and rewrites while the prompt is over budget. When nothing safe is left to remove it stops, and the prompt goes out over the limit: a loud failure rather than a quiet loss of facts. |
+
+All of them implement the framework's `CompactionStrategy` and attach wherever the framework takes one: `create_harness_agent`, or a `CompactionProvider` on a plain `Agent`.
+
+## Install
+
+```bash
+pip install maf-compaction
+```
+
+The package depends on `agent-framework-core` alone. The summarising strategies take any framework chat client as their summarizer, so install the client package for your provider separately.
+
+## Quickstart
+
+Every strategy sizes its decisions with a tokenizer. The one below counts exactly and needs `tiktoken`, which this package does not install (`pip install tiktoken`); the framework's `CharacterEstimatorTokenizer` needs nothing extra and works too, at the cost of precision.
+
+```python
+import tiktoken
+
+
+class Tokenizer:
+    def __init__(self, encoding: str = "o200k_base") -> None:
+        self._encoding = tiktoken.get_encoding(encoding)
+
+    def count_tokens(self, text: str) -> int:
+        return len(self._encoding.encode(text))
+
+
+tokenizer = Tokenizer()
+CONTEXT_WINDOW = 128_000  # the model's input limit
+MAX_OUTPUT = 4_000  # reserved for the reply
+BUDGET = CONTEXT_WINDOW - MAX_OUTPUT
+```
+
+The anchored strategy needs nothing else:
+
+```python
+from agent_framework import create_harness_agent
+from agent_framework_openai import OpenAIChatClient
+from maf_compaction import AnchoredCompactionStrategy
+
+strategy = AnchoredCompactionStrategy(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,
+    keep_head_groups=3,  # task and requirements, never touched
+    keep_tail_groups=4,  # the working set, never touched
+    band_share=0.25,  # the oldest banded result keeps 25% of the budget
+)
+
+client = OpenAIChatClient(model_id="gpt-6-luna")
+agent = create_harness_agent(
+    client,
+    name="assistant",
+    agent_instructions="Answer from the lookups you make. Quote values exactly.",
+    tools=[lookup_deployment],
+    max_context_window_tokens=CONTEXT_WINDOW,
+    max_output_tokens=MAX_OUTPUT,
+    before_compaction_strategy=strategy,
+    after_compaction_strategy=strategy,
+    tokenizer=tokenizer,
+)
+```
+
+The record strategy needs the recall tool registered and its middleware installed, because the model cannot be asked for a record from inside a compaction pass:
+
+```python
+from maf_compaction import (
+    AnchoredCompactionStrategy,
+    RecallGate,
+    ToolResultAnchoredSummarizationCompactionStrategy,
+    ToolResultRecallMiddleware,
+    make_recall_tool,
+)
+
+strategy = ToolResultAnchoredSummarizationCompactionStrategy(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,
+    trigger_fraction=0.6,  # ask for a record past 60% of the budget
+    fallback_fraction=0.9,  # stop waiting for one past 90%
+    fallback=AnchoredCompactionStrategy(max_input_tokens=BUDGET, tokenizer=tokenizer),
+)
+
+gate = RecallGate()
+recall_tool = make_recall_tool(gate, target_tokens=2_000)
+recall = ToolResultRecallMiddleware(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,  # the same tokenizer as the strategy
+    arm=gate.arm,
+    disarm=gate.disarm,
+    trigger_fraction=strategy.trigger_fraction,
+    record_max_tokens=4_000,
+    repeat_records=True,  # a record per new batch of tool work
+    reforce=strategy.take_reforce,
+)
+
+agent = create_harness_agent(
+    client,
+    name="assistant",
+    agent_instructions="Answer from the lookups you make. Quote values exactly.",
+    tools=[lookup_deployment, recall_tool],
+    middleware=[recall],
+    max_context_window_tokens=CONTEXT_WINDOW,
+    max_output_tokens=MAX_OUTPUT,
+    before_compaction_strategy=strategy,
+    after_compaction_strategy=strategy,
+    tokenizer=tokenizer,
+)
+```
+
+The summarising strategies, `RecallGate` and `ToolResultRecallMiddleware` keep one conversation's decisions on the instance, so build this stack, and the agent that holds it, once per session. The middleware raises if a second session reaches it.
+
+The composed strategy takes a record half and a user-turn half built the same way, the user half with `remembered_requests=2` unless it runs in the recompacting mode; `find_nested_strategy` finds the record half inside it for the middleware's `reforce`, and `record_text` reads the record the model wrote.
+
+## When to use it
+
+Below the context window, not compacting is cheaper than any strategy here: the whole conversation stays cached. These strategies pay off once a conversation outgrows its window, where the framework's own strategies either lose the facts in the tool results or re-bill the prompt on every turn. The measurements behind that, and what each strategy does at the edges, are in the [compaction documentation](https://github.com/sokolaidev/maf-extensions/blob/main/docs/compaction/README.md).
+
+## What it depends on
+
+The strategies call `agent_framework._compaction`, the framework's private compaction helpers, for grouping, token annotation and the exclusion flags. Nothing public exposes those, so the dependency on `agent-framework-core` is pinned to one minor and moved only after the new minor has been read against.
+
+## Licence
+
+MIT. See the [LICENSE](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE).

maf_compaction-0.1.0/README.md

@@ -0,0 +1,142 @@
+# maf-compaction
+
+[![PyPI](https://img.shields.io/pypi/v/maf-compaction)](https://pypi.org/project/maf-compaction/) [![Python](https://img.shields.io/pypi/pyversions/maf-compaction)](https://pypi.org/project/maf-compaction/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE)
+
+> **Experimental.** Releases before 1.0 may change or remove APIs. Importing this package emits `MafCompactionExperimentalWarning`.
+
+Compaction strategies for [Microsoft Agent Framework](https://aka.ms/AgentFramework) that are shaped around the provider's prompt cache. A prompt cache matches on an exact prefix, and every compaction rewrites history inside that prefix, so compaction breaks the cache by construction. The strategies here break it as rarely and as late as they can: they keep a fixed head and tail of the conversation verbatim, change only the band between them, and change it by rules that produce the same bytes on every later turn.
+
+This is an independent package. It is not affiliated with or endorsed by Microsoft.
+
+## What is in it
+
+| Strategy | What it does |
+|---|---|
+| `AnchoredCompactionStrategy` | Keeps the first and last groups of the conversation whole and shortens the oldest tool results between them, by position, so the compacted prefix is stable. |
+| `MinimumGainAnchoredCompactionStrategy` | The same, with a floor: a collapse that would save too little to repay the cache it invalidates is declined. |
+| `ToolResultAnchoredSummarizationCompactionStrategy` | Has the model write the facts from its tool results into a *record* through a recall tool, then drops the tool groups the record covers. Ships with `make_recall_tool`, `RecallGate` and `ToolResultRecallMiddleware`, which ask for the record at the right moment. |
+| `UserTurnAnchoredSummarizationCompactionStrategy` | Summarises the user's turns between a fixed head and tail with a summarizer client, in one of three modes. |
+| `ToolResultAndUserTurnAnchoredSummarizationCompactionStrategy` | Runs the two summarising strategies over one conversation, record phase first, with a bounded last-resort chain that merges and rewrites while the prompt is over budget. When nothing safe is left to remove it stops, and the prompt goes out over the limit: a loud failure rather than a quiet loss of facts. |
+
+All of them implement the framework's `CompactionStrategy` and attach wherever the framework takes one: `create_harness_agent`, or a `CompactionProvider` on a plain `Agent`.
+
+## Install
+
+```bash
+pip install maf-compaction
+```
+
+The package depends on `agent-framework-core` alone. The summarising strategies take any framework chat client as their summarizer, so install the client package for your provider separately.
+
+## Quickstart
+
+Every strategy sizes its decisions with a tokenizer. The one below counts exactly and needs `tiktoken`, which this package does not install (`pip install tiktoken`); the framework's `CharacterEstimatorTokenizer` needs nothing extra and works too, at the cost of precision.
+
+```python
+import tiktoken
+
+
+class Tokenizer:
+    def __init__(self, encoding: str = "o200k_base") -> None:
+        self._encoding = tiktoken.get_encoding(encoding)
+
+    def count_tokens(self, text: str) -> int:
+        return len(self._encoding.encode(text))
+
+
+tokenizer = Tokenizer()
+CONTEXT_WINDOW = 128_000  # the model's input limit
+MAX_OUTPUT = 4_000  # reserved for the reply
+BUDGET = CONTEXT_WINDOW - MAX_OUTPUT
+```
+
+The anchored strategy needs nothing else:
+
+```python
+from agent_framework import create_harness_agent
+from agent_framework_openai import OpenAIChatClient
+from maf_compaction import AnchoredCompactionStrategy
+
+strategy = AnchoredCompactionStrategy(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,
+    keep_head_groups=3,  # task and requirements, never touched
+    keep_tail_groups=4,  # the working set, never touched
+    band_share=0.25,  # the oldest banded result keeps 25% of the budget
+)
+
+client = OpenAIChatClient(model_id="gpt-6-luna")
+agent = create_harness_agent(
+    client,
+    name="assistant",
+    agent_instructions="Answer from the lookups you make. Quote values exactly.",
+    tools=[lookup_deployment],
+    max_context_window_tokens=CONTEXT_WINDOW,
+    max_output_tokens=MAX_OUTPUT,
+    before_compaction_strategy=strategy,
+    after_compaction_strategy=strategy,
+    tokenizer=tokenizer,
+)
+```
+
+The record strategy needs the recall tool registered and its middleware installed, because the model cannot be asked for a record from inside a compaction pass:
+
+```python
+from maf_compaction import (
+    AnchoredCompactionStrategy,
+    RecallGate,
+    ToolResultAnchoredSummarizationCompactionStrategy,
+    ToolResultRecallMiddleware,
+    make_recall_tool,
+)
+
+strategy = ToolResultAnchoredSummarizationCompactionStrategy(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,
+    trigger_fraction=0.6,  # ask for a record past 60% of the budget
+    fallback_fraction=0.9,  # stop waiting for one past 90%
+    fallback=AnchoredCompactionStrategy(max_input_tokens=BUDGET, tokenizer=tokenizer),
+)
+
+gate = RecallGate()
+recall_tool = make_recall_tool(gate, target_tokens=2_000)
+recall = ToolResultRecallMiddleware(
+    max_input_tokens=BUDGET,
+    tokenizer=tokenizer,  # the same tokenizer as the strategy
+    arm=gate.arm,
+    disarm=gate.disarm,
+    trigger_fraction=strategy.trigger_fraction,
+    record_max_tokens=4_000,
+    repeat_records=True,  # a record per new batch of tool work
+    reforce=strategy.take_reforce,
+)
+
+agent = create_harness_agent(
+    client,
+    name="assistant",
+    agent_instructions="Answer from the lookups you make. Quote values exactly.",
+    tools=[lookup_deployment, recall_tool],
+    middleware=[recall],
+    max_context_window_tokens=CONTEXT_WINDOW,
+    max_output_tokens=MAX_OUTPUT,
+    before_compaction_strategy=strategy,
+    after_compaction_strategy=strategy,
+    tokenizer=tokenizer,
+)
+```
+
+The summarising strategies, `RecallGate` and `ToolResultRecallMiddleware` keep one conversation's decisions on the instance, so build this stack, and the agent that holds it, once per session. The middleware raises if a second session reaches it.
+
+The composed strategy takes a record half and a user-turn half built the same way, the user half with `remembered_requests=2` unless it runs in the recompacting mode; `find_nested_strategy` finds the record half inside it for the middleware's `reforce`, and `record_text` reads the record the model wrote.
+
+## When to use it
+
+Below the context window, not compacting is cheaper than any strategy here: the whole conversation stays cached. These strategies pay off once a conversation outgrows its window, where the framework's own strategies either lose the facts in the tool results or re-bill the prompt on every turn. The measurements behind that, and what each strategy does at the edges, are in the [compaction documentation](https://github.com/sokolaidev/maf-extensions/blob/main/docs/compaction/README.md).
+
+## What it depends on
+
+The strategies call `agent_framework._compaction`, the framework's private compaction helpers, for grouping, token annotation and the exclusion flags. Nothing public exposes those, so the dependency on `agent-framework-core` is pinned to one minor and moved only after the new minor has been read against.
+
+## Licence
+
+MIT. See the [LICENSE](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE).

maf_compaction-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "maf-compaction"
+version = "0.1.0"
+description = "Prompt-cache-aware compaction strategies for Microsoft Agent Framework: anchored trimming, tool-result records and user-turn summaries that keep the cached prefix intact."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "compaction",
+    "context-window",
+    "prompt-cache",
+    "agent-framework",
+    "microsoft-agent-framework",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["agent-framework-core>=1.20.0,<1.21"]
+
+[[project.authors]]
+name = "SOKOLAI BV"
+email = "info@sokolai.com"
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.build-backend]
+module-name = "maf_compaction"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+    "E501",
+    "W505",
+    "TD",
+    "FIX",
+    "ERA001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+    "E501",
+    "W505",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_compaction-0.1.0/pyproject.toml.orig

@@ -0,0 +1,70 @@
+[project]
+name = "maf-compaction"
+version = "0.1.0"
+description = "Prompt-cache-aware compaction strategies for Microsoft Agent Framework: anchored trimming, tool-result records and user-turn summaries that keep the cached prefix intact."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "compaction",
+    "context-window",
+    "prompt-cache",
+    "agent-framework",
+    "microsoft-agent-framework",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    # The strategies subclass the framework's `CompactionStrategy` and call its private
+    # `_compaction` helpers (grouping, token annotation, the exclusion flags), which nothing
+    # public exposes. The ceiling admits only the minor those helpers were read against: a
+    # private module changing shape must be a resolution failure, not a silent change of
+    # behaviour.
+    "agent-framework-core>=1.20.0,<1.21",
+]
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.build-backend]
+module-name = "maf_compaction"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104", "E501", "W505", "TD", "FIX", "ERA001"]
+
+[tool.ruff.lint.per-file-ignores]
+# ruff resolves [tool.ruff] per file by the NEAREST ancestor pyproject.toml that has one, so
+# this package carries its own copy rather than inheriting one from the workspace root.
+# The length rules join the docstring pair: test fixtures are lenient, not API surface.
+"tests/**" = ["D101", "D103", "E501", "W505"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_compaction-0.1.0/src/maf_compaction/__init__.py

@@ -0,0 +1,177 @@
+"""Compaction strategies that keep the prompt cache.
+
+Provider prompt caches match on exact prefixes, and compaction rewrites history by
+construction. Each strategy here is shaped to break the cached prefix as rarely and as late
+as it can:
+
+- :class:`AnchoredCompactionStrategy` keeps a fixed head and tail verbatim and collapses the
+  band between them by a rule that reads a group's *position* and nothing else, so the same
+  prefix compacts to the same bytes on every later turn and stays cached.
+- :class:`MinimumGainAnchoredCompactionStrategy` adds a floor: it projects the reduction
+  before mutating anything and declines a collapse too small to repay the prompt cache it
+  would invalidate.
+- :class:`ToolResultAnchoredSummarizationCompactionStrategy` has the agent write the facts
+  from its tool results into a record, then drops the tool groups that record covers.
+  :func:`make_recall_tool` is the tool the model writes the record with, :class:`RecallGate`
+  keeps that tool inert until it is asked for, and :class:`ToolResultRecallMiddleware` asks.
+- :class:`UserTurnAnchoredSummarizationCompactionStrategy` summarises the *user's* turns
+  between a fixed head and tail, in one of three modes: recompact its earlier summary once the
+  band is worth a pass again, leave it standing as a boundary the next pass compacts only
+  behind, or do that and fold the standing summaries into one.
+- :class:`ToolResultAndUserTurnAnchoredSummarizationCompactionStrategy` runs those two over
+  one conversation, the record phase first, with the user half judged against the prompt the
+  record phase left. While the prompt is still over the input budget it runs a last-resort
+  chain: merge the records, merge the user summaries, rewrite the record harder, then the
+  record phase's fallback. Every replacement is kept only if it is smaller than what it
+  replaces, and nothing is checked against content.
+- :func:`set_preserved` and :func:`is_preserved` mark a message no strategy may shorten, drop
+  or shed, which is how a record survives the fallback that trims tool results.
+- :func:`find_nested_strategy` and :func:`record_text` are for the code that wires a strategy
+  up: finding the record half inside a composition, and reading the record it wrote.
+
+The docstrings keep the vocabulary of the benchmark the strategies were measured with: a *row*
+is one strategy run over one conversation, a row reads *DQ* when its prompt went out over the
+window, and the *flags* are the counters each strategy reports about its own run.
+
+**This depends on ``agent_framework._compaction``, which is private API.** Grouping, token
+annotation and the exclusion flags all come from there; nothing public exposes them. The
+dependency is pinned to one minor of the framework for that reason, and each new minor is
+read against before the pin moves.
+
+What each strategy does, why it is shaped that way and where it fails is in the compaction
+documentation of the maf-extensions repository.
+"""
+
+from ._anchored import (
+    DEFAULT_BAND_SHARE,
+    DEFAULT_KEEP_TOKENS,
+    DEFAULT_MIN_GAIN_FRACTION,
+    MARKER_ID_PREFIX,
+    REMOVAL_MARKER,
+    AnchoredCompactionStrategy,
+    MinimumGainAnchoredCompactionStrategy,
+)
+from ._composed import (
+    DEFAULT_CHAIN_GAIN_FRACTION,
+    DEFAULT_HARDER_ATTEMPTS,
+    ChainDecisions,
+    ToolResultAndUserTurnAnchoredSummarizationCompactionStrategy,
+)
+from ._nested import find_nested_strategy
+from ._preserve import (
+    PRESERVE_REASON_KEY,
+    PRESERVED_KEY,
+    any_preserved,
+    is_preserved,
+    set_preserved,
+)
+from ._toolsummary import (
+    DEFAULT_COVERAGE_SHARE,
+    DEFAULT_FALLBACK_FRACTION,
+    DEFAULT_RECORD_MAX_TOKENS,
+    DEFAULT_RECORD_TARGET_TOKENS,
+    DEFAULT_TRIGGER_FRACTION,
+    PRESERVE_REASON_UNCOVERED,
+    PRESERVE_REASON_UNRECORDED,
+    RECALL_TOOL_NAME,
+    RECORD_MARKER,
+    RecallGate,
+    RecordDecisions,
+    ToolResultAnchoredSummarizationCompactionStrategy,
+    ToolResultRecallMiddleware,
+    find_record_index,
+    make_recall_tool,
+    record_text,
+)
+from ._usersummary import (
+    DEFAULT_KEEP_HEAD_USER_TURNS,
+    DEFAULT_KEEP_TAIL_USER_TURNS,
+    DEFAULT_MIN_BAND_SHARE,
+    DEFAULT_SUMMARY_MODE,
+    DEFAULT_USER_FOLD_PROMPT,
+    DEFAULT_USER_SUMMARY_PROMPT,
+    DEFAULT_USER_TRIGGER_FRACTION,
+    FOLD_EXCLUDE_REASON,
+    FOLD_ID_PREFIX,
+    SUMMARY_MODE_BOUNDARY,
+    SUMMARY_MODE_FOLD,
+    SUMMARY_MODE_RECOMPACT,
+    SUMMARY_MODES,
+    USER_SUMMARY_MARKER,
+    UserTurnAnchoredSummarizationCompactionStrategy,
+)
+
+__all__ = [
+    "DEFAULT_BAND_SHARE",
+    "DEFAULT_CHAIN_GAIN_FRACTION",
+    "DEFAULT_COVERAGE_SHARE",
+    "DEFAULT_FALLBACK_FRACTION",
+    "DEFAULT_HARDER_ATTEMPTS",
+    "DEFAULT_KEEP_HEAD_USER_TURNS",
+    "DEFAULT_KEEP_TAIL_USER_TURNS",
+    "DEFAULT_KEEP_TOKENS",
+    "DEFAULT_MIN_BAND_SHARE",
+    "DEFAULT_MIN_GAIN_FRACTION",
+    "DEFAULT_RECORD_MAX_TOKENS",
+    "DEFAULT_RECORD_TARGET_TOKENS",
+    "DEFAULT_SUMMARY_MODE",
+    "DEFAULT_TRIGGER_FRACTION",
+    "DEFAULT_USER_FOLD_PROMPT",
+    "DEFAULT_USER_SUMMARY_PROMPT",
+    "DEFAULT_USER_TRIGGER_FRACTION",
+    "FOLD_EXCLUDE_REASON",
+    "FOLD_ID_PREFIX",
+    "MARKER_ID_PREFIX",
+    "PRESERVED_KEY",
+    "PRESERVE_REASON_KEY",
+    "PRESERVE_REASON_UNCOVERED",
+    "PRESERVE_REASON_UNRECORDED",
+    "RECALL_TOOL_NAME",
+    "RECORD_MARKER",
+    "REMOVAL_MARKER",
+    "SUMMARY_MODES",
+    "SUMMARY_MODE_BOUNDARY",
+    "SUMMARY_MODE_FOLD",
+    "SUMMARY_MODE_RECOMPACT",
+    "USER_SUMMARY_MARKER",
+    "AnchoredCompactionStrategy",
+    "ChainDecisions",
+    "MafCompactionExperimentalWarning",
+    "MinimumGainAnchoredCompactionStrategy",
+    "RecallGate",
+    "RecordDecisions",
+    "ToolResultAnchoredSummarizationCompactionStrategy",
+    "ToolResultAndUserTurnAnchoredSummarizationCompactionStrategy",
+    "ToolResultRecallMiddleware",
+    "UserTurnAnchoredSummarizationCompactionStrategy",
+    "any_preserved",
+    "find_nested_strategy",
+    "find_record_index",
+    "is_preserved",
+    "make_recall_tool",
+    "record_text",
+    "set_preserved",
+]
+
+# Experimental package: importing it emits a warning, and catches it when `python -W error`
+# promotes it, so such a host can still import the package.
+import warnings as _warnings
+
+
+class MafCompactionExperimentalWarning(UserWarning):
+    """Warning category for maf-compaction's experimental-package notice."""
+
+
+def _warn_experimental() -> None:
+    message = (
+        "maf_compaction is experimental and may change or be removed in future versions "
+        "without notice."
+    )
+    try:
+        _warnings.warn(message, category=MafCompactionExperimentalWarning, stacklevel=2)
+    except MafCompactionExperimentalWarning:
+        # Deliberate: under `-W error` an informational notice must not fail the import.
+        pass
+
+
+_warn_experimental()