SDK Stability

Current as of 2026-05-04.

This page defines the compatibility contract for SecondBrain's builder-facing Python APIs. Import from the package facades listed here instead of importing from implementation modules directly.

Stability Classes

Class	Meaning	Change rule
Stable	Public facade symbols intended for external or local builder use.	Removals, renames, required parameter changes, and incompatible return-shape changes need a deprecation note before the breaking change lands.
Experimental	Public facade symbols that are useful today but may still change while the repo is pre-1.0.	Additive changes are allowed. Breaking changes still need an explicit deprecation note and migration path when practical.
Internal	Implementation modules, private helpers, storage layout, generated files, and direct table contracts.	No compatibility promise. Prefer a public facade or documented command instead.

Public Facade Matrix

Facade	Stable APIs	Experimental APIs	Internal or unsupported imports
brain.sdk	SecondBrain, Snapshot, SnapshotFilters, SnapshotMetadata, SnapshotPayload, SBError, SBNotInitializedError, SBConnectionError, SBSchemaError, SBVersionError, __version__. Trajectory is a stable optional export when the grounded subsystem is installed.	CognitiveClient, CognitiveConfig, CognitiveRunRequest, CognitiveRunResult, CognitiveHealth, CognitiveTrace, CognitiveSnapshot, CognitiveLayerSummary, CognitiveLayerState, and CognitiveStackState are experimental Antahkarana SDK facades, including additive local stack dependency injection through CognitiveClient.local(...) with policy_catalog, decision_store, memory_store, and llm_provider. AgentDiscoveryClient, AgentListFilters, SDKBuiltinAgentDefinition, SDKBuiltinAgentPrompt, SDKBuiltinAgentRegistryEntry, SDKBuiltinCatalogRegistryStatus, SDKAgentSummary, SDKAgentPromptPack, AgentRunPolicy, AgentRunRequest, and AgentRunResult are experimental read-only/default-guarded AgentBuilder catalog, discovery, and invocation facades. Snapshot schema v2 is opt-in and experimental; schema v1 remains the default stable snapshot contract.	Direct imports from brain.sdk.client, brain.sdk.snapshot, brain.sdk.agents, brain.sdk.cognitive, brain.sdk.compat, and brain.sdk.utils are implementation details unless promoted through brain.sdk.
brain.patterns	Core pattern classes, base result types, prompt registry helpers, tool schema helpers, memory, composition, HITL, streaming event types, async pattern classes, and deterministic testing utilities exported through brain.patterns.__all__.	Tracing backend span attributes from TracedPattern and trace_pattern may evolve with observability backends.	Direct imports from individual pattern modules are unsupported for compatibility purposes unless the same symbol is also exported through brain.patterns. Benchmark internals are not API.
brain.agent_sdk	None currently.	SecondBrainRunner, SecondBrainRunResult, readonly_config, research_config, and coding_config are public but experimental because this wrapper follows external agent-SDK behavior and session semantics.	Direct imports from brain.agent_sdk.runner and brain.agent_sdk.configs are implementation details.
brain.capabilities	None currently.	CapabilityBundle, contribution models, path resolution, bundle validation, quality coverage summaries, and read-only inventory helpers are experimental composition contracts for agents, workflows, tools, prompts, middleware, and eval suites.	Direct imports from brain.capabilities.loader, brain.capabilities.models, brain.capabilities.paths, and registry adapter internals are unsupported unless exported through the facade.
brain.runtime	None currently.	RuntimeMiddleware, RuntimeMiddlewareManager, ToolMiddlewareContext, and WorkflowStepMiddlewareContext are observe-only experimental hooks for tool-call and workflow-step telemetry.	Runtime service factories, quota internals, workspace backends, trigger internals, and direct middleware implementation details are unsupported unless exported through the facade and documented here.
brain.agent_builder	Manifest and reference models, advisory catalog definition helpers, AgentRegistry CRUD/discovery methods, prompt-pack loading/rendering, and validation/read-only policy helper types/functions exported through the facade.	AgentRuntime, scaffold/wizard orchestration, AutoAgentBuilder, AgentDemoRunner, and built-in seeding are public but may still receive workflow and payload refinements.	_builtin_prompts, executor internals, direct SQLite table layout, generated prompt files, and non-facade modules are internal.

Command Stability

Command family	Stability
sb sdk run, sb sdk configs	Stable command names. Output fields should be additive or explicitly deprecated before incompatible changes.
sb agents registry-list, registry-info, registry-prompts, registry-seed, registry-archive, registry-restore, registry-update, registry-export, registry-integrity	Stable command names for the AgentBuilder registry. Machine-readable JSON output should be additive or explicitly deprecated before incompatible changes.
sb agents build, sb agents build --auto, sb agents build-adk	Experimental builder workflows. Generated manifests are validated before registration, but prompts, scaffolds, and bundle layout may evolve.

Deprecation Workflow

Before changing a stable public symbol, required parameter, command name, or machine-readable output shape:

1. Add the deprecation to the Current Deprecations table below.
2. Update docs/reference/builder-apis.md when facade imports or command names change.
3. Add a DeprecationWarning on the old Python code path when the old path can still run.
4. Keep a compatibility alias for at least one minor release when practical.
5. Update the compatibility tests and golden files deliberately in the same diff.

For experimental APIs, prefer the same workflow for removals and renames. Purely additive changes do not need deprecation.

Internal APIs do not receive deprecation windows. Move an internal symbol into a facade first if callers need a compatibility promise.

Current Deprecations

None.

Verification

Run these checks when changing a public facade or this stability policy:

pytest -q tests/infra/test_agent_builder_public_api.py tests/infra/test_sdk_import.py tests/infra/test_sdk_stability_docs.py
pytest -q tests -k "sdk"
make docs

CI runs a narrow SDK catalog/package source smoke guardrail on Python 3.12 and 3.13 in parallel with the full quality job. The tag publish workflow runs the same slice as Release SDK catalog/package source smoke on both supported Python minors before building and publishing artifacts:

pytest -q -n 0 \
  tests/infra/test_sdk_import.py \
  tests/infra/test_builtin_agent_catalog.py \
  tests/infra/test_sdk_agents.py \
  tests/infra/test_package_data.py \
  tests/infra/test_sdk_stability_docs.py

Keep that slice offline-safe. It is intended to catch accidental regressions in the public SDK facade, built-in AgentBuilder catalog, packaged runtime assets, and this stability reference without making the main CI path materially slower.

The CI guardrail and publish workflow also build the source distribution and wheel, then run SDK catalog/package artifact smoke / Release SDK catalog/package artifact smoke with SB_PACKAGE_ARTIFACTS_DIR=dist on Python 3.12 and 3.13. That opt-in mode proves the shipped artifacts include the 30 catalog prompts, migrations, static UI assets, CLI schema, snapshot schemas, registry contracts, and zip-importable runtime resources while still skipping artifact inspection during ordinary local unit-test runs.