API Reference¶

from simplecontext import SimpleContext

# From config file
sc = SimpleContext("config.yaml")

# With inline overrides
sc = SimpleContext(
    "config.yaml",
    storage__backend="sqlite",
    storage__path="./my.db",
    agents__folder="./agents",
    debug__retrieval=True,
)

# No config (in-memory, for testing)
sc = SimpleContext()

with SimpleContext("config.yaml") as sc:
    ctx = sc.chat(user_id, message)
    # ...
# sc.close() called automatically

ctx = sc.chat(user_id, message, agent_id=None, history_limit=None)

# ctx.messages      → list[dict] ready for LLM
# ctx.agent_id      → str — routed agent name
# ctx.personality_level → str — "default" | "beginner" | "expert"

reply = your_llm(ctx.messages)
reply = ctx.save(reply)   # stores to memory, fires hooks, returns processed reply

ctx = sc.context(user_id)   # → TieredMemory

ctx.working.add(content, NodeKind.MESSAGE)
ctx.episodic.add(content, NodeKind.SUMMARY)
ctx.semantic.add(content, NodeKind.FACT, importance=0.8)

ctx.stats()           # → {"working": 5, "episodic": 1, "semantic": 12}
ctx.prune()           # remove expired + deleted nodes
ctx.get_all_active()  # → list[ContextNode]

mem = sc.memory(user_id)

# Messages
mem.add_user("message")
mem.add_assistant("reply")
mem.get_for_llm(limit=10)   # → list[dict]
mem.count()                  # → int
mem.clear()                  # clears messages, keeps profile

# Profile (persistent facts)
mem.remember("key", "value")
mem.recall("key")            # → "value" or None
mem.get_profile()            # → dict of all profile keys
mem.forget("key")            # removes a profile key

# Compression
mem.compress(keep_last=10)

result = sc.router.route(user_id, message)
# result.agent_id           → str
# result.system_prompt      → str
# result.personality_level  → str
# result.should_chain(msg)  → dict | None

# Force agent
sc.router.set_user_agent(user_id, "coding")
sc.router.clear_user_agent(user_id)

# Chain
result2 = sc.router.chain(user_id, message, reply, chain_rule, from_agent_id="coding")

messages = sc.prepare_messages(user_id, message, route_result)
# → list[dict] with system prompt + history + current message

reply = sc.process_response(user_id, message, reply, route_result)
# Fires after_llm hooks, stores to memory, returns processed reply

skills = sc.skills(agent_id)

skills.add("skill_name", content, priority=10, group="output", tags=["code"])
skills.get("skill_name")      # → str content
skills.delete("skill_name")
skills.list()                 # → list[dict]
skills.build_prompt()         # → str — full system prompt

# Register manually
sc.use(MyPlugin(config={"enabled": True, "option": "value"}))

# Get plugin instance
plugin = sc._plugins.get("my_plugin")

# List all loaded plugins
sc._plugins.all()   # → list[BasePlugin]

# Get all app_commands across plugins
sc._plugins.get_all_app_commands()   # → dict

# Fire a plugin command
from simplecontext.plugins.base import AppCommandContext
ctx = AppCommandContext.create("semantic", user_id, ["python", "error"], platform="telegram")
result = await sc._plugins.fire_app_command(ctx)

# Plan
plan = sc.planner.plan(message, user_id, profile, agent_id)

# Retrieve
nodes = sc.engine.retrieve(plan)

# Stats
stats = sc.engine.get_stats(plan)
# → {"candidates": 37, "active": 28, "selected": 11, "total_chars": 3200}

# Build messages
messages = sc.builder.build(system_prompt, nodes, message, history, profile)

# Debug
sc.enable_debug(True)
sc.engine.invalidate_cache(user_id)

# Export
sc.export().export_user(user_id)       # → dict
sc.export().export_all()               # → dict
sc.snapshot(user_id, label="v1")       # → dict with versioning

# Import
sc.export().import_data(data)

# Snapshots
snapshots = sc.list_snapshots(user_id)
sc.restore_snapshot("path/to/snapshot.json", merge=False)

# Importance decay (call periodically)
sc.apply_decay(user_id)   # single user
sc.apply_decay()          # all users

# Smart compression
compressed = sc.smart_compress(user_id, strategy="semantic", keep_last=5)

# Feedback for adaptive scoring
sc.feedback(user_id, selected_nodes=nodes, score=+1.0)

# Stats
sc.stats()              # → full stats dict
sc.list_users()         # → list[str]
sc.list_agents()        # → list[str]

# Agents
sc.reload_agents()                # hot-reload YAML files
sc.register_agent(agent_def)      # register AgentDef programmatically

from simplecontext.enums import Tier, NodeKind, NodeStatus, Intent

Tier.WORKING    # "working"
Tier.EPISODIC   # "episodic"
Tier.SEMANTIC   # "semantic"

NodeKind.MESSAGE     # "message"
NodeKind.FACT        # "fact"
NodeKind.SUMMARY     # "summary"
NodeKind.RESOURCE    # "resource"
NodeKind.TASK_STATE  # "task_state"
NodeKind.SKILL       # "skill"

NodeStatus.ACTIVE     # "active"
NodeStatus.SUPERSEDED # "superseded"
NodeStatus.EXPIRED    # "expired"
NodeStatus.DELETED    # "deleted"

Intent.CONVERSATION  # "conversation"
Intent.PERSONAL      # "personal"
Intent.CODING        # "coding"
Intent.KNOWLEDGE     # "knowledge"
Intent.TASK          # "task"