selectools 0.19.2__tar.gz → 0.20.0__tar.gz

{selectools-0.19.2/src/selectools.egg-info → selectools-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.19.2
+Version: 0.20.0
 Summary: 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.
 Author-email: John Nichev <johnnichev@gmail.com>
 Maintainer-email: NichevLabs <support@nichevlabs.com>
@@ -84,8 +84,43 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.20
+
+### v0.20.0 — Visual Agent Builder
+
+The first AI agent framework to ship a visual graph builder in a single `pip install`. No React. No build step. No CDN.
+
+```bash
+pip install selectools
+selectools serve --builder
+# → open http://localhost:8000/builder
+```
+
+- Drag START, END, and Agent nodes onto the canvas
+- Click ports to connect agents with edges
+- Add condition labels to edges (e.g. `"approved"`) for conditional routing
+- Edit provider, model, and system prompt in the properties panel
+- Generated Python and YAML update live in the code panel
+- Export or copy to clipboard with one click
+
 ## 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

{selectools-0.19.2 → selectools-0.20.0}/README.md

@@ -24,8 +24,43 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.20
+
+### v0.20.0 — Visual Agent Builder
+
+The first AI agent framework to ship a visual graph builder in a single `pip install`. No React. No build step. No CDN.
+
+```bash
+pip install selectools
+selectools serve --builder
+# → open http://localhost:8000/builder
+```
+
+- Drag START, END, and Agent nodes onto the canvas
+- Click ports to connect agents with edges
+- Add condition labels to edges (e.g. `"approved"`) for conditional routing
+- Edit provider, model, and system prompt in the properties panel
+- Generated Python and YAML update live in the code panel
+- Export or copy to clipboard with one click
+
 ## 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

{selectools-0.19.2 → selectools-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.19.2"
+version = "0.20.0"
 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"

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/__init__.py

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

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/agent/config.py

@@ -7,6 +7,8 @@ from __future__ import annotations
 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 @@ ConfirmAction = Union[
 ]
 
 
+@stable
 @dataclass
 class AgentConfig:
     """

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/agent/core.py

@@ -18,6 +18,7 @@ from ..parser import ToolCallParser
 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.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/analytics.py

@@ -10,6 +10,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict
 
+from .stability import stable
+
 
 @dataclass
 class ToolMetrics:
@@ -81,6 +83,7 @@ class ToolMetrics:
         }
 
 
+@stable
 class AgentAnalytics:
     """
     Analytics tracker for agent tool usage.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/audit.py

@@ -24,10 +24,12 @@ from enum import Enum
 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.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/cache.py

@@ -20,12 +20,14 @@ if TYPE_CHECKING:
     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 @@ class Cache(Protocol):
 # ---------------------------------------------------------------------------
 
 
+@stable
 class InMemoryCache:
     """
     Thread-safe in-memory LRU cache with per-entry TTL.
@@ -216,6 +220,7 @@ class InMemoryCache:
 # ---------------------------------------------------------------------------
 
 
+@stable
 class CacheKeyBuilder:
     """
     Builds deterministic cache keys from LLM request parameters.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/cancellation.py

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

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/compose.py

@@ -23,10 +23,12 @@ from __future__ import annotations
 
 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,

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/entity_memory.py

@@ -14,9 +14,11 @@ import time
 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 @@ _EXTRACTION_PROMPT = (
 )
 
 
+@stable
 class EntityMemory:
     """Maintains a registry of entities mentioned in conversation.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/evals/report.py

@@ -9,9 +9,11 @@ from dataclasses import dataclass, field
 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."""

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/evals/suite.py

@@ -11,11 +11,13 @@ from typing import Any, Callable, Dict, List, Optional
 
 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.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/evals/types.py

@@ -6,7 +6,10 @@ from dataclasses import dataclass, field
 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."""

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/base.py

@@ -12,7 +12,10 @@ from dataclasses import dataclass
 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.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/format.py

@@ -10,9 +10,12 @@ from __future__ import annotations
 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.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/length.py

@@ -9,9 +9,12 @@ from __future__ import annotations
 import re
 from typing import Optional
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailResult
 
 
+@stable
 class LengthGuardrail(Guardrail):
     """Enforce content length constraints.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/pii.py

@@ -11,6 +11,8 @@ import re
 from dataclasses import dataclass
 from typing import Dict, List, Optional
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailResult
 
 _BUILTIN_PATTERNS: Dict[str, re.Pattern[str]] = {
@@ -34,6 +36,7 @@ class PIIMatch:
     end: int
 
 
+@stable
 class PIIGuardrail(Guardrail):
     """Detect (and optionally redact) PII in content.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/pipeline.py

@@ -12,11 +12,14 @@ import logging
 from dataclasses import dataclass, field
 from typing import List, Optional
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailError, GuardrailResult
 
 logger = logging.getLogger("selectools.guardrails")
 
 
+@stable
 @dataclass
 class GuardrailsPipeline:
     """Ordered pipeline of input and output guardrails.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/topic.py

@@ -11,9 +11,12 @@ import re
 import unicodedata
 from typing import List, Optional
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailResult
 
 
+@stable
 class TopicGuardrail(Guardrail):
     """Reject content that mentions denied topics.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/guardrails/toxicity.py

@@ -11,6 +11,8 @@ from __future__ import annotations
 import re
 from typing import List, Optional, Set
 
+from selectools.stability import stable
+
 from .base import Guardrail, GuardrailAction, GuardrailResult
 
 _DEFAULT_BLOCKLIST: Set[str] = {
@@ -33,6 +35,7 @@ _DEFAULT_BLOCKLIST: Set[str] = {
 }
 
 
+@stable
 class ToxicityGuardrail(Guardrail):
     """Block content that exceeds a toxicity threshold.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/knowledge.py

@@ -19,11 +19,14 @@ from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
 
+from .stability import stable
+
 # ======================================================================
 # KnowledgeEntry — structured entry for the new store-based API
 # ======================================================================
 
 
+@stable
 @dataclass
 class KnowledgeEntry:
     """A single piece of knowledge stored by the agent.
@@ -66,6 +69,7 @@ class KnowledgeEntry:
 # ======================================================================
 
 
+@stable
 @runtime_checkable
 class KnowledgeStore(Protocol):
     """Protocol for knowledge storage backends.
@@ -113,6 +117,7 @@ class KnowledgeStore(Protocol):
 # ======================================================================
 
 
+@stable
 class FileKnowledgeStore:
     """File-based knowledge store (backward-compatible with the original KnowledgeMemory).
 
@@ -279,6 +284,7 @@ class FileKnowledgeStore:
 # ======================================================================
 
 
+@stable
 class SQLiteKnowledgeStore:
     """SQLite-backed knowledge store for production single-process use.
 
@@ -442,6 +448,7 @@ class SQLiteKnowledgeStore:
 # ======================================================================
 
 
+@stable
 class KnowledgeMemory:
     """Maintains cross-session knowledge with daily logs and persistent facts.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/knowledge_graph.py

@@ -14,6 +14,7 @@ import time
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
 
+from .stability import stable
 from .types import Message, Role
 
 
@@ -301,6 +302,7 @@ _EXTRACTION_PROMPT = (
 )
 
 
+@stable
 class KnowledgeGraphMemory:
     """Maintains a knowledge graph of relationship triples from conversation.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/memory.py

@@ -8,9 +8,11 @@ import copy
 from dataclasses import replace
 from typing import Any, Dict, List, Optional
 
+from .stability import stable
 from .types import Message, Role
 
 
+@stable
 class ConversationMemory:
     """
     Maintains conversation history with configurable limits.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/observer.py

@@ -35,10 +35,12 @@ import logging
 import time
 from typing import Any, Callable, Dict, List, Optional
 
+from .stability import beta, stable
 from .types import AgentResult, Message
 from .usage import UsageStats
 
 
+@stable
 class AgentObserver:
     """Base class for agent lifecycle observers.
 
@@ -602,6 +604,7 @@ class AgentObserver:
 # ======================================================================
 
 
+@stable
 class LoggingObserver(AgentObserver):
     """Observer that writes structured JSON events to Python's logging module.
 
@@ -1021,6 +1024,7 @@ class LoggingObserver(AgentObserver):
         )
 
 
+@stable
 class AsyncAgentObserver(AgentObserver):
     """Base class for async agent lifecycle observers.
 
@@ -1420,6 +1424,7 @@ class AsyncAgentObserver(AgentObserver):
 # ======================================================================
 
 
+@beta
 class SimpleStepObserver(AgentObserver):
     """Observer that routes all lifecycle events to a single callback.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/orchestration/checkpoint.py

@@ -32,6 +32,7 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Dict, List, Optional, Protocol, Tuple, runtime_checkable
 
+from ..stability import beta
 from .state import GraphState
 
 
@@ -56,6 +57,7 @@ class CheckpointMetadata:
     created_at: datetime
 
 
+@beta
 @runtime_checkable
 class CheckpointStore(Protocol):
     """Protocol for checkpoint backends.
@@ -117,6 +119,7 @@ def _deserialize_checkpoint(data: Dict) -> Tuple[GraphState, int]:
 # ------------------------------------------------------------------
 
 
+@beta
 class InMemoryCheckpointStore:
     """Thread-safe in-memory checkpoint store.
 
@@ -172,6 +175,7 @@ class InMemoryCheckpointStore:
 # ------------------------------------------------------------------
 
 
+@beta
 class FileCheckpointStore:
     """File-based checkpoint store.
 
@@ -290,6 +294,7 @@ CREATE INDEX IF NOT EXISTS idx_checkpoints_graph_id ON checkpoints (graph_id);
 """
 
 
+@beta
 class SQLiteCheckpointStore:
     """SQLite-backed checkpoint store with WAL mode for concurrent access.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/orchestration/graph.py

@@ -37,6 +37,7 @@ from typing import (
 )
 
 from ..exceptions import GraphExecutionError
+from ..stability import beta
 from ..trace import AgentTrace, StepType, TraceStep
 from ..types import AgentResult, Message, Role
 from ..usage import UsageStats
@@ -164,6 +165,7 @@ def _merge_usage(base: UsageStats, added: Any) -> UsageStats:
     )
 
 
+@beta
 class AgentGraph:
     """Directed graph of agent nodes with routing, parallelism, and HITL support.
 

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/orchestration/state.py

@@ -17,10 +17,12 @@ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple
 if TYPE_CHECKING:
     from ..types import AgentResult, Message
 
+from ..stability import beta
 
 STATE_KEY_LAST_OUTPUT: str = "__last_output__"
 
 
+@beta
 class MergePolicy(str, Enum):
     """Policy for merging parallel branch states.
 
@@ -34,6 +36,7 @@ class MergePolicy(str, Enum):
     APPEND = "append"
 
 
+@beta
 class ContextMode(str, Enum):
     """Controls what conversation history is forwarded to a node's agent.
 
@@ -51,6 +54,7 @@ class ContextMode(str, Enum):
     CUSTOM = "custom"
 
 
+@beta
 @dataclass
 class GraphState:
     """Shared context passed between nodes in an AgentGraph.
@@ -153,6 +157,7 @@ class GraphState:
         return cls(messages=[Message(role=Role.USER, content=prompt)])
 
 
+@beta
 @dataclass
 class InterruptRequest:
     """Yielded from generator nodes to pause execution for human input.
@@ -173,6 +178,7 @@ class InterruptRequest:
     interrupt_key: str = ""
 
 
+@beta
 @dataclass
 class Scatter:
     """Returned from routing functions to create dynamic parallel branches.

{selectools-0.19.2 → selectools-0.20.0}/src/selectools/orchestration/supervisor.py

@@ -45,6 +45,7 @@ if TYPE_CHECKING:
     from ..types import AgentResult
     from .checkpoint import CheckpointStore
 
+from ..stability import beta
 from ..types import Message, Role
 from ..usage import UsageStats
 from .graph import AgentGraph, ErrorPolicy, GraphResult, _merge_usage
@@ -168,6 +169,7 @@ def _safe_json_parse(text: str, default: Any = None) -> Any:
     return default
 
 
+@beta
 class SupervisorAgent:
     """High-level multi-agent coordinator.