diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 08ebfa0..043e049 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,6 +23,10 @@ jobs: run: ruff check src/ tests/ - name: Ruff format check run: ruff format --check src/ tests/ + - name: Marketing version sync + # Fails if README/landing/OG-card versions drift from pyproject — + # the served social card once sat 3 minors behind silently. + run: python scripts/sync_marketing_version.py --check test: runs-on: ubuntu-latest diff --git a/README.md b/README.md index 6af2c50..b87cb61 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ An open-source project from **[NichevLabs](https://nichevlabs.com)**. **Multi-agent orchestration in plain Python.** Build agent graphs, compose pipelines with `|`, deploy with one command. No DSL, no compile step, no paid debugger. Works with OpenAI, Anthropic, Gemini, and Ollama. -> 🎉 **selectools is 1.0 — stable.** The public API is frozen; `@stable` symbols carry a 2-minor compatibility promise. Python 3.10+. Latest: [v1.2](#whats-new-in-v12) — four-stage guardrails, native structured output, and observability events. +> 🎉 **selectools is 1.0 — stable.** The public API is frozen; `@stable` symbols carry a 2-minor compatibility promise. Python 3.10+. Latest: [v1.3](#whats-new-in-v13) — tested public streaming contracts for structured-output chat agents. ### 3 Ways to Build @@ -32,6 +32,17 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post") # selectools serve agent.yaml ``` +## What's New in v1.3 + +### v1.3.0 — Streaming Contracts + +Makes `final_turn_only` structured output safe to rely on in streaming chat agents. Behaviors that integrators previously had to learn from the source are now **documented, tested public contracts** — enforced on every consumption surface: `astream()` chunks, the `stream_handler` callback, and the `selectools.serve` SSE stream. + +- **The synthesis turn never streams** — its JSON arrives only on the terminal `AgentResult` (`.content` / `.parsed`), never as chunks or through `stream_handler`. `StreamChunk(event="structured_synthesis_start")` fires once when the synthesis turn begins so clients can show a pending state. +- **`single_pass` no longer streams the structured answer** (*Changed*, `@beta` surface) — content is suppressed since it's the JSON envelope by construction; tool-call chunks still stream for activity display. Read the answer from `AgentResult.parsed`. +- **New `StreamChunk(event="structured_reuse")`** — when the converged loop answer validates and is reused, the just-streamed chunks WERE the answer; this signal lets a chat surface convert or retract the bubble. The serve SSE endpoint forwards event chunks as `{"type": "event", ...}`. +- **`should_finalize` message contract** — the predicate's `messages` view is documented: TOOL messages always carry `tool_name`, and `tool_result` holds the result text for successful runs while staying `None` for errors/denials (the supported failure discriminator). + ## What's New in v1.2 ### v1.2.0 — Tool-Boundary Guardrails Complete & Structured Synthesis Follow-ups diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index a30af61..01e8f1f 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -49,4 +49,5 @@ Every feature MUST update all of these: - CHANGELOG.md lives at repo root — must be copied into `docs/` before build - Examples gallery (`landing/examples/index.html`) must be regenerated when examples are added or edited: `python scripts/build_examples_gallery.py > landing/examples/index.html` - Hardcoded counts (model count, test count, example count) appear across many files — audit all +- **Marketing version strings** (README banner, landing status bar/footer, OG-card badges) are synced from `pyproject.toml` by `scripts/sync_marketing_version.py`. CI runs it with `--check` and fails on drift; the release flow (`release.py`) runs the write mode. After it bumps the OG **SVG**, re-render the PNG: `uv run --with playwright python scripts/render_og_image.py`. - `docs/ARCHITECTURE.md` must be updated when adding new components diff --git a/docs/assets/og-card.html b/docs/assets/og-card.html index 1c8a015..5dd9fdf 100644 --- a/docs/assets/og-card.html +++ b/docs/assets/og-card.html @@ -152,7 +152,7 @@ selectools - v1.2 · STABLE + v1.3 · STABLE
AI agents that are just Python.
diff --git a/docs/assets/og-image.svg b/docs/assets/og-image.svg index 819a3a0..5c49aa3 100644 --- a/docs/assets/og-image.svg +++ b/docs/assets/og-image.svg @@ -46,7 +46,7 @@ v1.2 · STABLE + font-weight="700" font-size="19" fill="#22d3ee">v1.3 · STABLE - v1.2.0 · Apache-2.0 · 9 providers · OpenAI · Anthropic · Gemini · Ollama · LiteLLM + v1.3.0 · Apache-2.0 · 9 providers · OpenAI · Anthropic · Gemini · Ollama · LiteLLM [•] selectools diff --git a/landing/index.html b/landing/index.html index 0b3409e..a997f5e 100644 --- a/landing/index.html +++ b/landing/index.html @@ -4461,7 +4461,7 @@

AI agents that are just Python.

115 examples
50 evaluators
9 providers
-
v1.2.0
+
v1.3.0
@@ -5840,7 +5840,7 @@

Type a question. Or browse the docs.

├── pypi/ # pip install selectools └── changelog/ # what shipped, what changed -# selectools v1.2.0 · Apache-2.0 · made by NichevLabs +# selectools v1.3.0 · Apache-2.0 · made by NichevLabs # for developers who ship
$ diff --git a/scripts/release.py b/scripts/release.py index 89b5be4..41783c2 100755 --- a/scripts/release.py +++ b/scripts/release.py @@ -68,6 +68,21 @@ def update_changelog(self, version: str, message: Optional[str] = None) -> None: self.changelog_path.write_text("\n".join(lines)) print(f"✓ Updated CHANGELOG.md with version {version}") + def sync_marketing_version(self) -> None: + """Bump README banner + landing + OG-card version strings to match. + + The CI ``sync_marketing_version.py --check`` step fails the build on + drift, so this keeps a release from tripping its own gate. The OG + *PNG* still needs a manual re-render (``render_og_image.py``); the + script prints that reminder. + """ + script = self.repo_root / "scripts" / "sync_marketing_version.py" + if not script.exists(): + print("⚠ sync_marketing_version.py not found, skipping marketing sync") + return + subprocess.run([sys.executable, str(script)], cwd=self.repo_root, check=True) + print("✓ Synced marketing-surface version strings") + def run_command(self, cmd: list[str], check: bool = True) -> subprocess.CompletedProcess: """Run a shell command""" print(f" Running: {' '.join(cmd)}") @@ -206,6 +221,7 @@ def release( try: self.update_version(new_version) self.update_changelog(new_version, message) + self.sync_marketing_version() self.git_commit(new_version, message) self.git_tag(new_version) self.git_push(new_version) diff --git a/scripts/render_og_image.py b/scripts/render_og_image.py new file mode 100644 index 0000000..17ab87c --- /dev/null +++ b/scripts/render_og_image.py @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +"""Rasterize the landing OG social card SVG to PNG at 1200x630. + +The served social card (``landing/assets/og-image.png``) is a raster of +``landing/assets/og-image.svg``. Run this after the SVG changes (e.g. after +``sync_marketing_version.py`` bumps the version footer) so the PNG link +preview matches. + +Headless Chromium is used deliberately (not librsvg/cairosvg) so the font +fallback matches the design; ad-hoc rasterizers substitute fonts and shift +the layout. Requires the ``playwright`` package + its chromium browser: + + uv run --with playwright python scripts/render_og_image.py + # first time: uv run --with playwright playwright install chromium +""" + +from __future__ import annotations + +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +SVG = REPO_ROOT / "landing/assets/og-image.svg" +PNG = REPO_ROOT / "landing/assets/og-image.png" +WIDTH, HEIGHT = 1200, 630 + + +def main() -> int: + try: + from playwright.sync_api import sync_playwright + except ImportError: + print( + "playwright not installed. Run:\n" + " uv run --with playwright python scripts/render_og_image.py\n" + " (first time also: ... playwright install chromium)" + ) + return 1 + + with sync_playwright() as pw: + browser = pw.chromium.launch() + page = browser.new_page(viewport={"width": WIDTH, "height": HEIGHT}, device_scale_factor=1) + page.goto(SVG.as_uri()) + page.wait_for_timeout(500) + page.screenshot(path=str(PNG)) + browser.close() + print(f"Rendered {PNG.relative_to(REPO_ROOT)} ({WIDTH}x{HEIGHT}).") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/sync_marketing_version.py b/scripts/sync_marketing_version.py new file mode 100644 index 0000000..66e6be8 --- /dev/null +++ b/scripts/sync_marketing_version.py @@ -0,0 +1,165 @@ +#!/usr/bin/env python3 +"""Keep marketing-surface version strings in sync with pyproject.toml. + +The docs site, README banner, landing page, and OG social cards each carry +the current version in prose/markup. Three releases in one day (1.1 -> 1.3) +showed these drift silently: the served OG card sat at v0.20.1 for months +because nothing tied it to the package version. + +This script is the single source of truth binding. Run modes: + + python scripts/sync_marketing_version.py # rewrite drifted files + python scripts/sync_marketing_version.py --check # exit 1 on any drift + +``--check`` runs in CI so a stale marketing version fails the build instead +of shipping. Write mode is called from the release flow. + +NOTE: the OG *PNG* (landing/assets/og-image.png) is a raster derived from +landing/assets/og-image.svg. This script updates the SVG text and reminds +you to re-render the PNG; it does not rasterize (to avoid font-fallback +drift from an ad-hoc CI renderer). Re-render with the pinned tool: + + scripts/render_og_image.py # headless Chromium, 1200x630 +""" + +from __future__ import annotations + +import argparse +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Callable, List + +REPO_ROOT = Path(__file__).resolve().parent.parent + + +def read_version() -> str: + """The one source of truth: pyproject.toml ``version``.""" + content = (REPO_ROOT / "pyproject.toml").read_text() + match = re.search(r'^version\s*=\s*"([^"]+)"', content, re.MULTILINE) + if not match: + raise SystemExit("could not find version in pyproject.toml") + return match.group(1) + + +def _minor(version: str) -> str: + """``1.3.0`` -> ``1.3`` for the badges/banner that use the minor form.""" + parts = version.split(".") + return ".".join(parts[:2]) + + +@dataclass +class Rule: + """A single file + a regex whose one match holds the version token.""" + + path: str + pattern: "re.Pattern[str]" + # (version) -> the correct full matched string + replacement: Callable[[str], str] + required: bool = True + + +# Each rule pins ONE occurrence. A drift or a count change (someone adds a +# second version mention) is surfaced rather than silently half-fixed. +RULES: List[Rule] = [ + # README top banner: "Latest: [v1.3](#whats-new-in-v13) ..." + Rule( + path="README.md", + pattern=re.compile(r"Latest: \[v(\d+\.\d+)\]\(#whats-new-in-v\d+\)"), + replacement=lambda v: ( + f"Latest: [v{_minor(v)}](#whats-new-in-v{_minor(v).replace('.', '')})" + ), + ), + # Landing status bar: v1.3.0 + Rule( + path="landing/index.html", + pattern=re.compile(r'v(\d+\.\d+\.\d+)'), + replacement=lambda v: f'v{v}', + ), + # Landing footer terminal comment: "# selectools v1.3.0 ·" + Rule( + path="landing/index.html", + pattern=re.compile(r"# selectools v(\d+\.\d+\.\d+) ·"), + replacement=lambda v: f"# selectools v{v} ·", + ), + # Landing OG SVG footer: "v1.3.0 · Apache-2.0" + Rule( + path="landing/assets/og-image.svg", + pattern=re.compile(r"v(\d+\.\d+\.\d+) · Apache-2\.0"), + replacement=lambda v: f"v{v} · Apache-2.0", + ), + # Docs OG card badge: "v1.3 · STABLE" + Rule( + path="docs/assets/og-card.html", + pattern=re.compile(r"v(\d+\.\d+) · STABLE"), + replacement=lambda v: f"v{_minor(v)} · STABLE", + ), + # Docs OG SVG badge: "v1.3 · STABLE" + Rule( + path="docs/assets/og-image.svg", + pattern=re.compile(r"v(\d+\.\d+) · STABLE"), + replacement=lambda v: f"v{_minor(v)} · STABLE", + ), +] + + +def apply_rule(rule: Rule, version: str, *, check: bool) -> List[str]: + """Return a list of human-readable drift messages (empty when in sync).""" + path = REPO_ROOT / rule.path + if not path.exists(): + return [] if not rule.required else [f"{rule.path}: missing"] + text = path.read_text() + pat = rule.pattern + matches = pat.findall(text) + if not matches: + return [f"{rule.path}: no version token matched {pat.pattern!r}"] + if len(matches) > 1: + return [f"{rule.path}: {len(matches)} version tokens matched (expected 1)"] + correct = rule.replacement(version) + if pat.search(text).group(0) == correct: + return [] + if check: + return [f"{rule.path}: found v{matches[0]}, expected {version}"] + path.write_text(pat.sub(correct, text, count=1)) + print(f" updated {rule.path} -> {version}") + return [] + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--check", + action="store_true", + help="report drift and exit 1 without writing (for CI)", + ) + args = parser.parse_args() + + version = read_version() + drift: List[str] = [] + for rule in RULES: + drift.extend(apply_rule(rule, version, check=args.check)) + + if drift: + header = "Marketing version drift" if args.check else "Could not sync" + print(f"{header} (pyproject = {version}):", file=sys.stderr) + for msg in drift: + print(f" - {msg}", file=sys.stderr) + if args.check: + print( + "\nRun `python scripts/sync_marketing_version.py` to fix, then " + "re-render the OG PNG with `python scripts/render_og_image.py`.", + file=sys.stderr, + ) + return 1 + + if not args.check: + print(f"Marketing surfaces in sync at v{version}.") + print("Reminder: re-render the OG PNG with `python scripts/render_og_image.py`.") + else: + print(f"Marketing surfaces in sync at v{version}.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())