Skip to content

release: v0.17.7 — SemanticCache, Prompt Compression, Conversation Branching#32

Merged
johnnichev merged 2 commits intomainfrom
release/v0.17.7
Mar 25, 2026
Merged

release: v0.17.7 — SemanticCache, Prompt Compression, Conversation Branching#32
johnnichev merged 2 commits intomainfrom
release/v0.17.7

Conversation

@johnnichev
Copy link
Copy Markdown
Owner

@johnnichev johnnichev commented Mar 25, 2026

Summary

  • SemanticCache — drop-in replacement for InMemoryCache that serves cache hits for paraphrased queries using cosine similarity over embeddings. Configurable threshold, LRU eviction, TTL, thread-safe, pure-Python cosine (no NumPy). Exported as selectools.SemanticCache.
  • Prompt Compression — compress_context / compress_threshold / compress_keep_recent on AgentConfig. Fires before each LLM call when token fill-rate exceeds threshold; summarises old messages into [Compressed context] system message, leaving self.memory untouched. New StepType.PROMPT_COMPRESSED + on_prompt_compressed observer event.
  • Conversation Branching — ConversationMemory.branch() returns an independent snapshot. SessionStore.branch(src, dst) forks persisted sessions across all three backends (JSON, SQLite, Redis). Raises ValueError for missing source.

Stats

  • 55 new tests (2275 total)
  • 3 new examples (52: semantic cache, 53: prompt compression, 54: conversation branching)
  • 3 new doc pages + mkdocs nav entries
  • StepType count: 16 → 17
  • Observer events: 31 sync / 28 async → 32 sync / 29 async

Checklist

  • All tests pass (2275 tests, 0 failures)
  • Lint clean (black, isort, flake8, mypy)
  • Docs updated (README, ROADMAP, CHANGELOG, module docs, docs/index.md, mkdocs nav)
  • Audit passed (all counts consistent across docs)
  • mkdocs build clean (no errors)
  • Version bumped in __init__.py and pyproject.toml (0.17.6 → 0.17.7)

@johnnichev
feat: v0.17.7 — SemanticCache, prompt compression, conversation branc…
7115d83 
…hing

SemanticCache (cache_semantic.py): drop-in replacement for InMemoryCache that
serves hits for paraphrased queries using cosine similarity over embedding
vectors. Configurable threshold, LRU eviction, TTL, thread-safe.

Prompt Compression: fires before each LLM call when token fill-rate exceeds
compress_threshold; summarises old messages into a [Compressed context] system
message while keeping compress_keep_recent turns verbatim. Adds
StepType.PROMPT_COMPRESSED and on_prompt_compressed observer event.

Conversation Branching: ConversationMemory.branch() returns an independent
snapshot; SessionStore.branch(src, dst) forks persisted sessions across all
three backends (JSON, SQLite, Redis). Raises ValueError for missing source.

Stats: 55 new tests (2275 total), 3 examples (52-54), StepType 16→17,
observer events 31→32 sync / 28→29 async.
@johnnichev
docs: fix stale counts in README and docs/index.md for v0.17.7
4cfce56 
Update observer event count 28→32, test count 2220→2275, add SemanticCache /
Prompt Compression / Conversation Branching to docs/index.md feature table.
@johnnichev johnnichev merged commit d4bf6c6 into main Mar 25, 2026
5 checks passed
@johnnichev johnnichev deleted the release/v0.17.7 branch March 25, 2026 21:20
johnnichev added a commit that referenced this pull request Apr 7, 2026
@johnnichev
fix: terminal width, flow line fade, CONTRIBUTING.md staleness
56be261 
Three small fixes from the latest review pass.

1. **pip install terminal full-width on desktop** (Image #32):
   Removed `max-width: 440px` from `.terminal-install`. The terminal
   now spans 100% of the hero-content column, matching the width of
   the "Try the Builder" + "Read the Docs" button row directly below
   it. The hero grid (1fr 1fr split until 1024px) still constrains
   the column width itself, so this doesn't span the entire viewport
   on wide screens — it spans the column where the buttons live,
   which is what aligns them.

2. **SVG flow lines lingering after nodes fade out** (Image #33):
   Root cause: in the hero flow scene transitions, nodes fade via
   CSS `transition: opacity 0.3s` when `el.style.opacity = '0'`, but
   the SVG `<line>` elements (and `<circle>` pulses inside the same
   `<svg>`) had no fade animation — they stayed fully opaque until
   the next scene's `buildScene()` cleared the SVG via
   `svg.textContent = ''`. The visible result: nodes vanish at
   t=300ms, lines hang in the air alone for ~100ms, then snap to the
   next scene at t=400ms.

   Fix: added `transition: opacity 0.3s var(--ease)` to `.hf-svg`,
   and in playScene's "all done" handler set `svg.style.opacity = '0'`
   at the same time as `el.style.opacity = '0'` on the nodes. In
   buildScene, reset `svg.style.opacity = '1'` before drawing the
   next scene's lines so the new content fades in cleanly. Lines and
   nodes now vanish on the same curve.

3. **CONTRIBUTING.md stale facts** (user pointed out the version):
   The user noticed v0.19.2 in the header. While I was there I caught
   several other stale items and fixed them in the same pass:

   - Header version: v0.19.2 → v0.20.1 (current)
   - Header Python: "3.9+" → "3.9 – 3.13" (matches actual classifiers)
   - Header test status: "100%" → "95% coverage" (matches reality)
   - Project structure: "24 pre-built tools" → "33 pre-built tools"
     (verified via `grep -c '^@tool' src/selectools/toolbox/*.py`)
   - Project structure: "61 numbered examples (01–61)" → "88 numbered
     examples" (verified via `find examples -maxdepth 1 -name '*.py'
     | wc -l`)
   - Release script examples: 0.5.1 → 0.20.2 (current minor + 1)
   - Test command: `python tests/test_framework.py` → `pytest tests/`
     (the legacy single-file runner doesn't exist anymore)
   - Provider test path: `tests/test_framework.py` → `tests/providers/
     test_your_provider.py` (current convention)
   - Section header: "Adding RAG Features (New in v0.8.0!)" → "Adding
     RAG Features" (v0.8.0 was many releases ago)

   The biggest substantive fix: rewrote the "Adding a New Tool"
   example. The old example used `Tool(name=..., parameters=[
   ToolParameter(...)])`, which is the legacy class-based API.
   Selectools has used the `@tool()` decorator pattern for many
   versions now, where the function signature and docstring are
   introspected automatically. The old example was actively
   misleading new contributors into using a deprecated API. New
   example shows the modern decorator pattern with proper docstring
   conventions.

What's NOT in this PR:

- Full rewrite of the project structure block — only the genuinely
  stale numeric facts (24, 61) were fixed; the listed file names are
  still mostly accurate and a full architectural audit is out of
  scope for "the version is outdated"
- No CHANGELOG entry — these are doc fixes, not user-facing code
- No version bump
@johnnichev johnnichev mentioned this pull request Apr 7, 2026
Merged
13 tasks
johnnichev added a commit that referenced this pull request Apr 7, 2026
@johnnichev
fix: terminal width, flow line fade, CONTRIBUTING.md staleness (#45)
e31d31d 
Three small fixes from the latest review pass.

1. **pip install terminal full-width on desktop** (Image #32):
   Removed `max-width: 440px` from `.terminal-install`. The terminal
   now spans 100% of the hero-content column, matching the width of
   the "Try the Builder" + "Read the Docs" button row directly below
   it. The hero grid (1fr 1fr split until 1024px) still constrains
   the column width itself, so this doesn't span the entire viewport
   on wide screens — it spans the column where the buttons live,
   which is what aligns them.

2. **SVG flow lines lingering after nodes fade out** (Image #33):
   Root cause: in the hero flow scene transitions, nodes fade via
   CSS `transition: opacity 0.3s` when `el.style.opacity = '0'`, but
   the SVG `<line>` elements (and `<circle>` pulses inside the same
   `<svg>`) had no fade animation — they stayed fully opaque until
   the next scene's `buildScene()` cleared the SVG via
   `svg.textContent = ''`. The visible result: nodes vanish at
   t=300ms, lines hang in the air alone for ~100ms, then snap to the
   next scene at t=400ms.

   Fix: added `transition: opacity 0.3s var(--ease)` to `.hf-svg`,
   and in playScene's "all done" handler set `svg.style.opacity = '0'`
   at the same time as `el.style.opacity = '0'` on the nodes. In
   buildScene, reset `svg.style.opacity = '1'` before drawing the
   next scene's lines so the new content fades in cleanly. Lines and
   nodes now vanish on the same curve.

3. **CONTRIBUTING.md stale facts** (user pointed out the version):
   The user noticed v0.19.2 in the header. While I was there I caught
   several other stale items and fixed them in the same pass:

   - Header version: v0.19.2 → v0.20.1 (current)
   - Header Python: "3.9+" → "3.9 – 3.13" (matches actual classifiers)
   - Header test status: "100%" → "95% coverage" (matches reality)
   - Project structure: "24 pre-built tools" → "33 pre-built tools"
     (verified via `grep -c '^@tool' src/selectools/toolbox/*.py`)
   - Project structure: "61 numbered examples (01–61)" → "88 numbered
     examples" (verified via `find examples -maxdepth 1 -name '*.py'
     | wc -l`)
   - Release script examples: 0.5.1 → 0.20.2 (current minor + 1)
   - Test command: `python tests/test_framework.py` → `pytest tests/`
     (the legacy single-file runner doesn't exist anymore)
   - Provider test path: `tests/test_framework.py` → `tests/providers/
     test_your_provider.py` (current convention)
   - Section header: "Adding RAG Features (New in v0.8.0!)" → "Adding
     RAG Features" (v0.8.0 was many releases ago)

   The biggest substantive fix: rewrote the "Adding a New Tool"
   example. The old example used `Tool(name=..., parameters=[
   ToolParameter(...)])`, which is the legacy class-based API.
   Selectools has used the `@tool()` decorator pattern for many
   versions now, where the function signature and docstring are
   introspected automatically. The old example was actively
   misleading new contributors into using a deprecated API. New
   example shows the modern decorator pattern with proper docstring
   conventions.

What's NOT in this PR:

- Full rewrite of the project structure block — only the genuinely
  stale numeric facts (24, 61) were fixed; the listed file names are
  still mostly accurate and a full architectural audit is out of
  scope for "the version is outdated"
- No CHANGELOG entry — these are doc fixes, not user-facing code
- No version bump
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@johnnichev