Skills
A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.
Any agent — install with npx:
npx skills add https://rich-iannone.github.io/talk-box/Works with Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex, and 30+ other agents.
Codex / OpenCode — tell the agent:
Fetch the skill file at https://rich-iannone.github.io/talk-box/skill.md and follow the instructions.Manual — download the skill file:
curl -O https://rich-iannone.github.io/talk-box/skill.mdOr browse the SKILL.md file.
SKILL.md
--- name: talk-box description: > Build production AI assistants with battle-tested personas, structured conversations, and built-in quality assurance. Use when writing Python code that uses the talk_box package. license: MIT compatibility: Requires Python >=3.11. --- # 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`: Main entry point for building and managing conversational AI chatbots with integrated - `Conversation`: Manages sequences of messages in conversational AI interactions, primarily returned by ChatBot methods - `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` - `ChatBot.provider_model` - `ChatBot.preset` - `ChatBot.temperature` - `ChatBot.max_tokens` - `ChatBot.persona` - `ChatBot.system_prompt` - `ChatBot.get_system_prompt` - `ChatBot.avoid` - `ChatBot.get_avoid_topics` - `ChatBot.tools` - `ChatBot.add_tools` - `ChatBot.verbose` - `ChatBot.chat` - `ChatBot.start_conversation` - `ChatBot.continue_conversation` - `ChatBot.show` - `ChatBot.get_config_summary` - `ChatBot.get_config` - `ChatBot.prompt_builder` - `ChatBot.structured_prompt` - `ChatBot.chain_prompts` - `ChatBot.check_llm_status` - `ChatBot.quick_start` - `ChatBot.create_chat_session` ### Prompt Engineering Attention-optimized prompt construction - `PromptBuilder`: Builds structured prompts using attention mechanisms and cognitive principles - `PromptBuilder.persona` - `PromptBuilder.task_context` - `PromptBuilder.focus_on` - `PromptBuilder.critical_constraint` - `PromptBuilder.constraint` - `PromptBuilder.core_analysis` - `PromptBuilder.structured_section` - `PromptBuilder.avoid_topics` - `PromptBuilder.output_format` - `PromptBuilder.example` - `PromptBuilder.final_emphasis` - `PromptBuilder.vocabulary` - `PromptBuilder.pathways` - `PromptBuilder.print` - `Priority`: Control where a prompt section is placed relative to other sections - `PromptSection`: Represents a structured section of an attention-optimized prompt with priority and ordering - `VocabularyTerm`: Define domain-specific terminology with multilingual support for consistent AI understanding - `architectural_analysis_prompt`: Create a pre-configured `PromptBuilder` for architectural analysis - `code_review_prompt`: Create a pre-configured `PromptBuilder` for code review - `debugging_prompt`: Create a pre-configured `PromptBuilder` for debugging ### Conversation Pathways State-machine conversation flows with branching and fallbacks - `Pathways`: Chainable builder for defining structured conversational pathways - `Pathways.state` - `Pathways.required` - `Pathways.optional` - `Pathways.tools` - `Pathways.success_condition` - `Pathways.next_state` - `Pathways.branch_on` - `Pathways.fallback` - `Pathways.agent` - `Pathways.register_agent` - `Pathways.get_agent` - `Pathways.visualize` ### Conversation Methods Methods for managing conversation history - `Conversation.add_message` - `Conversation.add_user_message` - `Conversation.add_assistant_message` - `Conversation.add_system_message` - `Conversation.get_messages` - `Conversation.get_last_message` - `Conversation.clear_messages` - `Conversation.set_context_window` - `Conversation.get_context_messages` - `Conversation.get_message_count` - `Conversation.to_dict` - `Conversation.from_dict` ### File Attachments Multi-modal file handling for conversations - `Attachments`: File attachment handler for Talk Box conversations - `Attachments.with_prompt` - `Attachments.to_chat_contents` - `Attachments.get_metadata` - `Attachments.summary` - `AttachmentMetadata`: Metadata for individual file attachments ### Tools Tool registration, execution, and built-in utilities - `tool`: Register a function as a Talk Box tool - `ToolCategory`: Categorize tools by their primary function - `ToolContext`: Provide runtime context to every tool execution - `ToolResult`: Represent the outcome of a tool execution - `get_global_registry`: Return the process-wide `ToolRegistry` singleton - `load_tool_box`: Register all built-in Tool Box tools in the global registry - `get_builtin_tool`: Get a specific built-in tool by name - `load_selected_tools`: Register a subset of the built-in Tool Box tools ### Testing & Validation Automated testing for chatbot quality assurance - `autotest_avoid_topics`: Comprehensive avoid topics testing with automated violation detection - `autotest_pathways`: Automated testing for pathway adherence in chatbots - `TestResults`: Enhanced test results container with rich reporting and analysis capabilities - `TestResults.to_dataframe` - `TestResults.to_great_table` - `PathwayTestResults`: Aggregate and summarize the outcomes of a `autotest_pathways()` run - `ToolEnabledConversation`: Extend `Conversation` with automatic tool invocation support - `create_tool_conversation`: Create a `ToolEnabledConversation` with default settings ### Guardrails Composable input/output validation for chatbot messages - `Guard`: A configured guardrail ready to be attached to a ChatBot - `Guard.check` - `GuardAction`: The outcome of a guard check - `GuardPhase`: When the guard runs in the message lifecycle - `GuardResult`: The result of evaluating a guardrail against a message - `GuardPipeline`: Ordered pipeline of guards that processes messages sequentially - `GuardPipeline.add` - `GuardPipeline.run` - `GuardPipelineResult`: Result of running a message through the full guard pipeline - `guardrail`: Decorator that turns a function into a composable guardrail - `ChatBot.guardrail` - `ChatBot.guard_stats` - `no_pii`: Guard that detects and handles Personally Identifiable Information - `max_response_length`: Guard that enforces a maximum response length - `max_input_length`: Guard that rejects user messages exceeding a character limit - `tone_check`: Guard that flags responses not matching the expected tone - `disclaimer_required`: Guard that ensures a required disclaimer appears in the response - `must_cite_sources`: Guard that requires responses to contain source citations - `keyword_block`: Guard that blocks messages containing any of the specified keywords ### Evaluation Prompt evaluation, scoring, and regression detection - `eval.HAS_PANDAS` - `eval.HAS_GREAT_TABLES` - `eval.DEFAULT_DIMENSIONS` - `eval.ScorerFn` - `eval_regression`: Compare two bot versions and flag regressions - `eval_model_update`: Compare persona behavior across two model versions - `eval_suite`: Evaluate a persona across multiple models (model comparison matrix) - `EvalCase`: A single evaluation test case - `EvalDimension`: Scoring dimensions for evaluation - `EvalResults`: Collection of evaluation results with reporting capabilities - `EvalResults.summary` - `EvalResults.passed` - `EvalResults.regressions` - `EvalResults.scores_by_variant` - `EvalResults.to_dataframe` - `EvalResults.to_great_table` - `EvalResults.to_scorecard` - `EvalResult`: Results for a single query evaluated against a single bot variant - `EvalScore`: A score on a single dimension for a single response - `scorecard_table`: Render a scorecard as a polished Great Table - `sweep_table`: Render an eval sweep summary as a polished Great Table ### Model Profiles Model capability registry for routing, eval, and prompt optimization. - `ModelProfile`: Capability profile for a specific LLM model - `ModelProfile.key` - `ModelProfile.name` - `ModelProfile.supports` - `CostTier`: Relative cost tier for a model - `get_model_profile`: Look up a model's capability profile - `list_models`: List known model profiles, optionally filtered - `register_model`: Register a custom model profile - `model_profiles_table`: Render all known model profiles as a Great Table ### Ollama Detection Auto-detect local Ollama instances and register available models. - `OllamaStatus`: Status of the local Ollama instance - `detect_ollama`: Detect whether a local Ollama instance is running - `list_ollama_models`: Query Ollama for available models and return their profiles - `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`: Manages fitting content into a model's token budget - `ContextWindow.fit_messages` - `ContextWindow.fit_prompt` - `ContextWindow.count_tokens` - `ContextWindow.fits` - `ContextWindow.overflow` - `FitResult`: Result of fitting content into a context window budget - `PromptFitResult`: Result of fitting a PromptBuilder output into a token budget - `FitStrategy`: Strategy for fitting content into a token budget - `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`: Optimize a prompt for reduced token usage - `OptimizationLevel`: How aggressively to compress prompts - `OptimizeResult`: Result of prompt optimization ### Hybrid Routing Route tasks between local and cloud models based on complexity and cost. - `route`: Route a task to the best available model - `classify_complexity`: Estimate the complexity of a task from its prompt text - `Router`: Configurable model router for hybrid local/cloud routing - `Router.route` - `RoutingStrategy`: Strategy that governs how the router selects models - `RoutingResult`: Result of routing a task to a model - `TaskComplexity`: Estimated complexity of a task or prompt ### Consensus Mode Query multiple models, compare outputs, and resolve disagreements. - `consensus`: Determine consensus across multiple model responses - `find_disagreements`: Detect disagreements between model responses - `ConsensusStrategy`: Strategy for resolving consensus across multiple model responses - `ConsensusResult`: Result of running consensus across multiple model responses - `ModelResponse`: A single model's response to a prompt - `Disagreement`: A detected disagreement between model responses ### Cascade Consensus Start with one model, fan out to additional models when confidence is low. - `cascade.Responder` - `estimate_confidence`: Estimate confidence in a model response based on textual signals - `CascadeResult`: Result of a cascade consensus execution - `CascadeRound`: Record of a single round in a cascade execution ### Memory Tiers Working, short-term, and long-term memory for conversations. - `MemoryStore`: Unified memory interface across all three tiers - `MemoryStore.remember` - `MemoryStore.recall` - `MemoryStore.forget` - `MemoryStore.search` - `WorkingMemory`: In-conversation key-value memory, lost when the conversation ends - `ShortTermMemory`: Recent session memory with TTL and max-entry eviction - `LongTermMemory`: Persistent memory backed by SQLite - `MemoryEntry`: A single memory entry across any tier - `MemoryTier`: Which memory tier an entry belongs to ### WorkingMemory Methods Methods for the WorkingMemory class - `WorkingMemory.set` - `WorkingMemory.get` - `WorkingMemory.has` - `WorkingMemory.delete` - `WorkingMemory.keys` - `WorkingMemory.entries` - `WorkingMemory.search` - `WorkingMemory.clear` - `WorkingMemory.__len__` ### ShortTermMemory Methods Methods for the ShortTermMemory class - `ShortTermMemory.set` - `ShortTermMemory.get` - `ShortTermMemory.has` - `ShortTermMemory.delete` - `ShortTermMemory.keys` - `ShortTermMemory.entries` - `ShortTermMemory.search` - `ShortTermMemory.clear` - `ShortTermMemory.__len__` ### LongTermMemory Methods Methods for the LongTermMemory class - `LongTermMemory.set` - `LongTermMemory.get` - `LongTermMemory.has` - `LongTermMemory.delete` - `LongTermMemory.keys` - `LongTermMemory.entries` - `LongTermMemory.search` - `LongTermMemory.clear` - `LongTermMemory.close` - `LongTermMemory.__len__` ### Agent Self-contained AI agent bundling persona, memory, tools, and conversation history. - `Agent`: A self-contained AI agent bundling persona, memory, and conversation history - `Agent.from_persona` - `Agent.respond` - `Agent.remember` - `Agent.recall` - `Agent.retention` - `Agent.conversation` - `Agent.reset_conversation` ### Agent Methods Methods for the Agent class - `Agent.__post_init__` - `Agent.from_persona` - `Agent.respond` - `Agent.remember` - `Agent.recall` - `Agent.reset_conversation` ### Human-in-the-Loop Pause agent workflows for human review, approval, or revision. - `human_review`: Create a human-in-the-loop review request - `approve`: Approve a pending review - `reject`: Reject a pending review - `revise`: Revise the content and approve the review - `HumanReview`: A request for human review before proceeding - `HumanReview.status` - `HumanReview.decision` - `HumanReview.is_pending` - `HumanReview.is_resolved` - `HumanReview.is_approved` - `HumanReview.final_content` - `ReviewDecision`: A human's decision on a review request - `ReviewStatus`: Status of a human-in-the-loop review - `ReviewQueue`: Collects and tracks multiple review requests ### ReviewQueue Methods Methods for the ReviewQueue class - `ReviewQueue.add` - `ReviewQueue.pending` - `ReviewQueue.resolved` - `ReviewQueue.by_agent` - `ReviewQueue.by_status` - `ReviewQueue.__len__` ### Skill System Loadable capability packs for agents. - `SkillDefinition`: A loadable skill pack that adds capabilities to an agent - `create_skill`: Create a skill definition programmatically - `get_skill`: Get a skill definition by name - `list_skills`: List all available skill names - `register_skill`: Register a skill definition in the global registry - `load_skill`: Load a skill from an arbitrary YAML file - `skill_categories`: Get all skills grouped by category ### Structured Outputs Extract typed data from LLM responses using Pydantic models. - `ExtractResult`: Result of extracting structured data from an LLM response - `extract`: Extract structured data from an LLM response - `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`: A composable modifier that can be applied to any persona - `apply_trait`: Apply a trait to a persona, returning a new modified persona - `create_trait`: Create a trait definition programmatically - `get_trait`: Get a registered trait by name - `list_traits`: List all available trait names - `register_trait`: Register a trait so it can be retrieved with ``get_trait()`` - `load_trait`: Load a trait from an arbitrary YAML file path - `trait_categories`: Get all traits grouped by category ### MCP Bridge Bidirectional bridge between Talk Box tools and the Model Context Protocol. - `MCPToolInfo`: Description of an MCP tool discovered from a remote server - `MCPBridgeServer`: An MCP server that exposes Talk Box tools over the MCP protocol - `MCPBridgeServer.tool_names` - `MCPBridgeServer.build` - `MCPBridgeServer.run` - `tools_to_mcp_server`: Create an ``MCPBridgeServer`` from a list of Talk Box tools - `mcp_tool_to_talk_box`: Convert an ``MCPToolInfo`` into a ``TalkBoxTool`` - `list_mcp_tools`: Convert raw MCP tool dicts into ``MCPToolInfo`` objects - `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`: SQLite-backed knowledge graph with nodes, edges, and optional embeddings - `KnowledgeGraph.add_node` - `KnowledgeGraph.get_node` - `KnowledgeGraph.delete_node` - `KnowledgeGraph.list_nodes` - `KnowledgeGraph.node_count` - `KnowledgeGraph.add_edge` - `KnowledgeGraph.get_edges` - `KnowledgeGraph.delete_edge` - `KnowledgeGraph.edge_count` - `KnowledgeGraph.neighbors` - `KnowledgeGraph.search` - `KnowledgeGraph.stats` - `KnowledgeGraph.health` - `KnowledgeGraph.pending_questions` - `KnowledgeGraph.answer_question` - `KnowledgeGraph.dismiss_question` - `KnowledgeGraph.question_stats` - `KnowledgeGraph.clear` - `KnowledgeGraph.close` - `Node`: A node in the knowledge graph - `Edge`: A directed relationship between two nodes - `NodeType`: Type of a knowledge graph node - `cosine_similarity`: Compute cosine similarity between two vectors ### KnowledgeGraph Methods Methods for the KnowledgeGraph class - `KnowledgeGraph.add_node` - `KnowledgeGraph.get_node` - `KnowledgeGraph.delete_node` - `KnowledgeGraph.list_nodes` - `KnowledgeGraph.node_count` - `KnowledgeGraph.add_edge` - `KnowledgeGraph.get_edges` - `KnowledgeGraph.delete_edge` - `KnowledgeGraph.edge_count` - `KnowledgeGraph.neighbors` - `KnowledgeGraph.search` - `KnowledgeGraph.stats` - `KnowledgeGraph.health` - `KnowledgeGraph.pending_questions` - `KnowledgeGraph.answer_question` - `KnowledgeGraph.dismiss_question` - `KnowledgeGraph.question_stats` - `KnowledgeGraph.clear` - `KnowledgeGraph.close` - `KnowledgeGraph.__repr__` ### KG Visualization Render knowledge graphs as Mermaid diagrams or interactive HTML pages. - `VisNode`: A node prepared for visualization - `VisEdge`: An edge prepared for visualization - `VisGraph`: A complete graph prepared for visualization - `VisGraph.node_count` - `VisGraph.edge_count` - `VisGraph.to_dict` - `prepare_vis_graph`: Prepare a knowledge graph for visualization - `to_mermaid`: Render a knowledge graph as a Mermaid diagram string - `to_html`: Render a knowledge graph as an interactive HTML page - `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`: A document to ingest into the knowledge graph - `Connector`: Base class for knowledge graph connectors - `Connector.scan` - `MarkdownDir`: Ingest Markdown files from a directory - `MarkdownDir.scan` - `DirectoryConnector`: Ingest text-based files from a directory by extension - `DirectoryConnector.scan` - `AppleNotes`: Ingest notes from macOS Apple Notes (read-only) - `AppleNotes.scan` - `SyncResult`: Result of a connector sync operation - `SyncResult.total` - `connector`: Create a connector from a generator function - `sync`: Sync documents from connectors into a knowledge graph ### Enrichment Extract entities, topics, relationships, and summaries from documents in the knowledge graph. - `ExtractedEntity`: An entity extracted from a document - `ExtractedRelationship`: A relationship extracted between two entities - `EnrichmentResult`: Complete enrichment output for a single document - `EnrichmentResult.entity_names` - `EnrichmentResult.entity_count` - `EnrichmentResult.topic_count` - `EnrichmentResult.relationship_count` - `EnrichmentPipeline`: Configurable pipeline for enriching documents in a knowledge graph - `EnrichmentPipeline.run` - `PipelineResult`: Result of running the enrichment pipeline - `PipelineResult.total` - `EnrichmentConfig`: Configuration for how enrichment results are applied - `regex_enricher`: Simple regex-based enrichment (no LLM required) ### Compliance Export Export conversation transcripts as auditable JSON or HTML files. - `export_json`: Export a conversation capture as an auditable JSON file - `export_html`: Export a conversation capture as a human-readable HTML transcript ### CLI Command-line interface for managing and testing AI assistants. - `cli.main` - `cli.info` - `cli.personas` - `cli.models` - `cli.test_cmd` ### Configuration Layered configuration system with profiles, environment overrides, and CLI flags. - `TalkBoxConfig`: Complete Talk Box configuration - `TalkBoxConfig.resolve` - `TalkBoxConfig.to_dict` - `TalkBoxConfig.validate_model` - `TalkBoxConfig.is_cloud_model` - `ProfileConfig`: A named profile bundling model + persona + settings - `ProfileConfig.to_dict` - `ResolvedConfig`: The final resolved configuration after all layers are merged - `TUIMode`: TUI display mode - `load_config`: Load and merge the full config stack - `save_config`: Write a config to a YAML file - `load_profile`: Load a named profile from the profiles directory - `save_profile`: Save a named profile to the profiles directory - `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)