Strict Tools Mode - PraisonAI

Strict tools mode provides fail-fast dependency checking before running templates. When enabled, the template will not execute if any required tool, package, or environment variable is missing.

Python API

DependencyChecker

from praisonai.templates import DependencyChecker, StrictModeError
from praisonai.templates import TemplateLoader

# Load a template
loader = TemplateLoader()
template = loader.load("my-template")

# Create dependency checker
checker = DependencyChecker()

# Check all dependencies (non-strict - returns status)
result = checker.check_template_dependencies(template)
print(f"All satisfied: {result['all_satisfied']}")

# Enforce strict mode (raises exception if missing)
try:
    checker.enforce_strict_mode(template)
    print("✓ All dependencies satisfied")
except StrictModeError as e:
    print(f"Missing dependencies:\n{e}")
    print(f"Missing items: {e.missing_items}")

Checking Individual Dependencies

from praisonai.templates import DependencyChecker

checker = DependencyChecker()

# Check tool availability
tool_status = checker.check_tool("internet_search")
print(f"Available: {tool_status['available']}")
print(f"Source: {tool_status['source']}")  # local, builtin, external, registered, resolver, custom

# Check package availability
pkg_status = checker.check_package("pandas")
print(f"Available: {pkg_status['available']}")
print(f"Install hint: {pkg_status['install_hint']}")

# Check environment variable
env_status = checker.check_env_var("OPENAI_API_KEY")
print(f"Available: {env_status['available']}")
print(f"Masked value: {env_status['masked_value']}")  # sk-****1234

Tool Source Values

check_tool() delegates to ToolResolver.list_available_sources() — the same resolution chain used at agent run time. The source field reflects where the tool actually comes from:

Source	Where it comes from	Notes
`local`	Your local `tools.py` (via `ToolResolver`)	Requires `PRAISONAI_ALLOW_LOCAL_TOOLS=true`
`builtin`	`praisonaiagents.tools` (via `ToolResolver`)	No extra install needed
`external`	`praisonai-tools` package (via `ToolResolver`)	Requires `pip install praisonai-tools`
`registered`	Wrapper `ToolRegistry` or core SDK entry-point plugin (via `ToolResolver`)	Tools registered via `register_function()`
`resolver`	Resolvable but not attributed to a bucket (rare)	Conservative fallback
`custom`	Custom tool directories (`custom_tool_dirs=[...]`)	Always honored unconditionally
`builtin` / `praisonai-tools` / `custom`	Legacy fallback path	Only appears when `ToolResolver` cannot be imported

Tools registered via ToolRegistry.register_function() and core SDK entry-point plugins are now correctly reported as available. Before PR #2642, these tools resolved correctly at agent run time but were reported as “not installed” by the dependency checker. The checker now delegates to ToolResolver — the same source of truth used by resolve() — so diagnostic output matches runtime behaviour.If you are migrating from an earlier version and previously saw tools reported as missing in strict mode, verify those tools are registered via ToolRegistry or an entry-point plugin under the canonical praisonai.tools group. The legacy praisonaiagents.tools and praisonai.tool_sources groups still resolve tools registered under them (with a one-cycle DeprecationWarning on first discovery), and canonical-group tools take precedence on a name collision — they will now appear as available with source: "registered".

Getting Install Hints

from praisonai.templates import DependencyChecker, TemplateLoader

loader = TemplateLoader()
template = loader.load("video-analyzer")

checker = DependencyChecker()
hints = checker.get_install_hints(template)

for hint in hints:
    print(f"• {hint}")
# Output:
# • Tool 'youtube_tool': pip install praisonai-tools[video]
# • Package 'opencv-python': pip install opencv-python
# • Environment variable 'YOUTUBE_API_KEY': export YOUTUBE_API_KEY=<value>

Install hints are only generated for tools that are genuinely missing from all sources. Tools that resolve via ToolRegistry or entry-point plugins will not trigger install hints.

StrictModeError

When strict mode fails, StrictModeError is raised with:

Attribute	Type	Description
`message`	str	Human-readable error message
`missing_items`	dict	Dict with ‘tools’, ‘packages’, ‘env’ lists

try:
    checker.enforce_strict_mode(template)
except StrictModeError as e:
    if e.missing_items["tools"]:
        print(f"Missing tools: {e.missing_items['tools']}")
    if e.missing_items["packages"]:
        print(f"Missing packages: {e.missing_items['packages']}")
    if e.missing_items["env"]:
        print(f"Missing env vars: {e.missing_items['env']}")

Custom Tool Directories

The checker always honors custom_tool_dirs on top of the resolver’s chain:

checker = DependencyChecker(
    custom_tool_dirs=["~/.praisonai/tools", "./my-tools"]
)

# Tools in custom dirs will be found (source: "custom:<dir>")
result = checker.check_tool("my_custom_tool")

Custom directories are not part of the ToolResolver chain — they are checked unconditionally so template-local tool directories always resolve regardless of resolver availability.

Tools Doctor

Full tool availability diagnostics

Tool Resolver

Resolution chain and source labels

Tools

Source label table and CLI reference

​Python API

​DependencyChecker

​Checking Individual Dependencies

​Tool Source Values

​Getting Install Hints

​StrictModeError

​Custom Tool Directories

​Related