> ## Documentation Index > Fetch the complete documentation index at: https://docs.sxth.ai/llms.txt > Use this file to discover all available pages before exploring further. # Python API > Python SDK reference for sxth-mind # Python API Complete reference for the sxth-mind Python SDK. ## Mind The central abstraction. ```python theme={null} from sxth_mind import Mind mind = Mind( adapter=MyAdapter(), # Required provider=MyProvider(), # Optional storage=MyStorage(), # Optional ) ``` ### Methods #### chat() ```python theme={null} async def chat( user_id: str, message: str, project_id: str | None = None, ) -> str ``` Send a message and get a response. State is managed automatically. #### chat\_stream() ```python theme={null} async def chat_stream( user_id: str, message: str, project_id: str | None = None, ) -> AsyncIterator[str] ``` Stream a response token by token. #### get\_state() ```python theme={null} async def get_state( user_id: str, project_id: str | None = None, ) -> dict ``` Get cognitive state as a dictionary. #### explain\_state() ```python theme={null} async def explain_state( user_id: str, project_id: str | None = None, ) -> str ``` Get a human-readable state summary. #### get\_pending\_nudges() ```python theme={null} async def get_pending_nudges(user_id: str) -> list[Nudge] ``` Get pending nudges for a user. *** ## BaseAdapter Abstract base class for domain adapters. ```python theme={null} from sxth_mind import BaseAdapter class MyAdapter(BaseAdapter): ... ``` ### Required Methods ```python theme={null} @property def name(self) -> str: """Unique identifier.""" def get_identity_types(self) -> list[dict]: """Define user archetypes.""" def get_journey_stages(self) -> list[dict]: """Define progression stages.""" def detect_journey_stage(self, project_mind: ProjectMind) -> str: """Determine current stage.""" def get_nudge_templates(self) -> dict: """Define nudge templates.""" def get_insight_types(self) -> list[dict]: """Define insight types.""" ``` ### Optional Methods ```python theme={null} @property def display_name(self) -> str: """Human-readable name.""" def get_system_prompt( self, user_mind: UserMind, project_mind: ProjectMind, ) -> str: """Build context-aware system prompt.""" def get_context_for_prompt( self, user_mind: UserMind, project_mind: ProjectMind, ) -> dict: """Additional context for prompts.""" def update_after_interaction( self, user_mind: UserMind, project_mind: ProjectMind, message: str, response: str, ) -> None: """Custom state updates after interaction.""" ``` *** ## Schemas ### UserMind ```python theme={null} from sxth_mind.schemas import UserMind class UserMind: id: str user_id: str # Identity identity_type: str | None identity_data: dict # Patterns patterns: dict preferences: dict # Engagement total_interactions: int trust_score: float # 0.0 to 1.0 # Communication preferred_tone: str response_style: str # Nudges nudge_frequency: str muted_topics: list[str] # Timestamps created_at: datetime updated_at: datetime ``` ### ProjectMind ```python theme={null} from sxth_mind.schemas import ProjectMind class ProjectMind: id: str user_mind_id: str project_id: str # Journey journey_stage: str | None momentum_score: float # 0.0 to 1.0 days_since_activity: int # Metrics interaction_count: int trust_score: float # Custom data context_data: dict progress_data: dict # Derived conversation views (owned belief state, not raw bytes) conversation_summary: str | None topics: list[str] # Timestamps created_at: datetime updated_at: datetime ``` ### Event Raw evidence read from an [`EvidenceSource`](#evidencesource) — the rented substrate. Not part of the belief state. ```python theme={null} from sxth_mind.schemas import Event class Event: id: str user_id: str project_id: str | None kind: str # "message" | "action" | "signal" | ... role: str | None # for messages: user | assistant | system | tool content: str timestamp: datetime metadata: dict ``` ### Nudge ```python theme={null} from sxth_mind.schemas import Nudge class Nudge: id: str nudge_type: str title: str message: str priority: int # 1-10 status: str # pending, delivered, dismissed, acted project_mind_id: str scheduled_for: datetime | None delivered_at: datetime | None acted_at: datetime | None ``` *** ## Storage ### BaseStorage ```python theme={null} from sxth_mind.storage import BaseStorage class MyStorage(BaseStorage): async def initialize(self) -> None: ... async def close(self) -> None: ... # UserMind async def get_user_mind(self, user_id: str) -> UserMind | None: ... async def save_user_mind(self, user_mind: UserMind) -> None: ... async def delete_user_mind(self, user_id: str) -> None: ... # ProjectMind async def get_project_mind(self, user_id: str, project_id: str) -> ProjectMind | None: ... async def save_project_mind(self, project_mind: ProjectMind) -> None: ... async def get_project_minds_for_user(self, user_id: str) -> list[ProjectMind]: ... async def delete_project_mind(self, user_id: str, project_id: str) -> None: ... # Nudges async def get_pending_nudges(self, user_id: str) -> list[Nudge]: ... async def save_nudge(self, nudge: Nudge) -> None: ... async def update_nudge_status(self, nudge_id: str, status: str) -> bool: ... ``` `BaseStorage` persists the belief state only. Raw history is handled by the [`EvidenceSource`](#evidencesource), not storage. ### MemoryStorage ```python theme={null} from sxth_mind.storage import MemoryStorage storage = MemoryStorage() ``` ### SQLiteStorage ```python theme={null} from sxth_mind.storage import SQLiteStorage storage = SQLiteStorage("mind.db") await storage.initialize() ``` *** ## Evidence The rented raw substrate — messages, actions, signals — that sxth-mind reads but does not own. Pass one via `Mind(evidence=...)`. ### EvidenceSource ```python theme={null} from sxth_mind import EvidenceSource from sxth_mind.schemas import Event class MyEvidenceSource(EvidenceSource): async def recent( self, user_id: str, project_id: str | None = None, limit: int = 10 ) -> list[Event]: ... async def search( self, user_id: str, query: str, project_id: str | None = None, limit: int = 10 ) -> list[Event]: ... # Optional. Default is a no-op — override only if you want sxth-mind to # capture raw turns itself (the app often already logs its own events). async def append(self, event: Event) -> None: ... ``` Back it with your own database, a memory vendor (Mem0, Zep), or the bundled `LocalEvidenceSource`: ```python theme={null} from sxth_mind import Mind, LocalEvidenceSource mind = Mind(adapter=SalesAdapter(), evidence=LocalEvidenceSource()) # default ``` *** ## Providers ### BaseLLMProvider ```python theme={null} from sxth_mind.providers import BaseLLMProvider, LLMResponse, Message class MyProvider(BaseLLMProvider): @property def default_model(self) -> str: ... async def chat( self, messages: list[Message], model: str | None = None, tools: list[dict] | None = None, temperature: float = 0.7, max_tokens: int | None = None, ) -> LLMResponse: ... async def chat_stream( self, messages: list[Message], **kwargs, ) -> AsyncIterator[str]: ... ``` ### OpenAIProvider ```python theme={null} from sxth_mind.providers.openai import OpenAIProvider provider = OpenAIProvider( api_key="sk-...", organization="org-...", base_url="https://...", default_model="gpt-4o-mini", ) ``` *** ## Nudge Engine ```python theme={null} from sxth_mind.engine import BaselineNudgeEngine engine = BaselineNudgeEngine(adapter, storage) nudges = await engine.check_and_generate("user_123", project_id="proj_1") ```