release: v0.19.3 — stability markers applied to all public APIs

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to selectools will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.3] - 2026-03-31
+
+### Added
+
+#### Stability Markers Applied to All Public APIs
+
+Every public class and function exported from `selectools` now carries a stability marker:
+
+**`@stable`** (API frozen — breaking changes require a major version bump):
+`Role`, `Message`, `ToolCall`, `AgentResult`, `StepType`, `TraceStep`, `AgentTrace`, `Agent`, `AgentConfig`, `AgentObserver`, `AsyncAgentObserver`, `LoggingObserver`, `ConversationMemory`, `Tool`, `ToolParameter`, `ToolRegistry`, `tool`, `ToolPolicy`, `PolicyDecision`, `PolicyResult`, `OpenAIProvider`, `AnthropicProvider`, `GeminiProvider`, `OllamaProvider`, `FallbackProvider`, `TestCase`, `CaseResult`, `CaseVerdict`, `EvalSuite`, `EvalReport`, `AuditLogger`, `PrivacyLevel`, `CancellationToken`, `InMemoryCache`, `Cache`, `CacheKeyBuilder`, `CacheStats`, `SessionStore`, `JsonFileSessionStore`, `SQLiteSessionStore`, `KnowledgeMemory`, `KnowledgeEntry`, `KnowledgeStore`, `FileKnowledgeStore`, `SQLiteKnowledgeStore`, `Guardrail`, `GuardrailAction`, `GuardrailResult`, `GuardrailsPipeline`, `PIIGuardrail`, `ToxicityGuardrail`, `TopicGuardrail`, `FormatGuardrail`, `LengthGuardrail`, `TokenEstimate`, `estimate_tokens`, `estimate_run_tokens`, `AgentUsage`, `UsageStats`, `AgentAnalytics`, `Entity`, `EntityMemory`, `KnowledgeGraphMemory`
+
+**`@beta`** (API may change in a minor release):
+`trace_to_html`, `SimpleStepObserver`, `LocalProvider`, `RedisSessionStore`, `AgentGraph`, `SupervisorAgent`, `GraphState`, `MergePolicy`, `ContextMode`, `InterruptRequest`, `Scatter`, `CheckpointStore`, `InMemoryCheckpointStore`, `FileCheckpointStore`, `SQLiteCheckpointStore`, `PostgresCheckpointStore`, `Pipeline`, `Step`, `StepResult`, `step`, `parallel`, `branch`, `retry`, `cache_step`, `PlanAndExecuteAgent`, `ReflectiveAgent`, `DebateAgent`, `TeamLeadAgent`, `compose`
+
+Introspect programmatically:
+```python
+from selectools import Agent, AgentGraph
+print(Agent.__stability__)      # "stable"
+print(AgentGraph.__stability__) # "beta"
+```
+
+**Tests:** 3135 | **Examples:** 75 | **Models:** 152
+
 ## [0.19.2] - 2026-03-31
 
 ### Added

README.md

@@ -26,6 +26,22 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 
 ## What's New in v0.19
 
+### v0.19.3 — Stability Markers Applied to All Public APIs
+
+Every public class and function exported from `selectools` now carries a stability marker:
+
+```python
+from selectools import Agent, AgentGraph, PlanAndExecuteAgent
+
+print(Agent.__stability__)               # "stable"
+print(AgentGraph.__stability__)          # "beta"
+print(PlanAndExecuteAgent.__stability__) # "beta"
+```
+
+**`@stable`** — 60+ core symbols (Agent, AgentConfig, providers, memory, tools, evals, guardrails, sessions, knowledge, cache, cancellation)
+
+**`@beta`** — 30+ newer symbols (AgentGraph, SupervisorAgent, Pipeline, @step, parallel, branch, all four patterns, compose)
+
 ### v0.19.2 — Enterprise Hardening
 
 ```python

ROADMAP.md

@@ -55,6 +55,10 @@ Security audit → Stability markers (@stable/@beta/@deprecated) → Deprecation
 → Property-based tests (Hypothesis) → Concurrency smoke suite → 5 production simulations
 → 3135 tests, 75 examples
 
+v0.19.3 ✅ Stability Markers Applied to All Public APIs
+@stable on 60+ core symbols → @beta on 30+ orchestration/pipeline/patterns symbols
+→ Full stability introspection via .__stability__ on every exported class and function
+
 v0.20.0 🟡 Visual Agent Builder
 Zero-install web UI → Drag-drop graph builder → YAML/Python export → Live test execution
 
@@ -184,6 +188,29 @@ Focus: Production readiness and developer trust signals before the Visual Agent
 | **Production simulations** (5 new)    | ✅      | High   | Medium |
 
 
+---
+
+## v0.19.3: Stability Markers Applied ✅
+
+Focus: Apply `@stable` and `@beta` markers to every public symbol in the library, completing the stability annotation work started in v0.19.2.
+
+### Stable APIs (60+ symbols)
+
+Core types, providers, agent, memory, tools, evals, guardrails, sessions, knowledge, cache, cancellation, token estimation, analytics, audit — all marked `@stable`. Breaking changes to these require a major version bump.
+
+### Beta APIs (30+ symbols)
+
+Orchestration (`AgentGraph`, `SupervisorAgent`), pipelines (`Pipeline`, `@step`, `parallel`, `branch`), patterns (`PlanAndExecuteAgent`, `ReflectiveAgent`, `DebateAgent`, `TeamLeadAgent`), and composition (`compose`) — marked `@beta`. These may change in a minor release.
+
+### Introspection
+
+```python
+from selectools import Agent, AgentGraph, PlanAndExecuteAgent
+print(Agent.__stability__)              # "stable"
+print(AgentGraph.__stability__)         # "beta"
+print(PlanAndExecuteAgent.__stability__)  # "beta"
+```
+
 ---
 
 ## v0.20.0: Visual Agent Builder 🟡

docs/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to selectools will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.3] - 2026-03-31
+
+### Added
+
+#### Stability Markers Applied to All Public APIs
+
+Every public class and function exported from `selectools` now carries a stability marker:
+
+**`@stable`** (API frozen — breaking changes require a major version bump):
+`Role`, `Message`, `ToolCall`, `AgentResult`, `StepType`, `TraceStep`, `AgentTrace`, `Agent`, `AgentConfig`, `AgentObserver`, `AsyncAgentObserver`, `LoggingObserver`, `ConversationMemory`, `Tool`, `ToolParameter`, `ToolRegistry`, `tool`, `ToolPolicy`, `PolicyDecision`, `PolicyResult`, `OpenAIProvider`, `AnthropicProvider`, `GeminiProvider`, `OllamaProvider`, `FallbackProvider`, `TestCase`, `CaseResult`, `CaseVerdict`, `EvalSuite`, `EvalReport`, `AuditLogger`, `PrivacyLevel`, `CancellationToken`, `InMemoryCache`, `Cache`, `CacheKeyBuilder`, `CacheStats`, `SessionStore`, `JsonFileSessionStore`, `SQLiteSessionStore`, `KnowledgeMemory`, `KnowledgeEntry`, `KnowledgeStore`, `FileKnowledgeStore`, `SQLiteKnowledgeStore`, `Guardrail`, `GuardrailAction`, `GuardrailResult`, `GuardrailsPipeline`, `PIIGuardrail`, `ToxicityGuardrail`, `TopicGuardrail`, `FormatGuardrail`, `LengthGuardrail`, `TokenEstimate`, `estimate_tokens`, `estimate_run_tokens`, `AgentUsage`, `UsageStats`, `AgentAnalytics`, `Entity`, `EntityMemory`, `KnowledgeGraphMemory`
+
+**`@beta`** (API may change in a minor release):
+`trace_to_html`, `SimpleStepObserver`, `LocalProvider`, `RedisSessionStore`, `AgentGraph`, `SupervisorAgent`, `GraphState`, `MergePolicy`, `ContextMode`, `InterruptRequest`, `Scatter`, `CheckpointStore`, `InMemoryCheckpointStore`, `FileCheckpointStore`, `SQLiteCheckpointStore`, `PostgresCheckpointStore`, `Pipeline`, `Step`, `StepResult`, `step`, `parallel`, `branch`, `retry`, `cache_step`, `PlanAndExecuteAgent`, `ReflectiveAgent`, `DebateAgent`, `TeamLeadAgent`, `compose`
+
+Introspect programmatically:
+```python
+from selectools import Agent, AgentGraph
+print(Agent.__stability__)      # "stable"
+print(AgentGraph.__stability__) # "beta"
+```
+
+**Tests:** 3135 | **Examples:** 75 | **Models:** 152
+
 ## [0.19.2] - 2026-03-31
 
 ### Added

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.19.2"
+version = "0.19.3"
 description = "Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking."
 readme = "README.md"
 requires-python = ">=3.9"

src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.19.2"
+__version__ = "0.19.3"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, evals, guardrails, models, patterns, rag, toolbox

src/selectools/agent/config.py

@@ -7,6 +7,8 @@
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Coroutine, Dict, List, Optional, Union
 
+from ..stability import stable
+
 if TYPE_CHECKING:
     from ..cache import Cache
     from ..cancellation import CancellationToken
@@ -30,6 +32,7 @@
 ]
 
 
+@stable
 @dataclass
 class AgentConfig:
     """

src/selectools/agent/core.py

@@ -18,6 +18,7 @@
 from ..prompt import PromptBuilder
 from ..providers.base import Provider, ProviderError
 from ..providers.openai_provider import OpenAIProvider
+from ..stability import stable
 from ..structured import (
     ResponseFormat,
     build_schema_instruction,
@@ -57,6 +58,7 @@ class _RunContext:
     terminal_tool_result: Optional[str] = None
 
 
+@stable
 class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryManagerMixin):
     """
     Provider-agnostic AI agent that iteratively calls tools to accomplish tasks.

src/selectools/analytics.py

@@ -10,6 +10,8 @@
 from pathlib import Path
 from typing import Any, Dict
 
+from .stability import stable
+
 
 @dataclass
 class ToolMetrics:
@@ -81,6 +83,7 @@ def to_dict(self) -> dict:
         }
 
 
+@stable
 class AgentAnalytics:
     """
     Analytics tracker for agent tool usage.

src/selectools/audit.py

@@ -24,10 +24,12 @@
 from typing import Any, Dict, List, Optional
 
 from .observer import AgentObserver
+from .stability import stable
 from .types import AgentResult, Message
 from .usage import UsageStats
 
 
+@stable
 class PrivacyLevel(str, Enum):
     """Controls how tool arguments are recorded in audit logs."""
 
@@ -37,6 +39,7 @@ class PrivacyLevel(str, Enum):
     NONE = "none"
 
 
+@stable
 class AuditLogger(AgentObserver):
     """JSONL audit logger that implements the AgentObserver protocol.
 

src/selectools/cache.py

@@ -20,12 +20,14 @@
     from .tools.base import Tool
     from .types import Message
 
+from .stability import stable
 
 # ---------------------------------------------------------------------------
 # CacheStats
 # ---------------------------------------------------------------------------
 
 
+@stable
 @dataclass
 class CacheStats:
     """Tracks cache performance metrics."""
@@ -69,6 +71,7 @@ class _CacheEntry:
 # ---------------------------------------------------------------------------
 
 
+@stable
 @runtime_checkable
 class Cache(Protocol):
     """
@@ -109,6 +112,7 @@ def stats(self) -> CacheStats:
 # ---------------------------------------------------------------------------
 
 
+@stable
 class InMemoryCache:
     """
     Thread-safe in-memory LRU cache with per-entry TTL.
@@ -216,6 +220,7 @@ def __repr__(self) -> str:
 # ---------------------------------------------------------------------------
 
 
+@stable
 class CacheKeyBuilder:
     """
     Builds deterministic cache keys from LLM request parameters.

src/selectools/cancellation.py

@@ -10,8 +10,10 @@
 import threading
 
 from .exceptions import CancellationError
+from .stability import stable
 
 
+@stable
 class CancellationToken:
     """Thread-safe signal for cancelling an agent run.
 

src/selectools/compose.py

@@ -23,10 +23,12 @@ def extract(data: dict, field: str) -> str: ...
 
 from typing import Any, Callable, List, Optional, Sequence
 
+from .stability import beta
 from .tools.base import Tool
 from .tools.decorators import tool as tool_decorator
 
 
+@beta
 def compose(
     *tools_or_fns: Any,
     name: Optional[str] = None,

src/selectools/entity_memory.py

@@ -14,9 +14,11 @@
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
+from .stability import stable
 from .types import Message, Role
 
 
+@stable
 @dataclass
 class Entity:
     """A named entity extracted from conversation.
@@ -69,6 +71,7 @@ def from_dict(cls, data: Dict[str, Any]) -> "Entity":
 )
 
 
+@stable
 class EntityMemory:
     """Maintains a registry of entities mentioned in conversation.
 

src/selectools/evals/report.py

@@ -9,9 +9,11 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
+from ..stability import stable
 from .types import CaseResult, CaseVerdict, EvalMetadata
 
 
+@stable
 @dataclass
 class EvalReport:
     """Aggregated evaluation results with statistics."""

src/selectools/evals/suite.py

@@ -11,11 +11,13 @@
 
 from .. import __version__
 from ..agent import Agent
+from ..stability import stable
 from .evaluators import DEFAULT_EVALUATORS
 from .report import EvalReport
 from .types import CaseResult, CaseVerdict, EvalFailure, EvalMetadata, TestCase
 
 
+@stable
 class EvalSuite:
     """Evaluate an agent against a list of test cases.
 

src/selectools/evals/types.py

@@ -6,7 +6,10 @@
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional
 
+from selectools.stability import stable
 
+
+@stable
 class CaseVerdict(str, Enum):
     """Verdict for a single evaluated test case."""
 
@@ -16,6 +19,7 @@ class CaseVerdict(str, Enum):
     SKIP = "skip"
 
 
+@stable
 @dataclass
 class TestCase:
     """A single test case for agent evaluation.
@@ -125,6 +129,7 @@ class EvalFailure:
     message: str
 
 
+@stable
 @dataclass
 class CaseResult:
     """Result of evaluating a single TestCase."""

src/selectools/guardrails/base.py

@@ -12,7 +12,10 @@
 from enum import Enum
 from typing import Optional
 
+from selectools.stability import stable
 
+
+@stable
 class GuardrailAction(str, Enum):
     """Action to take when a guardrail check fails."""
 
@@ -21,6 +24,7 @@ class GuardrailAction(str, Enum):
     WARN = "warn"
 
 
+@stable
 @dataclass
 class GuardrailResult:
     """Result of a single guardrail check.
@@ -40,6 +44,7 @@ class GuardrailResult:
     guardrail_name: Optional[str] = None
 
 
+@stable
 class Guardrail:
     """Base class for all guardrails.
 

src/selectools/guardrails/format.py

@@ -10,9 +10,12 @@
 import json
 from typing import List, Optional
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailResult
 
 
+@stable
 class FormatGuardrail(Guardrail):
     """Validate that content matches expected format constraints.