Builder API Inventory¶

This page records the supported builder-facing imports and commands for SecondBrain. Import from these package facades rather than from internal modules unless a component maintainer explicitly asks for a lower-level integration. Stability classes and deprecation rules live in sdk-stability.md.

Supported Imports¶

`brain.patterns`¶

Core pattern imports:

from brain.patterns import (
    ReActAgent,
    PlanAndExecuteAgent,
    ReflexionAgent,
    MultiAgentOrchestrator,
    RAGAgent,
    StreamingReActAgent,
    HITLAgent,
)

Composition, async, tools, prompts, memory, tracing, and test helpers are also part of the facade:

from brain.patterns import (
    Agent,
    BasePattern,
    PatternResult,
    PatternChain,
    PatternRouter,
    ConversationMemory,
    ToolSpec,
    tool,
    tools_to_dict,
    tools_to_openai_schemas,
    PromptRegistry,
    registry,
    prompt,
    render,
    TracedPattern,
    trace_pattern,
    AsyncReActAgent,
    AsyncRAGAgent,
    AsyncPatternChain,
    run_concurrent,
    MockProvider,
    RecordingProvider,
    AgentHarness,
)

`brain.sdk`¶

The SDK facade is the stable programmatic entrypoint:

from brain.sdk import (
    SecondBrain,
    AgentDiscoveryClient,
    AgentListFilters,
    AgentRunPolicy,
    AgentRunRequest,
    AgentRunResult,
    SDKBuiltinAgentDefinition,
    SDKBuiltinAgentPrompt,
    SDKBuiltinAgentRegistryEntry,
    SDKBuiltinCatalogRegistryStatus,
    SDKAgentSummary,
    SDKAgentPromptPack,
    CognitiveClient,
    CognitiveConfig,
    CognitiveHealth,
    CognitiveLayerState,
    CognitiveLayerSummary,
    CognitiveRunRequest,
    CognitiveRunResult,
    CognitiveSnapshot,
    CognitiveStackState,
    CognitiveTrace,
    Snapshot,
    SnapshotFilters,
    SnapshotMetadata,
    SnapshotPayload,
    Trajectory,
    SBError,
    SBNotInitializedError,
    SBConnectionError,
    SBSchemaError,
    SBVersionError,
    __version__,
)

Trajectory is optional at runtime when the grounded subsystem is unavailable. The cognitive SDK classes are the experimental Antahkarana facade; use SecondBrain.cognitive(), SecondBrain.process_cognitive(...), SecondBrain.cognitive_health(), SecondBrain.cognitive_snapshot(...), and SecondBrain.cognitive_layers(), SecondBrain.cognitive_layer_state(...), SecondBrain.cognitive_stack_state(...), SecondBrain.cognitive_goals(), SecondBrain.cognitive_karma(), SecondBrain.cognitive_chitta(), SecondBrain.cognitive_identity(), SecondBrain.cognitive_functional_state(), and SecondBrain.cognitive_trace(...) instead of importing from brain.antahkarana directly when writing SDK integrations. Advanced local integrations that need stack dependencies can instantiate CognitiveClient.local(...) with SDK-facing CognitiveConfig, policy_catalog, decision_store, memory_store, and llm_provider; those are forwarded to the canonical Antahkarana stack builder while keeping the integration on the SDK facade. Supported layer IDs for cognitive_layer_state(...) are prana, indriya, dhyana, manas, ahamkara, sankalpa, buddhi, viveka, sabha, karma, chitta, atman, and bhava_monitor. AgentDiscoveryClient is the experimental read-only AgentBuilder discovery facade; use SecondBrain.agents(), SecondBrain.list_agents(...), SecondBrain.get_agent(...), SecondBrain.agent_prompts(...), SecondBrain.builtin_agent_catalog(...), SecondBrain.builtin_agent_definition(...), SecondBrain.builtin_agent_prompt(...), SecondBrain.builtin_agent_catalog_status(...), and SecondBrain.agent_run_policy(...) / SecondBrain.run_agent(...) instead of parsing registry CLI output or importing runtime internals in SDK integrations. SDK agent runs default to advisory/read-only agents.

SDK component coverage:

Component	SDK status	Facade
Snapshot/state summary	Stable	`brain.sdk.SecondBrain.snapshot()`
Memory, retrieval, context, ontology snapshot sections	Stable via snapshot payload	`brain.sdk.SnapshotPayload`
Grounded trajectories	Stable optional export	`brain.sdk.Trajectory`
Antahkarana cognitive stack and read-only layer state	Experimental	`brain.sdk.CognitiveClient`
Built-in catalog inspection, agent registry discovery, prompt reads, and advisory runs	Experimental read-only/default-guarded	`brain.sdk.AgentDiscoveryClient`
Agent SDK runner	Experimental	`brain.agent_sdk.SecondBrainRunner`
Agent manifest construction, registry writes, catalog seeding	Stable/experimental split	`brain.agent_builder`
Workflows, MCP, quality/autotune, governance, data agent, serve sessions	Not yet unified behind `brain.sdk`	Component CLIs and internal packages

Snapshot schema v2 is opt-in and adds the optional cognitive payload section:

from brain.sdk import SecondBrain

sb = SecondBrain.local()
result = sb.process_cognitive("What should I focus on today?")
cognitive_status = sb.cognitive_snapshot(trace_limit=10)
cognitive_layers = sb.cognitive_layers()
manas_state = sb.cognitive_layer_state("manas")
stack_state = sb.cognitive_stack_state(limit=5)
goals = sb.cognitive_goals()
karma = sb.cognitive_karma()
chitta = sb.cognitive_chitta()
identity = sb.cognitive_identity()
functional_state = sb.cognitive_functional_state()
snapshot = sb.snapshot(include=["cognitive"], schema_version="v2")
catalog_agents = sb.list_agents(tags=["capability-catalog"])
builtin_catalog = sb.builtin_agent_catalog(domains=["healthcare"])
builtin_prompt = sb.builtin_agent_prompt("planning")
catalog_status = sb.builtin_agent_catalog_status()
planning_prompts = sb.agent_prompts("planning")
planning_policy = sb.agent_run_policy("planning")
planning_result = sb.run_agent("planning", "Break this goal into a reviewable plan.")

`brain.agent_sdk`¶

The Agent SDK wrapper exposes the runner and preset config factories:

from brain.agent_sdk import (
    SecondBrainRunner,
    SecondBrainRunResult,
    readonly_config,
    research_config,
    coding_config,
)

`brain.capabilities`¶

Capability bundles are read-only manifests for publishing related agents, workflows, tools, prompt packs, protocol endpoints, middleware, and eval coverage as one reviewable unit.

from brain.capabilities import CapabilityBundle, validate_capability_bundle_file

sb capabilities validate checks schema shape, duplicate contribution IDs, declared quality targets, and eval coverage. Quality targets use <kind>:<contribution-id> refs such as agent:planner or workflow:briefing; release-gated bundles require those targets to be covered by at least one gate_required eval suite. Use --check-paths when the bundle should also prove referenced files exist under file://, repo://, or state:// roots.

`brain.runtime`¶

Runtime middleware hooks are observe-only extension points for tool calls and workflow steps. Hook failures are logged and do not replace tool outcomes or step results.

from brain.runtime import (
    RuntimeMiddleware,
    RuntimeMiddlewareManager,
    ToolMiddlewareContext,
    WorkflowStepMiddlewareContext,
)

`brain.agent_builder`¶

Agent-builder consumers should import models and services from the facade:

from brain.agent_builder import (
    AgentManifest,
    PromptPackManifest,
    MCPServerRef,
    AgentRef,
    A2AEnvelope,
    AgentCapabilityProfile,
    BuiltinAgentDefinition,
    iter_builtin_agent_definitions,
    get_builtin_agent_definition,
    build_builtin_agent_manifest,
    AgentRegistry,
    AgentRuntime,
    AgentScaffolder,
    AgentBuilderWizard,
    AgentBuilderAgent,
    AgentValidationError,
    AgentValidationIssue,
    AgentValidationResult,
    advisory_read_only_blocked_tools,
    validate_agent_registration,
    AutoAgentBuilder,
    AgentDemoRunner,
    PromptPack,
    load_prompt_pack,
    render_template,
    seed_builtin_agents,
)

Use validate_agent_registration() before writing generated agents when you need a structured error payload without performing the registry write. The registry and scaffold paths already call the same validator. Use advisory_read_only_blocked_tools() when an integration needs to explain which tools would violate the advisory/read-only policy before attempting a run.

PromptPackManifest path fields accept ordinary paths relative to <state_dir>/agents/<agent_id>/, plus file:// refs relative to that same agent directory, repo:// refs relative to the current repo root, and state:// refs relative to the configured state directory. Validation rejects unsupported schemes and .. escapes before registration.

The built-in advisory catalog exposes 30 deterministic template-runtime agent definitions through iter_builtin_agent_definitions(). These definitions seed as registry agents tagged capability-catalog and advisory-read-only; they retrieve, inspect, analyze, explain, and draft without mutating files, memory, tasks, connectors, or external systems.

Use the existing registry commands to expose the catalog:

sb agents registry-seed --force
sb agents registry-list --tag capability-catalog
sb agents registry-list --domain healthcare
sb agents registry-list --pattern rag --modality image
sb agents registry-list --safety-profile advisory_read_only
sb agents registry-info planning
sb agents registry-prompts planning

SDK integrations can read the same registry data without invoking the CLI:

from brain.sdk import SecondBrain

sb = SecondBrain.local()
agents = sb.list_agents(tags=["capability-catalog"], domains=["healthcare"])
builtin_definitions = sb.builtin_agent_catalog(patterns=["rag"])
builtin_planning = sb.builtin_agent_definition("planning")
builtin_prompt = sb.builtin_agent_prompt("planning")
catalog_status = sb.builtin_agent_catalog_status()
prompt_pack = sb.agent_prompts("planning")
policy = sb.agent_run_policy("planning")
result = sb.run_agent("planning", "Break down the integration work.")

Catalog agents are intentionally thin v1 profiles over the shared template_runtime:

#	Slug	Patterns	Tool policies	Modalities
1	`autonomous-decision-making`	plan-execute, reflexion	core	text
2	`planning`	plan-execute	core	text
3	`memory-augmented`	react, memory	core	text
4	`knowledge-retrieval`	rag	research	text
5	`document-intelligence`	rag, reflexion	document	text
6	`scientific-research`	rag, reflexion	research	text
7	`tool-using`	react	core	text
8	`agentic-workflow`	plan-execute, multi-agent	workflow	text
9	`data-analysis`	react, rag	data	text
10	`verification-validation`	reflexion	eval	text
11	`general-problem-solver`	router, plan-execute	core	text
12	`code-generation`	plan-execute, react	code	text
13	`security-hardened`	hitl, reflexion	code	text
14	`self-improving`	reflexion	eval	text
15	`conversational`	conversation, react	core	text
16	`content-creation`	plan-execute, reflexion	document	text
17	`recommendation`	rag, reflexion	research	text
18	`vision-language`	react, rag	perception	text, image
19	`audio-processing`	react, rag	perception	text, audio
20	`physical-world-sensing`	react, rag	perception	text, image, audio, sensor
21	`ethical-reasoning`	reflexion	core	text
22	`explainable`	reflexion	core	text
23	`healthcare-intelligence`	rag, reflexion	research	text
24	`scientific-discovery`	plan-execute, rag	research	text
25	`financial-advisory`	rag, reflexion	data + research	text
26	`legal-intelligence`	rag, reflexion	document + research	text
27	`education-intelligence`	plan-execute, rag	research	text
28	`collective-intelligence`	multi-agent	core	text
29	`embodied-intelligence`	plan-execute, perception	perception	text, image, audio, sensor
30	`domain-transforming-integration`	plan-execute, router	data + research	text

Supported Commands¶

sb sdk:

sb sdk run
sb sdk configs

sb agents:

sb agents instructions
sb agents registry-snapshot
sb agents list
sb agents build
sb agents build-adk
sb agents registry-list
sb agents registry-info
sb agents registry-prompts
sb agents registry-seed
sb agents registry-archive
sb agents registry-restore
sb agents registry-update
sb agents registry-export
sb agents registry-integrity

Internal Modules¶

Modules that are not re-exported through these facades are implementation details. Treat private modules and helpers such as _builtin_prompts, builder executor internals, SDK compatibility utilities, and low-level runtime modules as internal unless a plan or component maintainer promotes them into a facade.

When changing a public facade, update the compatibility test in tests/infra/test_agent_builder_public_api.py, update this page, and run:

pytest -q tests/infra/test_agent_builder_public_api.py

Builder API Inventory¶

Supported Imports¶

brain.patterns¶

brain.sdk¶

brain.agent_sdk¶

brain.capabilities¶

brain.runtime¶

brain.agent_builder¶