dao-ai 0.1.4__tar.gz → 0.1.6__tar.gz

{dao_ai-0.1.4 → dao_ai-0.1.6}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **MCP Tool Filtering**: Control which tools are loaded from MCP servers
+  - `include_tools`: Optional allowlist with glob pattern support (e.g., `["query_*", "list_*"]`)
+  - `exclude_tools`: Optional denylist with glob pattern support (e.g., `["drop_*", "delete_*"]`)
+  - Precedence: exclude always overrides include for maximum security
+  - Pattern syntax: `*` (any chars), `?` (single char), `[abc]` (char set), `[!abc]` (negation)
+  - Use cases: Security (block dangerous operations), performance (reduce context), access control
+  - New example config: `config/examples/02_mcp/filtered_mcp.yaml` with 6 filtering strategies
+  - Comprehensive documentation in configuration reference and MCP README
+
+- **CLI: list-mcp-tools Command**: Discover and inspect MCP tools from configuration
+  - Lists all available tools from configured MCP servers with full details
+  - Shows tool descriptions (no truncation), parameters, types, and requirements
+  - Pretty-printed schemas in readable format (53% more compact than JSON)
+  - Filter statistics: total available, included, and excluded tool counts
+  - `--apply-filters` flag: Show only tools that will be loaded (respects include/exclude)
+  - Aggregated output: Collects all data before display (no logging interference)
+  - Detailed exclusion reasons: Shows why tools are filtered out
+  - Use cases: Discovery, debugging, validation, planning, documentation
+
+- **AnyVariable Support for Additional Fields**: More configuration flexibility
+  - `SchemaModel.catalog_name` and `SchemaModel.schema_name` now support AnyVariable
+  - `DatabricksAppModel.url` now supports AnyVariable
+  - Allows environment variables, Databricks secrets, and fallback chains
+  - Benefits: Environment flexibility, security, portability, backwards compatible
+  - Examples: `{env: CATALOG_NAME}`, `{scope: secrets, secret: url}`, composite fallbacks
+
+### Changed
+- **Refactored Dynamic Prompt Creation**: Simplified and improved `prompts.py`
+  - Consolidated redundant prompt creation logic into single `make_prompt()` function
+  - Removed unused `create_prompt_middleware()` function (dead code)
+  - Cleaner context field handling with generic loop over all context attributes
+  - More maintainable codebase with reduced duplication
+
 ## [0.1.0] - 2025-12-19
 
 ### Added

{dao_ai-0.1.4 → dao_ai-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dao-ai
-Version: 0.1.4
+Version: 0.1.6
 Summary: DAO AI: A modular, multi-agent orchestration framework for complex AI workflows. Supports agent handoff, tool integration, and dynamic configuration via YAML.
 Project-URL: Homepage, https://github.com/natefleming/dao-ai
 Project-URL: Documentation, https://natefleming.github.io/dao-ai

dao_ai-0.1.6/config/examples/02_mcp/README.md

@@ -0,0 +1,281 @@
+# 02. Tools
+
+**Integrate with external services and Databricks capabilities**
+
+This category demonstrates how to connect your agents to various tools and services. Each example focuses on a specific tool integration pattern.
+
+## Examples
+
+| File | Description | Prerequisites |
+|------|-------------|---------------|
+| `slack_integration.yaml` | Slack messaging integration | Slack workspace, bot token |
+| `custom_mcp.yaml` | Custom MCP integration (JIRA example) | JIRA instance, API token |
+| `managed_mcp.yaml` | Managed Model Context Protocol integration | MCP server |
+| `external_mcp.yaml` | External MCP with Unity Catalog connections | Unity Catalog, MCP connection |
+| `filtered_mcp.yaml` | MCP tool filtering examples | MCP server with multiple tools |
+| `genie_with_conversation_id.yaml` | Genie with conversation tracking | Genie space |
+
+## What You'll Learn
+
+- **External service integration** - Connect to Slack, JIRA, and other services
+- **Model Context Protocol (MCP)** - Standardized tool integration
+- **Unity Catalog connections** - Secure credential management
+- **Vector Search** - Semantic search and RAG patterns
+- **Reranking** - Improve search relevance with FlashRank
+- **Conversation tracking** - Maintain context across interactions
+
+## Quick Start
+
+### Test Slack integration
+```bash
+# Set your Slack token
+export SLACK_BOT_TOKEN="xoxb-your-token"
+
+dao-ai chat -c config/examples/02_mcp/slack_integration.yaml
+```
+
+Example: *"Send a message to #general saying 'Hello from DAO AI!'"*
+
+
+Example: *"Find documentation about configuring agents"*
+
+## Integration Patterns
+
+### External APIs (Slack, JIRA)
+- **Authentication**: Tokens stored in environment variables or Databricks Secrets
+- **Tool definition**: Factory functions create tools from credentials
+- **Usage**: Agent calls tools based on natural language requests
+
+### Model Context Protocol (MCP)
+- **Standardized interface**: Consistent pattern for external integrations
+- **Server-based**: MCP servers expose tools to agents
+- **UC Connections**: Secure credential management via Unity Catalog
+
+### Vector Search & RAG
+- **Semantic search**: Find relevant information using embeddings
+- **Reranking**: Improve precision with FlashRank post-processing
+- **Context injection**: Retrieved content added to agent prompts
+
+### MCP Tool Filtering
+- **Security**: Block dangerous operations (drop, delete, execute DDL)
+- **Performance**: Load only relevant tools to reduce context size
+- **Access Control**: Filter tools based on user permissions
+- **Cost Optimization**: Minimize token usage by reducing tool set
+
+## MCP Tool Filtering
+
+MCP servers can expose many tools. Use `include_tools` and `exclude_tools` to control which tools are loaded from the server.
+
+### Why Filter Tools?
+
+**Security**
+- Block dangerous operations (drop_table, delete_data, execute_ddl)
+- Prevent unauthorized access to sensitive functions
+- Enforce principle of least privilege
+
+**Performance**
+- Reduce context window usage
+- Faster agent responses with fewer tools to consider
+- Lower token costs per request
+
+**Usability**
+- Agents make better decisions with focused tool sets
+- Reduce tool confusion and selection errors
+- Clearer audit trails of available operations
+
+### Filtering Options
+
+#### 1. Include Tools (Allowlist)
+Load only specified tools - most secure approach:
+
+```yaml
+function:
+  type: mcp
+  sql: true
+  include_tools:
+    - execute_query      # Exact name
+    - list_tables        # Exact name
+    - "query_*"          # Pattern: all query tools
+    - "get_*"            # Pattern: all getter tools
+```
+
+#### 2. Exclude Tools (Denylist)
+Load all tools except specified ones - flexible approach:
+
+```yaml
+function:
+  type: mcp
+  sql: true
+  exclude_tools:
+    - "drop_*"           # Pattern: block all drop operations
+    - "delete_*"         # Pattern: block all delete operations
+    - execute_ddl        # Exact name
+```
+
+#### 3. Hybrid Filtering
+Combine include and exclude for fine-grained control:
+
+```yaml
+function:
+  type: mcp
+  functions: *schema
+  include_tools:
+    - "query_*"          # Start with all query tools
+    - "list_*"           # And all list tools
+  exclude_tools:
+    - "*_sensitive"      # But exclude sensitive ones
+    - "*_admin"          # And admin functions
+```
+
+**Important:** `exclude_tools` always takes precedence over `include_tools`
+
+### Pattern Syntax
+
+Supports glob patterns (from Python's `fnmatch`):
+
+| Pattern | Description | Examples |
+|---------|-------------|----------|
+| `*` | Matches any characters | `query_*` matches `query_sales`, `query_inventory` |
+| `?` | Matches single character | `tool_?` matches `tool_a`, `tool_b` but not `tool_ab` |
+| `[abc]` | Matches any char in set | `tool_[123]` matches `tool_1`, `tool_2`, `tool_3` |
+| `[!abc]` | Matches any char NOT in set | `tool_[!abc]` matches `tool_d`, `tool_1` |
+
+### Common Filtering Patterns
+
+**Read-Only SQL Access**
+```yaml
+include_tools: ["query_*", "list_*", "describe_*", "show_*", "get_*"]
+```
+
+**Block Dangerous Operations**
+```yaml
+exclude_tools: ["drop_*", "delete_*", "truncate_*", "execute_ddl", "alter_*"]
+```
+
+**Development Mode (Safe Defaults)**
+```yaml
+exclude_tools: ["drop_*", "truncate_*", "execute_ddl"]
+```
+
+**Admin Functions Only**
+```yaml
+include_tools: ["admin_*", "manage_*", "configure_*"]
+```
+
+**No Sensitive Data Access**
+```yaml
+exclude_tools: ["*_sensitive", "*_secret", "*_password", "*_credential"]
+```
+
+### Examples in filtered_mcp.yaml
+
+The `filtered_mcp.yaml` file demonstrates 6 different filtering strategies:
+
+1. **sql_safe_tools**: Explicit allowlist of safe operations
+2. **sql_readonly**: Block all write operations with patterns
+3. **functions_filtered**: Hybrid filtering with include + exclude
+4. **query_tools_only**: Pattern-based inclusion for consistency
+5. **minimal_tools**: Maximum security with only 3 tools
+6. **dev_tools**: Development mode blocking only critical operations
+
+### Best Practices
+
+1. **Start with allowlist (include_tools) for production** - safest approach
+2. **Use denylist (exclude_tools) for development** - more flexible
+3. **Test your filters** - verify correct tools are loaded via logging
+4. **Document your reasoning** - why are you filtering these tools?
+5. **Use patterns for consistency** - avoid maintaining long lists
+6. **Review regularly** - as MCP servers change, update filters
+
+### Testing Filters
+
+```bash
+# Test with filtered MCP configuration
+dao-ai chat -c config/examples/02_mcp/filtered_mcp.yaml
+
+# Try these commands to verify filtering:
+# 1. "List all available tools" - see what's loaded
+# 2. "Drop the users table" - should fail (tool not available)
+# 3. "Query sales data" - should work (read operation)
+```
+
+The logs will show:
+- Original tool count from MCP server
+- Filtered tool count after include/exclude
+- Final list of available tools
+
+## Prerequisites
+
+### For Slack (`slack_integration.yaml`)
+- Slack workspace with bot created
+- Bot token with appropriate scopes
+- Channel access for the bot
+
+### For Custom MCP (`custom_mcp.yaml`)
+- JIRA instance URL
+- API token or OAuth credentials
+- Project permissions
+
+### For MCP (`managed_mcp.yaml`, `external_mcp.yaml`)
+- MCP server running and accessible
+- For external MCP: Unity Catalog connection configured
+
+- Databricks Vector Search index configured
+- Embedding model endpoint
+- FlashRank installed (for reranking)
+
+### For Genie (`genie_with_conversation_id.yaml`)
+- Genie space with tables
+- Conversation tracking enabled
+
+## Security Best Practices
+
+🔒 **Never commit credentials** to configuration files
+
+**Best practices:**
+- Use environment variables for development
+- Use Databricks Secrets for production
+- Use Unity Catalog connections for enterprise deployments
+- Rotate credentials regularly
+
+**Example credential management:**
+```yaml
+variables:
+  slack_token: &slack_token
+    options:
+      - env: SLACK_BOT_TOKEN          # Development
+      - scope: secrets                 # Production
+        secret: slack_bot_token
+```
+
+## Next Steps
+
+After mastering tool integrations:
+
+👉 **04_genie/** - Optimize tool calls with caching  
+👉 **05_memory/** - Add conversation persistence  
+👉 **07_human_in_the_loop/** - Add approval workflows for sensitive operations
+
+## Troubleshooting
+
+**"Authentication failed"**
+- Verify credentials are set correctly
+- Check token/API key has required permissions
+- Ensure Databricks Secrets scope exists
+
+**"Tool not found"**
+- Verify tool factory function is correctly configured
+- Check tool name matches agent configuration
+- Review tool registration in logs
+
+**"Vector search index not accessible"**
+- Confirm index exists and is active
+- Verify Unity Catalog permissions
+- Check embedding model endpoint is serving
+
+## Related Documentation
+
+- [Tool Development Guide](../../../docs/contributing.md#adding-a-new-tool)
+- [Unity Catalog Connections](../../../docs/configuration-reference.md)
+- [MCP Documentation](https://modelcontextprotocol.io/)
+

dao_ai-0.1.6/config/examples/02_mcp/filtered_mcp.yaml

@@ -0,0 +1,327 @@
+# yaml-language-server: $schema=../../../schemas/model_config_schema.json
+#
+# Example: Filtering MCP Server Tools
+#
+# This example demonstrates how to control which tools are loaded from
+# MCP servers using include_tools and exclude_tools with glob pattern support.
+#
+# Use Cases:
+# - Security: Block dangerous operations (drop, delete, execute_ddl)
+# - Performance: Load only relevant tools to reduce context size
+# - Access Control: Filter tools based on user permissions
+# - Cost Optimization: Minimize token usage by reducing tool set
+#
+# Pattern Syntax:
+# - * matches any characters: "query_*" matches "query_sales", "query_inventory"
+# - ? matches single character: "tool_?" matches "tool_a", "tool_b"
+# - [abc] matches any char in set: "tool_[123]" matches "tool_1", "tool_2"
+# - [!abc] matches any char NOT in set
+#
+# Precedence: exclude_tools ALWAYS overrides include_tools
+#
+# =============================================================================
+# ENVIRONMENT VARIABLES
+# =============================================================================
+
+variables:
+  client_id: &client_id
+    options:
+      - env: RETAIL_AI_DATABRICKS_CLIENT_ID
+      - scope: retail_ai
+        secret: RETAIL_AI_DATABRICKS_CLIENT_ID
+
+  client_secret: &client_secret
+    options:
+      - env: RETAIL_AI_DATABRICKS_CLIENT_SECRET
+      - scope: retail_ai
+        secret: RETAIL_AI_DATABRICKS_CLIENT_SECRET
+
+  workspace_host: &workspace_host
+    options:
+      - env: RETAIL_AI_DATABRICKS_HOST
+      - scope: retail_ai
+        secret: RETAIL_AI_DATABRICKS_HOST
+
+# =============================================================================
+# SCHEMAS
+# =============================================================================
+
+schemas:
+  retail_schema: &retail_schema
+    catalog_name: retail_consumer_goods
+    schema_name: hardware_store
+
+# =============================================================================
+# RESOURCES
+# =============================================================================
+
+resources:
+  llms:
+    default_llm: &default_llm
+      name: databricks-claude-sonnet-4
+      temperature: 0.1
+
+# =============================================================================
+# TOOLS - MCP WITH FILTERING
+# =============================================================================
+
+tools:
+  # ---------------------------------------------------------------------------
+  # Example 1: Include Specific Tools Only (Allowlist)
+  # ---------------------------------------------------------------------------
+  # Best for: Maximum security, explicit control
+  # Use when: You want to be very explicit about what's allowed
+  
+  sql_safe_tools: &sql_safe_tools
+    name: sql_safe
+    function:
+      type: mcp
+      sql: true  # Serverless DBSQL MCP
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Only load these specific tools - nothing else
+      include_tools:
+        - execute_query        # Exact match
+        - list_tables          # Exact match
+        - describe_table       # Exact match
+        - get_*                # Pattern: all getters
+        - show_*               # Pattern: all show operations
+
+  # ---------------------------------------------------------------------------
+  # Example 2: Exclude Dangerous Tools (Denylist)
+  # ---------------------------------------------------------------------------
+  # Best for: General purpose with safety guardrails
+  # Use when: You want most tools but need to block specific ones
+  
+  sql_readonly: &sql_readonly
+    name: sql_readonly
+    function:
+      type: mcp
+      sql: true
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Load all tools EXCEPT these dangerous ones
+      exclude_tools:
+        - drop_*               # Block all drop operations
+        - delete_*             # Block all delete operations
+        - truncate_*           # Block all truncate operations
+        - execute_ddl          # Block DDL execution
+        - alter_*              # Block all alter operations
+
+  # ---------------------------------------------------------------------------
+  # Example 3: Hybrid Filtering (Include + Exclude)
+  # ---------------------------------------------------------------------------
+  # Best for: Fine-grained control
+  # Use when: You want specific categories but with exceptions
+  
+  functions_filtered: &functions_filtered
+    name: functions_filtered
+    function:
+      type: mcp
+      functions: *retail_schema  # UC Functions MCP
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Start with these categories
+      include_tools:
+        - query_*              # All query functions
+        - get_*                # All getter functions
+        - list_*               # All list functions
+      # But exclude sensitive ones
+      exclude_tools:
+        - *_sensitive          # Exclude anything with "_sensitive"
+        - *_admin              # Exclude admin functions
+        - get_secret_*         # Exclude secret getters
+
+  # ---------------------------------------------------------------------------
+  # Example 4: Pattern-Based Inclusion
+  # ---------------------------------------------------------------------------
+  # Best for: Consistent naming conventions
+  # Use when: Your tools follow predictable patterns
+  
+  query_tools_only: &query_tools_only
+    name: query_tools
+    function:
+      type: mcp
+      sql: true
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Only read operations with patterns
+      include_tools:
+        - query_*              # All queries
+        - list_*               # All lists
+        - describe_*           # All describe operations
+        - show_*               # All show operations
+
+  # ---------------------------------------------------------------------------
+  # Example 5: Maximum Security (Very Restrictive)
+  # ---------------------------------------------------------------------------
+  # Best for: High-security environments
+  # Use when: You need maximum control and auditability
+  
+  minimal_tools: &minimal_tools
+    name: minimal_safe_tools
+    function:
+      type: mcp
+      sql: true
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Only these 3 specific tools, nothing else
+      include_tools:
+        - execute_query
+        - list_tables
+        - describe_table
+
+  # ---------------------------------------------------------------------------
+  # Example 6: Block Only Critical Operations
+  # ---------------------------------------------------------------------------
+  # Best for: Development/testing with safety nets
+  # Use when: You want flexibility but need to prevent disasters
+  
+  dev_tools: &dev_tools
+    name: dev_sql_tools
+    function:
+      type: mcp
+      sql: true
+      client_id: *client_id
+      client_secret: *client_secret
+      workspace_host: *workspace_host
+      # Allow everything except the really dangerous stuff
+      exclude_tools:
+        - drop_*               # Can't drop anything
+        - truncate_*           # Can't truncate
+        - execute_ddl          # Can't run arbitrary DDL
+
+# =============================================================================
+# AGENTS
+# =============================================================================
+
+agents:
+  # ---------------------------------------------------------------------------
+  # Safe SQL Agent (Read-Only)
+  # ---------------------------------------------------------------------------
+  # Can only query, list, and describe - no modifications
+  
+  safe_sql_agent: &safe_sql_agent
+    name: safe_sql_agent
+    description: |
+      SQL agent with read-only access.
+      Can query data and inspect schema, but cannot modify anything.
+    model: *default_llm
+    tools:
+      - *sql_safe_tools
+    prompt: |
+      You are a helpful SQL assistant with read-only access to the database.
+      You can query data, list tables, and describe schemas.
+      You CANNOT modify, delete, or drop any data or structures.
+
+  # ---------------------------------------------------------------------------
+  # Query-Focused Agent
+  # ---------------------------------------------------------------------------
+  # Specialized for data analysis queries only
+  
+  analyst_agent: &analyst_agent
+    name: data_analyst
+    description: |
+      Data analyst agent specialized in querying and analyzing data.
+      Only has access to query and inspection tools.
+    model: *default_llm
+    tools:
+      - *query_tools_only
+    prompt: |
+      You are a data analyst. 
+      Help users write and execute SQL queries to answer their questions.
+      Focus on data analysis and insights.
+
+  # ---------------------------------------------------------------------------
+  # Development Agent (With Safety Rails)
+  # ---------------------------------------------------------------------------
+  # Most tools available but critical operations blocked
+  
+  dev_agent: &dev_agent
+    name: dev_assistant
+    description: |
+      Development assistant with most SQL tools available.
+      Dangerous operations (drop, truncate, DDL) are blocked for safety.
+    model: *default_llm
+    tools:
+      - *dev_tools
+    prompt: |
+      You are a database development assistant.
+      You can help with queries, data manipulation, and schema inspection.
+      Note: Drop, truncate, and DDL operations are disabled for safety.
+
+  # ---------------------------------------------------------------------------
+  # High-Security Agent (Minimal Access)
+  # ---------------------------------------------------------------------------
+  # Only 3 specific tools for maximum security
+  
+  secure_agent: &secure_agent
+    name: secure_query_agent
+    description: |
+      Highly restricted agent with only 3 tools.
+      For use in high-security or audited environments.
+    model: *default_llm
+    tools:
+      - *minimal_tools
+    prompt: |
+      You are a database query assistant with restricted access.
+      You can only execute SELECT queries, list tables, and describe schemas.
+      All operations are logged and audited.
+
+  # ---------------------------------------------------------------------------
+  # Functions Agent with Filtering
+  # ---------------------------------------------------------------------------
+  # UC Functions with sensitive/admin functions excluded
+  
+  functions_agent: &functions_agent
+    name: functions_assistant
+    description: |
+      Assistant with access to Unity Catalog functions.
+      Sensitive and admin functions are excluded for safety.
+    model: *default_llm
+    tools:
+      - *functions_filtered
+    prompt: |
+      You are an assistant that can call Unity Catalog functions.
+      You have access to query, get, and list functions.
+      Sensitive and administrative functions are not available.
+
+# =============================================================================
+# APPLICATION CONFIGURATION
+# =============================================================================
+
+app_name: filtered_mcp_example
+entry_agent: safe_sql_agent
+
+# =============================================================================
+# USAGE NOTES
+# =============================================================================
+#
+# Testing Filters:
+# 1. Run with safe_sql_agent - try to call drop_table (should not be available)
+# 2. Run with dev_agent - verify you can query but not drop
+# 3. Run with secure_agent - verify only 3 tools are available
+#
+# Pattern Examples:
+# - "query_*" matches: query_sales, query_inventory, query_anything
+# - "get_?" matches: get_a, get_1, but NOT get_ab
+# - "*_admin" matches: user_admin, table_admin, delete_admin
+# - "[!s]*" matches: anything NOT starting with 's'
+#
+# Best Practices:
+# 1. Use include_tools for maximum security (allowlist)
+# 2. Use exclude_tools for general purpose with safety (denylist)
+# 3. Combine both for fine-grained control
+# 4. Test your filters - use logging to verify which tools are loaded
+# 5. Document why you're filtering (security, performance, access control)
+#
+# Common Patterns:
+# - Read-only SQL: include_tools: ["query_*", "list_*", "describe_*", "show_*"]
+# - Block dangerous: exclude_tools: ["drop_*", "delete_*", "truncate_*", "execute_ddl"]
+# - Admin only: exclude_tools: ["*_user", "*_public"]
+# - No sensitive: exclude_tools: ["*_sensitive", "*_secret", "*_password"]