Skip to content

Antahkarana API

The Antahkarana package exposes the cognitive-loop primitives used by the CLI and chat runtime. Builder integrations should prefer the public SDK facade in brain.sdk; direct brain.antahkarana imports are implementation-level hooks for runtime code and focused tests.

SDK Entry Points

from brain.sdk import SecondBrain

sb = SecondBrain.local()
result = sb.process_cognitive("What should I focus on today?")

print(result.trace_id)
print(result.confidence)

Read-only inspection is available for the whole cognitive stack and each layer:

layers = sb.cognitive_layers()
manas = sb.cognitive_layer_state("manas")
stack = sb.cognitive_stack_state(limit=10)

goals = sb.cognitive_goals()
karma = sb.cognitive_karma()
chitta = sb.cognitive_chitta()
identity = sb.cognitive_identity()
functional_state = sb.cognitive_functional_state()

The SDK state surface is advisory/read-only. It lists, summarizes, and inspects state; it does not create goals, mutate memory, complete tasks, alter identity, start focus sessions, or change runtime energy modes.

Advanced local builder integrations can use CognitiveClient.local(...) when they need to wire optional Antahkarana stack dependencies:

from brain.sdk import CognitiveClient, CognitiveConfig

client = CognitiveClient.local(
    db_path="antahkarana.db",
    config=CognitiveConfig(),
    policy_catalog=policy_catalog,
    decision_store=decision_store,
    memory_store=memory_store,
    llm_provider=llm_provider,
)

Those dependencies are forwarded to the canonical stack builder. The SDK still exposes read-only inspection and bounded process(...); direct layer mutation remains an internal runtime concern.

HTTP Surface

When connected through sb serve, the same SDK calls use:

GET  /sdk/cognitive/health
GET  /sdk/cognitive/snapshot
GET  /sdk/cognitive/layers
GET  /sdk/cognitive/layers/{layer_id}
GET  /sdk/cognitive/state
GET  /sdk/cognitive/goals
GET  /sdk/cognitive/karma
GET  /sdk/cognitive/chitta
GET  /sdk/cognitive/identity
GET  /sdk/cognitive/functional-state
POST /sdk/cognitive/process
GET  /sdk/cognitive/traces/{trace_id}

Supported layer identifiers are prana, indriya, dhyana, manas, ahamkara, sankalpa, buddhi, viveka, sabha, karma, chitta, atman, and bhava_monitor.

Runtime Internals

Runtime code can still build and run the stack directly:

from brain.antahkarana.builder import build_stack
from brain.antahkarana.loop import CognitiveLoop

stack = build_stack("antahkarana.db")
loop = CognitiveLoop(stack)
result = loop.process({"query": "What should I focus on today?"})

CLI Bridge

sb antahkarana status
sb antahkarana process "What should I focus on today?"
sb antahkarana trace <trace_id>

Current Package Areas

  • builder.py for constructing the stack
  • loop.py for the cognitive-loop orchestration
  • stack.py for the core stack object
  • layer packages under brain/antahkarana/
  • brain.sdk.CognitiveClient for public local/HTTP integrations