# talk_box

Build production AI assistants with battle-tested personas, structured conversations, and built-in quality assurance


# Installation

``` bash
pip install talk-box
```


# API overview


## Getting Started

Core classes for building AI assistants

- [ChatBot](reference/ChatBot.html#talk_box.ChatBot): Main entry point for building and managing conversational AI chatbots with integrated
- [Conversation](reference/Conversation.html#talk_box.Conversation): Manages sequences of messages in conversational AI interactions, primarily returned by ChatBot methods
- [Message](reference/Message.html#talk_box.Message): Represents a single message in a conversational AI interaction, discovered through Conversation objects


## ChatBot Methods

Configuration and interaction methods for the ChatBot class

- [ChatBot.model](reference/ChatBot.model.html#talk_box.ChatBot.model)
- [ChatBot.provider_model](reference/ChatBot.provider_model.html#talk_box.ChatBot.provider_model)
- [ChatBot.preset](reference/ChatBot.preset.html#talk_box.ChatBot.preset)
- [ChatBot.temperature](reference/ChatBot.temperature.html#talk_box.ChatBot.temperature)
- [ChatBot.max_tokens](reference/ChatBot.max_tokens.html#talk_box.ChatBot.max_tokens)
- [ChatBot.persona](reference/ChatBot.persona.html#talk_box.ChatBot.persona)
- [ChatBot.system_prompt](reference/ChatBot.system_prompt.html#talk_box.ChatBot.system_prompt)
- [ChatBot.get_system_prompt](reference/ChatBot.get_system_prompt.html#talk_box.ChatBot.get_system_prompt)
- [ChatBot.avoid](reference/ChatBot.avoid.html#talk_box.ChatBot.avoid)
- [ChatBot.get_avoid_topics](reference/ChatBot.get_avoid_topics.html#talk_box.ChatBot.get_avoid_topics)
- [ChatBot.tools](reference/ChatBot.tools.html#talk_box.ChatBot.tools)
- [ChatBot.add_tools](reference/ChatBot.add_tools.html#talk_box.ChatBot.add_tools)
- [ChatBot.verbose](reference/ChatBot.verbose.html#talk_box.ChatBot.verbose)
- [ChatBot.chat](reference/ChatBot.chat.html#talk_box.ChatBot.chat)
- [ChatBot.start_conversation](reference/ChatBot.start_conversation.html#talk_box.ChatBot.start_conversation)
- [ChatBot.continue_conversation](reference/ChatBot.continue_conversation.html#talk_box.ChatBot.continue_conversation)
- [ChatBot.show](reference/ChatBot.show.html#talk_box.ChatBot.show)
- [ChatBot.get_config_summary](reference/ChatBot.get_config_summary.html#talk_box.ChatBot.get_config_summary)
- [ChatBot.get_config](reference/ChatBot.get_config.html#talk_box.ChatBot.get_config)
- [ChatBot.prompt_builder](reference/ChatBot.prompt_builder.html#talk_box.ChatBot.prompt_builder)
- [ChatBot.structured_prompt](reference/ChatBot.structured_prompt.html#talk_box.ChatBot.structured_prompt)
- [ChatBot.chain_prompts](reference/ChatBot.chain_prompts.html#talk_box.ChatBot.chain_prompts)
- [ChatBot.check_llm_status](reference/ChatBot.check_llm_status.html#talk_box.ChatBot.check_llm_status)
- [ChatBot.quick_start](reference/ChatBot.quick_start.html#talk_box.ChatBot.quick_start)
- [ChatBot.create_chat_session](reference/ChatBot.create_chat_session.html#talk_box.ChatBot.create_chat_session)


## Prompt Engineering

Attention-optimized prompt construction

- [PromptBuilder](reference/PromptBuilder.html#talk_box.PromptBuilder): Builds structured prompts using attention mechanisms and cognitive principles
- [PromptBuilder.persona](reference/PromptBuilder.persona.html#talk_box.PromptBuilder.persona)
- [PromptBuilder.task_context](reference/PromptBuilder.task_context.html#talk_box.PromptBuilder.task_context)
- [PromptBuilder.focus_on](reference/PromptBuilder.focus_on.html#talk_box.PromptBuilder.focus_on)
- [PromptBuilder.critical_constraint](reference/PromptBuilder.critical_constraint.html#talk_box.PromptBuilder.critical_constraint)
- [PromptBuilder.constraint](reference/PromptBuilder.constraint.html#talk_box.PromptBuilder.constraint)
- [PromptBuilder.core_analysis](reference/PromptBuilder.core_analysis.html#talk_box.PromptBuilder.core_analysis)
- [PromptBuilder.structured_section](reference/PromptBuilder.structured_section.html#talk_box.PromptBuilder.structured_section)
- [PromptBuilder.avoid_topics](reference/PromptBuilder.avoid_topics.html#talk_box.PromptBuilder.avoid_topics)
- [PromptBuilder.output_format](reference/PromptBuilder.output_format.html#talk_box.PromptBuilder.output_format)
- [PromptBuilder.example](reference/PromptBuilder.example.html#talk_box.PromptBuilder.example)
- [PromptBuilder.final_emphasis](reference/PromptBuilder.final_emphasis.html#talk_box.PromptBuilder.final_emphasis)
- [PromptBuilder.vocabulary](reference/PromptBuilder.vocabulary.html#talk_box.PromptBuilder.vocabulary)
- [PromptBuilder.pathways](reference/PromptBuilder.pathways.html#talk_box.PromptBuilder.pathways)
- [PromptBuilder.print](reference/PromptBuilder.print.html#talk_box.PromptBuilder.print)
- [Priority](reference/Priority.html#talk_box.Priority): Control where a prompt section is placed relative to other sections
- [PromptSection](reference/PromptSection.html#talk_box.PromptSection): Represents a structured section of an attention-optimized prompt with priority and ordering
- [VocabularyTerm](reference/VocabularyTerm.html#talk_box.VocabularyTerm): Define domain-specific terminology with multilingual support for consistent AI understanding
- [architectural_analysis_prompt](reference/architectural_analysis_prompt.html#talk_box.architectural_analysis_prompt): Create a pre-configured [PromptBuilder](reference/PromptBuilder.html#talk_box.PromptBuilder) for architectural analysis
- [code_review_prompt](reference/code_review_prompt.html#talk_box.code_review_prompt): Create a pre-configured [PromptBuilder](reference/PromptBuilder.html#talk_box.PromptBuilder) for code review
- [debugging_prompt](reference/debugging_prompt.html#talk_box.debugging_prompt): Create a pre-configured [PromptBuilder](reference/PromptBuilder.html#talk_box.PromptBuilder) for debugging


## Conversation Pathways

State-machine conversation flows with branching and fallbacks

- [Pathways](reference/Pathways.html#talk_box.Pathways): Chainable builder for defining structured conversational pathways
- [Pathways.state](reference/Pathways.state.html#talk_box.Pathways.state)
- [Pathways.required](reference/Pathways.required.html#talk_box.Pathways.required)
- [Pathways.optional](reference/Pathways.optional.html#talk_box.Pathways.optional)
- [Pathways.tools](reference/Pathways.tools.html#talk_box.Pathways.tools)
- [Pathways.success_condition](reference/Pathways.success_condition.html#talk_box.Pathways.success_condition)
- [Pathways.next_state](reference/Pathways.next_state.html#talk_box.Pathways.next_state)
- [Pathways.branch_on](reference/Pathways.branch_on.html#talk_box.Pathways.branch_on)
- [Pathways.fallback](reference/Pathways.fallback.html#talk_box.Pathways.fallback)
- [Pathways.agent](reference/Pathways.agent.html#talk_box.Pathways.agent)
- [Pathways.register_agent](reference/Pathways.register_agent.html#talk_box.Pathways.register_agent)
- [Pathways.get_agent](reference/Pathways.get_agent.html#talk_box.Pathways.get_agent)
- [Pathways.visualize](reference/Pathways.visualize.html#talk_box.Pathways.visualize)


## Conversation Methods

Methods for managing conversation history

- [Conversation.add_message](reference/Conversation.add_message.html#talk_box.Conversation.add_message)
- [Conversation.add_user_message](reference/Conversation.add_user_message.html#talk_box.Conversation.add_user_message)
- [Conversation.add_assistant_message](reference/Conversation.add_assistant_message.html#talk_box.Conversation.add_assistant_message)
- [Conversation.add_system_message](reference/Conversation.add_system_message.html#talk_box.Conversation.add_system_message)
- [Conversation.get_messages](reference/Conversation.get_messages.html#talk_box.Conversation.get_messages)
- [Conversation.get_last_message](reference/Conversation.get_last_message.html#talk_box.Conversation.get_last_message)
- [Conversation.clear_messages](reference/Conversation.clear_messages.html#talk_box.Conversation.clear_messages)
- [Conversation.set_context_window](reference/Conversation.set_context_window.html#talk_box.Conversation.set_context_window)
- [Conversation.get_context_messages](reference/Conversation.get_context_messages.html#talk_box.Conversation.get_context_messages)
- [Conversation.get_message_count](reference/Conversation.get_message_count.html#talk_box.Conversation.get_message_count)
- [Conversation.to_dict](reference/Conversation.to_dict.html#talk_box.Conversation.to_dict)
- [Conversation.from_dict](reference/Conversation.from_dict.html#talk_box.Conversation.from_dict)


## File Attachments

Multi-modal file handling for conversations

- [Attachments](reference/Attachments.html#talk_box.Attachments): File attachment handler for Talk Box conversations
- [Attachments.with_prompt](reference/Attachments.with_prompt.html#talk_box.Attachments.with_prompt)
- [Attachments.to_chat_contents](reference/Attachments.to_chat_contents.html#talk_box.Attachments.to_chat_contents)
- [Attachments.get_metadata](reference/Attachments.get_metadata.html#talk_box.Attachments.get_metadata)
- [Attachments.summary](reference/Attachments.summary.html#talk_box.Attachments.summary)
- [AttachmentMetadata](reference/AttachmentMetadata.html#talk_box.AttachmentMetadata): Metadata for individual file attachments


## Tools

Tool registration, execution, and built-in utilities

- [tool](reference/tool.html#talk_box.tool): Register a function as a Talk Box tool
- [ToolCategory](reference/ToolCategory.html#talk_box.ToolCategory): Categorize tools by their primary function
- [ToolContext](reference/ToolContext.html#talk_box.ToolContext): Provide runtime context to every tool execution
- [ToolResult](reference/ToolResult.html#talk_box.ToolResult): Represent the outcome of a tool execution
- [get_global_registry](reference/get_global_registry.html#talk_box.get_global_registry): Return the process-wide `ToolRegistry` singleton
- [load_tool_box](reference/load_tool_box.html#talk_box.load_tool_box): Register all built-in Tool Box tools in the global registry
- [get_builtin_tool](reference/get_builtin_tool.html#talk_box.get_builtin_tool): Get a specific built-in tool by name
- [load_selected_tools](reference/load_selected_tools.html#talk_box.load_selected_tools): Register a subset of the built-in Tool Box tools


## Testing & Validation

Automated testing for chatbot quality assurance

- [autotest_avoid_topics](reference/autotest_avoid_topics.html#talk_box.autotest_avoid_topics): Comprehensive avoid topics testing with automated violation detection
- [autotest_pathways](reference/autotest_pathways.html#talk_box.autotest_pathways): Automated testing for pathway adherence in chatbots
- [TestResults](reference/TestResults.html#talk_box.TestResults): Enhanced test results container with rich reporting and analysis capabilities
- [TestResults.to_dataframe](reference/TestResults.to_dataframe.html#talk_box.TestResults.to_dataframe)
- [TestResults.to_great_table](reference/TestResults.to_great_table.html#talk_box.TestResults.to_great_table)
- [PathwayTestResults](reference/PathwayTestResults.html#talk_box.PathwayTestResults): Aggregate and summarize the outcomes of a [autotest_pathways()](reference/autotest_pathways.html#talk_box.autotest_pathways) run
- [ToolEnabledConversation](reference/ToolEnabledConversation.html#talk_box.ToolEnabledConversation): Extend [Conversation](reference/Conversation.html#talk_box.Conversation) with automatic tool invocation support
- [create_tool_conversation](reference/create_tool_conversation.html#talk_box.create_tool_conversation): Create a [ToolEnabledConversation](reference/ToolEnabledConversation.html#talk_box.ToolEnabledConversation) with default settings


## Guardrails

Composable input/output validation for chatbot messages

- [Guard](reference/Guard.html#talk_box.Guard): A configured guardrail ready to be attached to a ChatBot
- [Guard.check](reference/Guard.check.html#talk_box.Guard.check)
- [GuardAction](reference/GuardAction.html#talk_box.GuardAction): The outcome of a guard check
- [GuardPhase](reference/GuardPhase.html#talk_box.GuardPhase): When the guard runs in the message lifecycle
- [GuardResult](reference/GuardResult.html#talk_box.GuardResult): The result of evaluating a guardrail against a message
- [GuardPipeline](reference/GuardPipeline.html#talk_box.GuardPipeline): Ordered pipeline of guards that processes messages sequentially
- [GuardPipeline.add](reference/GuardPipeline.add.html#talk_box.GuardPipeline.add)
- [GuardPipeline.run](reference/GuardPipeline.run.html#talk_box.GuardPipeline.run)
- [GuardPipelineResult](reference/GuardPipelineResult.html#talk_box.GuardPipelineResult): Result of running a message through the full guard pipeline
- [guardrail](reference/guardrail.html#talk_box.guardrail): Decorator that turns a function into a composable guardrail
- [ChatBot.guardrail](reference/ChatBot.guardrail.html#talk_box.ChatBot.guardrail)
- [ChatBot.guard_stats](reference/ChatBot.guard_stats.html#talk_box.ChatBot.guard_stats)
- [no_pii](reference/no_pii.html#talk_box.no_pii): Guard that detects and handles Personally Identifiable Information
- [max_response_length](reference/max_response_length.html#talk_box.max_response_length): Guard that enforces a maximum response length
- [max_input_length](reference/max_input_length.html#talk_box.max_input_length): Guard that rejects user messages exceeding a character limit
- [tone_check](reference/tone_check.html#talk_box.tone_check): Guard that flags responses not matching the expected tone
- [disclaimer_required](reference/disclaimer_required.html#talk_box.disclaimer_required): Guard that ensures a required disclaimer appears in the response
- [must_cite_sources](reference/must_cite_sources.html#talk_box.must_cite_sources): Guard that requires responses to contain source citations
- [keyword_block](reference/keyword_block.html#talk_box.keyword_block): Guard that blocks messages containing any of the specified keywords


## Evaluation

Prompt evaluation, scoring, and regression detection

- [eval.HAS_PANDAS](reference/eval.HAS_PANDAS.html#talk_box.eval.HAS_PANDAS)
- [eval.HAS_GREAT_TABLES](reference/eval.HAS_GREAT_TABLES.html#talk_box.eval.HAS_GREAT_TABLES)
- [eval.DEFAULT_DIMENSIONS](reference/eval.DEFAULT_DIMENSIONS.html#talk_box.eval.DEFAULT_DIMENSIONS)
- [eval.ScorerFn](reference/eval.ScorerFn.html#talk_box.eval.ScorerFn)
- [eval_regression](reference/eval_regression.html#talk_box.eval_regression): Compare two bot versions and flag regressions
- [eval_model_update](reference/eval_model_update.html#talk_box.eval_model_update): Compare persona behavior across two model versions
- [eval_suite](reference/eval_suite.html#talk_box.eval_suite): Evaluate a persona across multiple models (model comparison matrix)
- [EvalCase](reference/EvalCase.html#talk_box.EvalCase): A single evaluation test case
- [EvalDimension](reference/EvalDimension.html#talk_box.EvalDimension): Scoring dimensions for evaluation
- [EvalResults](reference/EvalResults.html#talk_box.EvalResults): Collection of evaluation results with reporting capabilities
- [EvalResults.summary](reference/EvalResults.summary.html#talk_box.EvalResults.summary)
- [EvalResults.passed](reference/EvalResults.passed.html#talk_box.EvalResults.passed)
- [EvalResults.regressions](reference/EvalResults.regressions.html#talk_box.EvalResults.regressions)
- [EvalResults.scores_by_variant](reference/EvalResults.scores_by_variant.html#talk_box.EvalResults.scores_by_variant)
- [EvalResults.to_dataframe](reference/EvalResults.to_dataframe.html#talk_box.EvalResults.to_dataframe)
- [EvalResults.to_great_table](reference/EvalResults.to_great_table.html#talk_box.EvalResults.to_great_table)
- [EvalResults.to_scorecard](reference/EvalResults.to_scorecard.html#talk_box.EvalResults.to_scorecard)
- [EvalResult](reference/EvalResult.html#talk_box.EvalResult): Results for a single query evaluated against a single bot variant
- [EvalScore](reference/EvalScore.html#talk_box.EvalScore): A score on a single dimension for a single response
- [scorecard_table](reference/scorecard_table.html#talk_box.scorecard_table): Render a scorecard as a polished Great Table
- [sweep_table](reference/sweep_table.html#talk_box.sweep_table): Render an eval sweep summary as a polished Great Table


## Model Profiles

Model capability registry for routing, eval, and prompt optimization.

- [ModelProfile](reference/ModelProfile.html#talk_box.ModelProfile): Capability profile for a specific LLM model
- [ModelProfile.key](reference/ModelProfile.key.html#talk_box.ModelProfile.key)
- [ModelProfile.name](reference/ModelProfile.name.html#talk_box.ModelProfile.name)
- [ModelProfile.supports](reference/ModelProfile.supports.html#talk_box.ModelProfile.supports)
- [CostTier](reference/CostTier.html#talk_box.CostTier): Relative cost tier for a model
- [get_model_profile](reference/get_model_profile.html#talk_box.get_model_profile): Look up a model's capability profile
- [list_models](reference/list_models.html#talk_box.list_models): List known model profiles, optionally filtered
- [register_model](reference/register_model.html#talk_box.register_model): Register a custom model profile
- [model_profiles_table](reference/model_profiles_table.html#talk_box.model_profiles_table): Render all known model profiles as a Great Table


## Ollama Detection

Auto-detect local Ollama instances and register available models.

- [OllamaStatus](reference/OllamaStatus.html#talk_box.OllamaStatus): Status of the local Ollama instance
- [detect_ollama](reference/detect_ollama.html#talk_box.detect_ollama): Detect whether a local Ollama instance is running
- [list_ollama_models](reference/list_ollama_models.html#talk_box.list_ollama_models): Query Ollama for available models and return their profiles
- [sync_ollama_models](reference/sync_ollama_models.html#talk_box.sync_ollama_models): Detect Ollama models and register them in the profile registry


## Context Window Management

Token-aware fitting of prompts and messages within model context limits.

- [ContextWindow](reference/ContextWindow.html#talk_box.ContextWindow): Manages fitting content into a model's token budget
- [ContextWindow.fit_messages](reference/ContextWindow.fit_messages.html#talk_box.ContextWindow.fit_messages)
- [ContextWindow.fit_prompt](reference/ContextWindow.fit_prompt.html#talk_box.ContextWindow.fit_prompt)
- [ContextWindow.count_tokens](reference/ContextWindow.count_tokens.html#talk_box.ContextWindow.count_tokens)
- [ContextWindow.fits](reference/ContextWindow.fits.html#talk_box.ContextWindow.fits)
- [ContextWindow.overflow](reference/ContextWindow.overflow.html#talk_box.ContextWindow.overflow)
- [FitResult](reference/FitResult.html#talk_box.FitResult): Result of fitting content into a context window budget
- [PromptFitResult](reference/PromptFitResult.html#talk_box.PromptFitResult): Result of fitting a PromptBuilder output into a token budget
- [FitStrategy](reference/FitStrategy.html#talk_box.FitStrategy): Strategy for fitting content into a token budget
- [estimate_tokens](reference/estimate_tokens.html#talk_box.estimate_tokens): Estimate the token count for a string using a character-based heuristic


## Prompt Optimization

Reduce prompt token usage without losing semantic meaning.

- [optimize_prompt](reference/optimize_prompt.html#talk_box.optimize_prompt): Optimize a prompt for reduced token usage
- [OptimizationLevel](reference/OptimizationLevel.html#talk_box.OptimizationLevel): How aggressively to compress prompts
- [OptimizeResult](reference/OptimizeResult.html#talk_box.OptimizeResult): Result of prompt optimization


## Hybrid Routing

Route tasks between local and cloud models based on complexity and cost.

- [route](reference/route.html#talk_box.route): Route a task to the best available model
- [classify_complexity](reference/classify_complexity.html#talk_box.classify_complexity): Estimate the complexity of a task from its prompt text
- [Router](reference/Router.html#talk_box.Router): Configurable model router for hybrid local/cloud routing
- [Router.route](reference/Router.route.html#talk_box.Router.route)
- [RoutingStrategy](reference/RoutingStrategy.html#talk_box.RoutingStrategy): Strategy that governs how the router selects models
- [RoutingResult](reference/RoutingResult.html#talk_box.RoutingResult): Result of routing a task to a model
- [TaskComplexity](reference/TaskComplexity.html#talk_box.TaskComplexity): Estimated complexity of a task or prompt


## Consensus Mode

Query multiple models, compare outputs, and resolve disagreements.

- [consensus](reference/consensus.html#talk_box.consensus): Determine consensus across multiple model responses
- [find_disagreements](reference/find_disagreements.html#talk_box.find_disagreements): Detect disagreements between model responses
- [ConsensusStrategy](reference/ConsensusStrategy.html#talk_box.ConsensusStrategy): Strategy for resolving consensus across multiple model responses
- [ConsensusResult](reference/ConsensusResult.html#talk_box.ConsensusResult): Result of running consensus across multiple model responses
- [ModelResponse](reference/ModelResponse.html#talk_box.ModelResponse): A single model's response to a prompt
- [Disagreement](reference/Disagreement.html#talk_box.Disagreement): A detected disagreement between model responses


## Cascade Consensus

Start with one model, fan out to additional models when confidence is low.

- [cascade.Responder](reference/cascade.Responder.html#talk_box.cascade.Responder)
- [estimate_confidence](reference/estimate_confidence.html#talk_box.estimate_confidence): Estimate confidence in a model response based on textual signals
- [CascadeResult](reference/CascadeResult.html#talk_box.CascadeResult): Result of a cascade consensus execution
- [CascadeRound](reference/CascadeRound.html#talk_box.CascadeRound): Record of a single round in a cascade execution


## Memory Tiers

Working, short-term, and long-term memory for conversations.

- [MemoryStore](reference/MemoryStore.html#talk_box.MemoryStore): Unified memory interface across all three tiers
- [MemoryStore.remember](reference/MemoryStore.remember.html#talk_box.MemoryStore.remember)
- [MemoryStore.recall](reference/MemoryStore.recall.html#talk_box.MemoryStore.recall)
- [MemoryStore.forget](reference/MemoryStore.forget.html#talk_box.MemoryStore.forget)
- [MemoryStore.search](reference/MemoryStore.search.html#talk_box.MemoryStore.search)
- [WorkingMemory](reference/WorkingMemory.html#talk_box.WorkingMemory): In-conversation key-value memory, lost when the conversation ends
- [ShortTermMemory](reference/ShortTermMemory.html#talk_box.ShortTermMemory): Recent session memory with TTL and max-entry eviction
- [LongTermMemory](reference/LongTermMemory.html#talk_box.LongTermMemory): Persistent memory backed by SQLite
- [MemoryEntry](reference/MemoryEntry.html#talk_box.MemoryEntry): A single memory entry across any tier
- [MemoryTier](reference/MemoryTier.html#talk_box.MemoryTier): Which memory tier an entry belongs to


## WorkingMemory Methods

Methods for the WorkingMemory class

- [WorkingMemory.set](reference/WorkingMemory.set.html#talk_box.WorkingMemory.set)
- [WorkingMemory.get](reference/WorkingMemory.get.html#talk_box.WorkingMemory.get)
- [WorkingMemory.has](reference/WorkingMemory.has.html#talk_box.WorkingMemory.has)
- [WorkingMemory.delete](reference/WorkingMemory.delete.html#talk_box.WorkingMemory.delete)
- [WorkingMemory.keys](reference/WorkingMemory.keys.html#talk_box.WorkingMemory.keys)
- [WorkingMemory.entries](reference/WorkingMemory.entries.html#talk_box.WorkingMemory.entries)
- [WorkingMemory.search](reference/WorkingMemory.search.html#talk_box.WorkingMemory.search)
- [WorkingMemory.clear](reference/WorkingMemory.clear.html#talk_box.WorkingMemory.clear)
- [WorkingMemory.__len__](reference/WorkingMemory.__len__.html#talk_box.WorkingMemory.__len__)


## ShortTermMemory Methods

Methods for the ShortTermMemory class

- [ShortTermMemory.set](reference/ShortTermMemory.set.html#talk_box.ShortTermMemory.set)
- [ShortTermMemory.get](reference/ShortTermMemory.get.html#talk_box.ShortTermMemory.get)
- [ShortTermMemory.has](reference/ShortTermMemory.has.html#talk_box.ShortTermMemory.has)
- [ShortTermMemory.delete](reference/ShortTermMemory.delete.html#talk_box.ShortTermMemory.delete)
- [ShortTermMemory.keys](reference/ShortTermMemory.keys.html#talk_box.ShortTermMemory.keys)
- [ShortTermMemory.entries](reference/ShortTermMemory.entries.html#talk_box.ShortTermMemory.entries)
- [ShortTermMemory.search](reference/ShortTermMemory.search.html#talk_box.ShortTermMemory.search)
- [ShortTermMemory.clear](reference/ShortTermMemory.clear.html#talk_box.ShortTermMemory.clear)
- [ShortTermMemory.__len__](reference/ShortTermMemory.__len__.html#talk_box.ShortTermMemory.__len__)


## LongTermMemory Methods

Methods for the LongTermMemory class

- [LongTermMemory.set](reference/LongTermMemory.set.html#talk_box.LongTermMemory.set)
- [LongTermMemory.get](reference/LongTermMemory.get.html#talk_box.LongTermMemory.get)
- [LongTermMemory.has](reference/LongTermMemory.has.html#talk_box.LongTermMemory.has)
- [LongTermMemory.delete](reference/LongTermMemory.delete.html#talk_box.LongTermMemory.delete)
- [LongTermMemory.keys](reference/LongTermMemory.keys.html#talk_box.LongTermMemory.keys)
- [LongTermMemory.entries](reference/LongTermMemory.entries.html#talk_box.LongTermMemory.entries)
- [LongTermMemory.search](reference/LongTermMemory.search.html#talk_box.LongTermMemory.search)
- [LongTermMemory.clear](reference/LongTermMemory.clear.html#talk_box.LongTermMemory.clear)
- [LongTermMemory.close](reference/LongTermMemory.close.html#talk_box.LongTermMemory.close)
- [LongTermMemory.__len__](reference/LongTermMemory.__len__.html#talk_box.LongTermMemory.__len__)


## Agent

Self-contained AI agent bundling persona, memory, tools, and conversation history.

- [Agent](reference/Agent.html#talk_box.Agent): A self-contained AI agent bundling persona, memory, and conversation history
- [Agent.from_persona](reference/Agent.from_persona.html#talk_box.Agent.from_persona)
- [Agent.respond](reference/Agent.respond.html#talk_box.Agent.respond)
- [Agent.remember](reference/Agent.remember.html#talk_box.Agent.remember)
- [Agent.recall](reference/Agent.recall.html#talk_box.Agent.recall)
- [Agent.retention](reference/Agent.retention.html#talk_box.Agent.retention)
- [Agent.conversation](reference/Agent.conversation.html#talk_box.Agent.conversation)
- [Agent.reset_conversation](reference/Agent.reset_conversation.html#talk_box.Agent.reset_conversation)


## Agent Methods

Methods for the Agent class

- [Agent.__post_init__](reference/Agent.__post_init__.html#talk_box.Agent.__post_init__)
- [Agent.from_persona](reference/Agent.from_persona.html#talk_box.Agent.from_persona)
- [Agent.respond](reference/Agent.respond.html#talk_box.Agent.respond)
- [Agent.remember](reference/Agent.remember.html#talk_box.Agent.remember)
- [Agent.recall](reference/Agent.recall.html#talk_box.Agent.recall)
- [Agent.reset_conversation](reference/Agent.reset_conversation.html#talk_box.Agent.reset_conversation)


## Human-in-the-Loop

Pause agent workflows for human review, approval, or revision.

- [human_review](reference/human_review.html#talk_box.human_review): Create a human-in-the-loop review request
- [approve](reference/approve.html#talk_box.approve): Approve a pending review
- [reject](reference/reject.html#talk_box.reject): Reject a pending review
- [revise](reference/revise.html#talk_box.revise): Revise the content and approve the review
- [HumanReview](reference/HumanReview.html#talk_box.HumanReview): A request for human review before proceeding
- [HumanReview.status](reference/HumanReview.status.html#talk_box.HumanReview.status)
- [HumanReview.decision](reference/HumanReview.decision.html#talk_box.HumanReview.decision)
- [HumanReview.is_pending](reference/HumanReview.is_pending.html#talk_box.HumanReview.is_pending)
- [HumanReview.is_resolved](reference/HumanReview.is_resolved.html#talk_box.HumanReview.is_resolved)
- [HumanReview.is_approved](reference/HumanReview.is_approved.html#talk_box.HumanReview.is_approved)
- [HumanReview.final_content](reference/HumanReview.final_content.html#talk_box.HumanReview.final_content)
- [ReviewDecision](reference/ReviewDecision.html#talk_box.ReviewDecision): A human's decision on a review request
- [ReviewStatus](reference/ReviewStatus.html#talk_box.ReviewStatus): Status of a human-in-the-loop review
- [ReviewQueue](reference/ReviewQueue.html#talk_box.ReviewQueue): Collects and tracks multiple review requests


## ReviewQueue Methods

Methods for the ReviewQueue class

- [ReviewQueue.add](reference/ReviewQueue.add.html#talk_box.ReviewQueue.add)
- [ReviewQueue.pending](reference/ReviewQueue.pending.html#talk_box.ReviewQueue.pending)
- [ReviewQueue.resolved](reference/ReviewQueue.resolved.html#talk_box.ReviewQueue.resolved)
- [ReviewQueue.by_agent](reference/ReviewQueue.by_agent.html#talk_box.ReviewQueue.by_agent)
- [ReviewQueue.by_status](reference/ReviewQueue.by_status.html#talk_box.ReviewQueue.by_status)
- [ReviewQueue.__len__](reference/ReviewQueue.__len__.html#talk_box.ReviewQueue.__len__)


## Skill System

Loadable capability packs for agents.

- [SkillDefinition](reference/SkillDefinition.html#talk_box.SkillDefinition): A loadable skill pack that adds capabilities to an agent
- [create_skill](reference/create_skill.html#talk_box.create_skill): Create a skill definition programmatically
- [get_skill](reference/get_skill.html#talk_box.get_skill): Get a skill definition by name
- [list_skills](reference/list_skills.html#talk_box.list_skills): List all available skill names
- [register_skill](reference/register_skill.html#talk_box.register_skill): Register a skill definition in the global registry
- [load_skill](reference/load_skill.html#talk_box.load_skill): Load a skill from an arbitrary YAML file
- [skill_categories](reference/skill_categories.html#talk_box.skill_categories): Get all skills grouped by category


## Structured Outputs

Extract typed data from LLM responses using Pydantic models.

- [ExtractResult](reference/ExtractResult.html#talk_box.ExtractResult): Result of extracting structured data from an LLM response
- [extract](reference/extract.html#talk_box.extract): Extract structured data from an LLM response
- [schema_to_dict](reference/schema_to_dict.html#talk_box.schema_to_dict): Convert a Pydantic model class to a JSON Schema dictionary


## Persona Traits

Composable modifiers that add constraints, expertise, and tools to any persona.

- [TraitDefinition](reference/TraitDefinition.html#talk_box.TraitDefinition): A composable modifier that can be applied to any persona
- [apply_trait](reference/apply_trait.html#talk_box.apply_trait): Apply a trait to a persona, returning a new modified persona
- [create_trait](reference/create_trait.html#talk_box.create_trait): Create a trait definition programmatically
- [get_trait](reference/get_trait.html#talk_box.get_trait): Get a registered trait by name
- [list_traits](reference/list_traits.html#talk_box.list_traits): List all available trait names
- [register_trait](reference/register_trait.html#talk_box.register_trait): Register a trait so it can be retrieved with [get_trait()](reference/get_trait.html#talk_box.get_trait)
- [load_trait](reference/load_trait.html#talk_box.load_trait): Load a trait from an arbitrary YAML file path
- [trait_categories](reference/trait_categories.html#talk_box.trait_categories): Get all traits grouped by category


## MCP Bridge

Bidirectional bridge between Talk Box tools and the Model Context Protocol.

- [MCPToolInfo](reference/MCPToolInfo.html#talk_box.MCPToolInfo): Description of an MCP tool discovered from a remote server
- [MCPBridgeServer](reference/MCPBridgeServer.html#talk_box.MCPBridgeServer): An MCP server that exposes Talk Box tools over the MCP protocol
- [MCPBridgeServer.tool_names](reference/MCPBridgeServer.tool_names.html#talk_box.MCPBridgeServer.tool_names)
- [MCPBridgeServer.build](reference/MCPBridgeServer.build.html#talk_box.MCPBridgeServer.build)
- [MCPBridgeServer.run](reference/MCPBridgeServer.run.html#talk_box.MCPBridgeServer.run)
- [tools_to_mcp_server](reference/tools_to_mcp_server.html#talk_box.tools_to_mcp_server): Create an [MCPBridgeServer](reference/MCPBridgeServer.html#talk_box.MCPBridgeServer) from a list of Talk Box tools
- [mcp_tool_to_talk_box](reference/mcp_tool_to_talk_box.html#talk_box.mcp_tool_to_talk_box): Convert an [MCPToolInfo](reference/MCPToolInfo.html#talk_box.MCPToolInfo) into a `TalkBoxTool`
- [list_mcp_tools](reference/list_mcp_tools.html#talk_box.list_mcp_tools): Convert raw MCP tool dicts into [MCPToolInfo](reference/MCPToolInfo.html#talk_box.MCPToolInfo) objects
- [discover_mcp_tools](reference/discover_mcp_tools.html#talk_box.discover_mcp_tools): Discover tools from a live MCP client session


## Knowledge Graph

SQLite-backed knowledge graph with nodes, edges, traversal, search, and embedding support.

- [KnowledgeGraph](reference/KnowledgeGraph.html#talk_box.KnowledgeGraph): SQLite-backed knowledge graph with nodes, edges, and optional embeddings
- [KnowledgeGraph.add_node](reference/KnowledgeGraph.add_node.html#talk_box.KnowledgeGraph.add_node)
- [KnowledgeGraph.get_node](reference/KnowledgeGraph.get_node.html#talk_box.KnowledgeGraph.get_node)
- [KnowledgeGraph.delete_node](reference/KnowledgeGraph.delete_node.html#talk_box.KnowledgeGraph.delete_node)
- [KnowledgeGraph.list_nodes](reference/KnowledgeGraph.list_nodes.html#talk_box.KnowledgeGraph.list_nodes)
- [KnowledgeGraph.node_count](reference/KnowledgeGraph.node_count.html#talk_box.KnowledgeGraph.node_count)
- [KnowledgeGraph.add_edge](reference/KnowledgeGraph.add_edge.html#talk_box.KnowledgeGraph.add_edge)
- [KnowledgeGraph.get_edges](reference/KnowledgeGraph.get_edges.html#talk_box.KnowledgeGraph.get_edges)
- [KnowledgeGraph.delete_edge](reference/KnowledgeGraph.delete_edge.html#talk_box.KnowledgeGraph.delete_edge)
- [KnowledgeGraph.edge_count](reference/KnowledgeGraph.edge_count.html#talk_box.KnowledgeGraph.edge_count)
- [KnowledgeGraph.neighbors](reference/KnowledgeGraph.neighbors.html#talk_box.KnowledgeGraph.neighbors)
- [KnowledgeGraph.search](reference/KnowledgeGraph.search.html#talk_box.KnowledgeGraph.search)
- [KnowledgeGraph.stats](reference/KnowledgeGraph.stats.html#talk_box.KnowledgeGraph.stats)
- [KnowledgeGraph.health](reference/KnowledgeGraph.health.html#talk_box.KnowledgeGraph.health)
- [KnowledgeGraph.pending_questions](reference/KnowledgeGraph.pending_questions.html#talk_box.KnowledgeGraph.pending_questions)
- [KnowledgeGraph.answer_question](reference/KnowledgeGraph.answer_question.html#talk_box.KnowledgeGraph.answer_question)
- [KnowledgeGraph.dismiss_question](reference/KnowledgeGraph.dismiss_question.html#talk_box.KnowledgeGraph.dismiss_question)
- [KnowledgeGraph.question_stats](reference/KnowledgeGraph.question_stats.html#talk_box.KnowledgeGraph.question_stats)
- [KnowledgeGraph.clear](reference/KnowledgeGraph.clear.html#talk_box.KnowledgeGraph.clear)
- [KnowledgeGraph.close](reference/KnowledgeGraph.close.html#talk_box.KnowledgeGraph.close)
- [Node](reference/Node.html#talk_box.Node): A node in the knowledge graph
- [Edge](reference/Edge.html#talk_box.Edge): A directed relationship between two nodes
- [NodeType](reference/NodeType.html#talk_box.NodeType): Type of a knowledge graph node
- [cosine_similarity](reference/cosine_similarity.html#talk_box.cosine_similarity): Compute cosine similarity between two vectors


## KnowledgeGraph Methods

Methods for the KnowledgeGraph class

- [KnowledgeGraph.add_node](reference/KnowledgeGraph.add_node.html#talk_box.KnowledgeGraph.add_node)
- [KnowledgeGraph.get_node](reference/KnowledgeGraph.get_node.html#talk_box.KnowledgeGraph.get_node)
- [KnowledgeGraph.delete_node](reference/KnowledgeGraph.delete_node.html#talk_box.KnowledgeGraph.delete_node)
- [KnowledgeGraph.list_nodes](reference/KnowledgeGraph.list_nodes.html#talk_box.KnowledgeGraph.list_nodes)
- [KnowledgeGraph.node_count](reference/KnowledgeGraph.node_count.html#talk_box.KnowledgeGraph.node_count)
- [KnowledgeGraph.add_edge](reference/KnowledgeGraph.add_edge.html#talk_box.KnowledgeGraph.add_edge)
- [KnowledgeGraph.get_edges](reference/KnowledgeGraph.get_edges.html#talk_box.KnowledgeGraph.get_edges)
- [KnowledgeGraph.delete_edge](reference/KnowledgeGraph.delete_edge.html#talk_box.KnowledgeGraph.delete_edge)
- [KnowledgeGraph.edge_count](reference/KnowledgeGraph.edge_count.html#talk_box.KnowledgeGraph.edge_count)
- [KnowledgeGraph.neighbors](reference/KnowledgeGraph.neighbors.html#talk_box.KnowledgeGraph.neighbors)
- [KnowledgeGraph.search](reference/KnowledgeGraph.search.html#talk_box.KnowledgeGraph.search)
- [KnowledgeGraph.stats](reference/KnowledgeGraph.stats.html#talk_box.KnowledgeGraph.stats)
- [KnowledgeGraph.health](reference/KnowledgeGraph.health.html#talk_box.KnowledgeGraph.health)
- [KnowledgeGraph.pending_questions](reference/KnowledgeGraph.pending_questions.html#talk_box.KnowledgeGraph.pending_questions)
- [KnowledgeGraph.answer_question](reference/KnowledgeGraph.answer_question.html#talk_box.KnowledgeGraph.answer_question)
- [KnowledgeGraph.dismiss_question](reference/KnowledgeGraph.dismiss_question.html#talk_box.KnowledgeGraph.dismiss_question)
- [KnowledgeGraph.question_stats](reference/KnowledgeGraph.question_stats.html#talk_box.KnowledgeGraph.question_stats)
- [KnowledgeGraph.clear](reference/KnowledgeGraph.clear.html#talk_box.KnowledgeGraph.clear)
- [KnowledgeGraph.close](reference/KnowledgeGraph.close.html#talk_box.KnowledgeGraph.close)
- [KnowledgeGraph.__repr__](reference/KnowledgeGraph.__repr__.html#talk_box.KnowledgeGraph.__repr__)


## KG Visualization

Render knowledge graphs as Mermaid diagrams or interactive HTML pages.

- [VisNode](reference/VisNode.html#talk_box.VisNode): A node prepared for visualization
- [VisEdge](reference/VisEdge.html#talk_box.VisEdge): An edge prepared for visualization
- [VisGraph](reference/VisGraph.html#talk_box.VisGraph): A complete graph prepared for visualization
- [VisGraph.node_count](reference/VisGraph.node_count.html#talk_box.VisGraph.node_count)
- [VisGraph.edge_count](reference/VisGraph.edge_count.html#talk_box.VisGraph.edge_count)
- [VisGraph.to_dict](reference/VisGraph.to_dict.html#talk_box.VisGraph.to_dict)
- [prepare_vis_graph](reference/prepare_vis_graph.html#talk_box.prepare_vis_graph): Prepare a knowledge graph for visualization
- [to_mermaid](reference/to_mermaid.html#talk_box.to_mermaid): Render a knowledge graph as a Mermaid diagram string
- [to_html](reference/to_html.html#talk_box.to_html): Render a knowledge graph as an interactive HTML page
- [visualize](reference/visualize.html#talk_box.visualize): Render a knowledge graph and open it in the browser


## Connectors

Ingest documents from files, directories, and Apple Notes into the knowledge graph.

- [Document](reference/Document.html#talk_box.Document): A document to ingest into the knowledge graph
- [Connector](reference/Connector.html#talk_box.Connector): Base class for knowledge graph connectors
- [Connector.scan](reference/Connector.scan.html#talk_box.Connector.scan)
- [MarkdownDir](reference/MarkdownDir.html#talk_box.MarkdownDir): Ingest Markdown files from a directory
- [MarkdownDir.scan](reference/MarkdownDir.scan.html#talk_box.MarkdownDir.scan)
- [DirectoryConnector](reference/DirectoryConnector.html#talk_box.DirectoryConnector): Ingest text-based files from a directory by extension
- [DirectoryConnector.scan](reference/DirectoryConnector.scan.html#talk_box.DirectoryConnector.scan)
- [AppleNotes](reference/AppleNotes.html#talk_box.AppleNotes): Ingest notes from macOS Apple Notes (read-only)
- [AppleNotes.scan](reference/AppleNotes.scan.html#talk_box.AppleNotes.scan)
- [SyncResult](reference/SyncResult.html#talk_box.SyncResult): Result of a connector sync operation
- [SyncResult.total](reference/SyncResult.total.html#talk_box.SyncResult.total)
- [connector](reference/connector.html#talk_box.connector): Create a connector from a generator function
- [sync](reference/sync.html#talk_box.sync): Sync documents from connectors into a knowledge graph


## Enrichment

Extract entities, topics, relationships, and summaries from documents in the knowledge graph.

- [ExtractedEntity](reference/ExtractedEntity.html#talk_box.ExtractedEntity): An entity extracted from a document
- [ExtractedRelationship](reference/ExtractedRelationship.html#talk_box.ExtractedRelationship): A relationship extracted between two entities
- [EnrichmentResult](reference/EnrichmentResult.html#talk_box.EnrichmentResult): Complete enrichment output for a single document
- [EnrichmentResult.entity_names](reference/EnrichmentResult.entity_names.html#talk_box.EnrichmentResult.entity_names)
- [EnrichmentResult.entity_count](reference/EnrichmentResult.entity_count.html#talk_box.EnrichmentResult.entity_count)
- [EnrichmentResult.topic_count](reference/EnrichmentResult.topic_count.html#talk_box.EnrichmentResult.topic_count)
- [EnrichmentResult.relationship_count](reference/EnrichmentResult.relationship_count.html#talk_box.EnrichmentResult.relationship_count)
- [EnrichmentPipeline](reference/EnrichmentPipeline.html#talk_box.EnrichmentPipeline): Configurable pipeline for enriching documents in a knowledge graph
- [EnrichmentPipeline.run](reference/EnrichmentPipeline.run.html#talk_box.EnrichmentPipeline.run)
- [PipelineResult](reference/PipelineResult.html#talk_box.PipelineResult): Result of running the enrichment pipeline
- [PipelineResult.total](reference/PipelineResult.total.html#talk_box.PipelineResult.total)
- [EnrichmentConfig](reference/EnrichmentConfig.html#talk_box.EnrichmentConfig): Configuration for how enrichment results are applied
- [regex_enricher](reference/regex_enricher.html#talk_box.regex_enricher): Simple regex-based enrichment (no LLM required)


## Compliance Export

Export conversation transcripts as auditable JSON or HTML files.

- [export_json](reference/export_json.html#talk_box.export_json): Export a conversation capture as an auditable JSON file
- [export_html](reference/export_html.html#talk_box.export_html): Export a conversation capture as a human-readable HTML transcript


## CLI

Command-line interface for managing and testing AI assistants.

- [cli.main](reference/cli.main.html#talk_box.cli.main)
- [cli.info](reference/cli.info.html#talk_box.cli.info)
- [cli.personas](reference/cli.personas.html#talk_box.cli.personas)
- [cli.models](reference/cli.models.html#talk_box.cli.models)
- [cli.test_cmd](reference/cli.test_cmd.html#talk_box.cli.test_cmd)


## Configuration

Layered configuration system with profiles, environment overrides, and CLI flags.

- [TalkBoxConfig](reference/TalkBoxConfig.html#talk_box.TalkBoxConfig): Complete Talk Box configuration
- [TalkBoxConfig.resolve](reference/TalkBoxConfig.resolve.html#talk_box.TalkBoxConfig.resolve)
- [TalkBoxConfig.to_dict](reference/TalkBoxConfig.to_dict.html#talk_box.TalkBoxConfig.to_dict)
- [TalkBoxConfig.validate_model](reference/TalkBoxConfig.validate_model.html#talk_box.TalkBoxConfig.validate_model)
- [TalkBoxConfig.is_cloud_model](reference/TalkBoxConfig.is_cloud_model.html#talk_box.TalkBoxConfig.is_cloud_model)
- [ProfileConfig](reference/ProfileConfig.html#talk_box.ProfileConfig): A named profile bundling model + persona + settings
- [ProfileConfig.to_dict](reference/ProfileConfig.to_dict.html#talk_box.ProfileConfig.to_dict)
- [ResolvedConfig](reference/ResolvedConfig.html#talk_box.ResolvedConfig): The final resolved configuration after all layers are merged
- [TUIMode](reference/TUIMode.html#talk_box.TUIMode): TUI display mode
- [load_config](reference/load_config.html#talk_box.load_config): Load and merge the full config stack
- [save_config](reference/save_config.html#talk_box.save_config): Write a config to a YAML file
- [load_profile](reference/load_profile.html#talk_box.load_profile): Load a named profile from the profiles directory
- [save_profile](reference/save_profile.html#talk_box.save_profile): Save a named profile to the profiles directory
- [list_profiles](reference/list_profiles.html#talk_box.list_profiles): List available profile names from the profiles directory


# Resources

- [Full documentation](https://rich-iannone.github.io/talk-box/)
- [llms.txt](llms.txt) -- Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) -- Comprehensive documentation for LLMs
- [Source code](https://github.com/rich-iannone/talk-box)


## Reuse


MIT