Optional Dependencies Check

How praisonai doctor env –deep probes optional packages — available, missing, broken, or slow

praisonai doctor env --deep probes eight optional packages in parallel and reports each as available, missing, broken, or slow — no single hanging import can stall the check.

How It Works

Quick Start

1. Check before wiring up knowledge features

   An agent that uses chromadb for RAG will fail at runtime if the package is broken. Run the check first:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Knowledge Assistant",
       instructions="Answer using indexed documents.",
       knowledge=["docs/manual.pdf"],   # requires chromadb
   )
   agent.start("How do I configure auth?")

   # Confirm chromadb is present before wiring up knowledge features
   praisonai doctor env --deep

2. CI/CD — capture the JSON report

   Export the structured result so CI can gate on specific buckets:

   praisonai doctor env --deep --json > deps.json

   The metadata object contains one list per bucket:

   {
     "id": "optional_deps",
     "status": "WARN",
     "message": "5 optional packages available, 2 not installed, 1 broken",
     "details": "Missing: gradio (Gradio UI), tavily (Tavily search); Broken install: chromadb (Knowledge/RAG features)",
     "remediation": "Reinstall the broken optional package(s): chromadb (Knowledge/RAG features)",
     "metadata": {
       "available": ["mem0ai", "litellm", "praisonaiui", "crawl4ai", "duckduckgo_search"],
       "missing":   ["gradio (Gradio UI)", "tavily (Tavily search)"],
       "broken":    ["chromadb (Knowledge/RAG features)"],
       "slow":      []
     }
   }

How It Works

The Four Outcome Buckets

Each optional package lands in exactly one bucket per run:

Broken praisonaiagents Install Surfaces the Real Import Error

Accessing anything exported through praisonai (for example from praisonai import Agent) points straight at a broken dependency instead of hiding it.

When the praisonaiagents package is installed but fails to import — typically a transitive dependency version conflict — the error now reads:

AttributeError: module 'praisonai' has no attribute 'Agent': praisonaiagents is installed but failed to import (<real ImportError message>)

The underlying exception is chained via __cause__ and cached, so the failing import is not retried on every lookup. Previously the same situation surfaced as a plain AttributeError that hid the real root cause; now the message points straight at the broken dependency.

The Eight Optional Packages

Per-Package Timeout

Each import runs on its own daemon thread with an individual deadline computed from the global --timeout:

per_package_timeout = max(1.0, min(3.0, config.timeout / 4))

With the default --timeout 10, each package gets 2.5 seconds. The overall aggregate deadline is max(per_package_timeout, config.timeout * 0.8) — the check never exceeds 80% of the engine budget.

Why Daemon Threads

Configuration Options

Common Patterns

Gate CI on broken packages only:

praisonai doctor env --deep --json > deps.json
broken=$(python3 -c "import json; d=json.load(open('deps.json')); print(len(d.get('results',[{}])[0].get('metadata',{}).get('broken',[])))" 2>/dev/null || echo "0")
[ "$broken" -gt "0" ] && { echo "Broken optional packages — see deps.json"; exit 1; }

Raise per-package timeout for slow environments:

praisonai doctor env --deep --timeout 20

Run only the optional deps check:

praisonai doctor env --deep --only optional_deps

CI/JSON Output

Gate CI on metadata.broken being empty. A broken install is actionable; a missing install often is not.

{
  "id": "optional_deps",
  "status": "WARN",
  "message": "5 optional packages available, 2 not installed, 1 broken",
  "details": "Missing: gradio (Gradio UI), tavily (Tavily search); Broken install: chromadb (Knowledge/RAG features)",
  "remediation": "Reinstall the broken optional package(s): chromadb (Knowledge/RAG features)",
  "metadata": {
    "available": ["mem0ai", "litellm", "praisonaiui", "crawl4ai", "duckduckgo_search"],
    "missing":   ["gradio (Gradio UI)", "tavily (Tavily search)"],
    "broken":    ["chromadb (Knowledge/RAG features)"],
    "slow":      []
  }
}

Check the broken list in a shell script:

praisonai doctor env --deep --json > deps.json
broken=$(python3 -c "import json,sys; d=json.load(open('deps.json')); print(len(d.get('results',[{}])[0].get('metadata',{}).get('broken',[])))" 2>/dev/null || echo "0")
if [ "$broken" -gt "0" ]; then
  echo "Broken optional packages detected — check deps.json for remediation"
  exit 1
fi

Best Practices

Related