chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Context Compaction Samples
+
+This folder demonstrates context compaction patterns introduced by ADR-0019.
+
+## Files
+
+- `basics.py` — builds a local message list and applies each built-in strategy one at a time.
+- `summarization.py` — runs `SummarizationStrategy` directly with a real summarizing chat client.
+- `advanced.py` — composes multiple strategies with `TokenBudgetComposedStrategy`, including a real summarizer and tool-call groups.
+- `agent_client_overrides.py` — shows client defaults, agent-level overrides, and per-run compaction overrides.
+- `custom.py` — defines a custom strategy implementing the `CompactionStrategy` protocol.
+- `tiktoken_tokenizer.py` — shows a `TokenizerProtocol` implementation backed by `tiktoken`.
+- `compaction_provider.py` — uses `CompactionProvider` with an agent and `InMemoryHistoryProvider`.
+
+Run samples with:
+
+```bash
+uv run samples/02-agents/compaction/basics.py
+uv run samples/02-agents/compaction/summarization.py  # requires OPENAI_API_KEY
+uv run samples/02-agents/compaction/advanced.py  # requires OPENAI_API_KEY
+uv run samples/02-agents/compaction/agent_client_overrides.py
+uv run samples/02-agents/compaction/custom.py
+uv run samples/02-agents/compaction/tiktoken_tokenizer.py
+uv run samples/02-agents/compaction/compaction_provider.py  # requires OPENAI_API_KEY
+```
+
+## Security Considerations
+
+Most compaction strategies in this folder (`TruncationStrategy`, `SlidingWindowStrategy`,
+`SelectiveToolCallCompactionStrategy`, `ToolResultCompactionStrategy`) only remove or reorder
+existing messages and carry no additional risk. `SummarizationStrategy` is the exception: it
+calls out to an LLM to produce replacement summary content that permanently becomes part of
+chat history. A compromised or malicious summarization service could return a summary
+containing unsafe instructions, creating a persistent indirect-prompt-injection vector. Using
+`SummarizationStrategy` is optional and requires explicit configuration — only point its
+chat client at a summarization service you trust as much as the primary model.