fix: update docs/docs.json path for Mintlify subpath hosting

Generator looked for docs.json at repo root; PraisonAIDocs uses
docs/docs.json so nav was never updated after auto-gen. Also run
sync_sdk_reference_nav.py after generation as a safety net.

.github/scripts/merge-gate-selftest.js

@@ -41,6 +41,39 @@ const withClaudeReply = [
 assert('not stale when Claude replied after FINAL', !mg.isStaleFinalAfterPush(withClaudeReply, '2026-06-12T09:00:00Z'));
 assert('claude final reply detected', mg.isClaudeFinalReplyComment(withClaudeReply[1]));
 
+const mervinReply = {
+  user: { login: 'MervinPraison' },
+  body: "**Claude finished @MervinPraison's task** —— [View job](https://github.com/)",
+  created_at: '2026-06-12T08:30:00Z',
+};
+assert('mervin claude final reply detected', mg.isClaudeFinalReplyComment(mervinReply));
+assert(
+  'not stale when MervinPraison posted Claude finished',
+  !mg.isStaleFinalAfterPush([...finals, mervinReply], '2026-06-12T09:00:00Z')
+);
+
+const conflictRebaseComments = [
+  {
+    user: { login: 'MervinPraison' },
+    body: '@claude You are the FINAL architecture reviewer.',
+    created_at: '2026-06-12T08:00:00Z',
+  },
+  {
+    user: { login: 'MervinPraison' },
+    body: '@claude this PR has merge conflicts with `main`.',
+    created_at: '2026-06-12T08:10:00Z',
+  },
+  {
+    user: { login: 'MervinPraison' },
+    body: 'Rebase onto main complete. Force-pushed to branch.',
+    created_at: '2026-06-12T08:20:00Z',
+  },
+];
+assert(
+  'allow stale-FINAL recovery after conflict rebase push',
+  !mg.shouldSkipStaleFinalRecovery(conflictRebaseComments, '2026-06-12T08:25:00Z').skip
+);
+
 assert('cancelled detect-and-trigger does not block', mg.OPTIONAL_CANCELLED_CHECKS.has('detect-and-trigger'));
 
 // Stale-FINAL recovery guards (PR #2560 push loop)

.github/scripts/merge-gate.js

@@ -67,7 +67,11 @@ function isClaudeTriggerNoise(c) {
 
 function isClaudeFinalReplyComment(c) {
   const login = (c.user?.login || '').toLowerCase();
-  if (!login.includes('praisonai-triage')) return false;
+  const fromAutomation =
+    login.includes('praisonai-triage') ||
+    login.includes('github-actions') ||
+    AUTO_ACTORS.some((a) => a.toLowerCase() === login);
+  if (!fromAutomation) return false;
   return (c.body || '').includes('Claude finished');
 }
 
@@ -98,10 +102,38 @@ function isConflictRebaseCompletionComment(c) {
   return (
     body.includes('rebase complete') ||
     body.includes('rebase onto') ||
+    body.includes('force-pushed') ||
     (body.includes('conflict') && body.includes('resolved'))
   );
 }
 
+/** HEAD landed after conflict rebase but no FINAL @claude since that push. */
+function needsFinalReReviewAfterConflictRebase(comments, headPushedAt) {
+  if (!headPushedAt) return false;
+  const headTime = new Date(headPushedAt).getTime();
+  const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
+  if (conflictTriggers.length === 0) return false;
+
+  const latestConflict = conflictTriggers.reduce((a, b) =>
+    new Date(a.created_at) > new Date(b.created_at) ? a : b
+  );
+  const conflictTime = new Date(latestConflict.created_at).getTime();
+  if (headTime <= conflictTime) return false;
+
+  const rebaseDone = comments.some(
+    (c) =>
+      new Date(c.created_at).getTime() > conflictTime && isConflictRebaseCompletionComment(c)
+  );
+  if (!rebaseDone) return false;
+
+  const finalsAfterHead = comments.filter(
+    (c) =>
+      isFinalClaudeTriggerComment(c) &&
+      new Date(c.created_at).getTime() >= headTime - 60000
+  );
+  return finalsAfterHead.length === 0;
+}
+
 function conflictRebaseQuiescent(comments, headPushedAt) {
   const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
   if (conflictTriggers.length === 0) return true;
@@ -260,6 +292,9 @@ function shouldSkipStaleFinalRecovery(comments, headPushedAt, headPusherLogin =
   if (headPusherLogin && isClaudeAutomationLogin(headPusherLogin)) {
     return { skip: true, reason: 'head pushed by Claude automation' };
   }
+  if (needsFinalReReviewAfterConflictRebase(comments, headPushedAt)) {
+    return { skip: false, reason: '' };
+  }
   if (isPushSoonAfterLatestFinal(comments, headPushedAt)) {
     return {
       skip: true,
@@ -867,6 +902,7 @@ module.exports = {
   hasRecentConflictComment,
   isConflictRebaseTriggerComment,
   isConflictRebaseCompletionComment,
+  needsFinalReReviewAfterConflictRebase,
   conflictRebaseQuiescent,
   hasHumanChangesRequested,
   hasAnyChangesRequested,

.github/workflows/generate-docs.yml

@@ -5,14 +5,42 @@ on:
     branches:
       - main
     paths:
-      - 'praisonai_tools/docs_generator/**'
+      - 'praisonai_tools/**'
+      - 'pyproject.toml'
+      - 'scripts/generate_reference_docs.py'
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+    branches:
+      - main
   repository_dispatch:
     types: [trigger-docs-generation]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: generate-docs-praisonaidocs
+  cancel-in-progress: false
+
 jobs:
   generate-docs:
+    if: |
+      github.event_name != 'workflow_run' ||
+      (
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.head_branch == 'main' &&
+        github.event.workflow_run.event == 'push' &&
+        !startsWith(github.event.workflow_run.head_commit.message, 'docs: auto-generate')
+      )
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      DOCS_PUSH_TOKEN: ${{ secrets.DOCS_GITHUB_TOKEN || secrets.GH_TOKEN }}
     steps:
       - name: Checkout PraisonAI Tools
         uses: actions/checkout@v4
@@ -30,7 +58,7 @@ jobs:
         with:
           repository: MervinPraison/PraisonAIDocs
           path: praisonai-docs
-          token: ${{ secrets.DOCS_GITHUB_TOKEN }}
+          token: ${{ env.DOCS_PUSH_TOKEN }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -49,10 +77,14 @@ jobs:
             --package all \
             --docs-root $(pwd)/praisonai-docs \
             --source-root $(pwd)/praisonai-source
+
+      - name: Sync SDK reference navigation
+        run: python3 praisonai-docs/scripts/sync_sdk_reference_nav.py
         env:
           PYTHONPATH: $(pwd)/praisonai-tools
 
       - name: Commit and Push Docs
+        if: env.DOCS_PUSH_TOKEN != ''
         run: |
           cd praisonai-docs
           git config --global user.name "github-actions[bot]"
@@ -62,5 +94,6 @@ jobs:
             echo "No changes to commit"
           else
             git commit -m "docs: auto-generate SDK reference documentation"
-            git push
+            git pull --rebase origin main
+            git push origin main
           fi

.github/workflows/pipeline-status-sync.yml

@@ -3,9 +3,13 @@ name: Pipeline Status Sync
 # Sync pipeline/* stage and blocker labels on open internal PRs.
 
 on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
   schedule:
     - cron: '*/10 * * * *'
-  workflow_dispatch:
 
 permissions:
   pull-requests: read

.gitignore

@@ -24,6 +24,9 @@ venv/
 .coverage
 htmlcov/
 
+# Tool auto-discovery cache (generated at import time)
+._discovery_cache_v*.json
+
 # Lock files
 poetry.lock
 uv.lock

README.md

@@ -531,6 +531,37 @@ agent = Agent(
 )
 ```
 
+### How `praisonai-tools` registers its own tools
+
+The bundled tools in this package are **discovered automatically**. Every
+module under `praisonai_tools/tools/` is scanned (at import time, without
+executing the module) and its public top-level classes and functions become
+importable directly:
+
+```python
+from praisonai_tools.tools import WeatherTool, get_weather   # discovered
+from praisonai_tools import WeatherTool                       # same symbol
+```
+
+Adding a new tool therefore means **adding one file** to
+`praisonai_tools/tools/` — there is no import map or `__all__` to edit, and
+imports stay lazy (a tool module and its optional dependencies are only loaded
+the first time one of its symbols is accessed).
+
+By default the discovered public surface is the module's top-level classes and
+functions. If a module exposes tools through module-level aliases
+(e.g. `read_yaml = _yaml_tools.read_yaml`), declare a standard `__all__` in that
+module and the listed names are exported verbatim. Modules and names starting
+with `_` are treated as private and never exported.
+
+The scan result is memoised in a small on-disk cache next to the package, so
+import stays fast; the cache is rebuilt automatically whenever a tool file is
+added, removed, or edited.
+
+External packages that want their tools discovered by `praisonaiagents` should
+use the `[project.entry-points."praisonaiagents.tools"]` group shown above,
+which the core `praisonaiagents` registry resolves.
+
 ---
 
 ## 9. Video Editing Tools
@@ -703,6 +734,19 @@ pip install praisonai-tools[dev]
 pytest tests/ -v
 ```
 
+The `dev` extra installs the video/motion-graphics render deps
+(`playwright`, `imageio-ffmpeg`) so the full suite runs. To exercise the
+HTML render backend you also need the Chromium browser:
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+pytest tests/ -v
+```
+
+If you use a minimal install without those deps, the video tests under
+`tests/unit/video/` are skipped automatically rather than failing.
+
 ---
 
 ## License

contract-001.html

@@ -1 +0,0 @@
-<html>mock visualization</html>

docs/registry_proxy_integration.md

@@ -0,0 +1,141 @@
+# Tool-Registry Proxy Connector
+
+An **optional, bring-your-own-account** connector that lets any PraisonAI agent
+discover and call a large catalogue of third-party API endpoints (SEO,
+enrichment, social data, scraping, ads) through a single proxy token — with
+**credentials injected server-side by the registry, never held by the agent**.
+
+PraisonAI ships **no registry code, no bundled binary and no default endpoint**.
+You supply your own account token or a self-hosted base URL. The connector is
+disabled unless `TOOL_PROXY_URL` is configured.
+
+## Overview
+
+The connector mirrors PraisonAI's deferred tool-search bridge
+(`tool_search` / `tool_describe` / `tool_call`) with three functions:
+
+| Function | Cost | Purpose |
+| --- | --- | --- |
+| `registry_search(query)` | free | capability search over the catalogue |
+| `registry_describe(tool_id)` | free | params, price-per-call, example response |
+| `registry_call(tool_id, params)` | paid | invoke via proxy; credential injected server-side |
+
+## Installation
+
+```bash
+pip install "praisonai-tools[registry-proxy]"
+```
+
+## Setup (3 lines)
+
+```bash
+export TOOL_PROXY_URL="https://your-registry.example.com"   # or a self-hosted instance
+export TOOL_PROXY_TOKEN="your-proxy-token"
+# Optional: override the auth header for registries that expect a custom header.
+# Default is "Authorization" (sent as "Bearer <token>"); any other name (e.g.
+# "X-Treg-Token") sends the raw token in that header.
+export TOOL_PROXY_AUTH_HEADER="Authorization"
+# Optional: override the describe route for registries with a different layout.
+# Must contain "{tool_id}"; defaults to the live registry route below.
+export TOOL_PROXY_DESCRIBE_PATH="/catalog/endpoints/{tool_id}"
+```
+
+```python
+from praisonaiagents import Agent
+from praisonai_tools.registry_proxy import (
+    registry_search, registry_describe, registry_call,
+)
+
+agent = Agent(
+    instructions="SEO analyst",
+    tools=[registry_search, registry_describe, registry_call],
+)
+agent.start("Find the top backlink sources for example.com and summarise")
+# → registry_search("backlinks for a domain") → describe → call
+# one token, no vendor keys in the agent
+```
+
+## Spend safety
+
+`registry_call` accepts optional budget guards. When a configured budget would
+be exceeded, the call is **denied and reported** as a tool-result error (never
+raised as an exception):
+
+```python
+registry_call(
+    "seo.backlinks",
+    {"domain": "example.com"},
+    max_cost_per_call=0.10,     # deny if price-per-call exceeds this
+    max_session_spend=5.00,     # deny if cumulative spend would exceed this
+)
+```
+
+Per-call price is read from `registry_describe`, so guards work without any
+vendor-specific configuration. Guards **fail closed**: if a budget is set but
+the price cannot be validated, the call is denied. Cumulative `max_session_spend`
+persists across separate `registry_call` invocations within the same process,
+scoped per `(proxy_url, token)` so distinct accounts never share a budget.
+
+## HTTP methods
+
+The registry enforces each endpoint's declared HTTP method on `/call/{id}`.
+`registry_call` derives the method automatically from `registry_describe`
+(the endpoint doc carries `method`): `GET` endpoints send `params` as the query
+string, `POST`/`PUT` send them as a JSON body. Pass `method="GET"` explicitly to
+skip the describe lookup when you already know the method. Only the standard
+`GET`/`POST`/`PUT`/`PATCH`/`DELETE` verbs are accepted; any other value (e.g. a
+mislabelled endpoint doc) is rejected as a tool-result error before any request.
+`tool_id` is URL-encoded before being placed in the describe/call route, so it
+cannot alter the requested path.
+
+## Passthrough-URL calls
+
+Passthrough-URL calls require the upstream to be **registered on the registry
+first**. Loopback/private upstreams (e.g. `127.0.0.1`, RFC-1918 addresses) are
+**refused by the registry's SSRF guard by design** — the base URL must be a
+public `http(s)` address. This is registry-side policy, not a connector setting.
+
+## Credential safety
+
+The proxy token is only sent to the endpoint it was configured for. If a caller
+(or a prompt-injected agent) supplies an explicit `proxy_url` without a matching
+`token`, the ambient `TOOL_PROXY_TOKEN` is **not** attached — preventing the
+token from being exfiltrated to an untrusted endpoint. For normal use, leave
+`proxy_url`/`token` unset and configure `TOOL_PROXY_URL`/`TOOL_PROXY_TOKEN` via
+the environment.
+
+## Error taxonomy
+
+All failures are returned as `{"error": ...}` tool results:
+
+- Authentication failed (HTTP 401/403)
+- Insufficient balance (HTTP 402)
+- Upstream 4xx/5xx passed through
+- Request timeout
+- `httpx` not installed → install hint
+
+## Tier 0 — Skills directory compatibility (zero code)
+
+Registries that expose `skill install <name>` install skills into
+`./.claude/skills/`. PraisonAI **already scans** this directory, so
+registry-installed skills are discoverable by PraisonAI agents today with no
+additional code:
+
+- `praisonaiagents/skills/discovery.py` — `.claude/skills` compatibility scan
+  plus an ancestor walk for monorepos.
+
+## Tier 2 — Environment / CLI passthrough (config-only)
+
+A registry's `shell` / `run <vendor> -- args` inject vendor-CLI credentials at
+execution time. Using a PraisonAI environment definition, install the registry
+CLI and log in via a token env var in `setup:`; the agent's `execute_command`
+then has authenticated vendor CLIs (e.g. `run gh -- pr list`) without any key in
+the container. Sandbox / board workers inherit the same via the environment
+definition.
+
+## Licensing note
+
+Some registries are Apache-2.0 **with additional terms** prohibiting embedding
+in commercially distributed products without permission. This connector is
+therefore **optional and bring-your-own-account only**: it ships no registry
+code and no default endpoint — the same posture as other BYO-account connectors.

examples/motion_graphics_example.py

@@ -194,7 +194,7 @@ def example_team_preset():
         
         print("✓ Motion graphics team created successfully!")
         print(f"  Agents: {[agent.name for agent in team.agents]}")
-        print(f"  Leader: {team.leader.name}")
+        print(f"  Coordinator: {team.agents[0].name}")
         print(f"  Workspace: {team._motion_graphics_workspace}")
         
     except ImportError as e:

financial-analysis.html

@@ -1,189 +0,0 @@
-<style>
-.lx-highlight { position: relative; border-radius:3px; padding:1px 2px;}
-.lx-highlight .lx-tooltip {
-  visibility: hidden;
-  opacity: 0;
-  transition: opacity 0.2s ease-in-out;
-  background: #333;
-  color: #fff;
-  text-align: left;
-  border-radius: 4px;
-  padding: 6px 8px;
-  position: absolute;
-  z-index: 1000;
-  bottom: 125%;
-  left: 50%;
-  transform: translateX(-50%);
-  font-size: 12px;
-  max-width: 240px;
-  white-space: normal;
-  box-shadow: 0 2px 6px rgba(0,0,0,0.3);
-}
-.lx-highlight:hover .lx-tooltip { visibility: visible; opacity:1; }
-.lx-animated-wrapper { max-width: 100%; font-family: Arial, sans-serif; }
-.lx-controls {
-  background: #fafafa; border: 1px solid #90caf9; border-radius: 8px;
-  padding: 12px; margin-bottom: 16px;
-}
-.lx-button-row {
-  display: flex; justify-content: center; gap: 8px; margin-bottom: 12px;
-}
-.lx-control-btn {
-  background: #4285f4; color: white; border: none; border-radius: 4px;
-  padding: 8px 16px; cursor: pointer; font-size: 13px; font-weight: 500;
-  transition: background-color 0.2s;
-}
-.lx-control-btn:hover { background: #3367d6; }
-.lx-progress-container {
-  margin-bottom: 8px;
-}
-.lx-progress-slider {
-  width: 100%; margin: 0; appearance: none; height: 6px;
-  background: #ddd; border-radius: 3px; outline: none;
-}
-.lx-progress-slider::-webkit-slider-thumb {
-  appearance: none; width: 18px; height: 18px; background: #4285f4;
-  border-radius: 50%; cursor: pointer;
-}
-.lx-progress-slider::-moz-range-thumb {
-  width: 18px; height: 18px; background: #4285f4; border-radius: 50%;
-  cursor: pointer; border: none;
-}
-.lx-status-text {
-  text-align: center; font-size: 12px; color: #666; margin-top: 4px;
-}
-.lx-text-window {
-  font-family: monospace; white-space: pre-wrap; border: 1px solid #90caf9;
-  padding: 12px; max-height: 260px; overflow-y: auto; margin-bottom: 12px;
-  line-height: 1.6;
-}
-.lx-attributes-panel {
-  background: #fafafa; border: 1px solid #90caf9; border-radius: 6px;
-  padding: 8px 10px; margin-top: 8px; font-size: 13px;
-}
-.lx-current-highlight {
-  border-bottom: 4px solid #ff4444;
-  font-weight: bold;
-  animation: lx-pulse 1s ease-in-out;
-}
-@keyframes lx-pulse {
-  0% { text-decoration-color: #ff4444; }
-  50% { text-decoration-color: #ff0000; }
-  100% { text-decoration-color: #ff4444; }
-}
-.lx-legend {
-  font-size: 12px; margin-bottom: 8px;
-  padding-bottom: 8px; border-bottom: 1px solid #e0e0e0;
-}
-.lx-label {
-  display: inline-block;
-  padding: 2px 4px;
-  border-radius: 3px;
-  margin-right: 4px;
-  color: #000;
-}
-.lx-attr-key {
-  font-weight: 600;
-  color: #1565c0;
-  letter-spacing: 0.3px;
-}
-.lx-attr-value {
-  font-weight: 400;
-  opacity: 0.85;
-  letter-spacing: 0.2px;
-}
-
-/* Add optimizations with larger fonts and better readability for GIFs */
-.lx-gif-optimized .lx-text-window { font-size: 16px; line-height: 1.8; }
-.lx-gif-optimized .lx-attributes-panel { font-size: 15px; }
-.lx-gif-optimized .lx-current-highlight { text-decoration-thickness: 4px; }
-</style>
-<div class="lx-animated-wrapper lx-gif-optimized">
-  <div class="lx-attributes-panel">
-    <div class="lx-legend">Highlights Legend: <span class="lx-label" style="background-color:#D2E3FC;">extraction_0</span> <span class="lx-label" style="background-color:#C8E6C9;">extraction_1</span> <span class="lx-label" style="background-color:#FEF0C3;">extraction_2</span></div>
-    <div id="attributesContainer"></div>
-  </div>
-  <div class="lx-text-window" id="textWindow">
-    The <span class="lx-highlight lx-current-highlight" data-idx="0" style="background-color:#FEF0C3;">quarterly report</span> shows revenue of <span class="lx-highlight" data-idx="1" style="background-color:#D2E3FC;">$1.2M</span> and profit of <span class="lx-highlight" data-idx="2" style="background-color:#C8E6C9;">$300K</span>.
-  </div>
-  <div class="lx-controls">
-    <div class="lx-button-row">
-      <button class="lx-control-btn" onclick="playPause()">▶️ Play</button>
-      <button class="lx-control-btn" onclick="prevExtraction()">⏮ Previous</button>
-      <button class="lx-control-btn" onclick="nextExtraction()">⏭ Next</button>
-    </div>
-    <div class="lx-progress-container">
-      <input type="range" id="progressSlider" class="lx-progress-slider"
-             min="0" max="2" value="0"
-             onchange="jumpToExtraction(this.value)">
-    </div>
-    <div class="lx-status-text">
-      Entity <span id="entityInfo">1/3</span> |
-      Pos <span id="posInfo">[38-43]</span>
-    </div>
-  </div>
-</div>
-
-<script>
-  (function() {
-    const extractions = [{"index": 0, "class": "extraction_2", "text": "quarterly report", "color": "#FEF0C3", "startPos": 4, "endPos": 20, "beforeText": "The ", "extractionText": "quarterly report", "afterText": " shows revenue of $1.2M and profit of $300K.", "attributesHtml": "<div><strong>class:</strong> extraction_2</div><div><strong>attributes:</strong> {<span class=\"lx-attr-key\">index</span>: <span class=\"lx-attr-value\">2</span>, <span class=\"lx-attr-key\">original_text</span>: <span class=\"lx-attr-value\">quarterly report</span>, <span class=\"lx-attr-key\">tool</span>: <span class=\"lx-attr-value\">langextract_extract</span>}</div>"}, {"index": 1, "class": "extraction_0", "text": "$1.2M", "color": "#D2E3FC", "startPos": 38, "endPos": 43, "beforeText": "The quarterly report shows revenue of ", "extractionText": "$1.2M", "afterText": " and profit of $300K.", "attributesHtml": "<div><strong>class:</strong> extraction_0</div><div><strong>attributes:</strong> {<span class=\"lx-attr-key\">index</span>: <span class=\"lx-attr-value\">0</span>, <span class=\"lx-attr-key\">original_text</span>: <span class=\"lx-attr-value\">$1.2M</span>, <span class=\"lx-attr-key\">tool</span>: <span class=\"lx-attr-value\">langextract_extract</span>}</div>"}, {"index": 2, "class": "extraction_1", "text": "$300K", "color": "#C8E6C9", "startPos": 58, "endPos": 63, "beforeText": "The quarterly report shows revenue of $1.2M and profit of ", "extractionText": "$300K", "afterText": ".", "attributesHtml": "<div><strong>class:</strong> extraction_1</div><div><strong>attributes:</strong> {<span class=\"lx-attr-key\">index</span>: <span class=\"lx-attr-value\">1</span>, <span class=\"lx-attr-key\">original_text</span>: <span class=\"lx-attr-value\">$300K</span>, <span class=\"lx-attr-key\">tool</span>: <span class=\"lx-attr-value\">langextract_extract</span>}</div>"}];
-    let currentIndex = 0;
-    let isPlaying = false;
-    let animationInterval = null;
-    let animationSpeed = 1.0;
-
-    function updateDisplay() {
-      const extraction = extractions[currentIndex];
-      if (!extraction) return;
-
-      document.getElementById('attributesContainer').innerHTML = extraction.attributesHtml;
-      document.getElementById('entityInfo').textContent = (currentIndex + 1) + '/' + extractions.length;
-      document.getElementById('posInfo').textContent = '[' + extraction.startPos + '-' + extraction.endPos + ']';
-      document.getElementById('progressSlider').value = currentIndex;
-
-      const playBtn = document.querySelector('.lx-control-btn');
-      if (playBtn) playBtn.textContent = isPlaying ? '⏸ Pause' : '▶️ Play';
-
-      const prevHighlight = document.querySelector('.lx-text-window .lx-current-highlight');
-      if (prevHighlight) prevHighlight.classList.remove('lx-current-highlight');
-      const currentSpan = document.querySelector('.lx-text-window span[data-idx="' + currentIndex + '"]');
-      if (currentSpan) {
-        currentSpan.classList.add('lx-current-highlight');
-        currentSpan.scrollIntoView({block: 'center', behavior: 'smooth'});
-      }
-    }
-
-    function nextExtraction() {
-      currentIndex = (currentIndex + 1) % extractions.length;
-      updateDisplay();
-    }
-
-    function prevExtraction() {
-      currentIndex = (currentIndex - 1 + extractions.length) % extractions.length;
-      updateDisplay();
-    }
-
-    function jumpToExtraction(index) {
-      currentIndex = parseInt(index);
-      updateDisplay();
-    }
-
-    function playPause() {
-      if (isPlaying) {
-        clearInterval(animationInterval);
-        isPlaying = false;
-      } else {
-        animationInterval = setInterval(nextExtraction, animationSpeed * 1000);
-        isPlaying = true;
-      }
-      updateDisplay();
-    }
-
-    window.playPause = playPause;
-    window.nextExtraction = nextExtraction;
-    window.prevExtraction = prevExtraction;
-    window.jumpToExtraction = jumpToExtraction;
-
-    updateDisplay();
-  })();
-</script>

praisonai_tools/__init__.py

@@ -37,6 +37,15 @@ from importlib.metadata import version, PackageNotFoundError
 
 from praisonai_tools.tools.base import BaseTool, ToolResult, ToolValidationError, validate_tool
 from praisonai_tools.tools.decorator import tool, FunctionTool, is_tool, get_tool_schema
+from praisonai_tools.catalogue import (
+    ToolCatalogueEntry,
+    list_tools,
+    get_tool_names,
+)
+
+# Imported at top (not below ``__getattr__``) to satisfy ruff E402. This only
+# reads the auto-discovered manifest - no tool module is eagerly imported.
+from praisonai_tools.tools import __all__ as _tools_all
 
 try:
     __version__ = version("praisonai-tools")
@@ -53,101 +62,20 @@ def __getattr__(name):
     except AttributeError:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-__all__ = [
-    # Base classes for custom tools
-    "BaseTool",
-    "ToolResult", 
-    "ToolValidationError",
-    "validate_tool",
-    # Decorator for function-based tools
-    "tool",
-    "FunctionTool",
-    "is_tool",
-    "get_tool_schema",
-    # Email Tool
-    "EmailTool",
-    "send_email",
-    "read_emails",
-    "search_emails",
-    # Slack Tool
-    "SlackTool",
-    "send_slack_message",
-    "get_slack_channels",
-    "get_slack_history",
-    # Discord Tool
-    "DiscordTool",
-    "send_discord_webhook",
-    "send_discord_message",
-    # GitHub Tool
-    "GitHubTool",
-    "search_github_repos",
-    "get_github_repo",
-    "create_github_issue",
-    # Image Tool
-    "ImageTool",
-    "generate_image",
-    # Weather Tool
-    "WeatherTool",
-    "get_weather",
-    "get_forecast",
-    "get_air_quality",
-    # YouTube Tool
-    "YouTubeTool",
-    "search_youtube",
-    "get_youtube_video",
-    "get_youtube_transcript",
-    # TTS Tool
-    "TTSTool",
-    "text_to_speech",
-    "list_tts_voices",
-    # Telegram Tool
-    "TelegramTool",
-    "send_telegram_message",
-    # Notion Tool
-    "NotionTool",
-    "search_notion",
-    "create_notion_page",
-    # PostgreSQL Tool
-    "PostgresTool",
-    "query_postgres",
-    "list_postgres_tables",
-    # Reddit Tool
-    "RedditTool",
-    "search_reddit",
-    "get_reddit_hot",
-    # Docker Tool
-    "DockerTool",
-    "list_docker_containers",
-    "run_docker_container",
-    # Signal Tool
-    "SignalTool",
-    "send_signal_message",
-    "check_signal_connection",
-    # LINE Tool
-    "LineTool",
-    "send_line_message",
-    "broadcast_line_message",
-    # iMessage Tool
-    "iMessageTool",
-    "send_imessage",
-    "check_imessage_availability",
-    # WhatsApp Tool
-    "WhatsAppTool",
-    "send_whatsapp_message",
-    # Marketplace Tools
-    "PinchworkTool",
-    "pinchwork_delegate",
-    "AgentIDTool", 
-    "verify_agent_identity",
-    "JoyTrustTool",
-    "check_trust_score",
-    "AgentFolioTool",
-    "check_behavioral_trust",
-    "verify_task_delegation_safety",
-    # Composio
-    "ComposioTool",
-    "ComposioTools",
-    "composio_execute",
-    "composio_tools",
-    "composio_list_apps",
-]
+# Catalogue/discovery helpers exported eagerly above (not tool symbols, so they
+# are not part of the auto-discovered manifest).
+_CATALOGUE_EXPORTS = [
+    "ToolCatalogueEntry",
+    "list_tools",
+    "get_tool_names",
+]
+
+# The remainder of ``__all__`` is derived from the tools package's
+# automatically-discovered manifest so the two levels cannot drift apart. Only
+# source files are parsed (via AST) to build it - no tool module is eagerly
+# imported here.
+__all__ = sorted(set(_tools_all) | set(_CATALOGUE_EXPORTS))
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

praisonai_tools/catalogue.py

@@ -0,0 +1,273 @@
+"""Tool discovery / catalogue contract for PraisonAI Tools.
+
+This module provides a single, programmatic way to enumerate every tool that
+``praisonai-tools`` ships, plus any third-party tool registered via the
+``praisonai.tools`` entry-point group. It exists so that the wider SDK (CLI,
+docs, YAML validators, third-party packages) can answer *"what tools can I
+actually use here?"* against a live catalogue derived from the real registry
+rather than a hand-maintained allowlist that drifts.
+
+Usage:
+    from praisonai_tools import list_tools
+
+    for entry in list_tools():
+        print(entry.name, entry.module, entry.extras, entry.summary)
+
+Third-party packages can register their own tools by declaring an entry point:
+
+    # pyproject.toml (third-party tool package)
+    [project.entry-points."praisonai.tools"]
+    my_tool = "my_pkg:MyTool"
+
+Nothing here imports optional/heavy dependencies: the catalogue is built from
+the module map alone, so ``list_tools()`` is safe to call without any extras
+installed.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Dict, Optional, Tuple
+
+ENTRY_POINT_GROUP = "praisonai.tools"
+
+# Directory that holds the first-party ``*_tool.py`` files. The catalogue is
+# derived by scanning this directory, so dropping a new ``*_tool.py`` that
+# defines a ``*Tool`` class makes the tool discoverable with no edits to any
+# hand-maintained list.
+_TOOLS_DIR = os.path.join(os.path.dirname(__file__), "tools")
+
+# Map from the module (as recorded in ``_TOOL_MAP``) to the optional-dependency
+# extras required to use tools defined in it. Modules absent from this mapping
+# have no extra requirements (they rely only on the standard library or on the
+# base dependencies). Keep this aligned with ``[project.optional-dependencies]``
+# in ``pyproject.toml``.
+_MODULE_EXTRAS = {
+    "wordpress_tool": ("wordpress",),
+    "pinchwork_tool": ("pinchwork", "marketplace"),
+    "agentid_tool": ("agentid", "marketplace"),
+    "joy_trust_tool": ("joy-trust", "marketplace"),
+    "agentfolio_tool": ("agentfolio", "marketplace"),
+    "praisonai_tools.n8n.n8n_workflow": ("n8n",),
+    "langextract_tool": ("langextract",),
+    "swarmscore_tool": ("swarmscore",),
+    "composio_tool": ("composio",),
+}
+
+
+@dataclass(frozen=True)
+class ToolCatalogueEntry:
+    """A single discoverable tool.
+
+    Attributes:
+        name: Public name used to import/reference the tool, e.g. ``"QdrantTool"``.
+        module: Dotted or relative module path that defines the tool.
+        extras: Optional-dependency extras required to use the tool, e.g.
+            ``("swarmscore",)``. Empty when no extra install is needed.
+        summary: A one-line human-readable description of the tool.
+    """
+
+    name: str
+    module: str
+    extras: Tuple[str, ...] = field(default_factory=tuple)
+    summary: str = ""
+
+
+def _summary_for(name: str) -> str:
+    """Derive a concise one-line summary for a tool class name.
+
+    Fallback used only when a tool class does not declare a literal
+    ``description``. We avoid importing the tool (which could pull heavy/optional
+    deps) and instead produce a stable, human-friendly summary from the name.
+    """
+    if name.endswith("Tool"):
+        base = name[:-4]
+    else:
+        base = name
+    return f"{base} integration tool".strip()
+
+
+def _first_line(text: str) -> str:
+    """Return the first non-empty line of ``text`` (a tool ``description``)."""
+    for line in text.splitlines():
+        line = line.strip()
+        if line:
+            return line
+    return ""
+
+
+def _scan_module(path: str) -> "list[tuple[str, str]]":
+    """AST-scan a ``*_tool.py`` file for ``*Tool`` classes and descriptions.
+
+    Returns a list of ``(class_name, summary)`` tuples. The file is parsed, not
+    imported, so this stays cheap and never triggers optional dependencies.
+    Classes without a literal ``description`` fall back to a name-synthesised
+    summary.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            tree = ast.parse(fh.read(), filename=path)
+    except (OSError, SyntaxError):  # pragma: no cover - defensive
+        return []
+
+    found = []
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef) or not node.name.endswith("Tool"):
+            continue
+        description: Optional[str] = None
+        for stmt in node.body:
+            # Accept both plain ``description = "..."`` and annotated
+            # ``description: str = "..."`` class attributes.
+            if isinstance(stmt, ast.Assign):
+                targets = [t.id for t in stmt.targets if isinstance(t, ast.Name)]
+                value = stmt.value
+            elif isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                targets = [stmt.target.id]
+                value = stmt.value
+            else:
+                continue
+            if (
+                "description" in targets
+                and isinstance(value, ast.Constant)
+                and isinstance(value.value, str)
+            ):
+                description = value.value
+        summary = _first_line(description) if description else _summary_for(node.name)
+        found.append((node.name, summary or _summary_for(node.name)))
+    return found
+
+
+@lru_cache(maxsize=1)
+def _scan_source_tree() -> "Dict[str, Tuple[str, str]]":
+    """Derive the first-party tool catalogue from the source tree.
+
+    Scans every ``praisonai_tools/tools/*_tool.py`` file for ``*Tool`` classes
+    and returns ``{class_name: (module, summary)}``. Because the mapping is
+    derived from the files that actually exist, phantom names (advertised tools
+    with no file) are impossible by construction, and adding a tool is a single
+    new-file change.
+    """
+    derived: "Dict[str, Tuple[str, str]]" = {}
+    try:
+        filenames = sorted(os.listdir(_TOOLS_DIR))
+    except OSError:  # pragma: no cover - defensive
+        return derived
+
+    for filename in filenames:
+        if not filename.endswith("_tool.py"):
+            continue
+        module = filename[:-3]  # strip ".py"; relative module name within tools
+        path = os.path.join(_TOOLS_DIR, filename)
+        for class_name, summary in _scan_module(path):
+            derived.setdefault(class_name, (module, summary))
+    return derived
+
+
+def _first_party_entries() -> "list[ToolCatalogueEntry]":
+    """Build catalogue entries for every first-party tool class.
+
+    The catalogue is source-derived: it is built by scanning the actual
+    ``*_tool.py`` files on disk (see ``_scan_source_tree``) rather than a
+    hand-maintained dictionary, so it can never advertise a tool whose file does
+    not exist. Summaries come from each tool's own ``description``.
+
+    A few tools live in nested packages (e.g. the n8n workflow tool under
+    ``praisonai_tools.n8n``) rather than flat ``*_tool.py`` files; those are
+    still surfaced via ``_TOOL_MAP`` so their public names remain stable.
+    """
+    entries: "Dict[str, ToolCatalogueEntry]" = {}
+
+    for name, (module, summary) in _scan_source_tree().items():
+        entries[name] = ToolCatalogueEntry(
+            name=name,
+            module=module,
+            extras=_MODULE_EXTRAS.get(module, ()),
+            summary=summary,
+        )
+
+    # Include tool classes defined outside the flat ``*_tool.py`` layout (e.g.
+    # nested subpackages such as ``praisonai_tools.n8n``) that the scan cannot
+    # reach, keeping their names stable. Only *nested* (absolute-module) tools
+    # are merged here: flat ``*_tool.py`` classes are already source-derived by
+    # the scan above, so restoring them from ``_TOOL_MAP`` would reintroduce the
+    # hand-maintained bookkeeping this catalogue exists to eliminate.
+    try:
+        from praisonai_tools.tools import _TOOL_MAP
+    except Exception:  # pragma: no cover - defensive
+        _TOOL_MAP = {}
+    for name, module in _TOOL_MAP.items():
+        if not name.endswith("Tool") or name in entries:
+            continue
+        if not module.startswith("praisonai_tools."):
+            continue
+        entries[name] = ToolCatalogueEntry(
+            name=name,
+            module=module,
+            extras=_MODULE_EXTRAS.get(module, ()),
+            summary=_summary_for(name),
+        )
+
+    return list(entries.values())
+
+
+def _entry_point_entries() -> "list[ToolCatalogueEntry]":
+    """Build catalogue entries for third-party tools registered via entry points.
+
+    Third-party packages register under the ``praisonai.tools`` entry-point
+    group. We do not import the target object (to keep discovery cheap and
+    dependency-free); we record the declared name and module value instead.
+    """
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:  # pragma: no cover - Python < 3.8
+        return []
+
+    entries = []
+    try:
+        eps = entry_points()
+        # importlib.metadata API differs across versions.
+        if hasattr(eps, "select"):
+            selected = eps.select(group=ENTRY_POINT_GROUP)
+        else:  # pragma: no cover - Python < 3.10 dict interface
+            selected = eps.get(ENTRY_POINT_GROUP, [])
+    except Exception:  # pragma: no cover - defensive
+        return []
+
+    for ep in selected:
+        entries.append(
+            ToolCatalogueEntry(
+                name=ep.name,
+                module=getattr(ep, "value", "") or "",
+                extras=(),
+                summary=f"Third-party tool registered via {ENTRY_POINT_GROUP}",
+            )
+        )
+    return entries
+
+
+def list_tools() -> "list[ToolCatalogueEntry]":
+    """Return the full catalogue of available tools.
+
+    Includes every first-party tool shipped with ``praisonai-tools`` plus any
+    third-party tool registered via the ``praisonai.tools`` entry-point group.
+    Entries are de-duplicated by name (first-party wins) and returned sorted by
+    name.
+    """
+    seen = {}
+    for entry in _first_party_entries():
+        seen[entry.name] = entry
+    for entry in _entry_point_entries():
+        seen.setdefault(entry.name, entry)
+    return sorted(seen.values(), key=lambda e: e.name)
+
+
+def get_tool_names() -> "set[str]":
+    """Return the set of every available tool name.
+
+    Convenience helper for validators that only need membership checks (e.g. to
+    replace a hand-maintained allowlist).
+    """
+    return {entry.name for entry in list_tools()}

praisonai_tools/cli.py

@@ -11,6 +11,7 @@ def main():
         print("PraisonAI Developer Tools CLI")
         print("\nUsage: praisonai-tools [tool] [args]")
         print("\nAvailable tools:")
+        print("  list             List the available tool catalogue")
         print("  docs-generate    Generate SDK reference documentation")
         print("  video            AI-powered video editing tools")
         print("  fcp              Final Cut Pro automation tools")
@@ -19,7 +20,23 @@ def main():
     tool = sys.argv[1]
     tool_args = sys.argv[2:]
     
-    if tool == "docs-generate":
+    if tool == "list":
+        parser = argparse.ArgumentParser(prog="praisonai-tools list")
+        parser.add_argument("--extras", action="store_true",
+                            help="Only show tools that require optional-dependency extras")
+        args = parser.parse_args(tool_args)
+        from .catalogue import list_tools
+        entries = list_tools()
+        if args.extras:
+            entries = [e for e in entries if e.extras]
+        width = max((len(e.name) for e in entries), default=0)
+        for entry in entries:
+            extras = f"  [extras: {', '.join(entry.extras)}]" if entry.extras else ""
+            print(f"{entry.name.ljust(width)}  {entry.summary}{extras}")
+        print(f"\n{len(entries)} tools")
+        return 0
+
+    elif tool == "docs-generate":
         # Handle docs-generate with its own parser for better help
         parser = argparse.ArgumentParser(prog="praisonai-tools docs-generate")
         parser.add_argument("--package", choices=["praisonaiagents", "praisonai", "typescript", "all"], 

praisonai_tools/docs_generator/generator.py

@@ -13,6 +13,7 @@ from typing import Any, Dict, List, Optional, Tuple
 import ast
 import re
 import json
+import uuid
 
 
 # =============================================================================
@@ -111,45 +112,239 @@ class LayoutType(Enum):
 # UTILS
 # =============================================================================
 
+# Generic containers whose *simple* single-level form is safe to keep as-is
+# (e.g. ``Optional[str]``, ``Union[str, int]``, ``Dict[str, Any]``). When these
+# wrap complex/nested types they are collapsed to just the container name.
+_SIMPLE_KEEP_CONTAINERS = ("Optional", "Union", "Dict", "List", "Tuple", "Sequence", "Set")
+
+# Containers that should always collapse to just their name because their inner
+# contents commonly contain nested brackets or quoted literals that break MDX.
+_ALWAYS_COLLAPSE_CONTAINERS = ("Callable", "Literal", "Coroutine", "Awaitable", "Generator", "AsyncGenerator")
+
+
 def sanitize_type_for_mdx(type_str: Optional[str]) -> Optional[str]:
-    """Sanitize complex type annotations for MDX compatibility."""
+    """Sanitize complex type annotations for MDX compatibility.
+
+    Rules:
+        - Simple types pass through unchanged (``str`` -> ``str``).
+        - Forward references have their quotes removed
+          (``Optional['Agent']`` -> ``Optional[Agent]``).
+        - Containers known to hold nested brackets are collapsed to their bare
+          name (``Callable[[X], Y]`` -> ``Callable``, ``Literal['a']`` ->
+          ``Literal``, ``Coroutine[...]`` -> ``Coroutine``).
+        - A container wrapping another complex/nested type is collapsed to just
+          its name (``Optional[Union[str, int]]`` -> ``Optional``).
+        - A container wrapping only simple types is preserved
+          (``Optional[str]`` -> ``Optional[str]``,
+          ``Union[str, int]`` -> ``Union[str, int]``).
+    """
     if not type_str:
         return type_str
-    
+
     result = type_str.strip()
-    result = re.sub(r"'([A-Z][a-zA-Z0-9_]*)'", r"\1", result)
-    
-    while "[[" in result or " Union[" in result or " Optional[" in result:
-        new_result = re.sub(r"\[\[(.*?)\]\]", r"[\1]", result)
-        if new_result == result:
-            break
-        result = new_result
-        
-    if "[" in result:
-        return result.split("[")[0]
-        
+
+    # Remove quotes from forward references, e.g. 'Agent' -> Agent
+    result = re.sub(r"'([A-Za-z_][a-zA-Z0-9_.]*)'", r"\1", result)
+
+    # No subscription -> nothing more to simplify.
+    if "[" not in result:
+        return result
+
+    container = result.split("[", 1)[0].strip()
+
+    # Containers that always collapse (Callable, Literal, Coroutine, ...).
+    if container in _ALWAYS_COLLAPSE_CONTAINERS:
+        return container
+
+    # For keep-able containers, inspect the inner content. If it contains nested
+    # brackets (another generic) collapse to the bare container name; otherwise
+    # keep the single-level form intact.
+    if container in _SIMPLE_KEEP_CONTAINERS:
+        inner = result[len(container) + 1:]
+        if inner.endswith("]"):
+            inner = inner[:-1]
+        if "[" in inner:
+            return container
+        # A bare ``Any`` member makes the type uninformative for the table, so
+        # collapse ``Union``/``Optional`` to just the container name.
+        members = [m.strip() for m in inner.split(",")]
+        if container in ("Union", "Optional") and "Any" in members:
+            return container
+        return result
+
+    # Unknown container with nested brackets -> keep the base name to stay safe.
+    if "[[" in result:
+        return container
+
     return result
 
 
+# Plain HTML tags. HTML is case-insensitive, so ``<div>`` and ``<DIV>`` are the
+# same element and both must be preserved (never escaped) by escape_mdx.
+_HTML_TAGS = {
+    'div', 'span', 'p', 'a', 'br', 'hr', 'img', 'ul', 'ol', 'li',
+    'table', 'tr', 'td', 'th', 'thead', 'tbody', 'code', 'pre',
+    'strong', 'em', 'b', 'i', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+}
+
+# Mintlify JSX components. Unlike HTML, JSX component names are CASE-SENSITIVE:
+# ``<Badge>`` is a valid component but ``<badge>`` is not and must be escaped as
+# prose. These are therefore matched exactly (no case folding).
+_MDX_COMPONENTS = {
+    'Card', 'CardGroup', 'Note', 'Warning', 'Info', 'Tip', 'Check',
+    'Danger', 'Accordion', 'AccordionGroup', 'Tab', 'Tabs', 'Step',
+    'Steps', 'Frame', 'Icon', 'Badge', 'Tooltip', 'CodeGroup',
+    'Expandable', 'ParamField', 'ResponseField', 'Columns', 'Column',
+    'RequestExample', 'ResponseExample', 'Banner', 'Update', 'View',
+    'Tree', 'Tile', 'Tiles', 'Panel', 'Color',
+}
+
+# Combined allowlist of tags that must NOT be escaped by escape_mdx.
+VALID_MDX_TAGS = _HTML_TAGS | _MDX_COMPONENTS
+
+# Lower-cased view of the HTML tags only, so ``<DIV>``/``<Div>`` resolve
+# case-insensitively while JSX components stay case-sensitive.
+_HTML_TAGS_LOWER = {t.lower() for t in _HTML_TAGS}
+
+
+def _is_valid_mdx_tag(tag: str) -> bool:
+    """Return True if ``tag`` is a tag that must be preserved (not escaped).
+
+    HTML tags are matched case-insensitively (HTML is case-insensitive) while
+    Mintlify JSX components must match exactly, so a mis-cased component such as
+    ``badge`` is treated as prose and escaped rather than emitted as a broken
+    component.
+    """
+    return tag in _MDX_COMPONENTS or tag.lower() in _HTML_TAGS_LOWER
+
+# Docstring section headers whose indented body is source code and should be
+# wrapped in a fenced code block so MDX/Mintlify renders it verbatim.
+_CODE_SECTION_HEADERS = ("usage", "example", "examples")
+
+
+def _wrap_docstring_code_examples(text: str) -> str:
+    """Wrap indented code under Usage/Example sections in fenced code blocks.
+
+    Detects a header line like ``Usage:`` followed by an indented block and
+    converts that block into a ```python fenced code block so it survives MDX
+    escaping untouched.
+
+    Existing fenced blocks are passed through verbatim, but any indented
+    Usage/Example sections that appear *outside* of a fence (including ones
+    that follow an unrelated fenced block earlier in the docstring) are still
+    wrapped.
+    """
+    lines = text.split('\n')
+    out: List[str] = []
+    i = 0
+    n = len(lines)
+    in_fence = False
+    while i < n:
+        line = lines[i]
+
+        # Pass through content inside an existing fenced code block untouched.
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            out.append(line)
+            i += 1
+            continue
+        if in_fence:
+            out.append(line)
+            i += 1
+            continue
+
+        header = line.strip().rstrip(':').lower()
+        is_header = (
+            line.strip().endswith(':')
+            and header in _CODE_SECTION_HEADERS
+            and not line.startswith((' ', '\t'))
+        )
+        if is_header:
+            # Collect the following indented block.
+            block: List[str] = []
+            j = i + 1
+            # Skip a single blank separator line if present.
+            while j < n and not lines[j].strip():
+                block.append(lines[j])
+                j += 1
+            code_lines: List[str] = []
+            while j < n and (lines[j].startswith((' ', '\t')) or not lines[j].strip()):
+                code_lines.append(lines[j])
+                j += 1
+            # Trim trailing blank lines from the captured code.
+            while code_lines and not code_lines[-1].strip():
+                code_lines.pop()
+            if code_lines:
+                out.append(line)
+                out.extend(block)
+                import textwrap
+                dedented = textwrap.dedent('\n'.join(code_lines))
+                out.append("```python")
+                out.extend(dedented.split('\n'))
+                out.append("```")
+                i = j
+                continue
+        out.append(line)
+        i += 1
+    return '\n'.join(out)
+
+
 def escape_mdx(text: str) -> str:
-    """Escape text for MDX compatibility."""
+    """Escape text for MDX compatibility.
+
+    Escapes stray ``{...}`` expressions and unknown ``<tag>`` patterns that
+    would break Mintlify's MDX parser, while:
+        - Preserving content inside inline/fenced code blocks.
+        - Preserving valid Mintlify component tags (see ``VALID_MDX_TAGS``).
+        - Wrapping indented code under ``Usage:``/``Example:`` docstring
+          sections in fenced code blocks.
+    """
     if not text:
         return text
-        
+
+    text = _wrap_docstring_code_examples(text)
+
+    # Use a per-call random sentinel so literal documentation text such as
+    # ``__CODE_BLOCK_0__`` or ``__MDX_TAG_0__`` cannot be mistaken for one of
+    # our internal placeholders during the restore phase below.
+    token = uuid.uuid4().hex
+    code_marker = f"\x00CB{token}"
+    tag_marker = f"\x00MT{token}"
+
     code_blocks = []
     def save_code_block(match):
         code_blocks.append(match.group(0))
-        return f"__CODE_BLOCK_{len(code_blocks)-1}__"
-    
+        return f"{code_marker}{len(code_blocks) - 1}\x00"
+
     text = re.sub(r"```.*?```", save_code_block, text, flags=re.DOTALL)
     text = re.sub(r"`.*?`", save_code_block, text)
-    
+
     text = text.replace('{', '&#123;').replace('}', '&#125;')
+
+    # Protect valid Mintlify/HTML component tags so they survive the blanket
+    # angle-bracket escaping below.
+    preserved_tags = []
+
+    def preserve_valid_tag(match):
+        full = match.group(0)
+        tag = match.group(1)
+        if _is_valid_mdx_tag(tag):
+            preserved_tags.append(full)
+            return f"{tag_marker}{len(preserved_tags) - 1}\x00"
+        return full
+
+    # Match opening tags <Tag ...>, closing tags </Tag>, and self-contained <tag>.
+    text = re.sub(r"</?([A-Za-z][A-Za-z0-9]*)(?:\s[^<>]*?)?/?>", preserve_valid_tag, text)
+
+    # Escape all remaining angle brackets (unknown tags / stray brackets).
     text = text.replace('<', '&lt;').replace('>', '&gt;')
-    
+
+    for i, tag in enumerate(preserved_tags):
+        text = text.replace(f"{tag_marker}{i}\x00", tag)
+
     for i, block in enumerate(code_blocks):
-        text = text.replace(f"__CODE_BLOCK_{i}__", block)
-        
+        text = text.replace(f"{code_marker}{i}\x00", block)
+
     return text
 
 
@@ -160,18 +355,6 @@ def validate_mdx(content: str) -> List[str]:
     in_code_block = False
     in_frontmatter = False
     frontmatter_count = 0
-    
-    VALID_MDX_TAGS = {
-        'div', 'span', 'p', 'a', 'br', 'hr', 'img', 'ul', 'ol', 'li', 
-        'table', 'tr', 'td', 'th', 'thead', 'tbody', 'code', 'pre',
-        'strong', 'em', 'b', 'i', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
-        'Card', 'CardGroup', 'Note', 'Warning', 'Info', 'Tip', 'Check',
-        'Danger', 'Accordion', 'AccordionGroup', 'Tab', 'Tabs', 'Step',
-        'Steps', 'Frame', 'Icon', 'Badge', 'Tooltip', 'CodeGroup',
-        'Expandable', 'ParamField', 'ResponseField', 'Columns', 'Column',
-        'RequestExample', 'ResponseExample', 'Banner', 'Update', 'View',
-        'Tree', 'Tile', 'Tiles', 'Panel', 'Color'
-    }
 
     for i, line in enumerate(lines, 1):
         stripped = line.strip()
@@ -196,7 +379,9 @@ def validate_mdx(content: str) -> List[str]:
         angle_matches = re.findall(r'(?<!`)(<[a-zA-Z_][a-zA-Z0-9_]*>)(?!`)', line)
         for match in angle_matches:
             tag = match[1:-1]
-            if tag not in VALID_MDX_TAGS and tag.lower() not in {t.lower() for t in VALID_MDX_TAGS if t.islower()}:
+            # Mirror escape_mdx's allowlist exactly so the two stay in lockstep:
+            # HTML tags are case-insensitive, JSX components are case-sensitive.
+            if not _is_valid_mdx_tag(tag):
                 errors.append(f"Line {i}: Unescaped JSX-like tag: {match}")
         
         curly_matches = re.findall(r'(?<!`)(?<!=)\{([a-zA-Z_][a-zA-Z0-9_]*)\}(?!`)', line)
@@ -210,10 +395,13 @@ def escape_for_table(text: str, is_type: bool = False) -> str:
     """Escape text for use in markdown tables."""
     if not text:
         return text
-    
-    if is_type:
+
+    # Always simplify complex type signatures containing nested brackets
+    # (e.g. ``Callable[[...], ...]``); these break MDX table rendering even
+    # when the caller did not explicitly flag the value as a type.
+    if is_type or "[[" in text:
         text = sanitize_type_for_mdx(text) or text
-        
+
     text = text.replace('|', '\\|')
     # Use HTML entities for angle brackets to avoid tag confusion
     text = text.replace('<', '&lt;').replace('>', '&gt;')
@@ -221,6 +409,48 @@ def escape_for_table(text: str, is_type: bool = False) -> str:
     return text
 
 
+def validate_docs_json_structure(config: Dict[str, Any]) -> List[str]:
+    """Validate the structure of a docs.json navigation config.
+
+    Ensures the expected ``navigation.tabs`` -> ``SDK`` tab -> ``Reference``
+    group hierarchy exists before it is modified.
+
+    Args:
+        config: Parsed docs.json content.
+
+    Returns:
+        A list of error strings; empty if the structure is valid.
+    """
+    errors: List[str] = []
+
+    if not isinstance(config, dict):
+        return ["docs.json root must be an object"]
+
+    navigation = config.get("navigation")
+    if not isinstance(navigation, dict):
+        return ["Missing or invalid 'navigation' object"]
+
+    tabs = navigation.get("tabs")
+    if not isinstance(tabs, list):
+        return ["Missing or invalid 'navigation.tabs' array"]
+
+    sdk_tab = next((t for t in tabs if isinstance(t, dict) and t.get("tab") == "SDK"), None)
+    if sdk_tab is None:
+        errors.append("Missing 'SDK' tab in navigation.tabs")
+        return errors
+
+    groups = sdk_tab.get("groups")
+    if not isinstance(groups, list):
+        errors.append("Missing or invalid 'groups' in SDK tab")
+        return errors
+
+    ref_group = next((g for g in groups if isinstance(g, dict) and g.get("group") == "Reference"), None)
+    if ref_group is None:
+        errors.append("Missing 'Reference' group in SDK tab")
+
+    return errors
+
+
 def sanitize_description(text: str, max_length: int = 150) -> str:
     """Sanitize description for YAML frontmatter. Truncates at word boundary."""
     if not text:
@@ -1657,6 +1887,9 @@ ICON_MAP = {
     "workflows": "route",
     "telemetry": "chart-line",
     "search": "magnifying-glass",
+    "hooks": "link",
+    "mcp": "plug",
+    "policy": "gavel",
     
     # Modules & Integration
     "a2a": "network-wired",
@@ -2223,11 +2456,12 @@ class TypeScriptDocParser:
 class MDXGenerator:
     """Generate MDX documentation files."""
     
-    def __init__(self, output_dir: Path, package_name: str, config: Dict[str, Any], layout: LayoutType = LayoutType.LEGACY):
+    def __init__(self, output_dir: Path, package_name: str, config: Dict[str, Any], layout: LayoutType = LayoutType.LEGACY, docs_root: Optional[Path] = None):
         self.output_dir = output_dir
         self.package_name = package_name
         self.config = config
         self.layout = layout
+        self.docs_root = docs_root or output_dir
         self.generated_files = set()  # Use set for faster lookups and cleanup
         # Index for "Used By" cross-references: {function_name: [(caller_name, caller_path), ...]}
         self.used_by_index: Dict[str, List[Tuple[str, str]]] = {}
@@ -2345,8 +2579,7 @@ class MDXGenerator:
         return generated
 
     def _track_file(self, path: Path):
-        docs_root = Path("/Users/praison/PraisonAIDocs")
-        rel_path = str(path.relative_to(docs_root))
+        rel_path = str(path.relative_to(self.docs_root))
         nav_path = rel_path.replace('.mdx', '').replace('\\', '/')
         self.generated_files.add(nav_path)
     
@@ -2892,7 +3125,15 @@ class ReferenceDocsGenerator:
         layout: LayoutType = LayoutType.GRANULAR
     ):
         self.docs_root = Path(docs_root)
-        self.docs_json_path = self.docs_root / "docs.json"
+        # Mintlify subpath hosting uses docs/docs.json (see PraisonAIDocs migrate script).
+        docs_json_in_docs = self.docs_root / "docs" / "docs.json"
+        docs_json_at_root = self.docs_root / "docs.json"
+        if docs_json_in_docs.exists():
+            self.docs_json_path = docs_json_in_docs
+        elif docs_json_at_root.exists():
+            self.docs_json_path = docs_json_at_root
+        else:
+            self.docs_json_path = docs_json_in_docs
         self.layout = layout
         
         # Base source root - default to local development path if not provided
@@ -2969,7 +3210,7 @@ class ReferenceDocsGenerator:
             workspace_parser = RustWorkspaceParser(config["source"])
             # Parse all crates in the workspace
             all_modules = workspace_parser.parse_all()
-            generator = MDXGenerator(config["output"], package_name, config, layout=self.layout)
+            generator = MDXGenerator(config["output"], package_name, config, layout=self.layout, docs_root=self.docs_root)
             generated = 0
             for crate_name, modules in all_modules.items():
                 print(f"  Crate: {crate_name} ({len(modules)} modules)")
@@ -2995,7 +3236,7 @@ class ReferenceDocsGenerator:
         else:
             parser = PythonDocParser(config["source"], config["import_prefix"])
         
-        generator = MDXGenerator(config["output"], package_name, config, layout=self.layout)
+        generator = MDXGenerator(config["output"], package_name, config, layout=self.layout, docs_root=self.docs_root)
         modules = parser.get_modules()
         print(f"Found {len(modules)} modules")
         
@@ -3039,14 +3280,13 @@ class ReferenceDocsGenerator:
 
     def cleanup_orphaned_files(self, output_dir: Path, current_files: set):
         """Delete MDX files that are no longer part of the generated set."""
-        docs_root = Path("/Users/praison/PraisonAIDocs")
         for sub_dir in ["functions", "classes", "modules"]:
             target_dir = output_dir / sub_dir
             if not target_dir.exists():
                 continue
                 
             for mdx_file in target_dir.glob("*.mdx"):
-                rel_path = str(mdx_file.relative_to(docs_root))
+                rel_path = str(mdx_file.relative_to(self.docs_root))
                 nav_path = rel_path.replace('.mdx', '').replace('\\', '/')
                 if nav_path not in current_files:
                     print(f"    Deleting orphaned file: {mdx_file.name}")
@@ -3095,9 +3335,16 @@ class ReferenceDocsGenerator:
             
             with open(self.docs_json_path, 'w') as f:
                 json.dump(docs_config, f, indent=2)
-                
-        except Exception:
-            pass
+
+            if self.layout == LayoutType.GRANULAR:
+                page_count = sum(len(group.get('pages', [])) for group in package_group['pages'])
+            else:
+                page_count = len(package_group['pages'])
+            print(f"  Updated docs.json: {page_count} pages for {package_name}")
+
+        except Exception as exc:
+            print(f"  Error updating docs.json for {package_name}: {exc}")
+            raise
 
 if __name__ == "__main__":
     import argparse

praisonai_tools/registry_proxy/__init__.py

@@ -0,0 +1,43 @@
+"""Tool-registry proxy connector for PraisonAI Agents.
+
+Optional bring-your-own-account connector that lets an agent discover and call
+a large catalogue of third-party API endpoints through a single proxy token,
+with credentials injected server-side by the registry (never held by the agent).
+
+Mirrors PraisonAI's deferred tool-search bridge:
+    registry_search(query)      -> capability search over the catalogue
+    registry_describe(tool_id)  -> params, price-per-call, example response
+    registry_call(tool_id, ...) -> invoke via proxy (credential injected server-side)
+
+The connector is disabled unless ``TOOL_PROXY_URL`` is configured. PraisonAI
+ships no registry code, no bundled binary and no default endpoint - the user
+supplies their own account token or self-hosted base URL.
+
+Usage:
+    from praisonai_tools.registry_proxy import (
+        registry_search, registry_describe, registry_call,
+    )
+
+    agent = Agent(
+        instructions="SEO analyst",
+        tools=[registry_search, registry_describe, registry_call],
+    )
+
+Environment Variables:
+    TOOL_PROXY_URL:   base URL of the tool registry (unset -> connector disabled)
+    TOOL_PROXY_TOKEN: proxy token sent as the auth header
+"""
+
+from .registry_proxy import (
+    RegistryProxyTool,
+    registry_search,
+    registry_describe,
+    registry_call,
+)
+
+__all__ = [
+    "RegistryProxyTool",
+    "registry_search",
+    "registry_describe",
+    "registry_call",
+]

praisonai_tools/registry_proxy/registry_proxy.py

@@ -0,0 +1,533 @@
+"""Tool-registry proxy connector implementation.
+
+Three agent-callable functions over a registry's plain-HTTP surface:
+
+- ``registry_search(query)``     free capability search over the catalogue
+- ``registry_describe(tool_id)`` free read: params, price-per-call, example
+- ``registry_call(tool_id, ...)``paid invoke through the proxy; the registry
+  injects the upstream vendor credential server-side.
+
+Design notes:
+- ``httpx`` is lazy-imported so the connector adds zero import-time overhead and
+  no hard dependency when unconfigured.
+- The connector is disabled unless ``TOOL_PROXY_URL`` is set.
+- Errors (auth / insufficient balance / upstream 4xx / timeout) are returned as
+  ``{"error": ...}`` tool results, never raised as exceptions.
+- ``registry_call`` supports optional per-call and per-session spend guards; the
+  price is read from ``registry_describe`` and the call is denied + reported when
+  a configured budget would be exceeded.
+"""
+
+import os
+import math
+import logging
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from praisonai_tools.tools.base import BaseTool
+from praisonai_tools.tools.decorator import tool
+
+logger = logging.getLogger(__name__)
+
+_INSTALL_HINT = "httpx not installed. Install with: pip install 'praisonai-tools[registry-proxy]'"
+
+# Cumulative spend is tracked per (proxy_url, token) so that ``max_session_spend``
+# persists across the short-lived connector instances created by the decorated
+# functions, without mixing budgets across distinct accounts/endpoints.
+_SESSION_SPEND: Dict[tuple, float] = {}
+
+# The registry enforces the endpoint's declared HTTP method on ``/call/{id}``.
+# Restricting to a known set keeps the wire behaviour predictable and returns a
+# clear tool-result error instead of forwarding a mislabelled/unexpected verb.
+_ALLOWED_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
+
+
+class RegistryProxyTool(BaseTool):
+    """Connector for a self-hostable tool registry exposing a plain-HTTP proxy."""
+
+    name = "registry_proxy"
+    description = (
+        "Discover and call third-party API endpoints through a tool registry "
+        "proxy; credentials are injected server-side, never held by the agent."
+    )
+
+    def __init__(
+        self,
+        proxy_url: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: float = 60.0,
+        max_cost_per_call: Optional[float] = None,
+        max_session_spend: Optional[float] = None,
+        auth_header: Optional[str] = None,
+        describe_path: Optional[str] = None,
+    ):
+        url_from_env = proxy_url is None
+        self.proxy_url = (proxy_url or os.getenv("TOOL_PROXY_URL") or "").rstrip("/")
+        # Security: only fall back to the environment token when the URL is also
+        # env-derived (trusted config). An agent-supplied ``proxy_url`` must never
+        # receive the ambient ``TOOL_PROXY_TOKEN`` - otherwise a prompt-injected
+        # agent could exfiltrate the token to an attacker-controlled endpoint.
+        if token is not None:
+            self.token = token
+        elif url_from_env:
+            self.token = os.getenv("TOOL_PROXY_TOKEN")
+        else:
+            self.token = None
+        # Auth header is configurable for wire-compatibility with different
+        # registry deployments. Default ``Authorization`` sends ``Bearer {token}``;
+        # a custom header name (e.g. ``X-Treg-Token``) sends the raw token instead.
+        self.auth_header = auth_header or os.getenv("TOOL_PROXY_AUTH_HEADER") or "Authorization"
+        # The describe path template is configurable for wire-compatibility with
+        # different registry deployments. It must contain ``{tool_id}``; the
+        # default mirrors the live registry route (``/catalog/endpoints/{id}``).
+        self.describe_path = (
+            describe_path
+            or os.getenv("TOOL_PROXY_DESCRIBE_PATH")
+            or "/catalog/endpoints/{tool_id}"
+        )
+        self.timeout = timeout
+        self.max_cost_per_call = max_cost_per_call
+        self.max_session_spend = max_session_spend
+        super().__init__()
+
+    @property
+    def _spend_key(self) -> tuple:
+        return (self.proxy_url, self.token)
+
+    @property
+    def _session_spend(self) -> float:
+        return _SESSION_SPEND.get(self._spend_key, 0.0)
+
+    @_session_spend.setter
+    def _session_spend(self, value: float) -> None:
+        _SESSION_SPEND[self._spend_key] = value
+
+    def run(self, action: str, **kwargs: Any) -> Dict[str, Any]:
+        """Dispatch to search/describe/call.
+
+        Args:
+            action: One of ``"search"``, ``"describe"`` or ``"call"``.
+            **kwargs: Arguments forwarded to the selected operation.
+        """
+        if action == "search":
+            return self.search(kwargs.get("query", ""))
+        if action == "describe":
+            return self.describe(kwargs.get("tool_id", ""))
+        if action == "call":
+            return self.call(
+                kwargs.get("tool_id", ""),
+                kwargs.get("params"),
+                kwargs.get("method"),
+            )
+        return {"error": f"Unknown action '{action}'. Use search, describe or call."}
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            if self.auth_header.lower() == "authorization":
+                headers[self.auth_header] = f"Bearer {self.token}"
+            else:
+                headers[self.auth_header] = self.token
+        return headers
+
+    def _require_config(self) -> Optional[Dict[str, Any]]:
+        if not self.proxy_url:
+            return {
+                "error": (
+                    "Tool registry proxy is not configured. Set TOOL_PROXY_URL "
+                    "(and optionally TOOL_PROXY_TOKEN) to enable the connector."
+                )
+            }
+        return None
+
+    @staticmethod
+    def _http_error(exc: Any) -> Dict[str, Any]:
+        response = getattr(exc, "response", None)
+        status = getattr(response, "status_code", None)
+        text = getattr(response, "text", "") if response is not None else str(exc)
+        if status == 401 or status == 403:
+            return {"error": f"Authentication failed (HTTP {status}): {text}"}
+        if status == 402:
+            return {"error": f"Insufficient balance (HTTP {status}): {text}"}
+        return {"error": f"HTTP {status}: {text}"}
+
+    def search(self, query: str) -> Dict[str, Any]:
+        """Search the registry catalogue by capability."""
+        missing = self._require_config()
+        if missing:
+            return missing
+        if not query:
+            return {"error": "query is required"}
+        try:
+            import httpx
+        except ImportError:
+            return {"error": _INSTALL_HINT}
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(
+                    f"{self.proxy_url}/catalog/search",
+                    params={"q": query},
+                    headers=self._headers(),
+                )
+                response.raise_for_status()
+                return response.json()
+        except httpx.TimeoutException:
+            return {"error": f"Registry search timed out after {self.timeout} seconds"}
+        except httpx.HTTPStatusError as exc:
+            return self._http_error(exc)
+        except Exception as exc:  # noqa: BLE001 - surface as tool-result error
+            logger.error("registry search error: %s", exc)
+            return {"error": str(exc)}
+
+    def describe(self, tool_id: str) -> Dict[str, Any]:
+        """Describe one catalogue entry: params, price-per-call, example."""
+        missing = self._require_config()
+        if missing:
+            return missing
+        if not tool_id:
+            return {"error": "tool_id is required"}
+        try:
+            import httpx
+        except ImportError:
+            return {"error": _INSTALL_HINT}
+        if "{tool_id}" not in self.describe_path:
+            return {
+                "error": (
+                    f"Invalid describe path template '{self.describe_path}': "
+                    "it must contain '{tool_id}'."
+                )
+            }
+        try:
+            path = self.describe_path.format(tool_id=quote(tool_id, safe=""))
+        except (KeyError, IndexError, ValueError) as exc:
+            return {
+                "error": (
+                    f"Invalid describe path template '{self.describe_path}': {exc}"
+                )
+            }
+        if not path.startswith("/"):
+            path = "/" + path
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(
+                    f"{self.proxy_url}{path}",
+                    headers=self._headers(),
+                )
+                response.raise_for_status()
+                return response.json()
+        except httpx.TimeoutException:
+            return {"error": f"Registry describe timed out after {self.timeout} seconds"}
+        except httpx.HTTPStatusError as exc:
+            return self._http_error(exc)
+        except Exception as exc:  # noqa: BLE001 - surface as tool-result error
+            logger.error("registry describe error: %s", exc)
+            return {"error": str(exc)}
+
+    @staticmethod
+    def _unwrap_envelope(data: Any) -> Any:
+        """Return the dict that carries the endpoint fields.
+
+        The live registry nests ``method``/``cost`` under an ``endpoint`` key
+        (``{"endpoint": {...}, "provider": {}, ...}``); flatter registry
+        implementations put them at the top level. Prefer ``data["endpoint"]``
+        when it is a dict, else use ``data`` itself.
+        """
+        if not isinstance(data, dict):
+            return data
+        endpoint = data.get("endpoint")
+        if isinstance(endpoint, dict):
+            return endpoint
+        return data
+
+    @classmethod
+    def _extract_method(cls, data: Any) -> Optional[str]:
+        """Read the HTTP method from a describe response, if present.
+
+        The live registry's endpoint doc carries ``method: "GET"`` (or POST/PUT)
+        nested under ``endpoint``; the registry enforces the declared method on
+        ``/call/{id}``. Flat implementations expose it at the top level.
+        """
+        data = cls._unwrap_envelope(data)
+        if not isinstance(data, dict):
+            return None
+        method = data.get("method")
+        if isinstance(method, str) and method.strip():
+            return method.strip().upper()
+        return None
+
+    @classmethod
+    def _extract_price(cls, data: Any) -> Any:
+        """Read a price from a response, tolerating field-name/shape variation.
+
+        Unwraps the ``endpoint`` envelope, then tries ``price_per_call`` then
+        ``price`` then ``cost`` so the budget check and spend recording share the
+        same tolerance against the live schema. ``cost`` may be a structured
+        object (``{"value": 25, "currency": "credit", "usd": 0.0299, ...}``); in
+        that case prefer ``usd`` since the guard budgets are in USD (``value`` is
+        in provider credits). Flat numeric forms are returned unchanged.
+        """
+        data = cls._unwrap_envelope(data)
+        if not isinstance(data, dict):
+            return None
+        for key in ("price_per_call", "price", "cost"):
+            if key in data:
+                value = data[key]
+                if isinstance(value, dict):
+                    return value.get("usd")
+                return value
+        return None
+
+    def _check_budget(self, tool_id: str):
+        """Deny + report if a configured spend guard would be exceeded.
+
+        Returns ``(denial, price, described)``: ``denial`` is a ``{"error": ...}``
+        dict when the call must be rejected (else ``None``); ``price`` is the
+        validated per-call price when a guard applies (else ``None``);
+        ``described`` is the describe response fetched for the guard (else
+        ``None``) so the caller can reuse it (e.g. to derive the HTTP method)
+        without a second network round-trip.
+        """
+        if self.max_cost_per_call is None and self.max_session_spend is None:
+            return None, None, None
+        described = self.describe(tool_id)
+        if isinstance(described, dict) and "error" in described:
+            return described, None, None
+        # Accept the same price field names tolerated by spend recording so the
+        # budget check does not fail closed on a field-name mismatch against the
+        # live registry schema (``price_per_call`` -> ``price`` -> ``cost``).
+        price = self._extract_price(described)
+        try:
+            price = float(price)
+        except (TypeError, ValueError):
+            # Fail closed: a spend guard is configured but the price cannot be
+            # validated, so we cannot guarantee the budget - deny the call.
+            return {
+                "error": (
+                    "Denied: price (price_per_call/price/cost) is missing or "
+                    "invalid, cannot enforce the configured spend guard."
+                )
+            }, None, described
+        # Fail closed on non-finite (NaN/inf) or negative prices: NaN comparisons
+        # are always false, so an unvalidated NaN would silently bypass both the
+        # per-call and session guards and then corrupt ``_session_spend``.
+        if not math.isfinite(price) or price < 0:
+            return {
+                "error": (
+                    "Denied: price (price_per_call/price/cost) is missing or "
+                    "invalid, cannot enforce the configured spend guard."
+                )
+            }, None, described
+        if self.max_cost_per_call is not None and price > self.max_cost_per_call:
+            return {
+                "error": (
+                    f"Denied: price per call {price} exceeds max_cost_per_call "
+                    f"{self.max_cost_per_call}."
+                )
+            }, price, described
+        if (
+            self.max_session_spend is not None
+            and self._session_spend + price > self.max_session_spend
+        ):
+            return {
+                "error": (
+                    f"Denied: session spend would reach "
+                    f"{self._session_spend + price}, exceeding max_session_spend "
+                    f"{self.max_session_spend}."
+                )
+            }, price, described
+        return None, price, described
+
+    def call(
+        self,
+        tool_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        method: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Invoke an endpoint through the proxy (credential injected server-side).
+
+        The registry enforces each endpoint's declared HTTP method on
+        ``/call/{id}``. When ``method`` is not supplied it is derived from
+        ``describe`` (the endpoint doc carries ``method``); GET requests send
+        ``params`` as the query string, POST/PUT (and others) send them as a
+        JSON body.
+        """
+        missing = self._require_config()
+        if missing:
+            return missing
+        if not tool_id:
+            return {"error": "tool_id is required"}
+        denied, quoted_price, described = self._check_budget(tool_id)
+        if denied:
+            return denied
+        # Derive the HTTP method from the endpoint doc when not supplied. Reuse
+        # the describe fetched by the spend guard when present to avoid a second
+        # round-trip; otherwise fetch describe only when the method is unknown.
+        if method is None:
+            if described is None:
+                described = self.describe(tool_id)
+                if isinstance(described, dict) and "error" in described:
+                    return described
+            method = self._extract_method(described)
+        method = (method or "POST").strip().upper()
+        if method not in _ALLOWED_METHODS:
+            return {
+                "error": (
+                    f"Unsupported HTTP method '{method}'. Allowed: "
+                    f"{', '.join(sorted(_ALLOWED_METHODS))}."
+                )
+            }
+        try:
+            import httpx
+        except ImportError:
+            return {"error": _INSTALL_HINT}
+        url = f"{self.proxy_url}/call/{quote(tool_id, safe='')}"
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                if method == "GET":
+                    response = client.get(
+                        url, params=params or {}, headers=self._headers()
+                    )
+                else:
+                    response = client.request(
+                        method, url, json=params or {}, headers=self._headers()
+                    )
+                response.raise_for_status()
+                result = response.json()
+        except httpx.TimeoutException:
+            return {"error": f"Registry call timed out after {self.timeout} seconds"}
+        except httpx.HTTPStatusError as exc:
+            return self._http_error(exc)
+        except Exception as exc:  # noqa: BLE001 - surface as tool-result error
+            logger.error("registry call error: %s", exc)
+            return {"error": str(exc)}
+
+        # Record cumulative spend. Prefer the charge reported by the proxy; fall
+        # back to the price quoted at budget-check time so the session budget
+        # still accrues when the response omits cost fields.
+        charged = self._extract_price(result)
+        try:
+            charged = float(charged)
+            if not math.isfinite(charged) or charged < 0:
+                raise ValueError("non-finite or negative charge")
+        except (TypeError, ValueError):
+            # The response omitted a usable charge; fall back to the finite,
+            # non-negative price validated at budget-check time so a malformed
+            # (NaN/inf/negative) response cannot corrupt cumulative spend.
+            charged = quoted_price
+        if charged is not None:
+            self._session_spend += charged
+        return result
+
+
+@tool
+def registry_search(
+    query: str,
+    proxy_url: Optional[str] = None,
+    token: Optional[str] = None,
+    auth_header: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Search the connected tool registry by capability.
+
+    Free read. Returns catalogue matches for a natural-language capability query
+    such as "backlinks for a domain" or "company enrichment by email".
+
+    Args:
+        query: Capability to search for.
+        proxy_url: Registry base URL (defaults to TOOL_PROXY_URL env var).
+        token: Proxy token (defaults to TOOL_PROXY_TOKEN env var).
+        auth_header: Auth header name (defaults to TOOL_PROXY_AUTH_HEADER env var,
+            then ``Authorization``).
+
+    Returns:
+        Dict with catalogue matches, or ``{"error": ...}`` on failure.
+    """
+    return RegistryProxyTool(
+        proxy_url=proxy_url, token=token, auth_header=auth_header
+    ).search(query)
+
+
+@tool
+def registry_describe(
+    tool_id: str,
+    proxy_url: Optional[str] = None,
+    token: Optional[str] = None,
+    auth_header: Optional[str] = None,
+    describe_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Describe one registry catalogue entry.
+
+    Free read. Returns the endpoint's parameters, price-per-call and an example
+    response so the model can decide whether and how to invoke it.
+
+    Args:
+        tool_id: Catalogue entry identifier (from ``registry_search``).
+        proxy_url: Registry base URL (defaults to TOOL_PROXY_URL env var).
+        token: Proxy token (defaults to TOOL_PROXY_TOKEN env var).
+        auth_header: Auth header name (defaults to TOOL_PROXY_AUTH_HEADER env var,
+            then ``Authorization``).
+        describe_path: Path template for the describe route (defaults to
+            TOOL_PROXY_DESCRIBE_PATH env var, then ``/catalog/endpoints/{tool_id}``).
+            Must contain ``{tool_id}``.
+
+    Returns:
+        Dict describing the entry, or ``{"error": ...}`` on failure.
+    """
+    return RegistryProxyTool(
+        proxy_url=proxy_url, token=token, auth_header=auth_header,
+        describe_path=describe_path,
+    ).describe(tool_id)
+
+
+@tool
+def registry_call(
+    tool_id: str,
+    params: Optional[Dict[str, Any]] = None,
+    proxy_url: Optional[str] = None,
+    token: Optional[str] = None,
+    max_cost_per_call: Optional[float] = None,
+    max_session_spend: Optional[float] = None,
+    auth_header: Optional[str] = None,
+    method: Optional[str] = None,
+    describe_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Invoke a registry endpoint through the proxy.
+
+    Paid call. The registry injects the upstream vendor credential server-side,
+    so no vendor keys are ever held by the agent. Optional spend guards deny +
+    report the call when a configured budget would be exceeded.
+
+    The registry enforces each endpoint's declared HTTP method. When ``method``
+    is not supplied it is derived from ``registry_describe`` (the endpoint doc
+    carries ``method``); GET params are sent as the query string, POST/PUT as a
+    JSON body.
+
+    Note: passthrough-URL calls require the upstream to be registered on the
+    registry first; loopback/private upstreams are refused by the registry's
+    SSRF guard by design.
+
+    Args:
+        tool_id: Catalogue entry identifier (from ``registry_search``).
+        params: Parameters for the upstream endpoint.
+        proxy_url: Registry base URL (defaults to TOOL_PROXY_URL env var).
+        token: Proxy token (defaults to TOOL_PROXY_TOKEN env var).
+        max_cost_per_call: Deny the call if its price exceeds this value.
+        max_session_spend: Deny the call if it would push cumulative spend past this value.
+        auth_header: Auth header name (defaults to TOOL_PROXY_AUTH_HEADER env var,
+            then ``Authorization``). ``Authorization`` sends ``Bearer {token}``;
+            any other name (e.g. ``X-Treg-Token``) sends the raw token.
+        method: HTTP method for the endpoint (e.g. ``GET``/``POST``). When
+            omitted it is derived from the endpoint's describe doc.
+        describe_path: Path template for the describe route (defaults to
+            TOOL_PROXY_DESCRIBE_PATH env var, then ``/catalog/endpoints/{tool_id}``).
+
+    Returns:
+        Dict with the endpoint response, or ``{"error": ...}`` on failure/denial.
+    """
+    return RegistryProxyTool(
+        proxy_url=proxy_url,
+        token=token,
+        max_cost_per_call=max_cost_per_call,
+        max_session_spend=max_session_spend,
+        auth_header=auth_header,
+        describe_path=describe_path,
+    ).call(tool_id, params, method)

praisonai_tools/tools/__init__.py

@@ -14,913 +14,64 @@ Ready-to-use tools:
 - WeatherTool: Get weather data
 - YouTubeTool: Search YouTube, get transcripts
 - TTSTool: Text-to-speech conversion
+
+Tools are discovered automatically: adding a module under
+``praisonai_tools/tools/`` exposes its public top-level classes and functions
+without any manual registration. Imports remain lazy - a tool module (and its
+optional dependencies) is only imported the first time one of its symbols is
+accessed.
 """
 
+import os
+
 from praisonai_tools.tools.base import BaseTool, ToolResult, ToolValidationError, validate_tool
 from praisonai_tools.tools.decorator import tool, FunctionTool, is_tool, get_tool_schema
+from praisonai_tools.tools._discovery import build_manifest
 
-# Lazy imports for tools to avoid loading dependencies until needed
-def __getattr__(name):
-    """Lazy load tool classes."""
-    tool_map = {
-        # Email
-        "EmailTool": "email_tool",
-        "send_email": "email_tool",
-        "read_emails": "email_tool",
-        "search_emails": "email_tool",
-        # Slack
-        "SlackTool": "slack_tool",
-        "send_slack_message": "slack_tool",
-        "get_slack_channels": "slack_tool",
-        "get_slack_history": "slack_tool",
-        # Discord
-        "DiscordTool": "discord_tool",
-        "send_discord_webhook": "discord_tool",
-        "send_discord_message": "discord_tool",
-        # GitHub
-        "GitHubTool": "github_tool",
-        "search_github_repos": "github_tool",
-        "get_github_repo": "github_tool",
-        "create_github_issue": "github_tool",
-        # Image Generation
-        "ImageTool": "image_tool",
-        "generate_image": "image_tool",
-        # Weather
-        "WeatherTool": "weather_tool",
-        "get_weather": "weather_tool",
-        "get_forecast": "weather_tool",
-        "get_air_quality": "weather_tool",
-        # YouTube
-        "YouTubeTool": "youtube_tool",
-        "search_youtube": "youtube_tool",
-        "get_youtube_video": "youtube_tool",
-        "get_youtube_transcript": "youtube_tool",
-        # Text-to-Speech
-        "TTSTool": "tts_tool",
-        "text_to_speech": "tts_tool",
-        "list_tts_voices": "tts_tool",
-        # Telegram
-        "TelegramTool": "telegram_tool",
-        "send_telegram_message": "telegram_tool",
-        # Notion
-        "NotionTool": "notion_tool",
-        "search_notion": "notion_tool",
-        "create_notion_page": "notion_tool",
-        # PostgreSQL
-        "PostgresTool": "postgres_tool",
-        "query_postgres": "postgres_tool",
-        "list_postgres_tables": "postgres_tool",
-        # Reddit
-        "RedditTool": "reddit_tool",
-        "search_reddit": "reddit_tool",
-        "get_reddit_hot": "reddit_tool",
-        # Docker
-        "DockerTool": "docker_tool",
-        "list_docker_containers": "docker_tool",
-        "run_docker_container": "docker_tool",
-        # MySQL
-        "MySQLTool": "mysql_tool",
-        "query_mysql": "mysql_tool",
-        # SQLite
-        "SQLiteTool": "sqlite_tool",
-        "query_sqlite": "sqlite_tool",
-        # MongoDB
-        "MongoDBTool": "mongodb_tool",
-        "query_mongodb": "mongodb_tool",
-        # Redis
-        "RedisTool": "redis_tool",
-        "redis_get": "redis_tool",
-        "redis_set": "redis_tool",
-        # DuckDuckGo
-        "DuckDuckGoTool": "duckduckgo_tool",
-        "duckduckgo_search": "duckduckgo_tool",
-        # Tavily
-        "TavilyTool": "tavily_tool",
-        "tavily_search": "tavily_tool",
-        "tavily_extract": "tavily_tool",
-        # Wikipedia
-        "WikipediaTool": "wikipedia_tool",
-        "wikipedia_search": "wikipedia_tool",
-        # ArXiv
-        "ArxivTool": "arxiv_tool",
-        "arxiv_search": "arxiv_tool",
-        # SwarmScore
-        "SwarmScoreTool": "swarmscore_tool",
-        "load_swarmscore_by_slug": "swarmscore_tool",
-        "verify_swarmscore_freshness": "swarmscore_tool",
-        "get_agent_discovery_manifest": "swarmscore_tool",
-        # Calculator
-        "CalculatorTool": "calculator_tool",
-        "calculate": "calculator_tool",
-        # Shell
-        "ShellTool": "shell_tool",
-        "shell_execute": "shell_tool",
-        # File
-        "FileTool": "file_tool",
-        "read_file": "file_tool",
-        "write_file": "file_tool",
-        # Firecrawl
-        "FirecrawlTool": "firecrawl_tool",
-        "firecrawl_scrape": "firecrawl_tool",
-        "firecrawl_search": "firecrawl_tool",
-        # Serper
-        "SerperTool": "serper_tool",
-        "serper_search": "serper_tool",
-        # Jina
-        "JinaTool": "jina_tool",
-        "jina_read": "jina_tool",
-        # Google Calendar
-        "GoogleCalendarTool": "google_calendar_tool",
-        "list_calendar_events": "google_calendar_tool",
-        # Google Sheets
-        "GoogleSheetsTool": "google_sheets_tool",
-        "read_google_sheet": "google_sheets_tool",
-        # Jira
-        "JiraTool": "jira_tool",
-        "jira_search": "jira_tool",
-        "jira_list_boards": "jira_tool",
-        "jira_get_board": "jira_tool",
-        "jira_get_board_issues": "jira_tool",
-        "jira_get_backlog": "jira_tool",
-        "jira_get_transitions": "jira_tool",
-        "jira_move_issue": "jira_tool",
-        "jira_create_task": "jira_tool",
-        "jira_watch_issue": "jira_watch_tool",
-        "jira_watch_project": "jira_watch_tool",
-        "jira_get_issue_info": "jira_watch_tool",
-        "jira_search_issues": "jira_watch_tool",
-        "jira_tools": "jira_watch_tool",
-        # Trello
-        "TrelloTool": "trello_tool",
-        "list_trello_boards": "trello_tool",
-        # YFinance
-        "YFinanceTool": "yfinance_tool",
-        "get_stock_price": "yfinance_tool",
-        # Pinecone
-        "PineconeTool": "pinecone_tool",
-        "pinecone_query": "pinecone_tool",
-        # Qdrant
-        "QdrantTool": "qdrant_tool",
-        "qdrant_search": "qdrant_tool",
-        # Chroma
-        "ChromaTool": "chroma_tool",
-        "chroma_query": "chroma_tool",
-        # HackerNews
-        "HackerNewsTool": "hackernews_tool",
-        "get_hackernews_top": "hackernews_tool",
-        # Twilio
-        "TwilioTool": "twilio_tool",
-        "send_sms": "twilio_tool",
-        # Spotify
-        "SpotifyTool": "spotify_tool",
-        "spotify_search": "spotify_tool",
-        # Linear
-        "LinearTool": "linear_tool",
-        "list_linear_issues": "linear_tool",
-        # Crawl4AI
-        "Crawl4AITool": "crawl4ai_tool",
-        "crawl4ai_crawl": "crawl4ai_tool",
-        # Exa
-        "ExaTool": "exa_tool",
-        "exa_search": "exa_tool",
-        # DuckDB
-        "DuckDBTool": "duckdb_tool",
-        "duckdb_query": "duckdb_tool",
-        # Neo4j
-        "Neo4jTool": "neo4j_tool",
-        "neo4j_query": "neo4j_tool",
-        # Weaviate
-        "WeaviateTool": "weaviate_tool",
-        "weaviate_search": "weaviate_tool",
-        # LanceDB
-        "LanceDBTool": "lancedb_tool",
-        "lancedb_search": "lancedb_tool",
-        # Supabase
-        "SupabaseTool": "supabase_tool",
-        "supabase_select": "supabase_tool",
-        # Milvus
-        "MilvusTool": "milvus_tool",
-        "milvus_search": "milvus_tool",
-        # Google Maps
-        "GoogleMapsTool": "google_maps_tool",
-        "geocode_address": "google_maps_tool",
-        # Zendesk
-        "ZendeskTool": "zendesk_tool",
-        "list_zendesk_tickets": "zendesk_tool",
-        # Shopify
-        "ShopifyTool": "shopify_tool",
-        "list_shopify_products": "shopify_tool",
-        # Brave Search
-        "BraveSearchTool": "brave_search_tool",
-        "brave_search": "brave_search_tool",
-        # PubMed
-        "PubMedTool": "pubmed_tool",
-        "pubmed_search": "pubmed_tool",
-        # SerpAPI
-        "SerpAPITool": "serpapi_tool",
-        "serpapi_search": "serpapi_tool",
-        # SearxNG
-        "SearxNGTool": "searxng_tool",
-        "searxng_search": "searxng_tool",
-        # LinkUp
-        "LinkUpTool": "linkup_tool",
-        "linkup_search": "linkup_tool",
-        # Baidu Search
-        "BaiduSearchTool": "baidu_search_tool",
-        "baidu_search": "baidu_search_tool",
-        # Valyu
-        "ValyuTool": "valyu_tool",
-        "valyu_search": "valyu_tool",
-        # Gmail
-        "GmailTool": "gmail_tool",
-        "list_gmail_emails": "gmail_tool",
-        "gmail_archive_email": "gmail_tool",
-        "gmail_label_email": "gmail_tool",
-        "gmail_mark_read": "gmail_tool",
-        "gmail_draft_email": "gmail_tool",
-        "gmail_trash_email": "gmail_tool",
-        # Outlook
-        "OutlookTool": "outlook_tool",
-        "outlook_list_emails": "outlook_tool",
-        "outlook_send_email": "outlook_tool",
-        "outlook_search_emails": "outlook_tool",
-        "outlook_archive_email": "outlook_tool",
-        "outlook_draft_email": "outlook_tool",
-        # WhatsApp
-        "WhatsAppTool": "whatsapp_tool",
-        "send_whatsapp_message": "whatsapp_tool",
-        # Signal
-        "SignalTool": "signal_tool",
-        "send_signal_message": "signal_tool",
-        "check_signal_connection": "signal_tool",
-        # LINE
-        "LineTool": "line_tool",
-        "send_line_message": "line_tool",
-        "broadcast_line_message": "line_tool",
-        # iMessage
-        "iMessageTool": "imessage_tool",
-        "send_imessage": "imessage_tool",
-        "check_imessage_availability": "imessage_tool",
-        # Zoom
-        "ZoomTool": "zoom_tool",
-        "list_zoom_meetings": "zoom_tool",
-        # Webex
-        "WebexTool": "webex_tool",
-        "list_webex_rooms": "webex_tool",
-        # X (Twitter)
-        "XTool": "x_tool",
-        "post_to_x": "x_tool",
-        # Newspaper
-        "NewspaperTool": "newspaper_tool",
-        "extract_article": "newspaper_tool",
-        # Trafilatura
-        "TrafilaturaTool": "trafilatura_tool",
-        "trafilatura_extract": "trafilatura_tool",
-        # Spider
-        "SpiderTool": "spider_tool",
-        "spider_crawl": "spider_tool",
-        # BrowserBase
-        "BrowserBaseTool": "browserbase_tool",
-        "browserbase_scrape": "browserbase_tool",
-        # BrightData
-        "BrightDataTool": "brightdata_tool",
-        "brightdata_scrape": "brightdata_tool",
-        # Oxylabs
-        "OxylabsTool": "oxylabs_tool",
-        "oxylabs_scrape": "oxylabs_tool",
-        # ScrapeGraph
-        "ScrapeGraphTool": "scrapegraph_tool",
-        "scrapegraph_scrape": "scrapegraph_tool",
-        # AgentQL
-        "AgentQLTool": "agentql_tool",
-        "agentql_query": "agentql_tool",
-        # DynamoDB
-        "DynamoDBTool": "dynamodb_tool",
-        "dynamodb_scan": "dynamodb_tool",
-        # Firestore
-        "FirestoreTool": "firestore_tool",
-        "firestore_list": "firestore_tool",
-        # GCS
-        "GCSTool": "gcs_tool",
-        "gcs_list_objects": "gcs_tool",
-        # BigQuery
-        "BigQueryTool": "bigquery_tool",
-        "bigquery_query": "bigquery_tool",
-        # SingleStore
-        "SingleStoreTool": "singlestore_tool",
-        "singlestore_query": "singlestore_tool",
-        # SurrealDB
-        "SurrealDBTool": "surrealdb_tool",
-        "surrealdb_query": "surrealdb_tool",
-        # CSV
-        "CSVTool": "csv_tool",
-        "read_csv": "csv_tool",
-        # Pandas
-        "PandasTool": "pandas_tool",
-        "pandas_read_csv": "pandas_tool",
-        # Redshift
-        "RedshiftTool": "redshift_tool",
-        "redshift_query": "redshift_tool",
-        # ElevenLabs
-        "ElevenLabsTool": "elevenlabs_tool",
-        "elevenlabs_speak": "elevenlabs_tool",
-        "elevenlabs_speak_to_file": "elevenlabs_tool",
-        "elevenlabs_list_voices": "elevenlabs_tool",
-        "elevenlabs_get_voice": "elevenlabs_tool",
-        "elevenlabs_list_models": "elevenlabs_tool",
-        "elevenlabs_get_history": "elevenlabs_tool",
-        "elevenlabs_get_user_info": "elevenlabs_tool",
-        # Replicate
-        "ReplicateTool": "replicate_tool",
-        "replicate_run": "replicate_tool",
-        # Fal
-        "FalTool": "fal_tool",
-        "fal_run": "fal_tool",
-        # Giphy
-        "GiphyTool": "giphy_tool",
-        "giphy_search": "giphy_tool",
-        # Apify
-        "ApifyTool": "apify_tool",
-        "apify_run_actor": "apify_tool",
-        # Airflow
-        "AirflowTool": "airflow_tool",
-        "list_airflow_dags": "airflow_tool",
-        # AWS Lambda
-        "AWSLambdaTool": "aws_lambda_tool",
-        "invoke_lambda": "aws_lambda_tool",
-        # AWS SES
-        "AWSSESTool": "aws_ses_tool",
-        "ses_send_email": "aws_ses_tool",
-        # Resend
-        "ResendTool": "resend_tool",
-        "resend_send_email": "resend_tool",
-        # ClickUp
-        "ClickUpTool": "clickup_tool",
-        "clickup_list_tasks": "clickup_tool",
-        # Confluence
-        "ConfluenceTool": "confluence_tool",
-        "confluence_search": "confluence_tool",
-        # Todoist
-        "TodoistTool": "todoist_tool",
-        "todoist_list_tasks": "todoist_tool",
-        # Bitbucket
-        "BitbucketTool": "bitbucket_tool",
-        "bitbucket_list_repos": "bitbucket_tool",
-        # OpenBB
-        "OpenBBTool": "openbb_tool",
-        "openbb_stock": "openbb_tool",
-        # E2B
-        "E2BTool": "e2b_tool",
-        "e2b_run_code": "e2b_tool",
-        # Sleep
-        "SleepTool": "sleep_tool",
-        "sleep_wait": "sleep_tool",
-        # Python
-        "PythonTool": "python_tool",
-        "python_execute": "python_tool",
-        # Capsule
-        "CapsuleTool": "capsule_tool",
-        "capsule_run_code": "capsule_tool",
-        # Mem0
-        "Mem0Tool": "mem0_tool",
-        "mem0_add": "mem0_tool",
-        # PGVector
-        "PGVectorTool": "pgvector_tool",
-        "pgvector_search": "pgvector_tool",
-        # Cassandra
-        "CassandraTool": "cassandra_tool",
-        "cassandra_query": "cassandra_tool",
-        # ClickHouse
-        "ClickHouseTool": "clickhouse_tool",
-        "clickhouse_query": "clickhouse_tool",
-        # Upstash
-        "UpstashTool": "upstash_tool",
-        "upstash_get": "upstash_tool",
-        # Couchbase
-        "CouchbaseTool": "couchbase_tool",
-        "couchbase_get": "couchbase_tool",
-        # Google Drive
-        "GoogleDriveTool": "google_drive_tool",
-        "list_drive_files": "google_drive_tool",
-        # LumaLabs
-        "LumaLabsTool": "lumalabs_tool",
-        "lumalabs_generate": "lumalabs_tool",
-        # Langextract
-        "LangExtractTool": "langextract_tool",
-        "langextract_extract": "langextract_tool",
-        "langextract_render_file": "langextract_tool",
-# HeyGen
-        "HeyGenTool": "heygen_tool",
-        "heygen_list_avatars": "heygen_tool",
-        "heygen_list_avatar_groups": "heygen_tool",
-        "heygen_list_group_avatars": "heygen_tool",
-        "heygen_get_avatar_details": "heygen_tool",
-        "heygen_list_voices": "heygen_tool",
-        "heygen_list_voice_locales": "heygen_tool",
-        "heygen_generate_video": "heygen_tool",
-        "heygen_generate_video_with_audio": "heygen_tool",
-        "heygen_upload_asset": "heygen_tool",
-        "heygen_video_status": "heygen_tool",
-        "heygen_wait_for_video": "heygen_tool",
-        "heygen_list_videos": "heygen_tool",
-        "heygen_delete_video": "heygen_tool",
-        "heygen_list_assets": "heygen_tool",
-        "heygen_delete_asset": "heygen_tool",
-        "heygen_get_remaining_quota": "heygen_tool",
-        "heygen_get_user_info": "heygen_tool",
-        "heygen_list_templates": "heygen_tool",
-        "heygen_generate_from_template": "heygen_tool",
-        "heygen_translate_video": "heygen_tool",
-# Higgsfield
-        "HiggsfieldTool": "higgsfield_tool",
-        "higgsfield_generate": "higgsfield_tool",
-        "higgsfield_status": "higgsfield_tool",
-        "higgsfield_upload": "higgsfield_tool",
-        # OpenCV
-        "OpenCVTool": "opencv_tool",
-        "opencv_resize": "opencv_tool",
-        # CalCom
-        "CalComTool": "calcom_tool",
-        "calcom_list_bookings": "calcom_tool",
-        # Cartesia
-        "CartesiaTool": "cartesia_tool",
-        "cartesia_speak": "cartesia_tool",
-        # Brandfetch
-        "BrandfetchTool": "brandfetch_tool",
-        "brandfetch_get_brand": "brandfetch_tool",
-        # Daytona
-        "DaytonaTool": "daytona_tool",
-        "daytona_list_workspaces": "daytona_tool",
-        # Composio
-        "ComposioTool": "composio_tool",
-        "ComposioTools": "composio_tool",
-        "composio_execute": "composio_tool",
-        "composio_tools": "composio_tool",
-        "composio_list_apps": "composio_tool",
-        # JSON
-        "JSONTool": "json_tool",
-        "read_json": "json_tool",
-        # Zep
-        "ZepTool": "zep_tool",
-        "zep_add_memory": "zep_tool",
-        # WebBrowser
-        "WebBrowserTool": "webbrowser_tool",
-        "webbrowser_get_page": "webbrowser_tool",
-        # WebTools
-        "WebToolsTool": "webtools_tool",
-        "webtools_fetch": "webtools_tool",
-        # LocalFileSystem
-        "LocalFileSystemTool": "local_filesystem_tool",
-        "list_local_directory": "local_filesystem_tool",
-        # Knowledge
-        "KnowledgeTool": "knowledge_tool",
-        "knowledge_search": "knowledge_tool",
-        # Visualization
-        "VisualizationTool": "visualization_tool",
-        "create_bar_chart": "visualization_tool",
-        "SQLiteVectorTool": "sqlite_vector_tool",
-        "sqlite_vector_query": "sqlite_vector_tool",
-        "sqlite_vector_add": "sqlite_vector_tool",
-        # WordPress
-        "WordPressTool": "wordpress_tool",
-        "check_wp_duplicate": "wordpress_tool",
-        "create_wp_post": "wordpress_tool",
-        # Marketplace Tools
-        "PinchworkTool": "pinchwork_tool",
-        "pinchwork_delegate": "pinchwork_tool",
-        "AgentIDTool": "agentid_tool",
-        "verify_agent_identity": "agentid_tool",
-        "JoyTrustTool": "joy_trust_tool",
-        "check_trust_score": "joy_trust_tool",
-        "verify_handoff_safety": "joy_trust_tool",
-        "trust_verified_handoff": "joy_trust_tool",
-        "is_trust_verification_enabled": "joy_trust_tool",
-        "get_trust_config": "joy_trust_tool",
-        "AgentFolioTool": "agentfolio_tool",
-        "check_behavioral_trust": "agentfolio_tool",
-        "verify_task_delegation_safety": "agentfolio_tool",
-        # LinkedIn
-        "LinkedInTool": "linkedin_tool",
-        "linkedin_post_text": "linkedin_tool",
-        "linkedin_post_image": "linkedin_tool",
-        "linkedin_post_article": "linkedin_tool",
-        "linkedin_get_profile": "linkedin_tool",
-        "linkedin_delete_post": "linkedin_tool",
-        # Facebook
-        "FacebookTool": "facebook_tool",
-        "facebook_post_text": "facebook_tool",
-        "facebook_post_image": "facebook_tool",
-        "facebook_post_link": "facebook_tool",
-        "facebook_post_video": "facebook_tool",
-        "facebook_get_page_info": "facebook_tool",
-        "facebook_delete_post": "facebook_tool",
-        # Instagram
-        "InstagramTool": "instagram_tool",
-        "instagram_post_image": "instagram_tool",
-        "instagram_post_carousel": "instagram_tool",
-        "instagram_post_reel": "instagram_tool",
-        "instagram_get_media": "instagram_tool",
-        "instagram_get_account_info": "instagram_tool",
-        # TikTok
-        "TikTokTool": "tiktok_tool",
-        "tiktok_post_video": "tiktok_tool",
-        "tiktok_post_photo": "tiktok_tool",
-        "tiktok_get_creator_info": "tiktok_tool",
-        "tiktok_get_post_status": "tiktok_tool",
-        # Threads
-        "ThreadsTool": "threads_tool",
-        "threads_post_text": "threads_tool",
-        "threads_post_image": "threads_tool",
-        "threads_post_video": "threads_tool",
-        "threads_get_threads": "threads_tool",
-        "threads_get_profile": "threads_tool",
-        # Pinterest
-        "PinterestTool": "pinterest_tool",
-        "pinterest_create_pin": "pinterest_tool",
-        "pinterest_list_boards": "pinterest_tool",
-        "pinterest_get_pin": "pinterest_tool",
-        "pinterest_delete_pin": "pinterest_tool",
-        "pinterest_get_account_info": "pinterest_tool",
-        # Medium
-        "MediumTool": "medium_tool",
-        "medium_publish_post": "medium_tool",
-        "medium_get_user": "medium_tool",
-        "medium_list_publications": "medium_tool",
-        "medium_publish_to_publication": "medium_tool",
-        # n8n Tools
-        "N8nWorkflowTool": "praisonai_tools.n8n.n8n_workflow",
-        "n8n_workflow": "praisonai_tools.n8n.n8n_workflow",
-        "n8n_list_workflows": "praisonai_tools.n8n.n8n_workflow",
-        # NEXUS Prediction Market Tool
-        "NexusPredictionMarketTool": "nexus_prediction_market_tool",
-        "nexus_prediction_market_tool": "nexus_prediction_market_tool",
-        # Inkog Security Tool
-        "InkogTool": "inkog_tool",
-        "scan_agent_code": "inkog_tool",
-        "scan_skill_package": "inkog_tool",
-        "scan_mcp_server": "inkog_tool",
-    }
-
-    if name in tool_map:
-        module_name = tool_map[name]
-        from importlib import import_module
-        
-        # Handle absolute module paths (e.g., praisonai_tools.n8n.n8n_workflow)
-        if module_name.startswith("praisonai_tools."):
-            module = import_module(module_name)
-        else:
-            # Handle relative module paths within tools package
-            module = import_module(f".{module_name}", __package__)
-        
-        return getattr(module, name)
-
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-__all__ = [
-    # Base classes
+# Symbols exported eagerly above (base classes + decorator helpers).
+_BASE_EXPORTS = [
     "BaseTool",
     "ToolResult",
     "ToolValidationError",
     "validate_tool",
-    # Decorator
     "tool",
     "FunctionTool",
     "is_tool",
     "get_tool_schema",
-    # Email Tool
-    "EmailTool",
-    "send_email",
-    "read_emails",
-    "search_emails",
-    # Slack Tool
-    "SlackTool",
-    "send_slack_message",
-    "get_slack_channels",
-    "get_slack_history",
-    # Discord Tool
-    "DiscordTool",
-    "send_discord_webhook",
-    "send_discord_message",
-    # GitHub Tool
-    "GitHubTool",
-    "search_github_repos",
-    "get_github_repo",
-    "create_github_issue",
-    # Image Tool
-    "ImageTool",
-    "generate_image",
-    # Weather Tool
-    "WeatherTool",
-    "get_weather",
-    "get_forecast",
-    "get_air_quality",
-    # YouTube Tool
-    "YouTubeTool",
-    "search_youtube",
-    "get_youtube_video",
-    "get_youtube_transcript",
-    # TTS Tool
-    "TTSTool",
-    "text_to_speech",
-    "list_tts_voices",
-    # Telegram Tool
-    "TelegramTool",
-    "send_telegram_message",
-    # Notion Tool
-    "NotionTool",
-    "search_notion",
-    "create_notion_page",
-    # PostgreSQL Tool
-    "PostgresTool",
-    "query_postgres",
-    "list_postgres_tables",
-    # Reddit Tool
-    "RedditTool",
-    "search_reddit",
-    "get_reddit_hot",
-    # Docker Tool
-    "DockerTool",
-    "list_docker_containers",
-    "run_docker_container",
-    # MySQL Tool
-    "MySQLTool",
-    "query_mysql",
-    # SQLite Tool
-    "SQLiteTool",
-    "query_sqlite",
-    # MongoDB Tool
-    "MongoDBTool",
-    "query_mongodb",
-    # Redis Tool
-    "RedisTool",
-    "redis_get",
-    "redis_set",
-    # DuckDuckGo Tool
-    "DuckDuckGoTool",
-    "duckduckgo_search",
-    # Tavily Tool
-    "TavilyTool",
-    "tavily_search",
-    "tavily_extract",
-    # Wikipedia Tool
-    "WikipediaTool",
-    "wikipedia_search",
-    # ArXiv Tool
-    "ArxivTool",
-    "arxiv_search",
-    # SwarmScore Tool
-    "SwarmScoreTool",
-    "load_swarmscore_by_slug",
-    "verify_swarmscore_freshness",
-    "get_agent_discovery_manifest",
-    # Calculator Tool
-    "CalculatorTool",
-    "calculate",
-    # Shell Tool
-    "ShellTool",
-    "shell_execute",
-    # File Tool
-    "FileTool",
-    "read_file",
-    "write_file",
-    # Firecrawl Tool
-    "FirecrawlTool",
-    "firecrawl_scrape",
-    "firecrawl_search",
-    # Serper Tool
-    "SerperTool",
-    "serper_search",
-    # Jina Tool
-    "JinaTool",
-    "jina_read",
-    # Google Calendar Tool
-    "GoogleCalendarTool",
-    "list_calendar_events",
-    # Google Sheets Tool
-    "GoogleSheetsTool",
-    "read_google_sheet",
-    # Jira Tool
-    "JiraTool",
-    "jira_search",
-    "jira_list_boards",
-    "jira_get_board",
-    "jira_get_board_issues",
-    "jira_get_backlog",
-    "jira_get_transitions",
-    "jira_move_issue",
-    "jira_create_task",
-    "jira_watch_issue",
-    "jira_watch_project",
-    "jira_get_issue_info",
-    "jira_search_issues",
-    "jira_tools",
-    # Trello Tool
-    "TrelloTool",
-    "list_trello_boards",
-    # YFinance Tool
-    "YFinanceTool",
-    "get_stock_price",
-    # Pinecone Tool
-    "PineconeTool",
-    "pinecone_query",
-    # Qdrant Tool
-    "QdrantTool",
-    "qdrant_search",
-    # Chroma Tool
-    "ChromaTool",
-    "chroma_query",
-    # HackerNews Tool
-    "HackerNewsTool",
-    "get_hackernews_top",
-    # Twilio Tool
-    "TwilioTool",
-    "send_sms",
-    # Spotify Tool
-    "SpotifyTool",
-    "spotify_search",
-    # Linear Tool
-    "LinearTool",
-    "list_linear_issues",
-    # Crawl4AI Tool
-    "Crawl4AITool",
-    "crawl4ai_crawl",
-    # Exa Tool
-    "ExaTool",
-    "exa_search",
-    # DuckDB Tool
-    "DuckDBTool",
-    "duckdb_query",
-    # Neo4j Tool
-    "Neo4jTool",
-    "neo4j_query",
-    # Weaviate Tool
-    "WeaviateTool",
-    "weaviate_search",
-    # LanceDB Tool
-    "LanceDBTool",
-    "lancedb_search",
-    # Supabase Tool
-    "SupabaseTool",
-    "supabase_select",
-    # Milvus Tool
-    "MilvusTool",
-    "milvus_search",
-    # Google Maps Tool
-    "GoogleMapsTool",
-    "geocode_address",
-    # Zendesk Tool
-    "ZendeskTool",
-    "list_zendesk_tickets",
-    # Shopify Tool
-    "ShopifyTool",
-    "list_shopify_products",
-    # SQLite Vector Store (zero deps)
-    "SQLiteVectorTool",
-    "sqlite_vector_query",
-    "sqlite_vector_add",
-    # WordPress Tool (requires praisonaiwp)
-    "WordPressTool",
-    "check_wp_duplicate",
-    "create_wp_post",
-# HeyGen Tool
-    "HeyGenTool",
-    "heygen_list_avatars",
-    "heygen_list_avatar_groups",
-    "heygen_list_group_avatars",
-    "heygen_get_avatar_details",
-    "heygen_list_voices",
-    "heygen_list_voice_locales",
-    "heygen_generate_video",
-    "heygen_generate_video_with_audio",
-    "heygen_upload_asset",
-    "heygen_video_status",
-    "heygen_wait_for_video",
-    "heygen_list_videos",
-    "heygen_delete_video",
-    "heygen_list_assets",
-    "heygen_delete_asset",
-    "heygen_get_remaining_quota",
-    "heygen_get_user_info",
-    "heygen_list_templates",
-    "heygen_generate_from_template",
-    "heygen_translate_video",
-    # ElevenLabs Tool
-    "ElevenLabsTool",
-    "elevenlabs_speak",
-    "elevenlabs_speak_to_file",
-    "elevenlabs_list_voices",
-    "elevenlabs_get_voice",
-    "elevenlabs_list_models",
-    "elevenlabs_get_history",
-    "elevenlabs_get_user_info",
-# Higgsfield Tool
-    "HiggsfieldTool",
-    "higgsfield_generate",
-    "higgsfield_status",
-    "higgsfield_upload",
-    # Signal Tool
-    "SignalTool",
-    "send_signal_message",
-    "check_signal_connection",
-    # LINE Tool
-    "LineTool",
-    "send_line_message",
-    "broadcast_line_message",
-    # iMessage Tool
-    "iMessageTool",
-    "send_imessage",
-    "check_imessage_availability",
-    # Gmail Tool (extended)
-    "GmailTool",
-    "list_gmail_emails",
-    "gmail_archive_email",
-    "gmail_label_email",
-    "gmail_mark_read",
-    "gmail_draft_email",
-    "gmail_trash_email",
-    # Outlook Tool
-    "OutlookTool",
-    "outlook_list_emails",
-    "outlook_send_email",
-    "outlook_search_emails",
-    "outlook_archive_email",
-    "outlook_draft_email",
-    # Marketplace Tools
-    "PinchworkTool",
-    "pinchwork_delegate",
-    "AgentIDTool",
-    "verify_agent_identity",
-    "JoyTrustTool",
-    "check_trust_score",
-    "verify_handoff_safety",
-    "trust_verified_handoff",
-    "is_trust_verification_enabled",
-    "get_trust_config",
-    "AgentFolioTool",
-    "check_behavioral_trust",
-    "verify_task_delegation_safety",
-    # LinkedIn Tool
-    "LinkedInTool",
-    "linkedin_post_text",
-    "linkedin_post_image",
-    "linkedin_post_article",
-    "linkedin_get_profile",
-    "linkedin_delete_post",
-    # Facebook Tool
-    "FacebookTool",
-    "facebook_post_text",
-    "facebook_post_image",
-    "facebook_post_link",
-    "facebook_post_video",
-    "facebook_get_page_info",
-    "facebook_delete_post",
-    # Instagram Tool
-    "InstagramTool",
-    "instagram_post_image",
-    "instagram_post_carousel",
-    "instagram_post_reel",
-    "instagram_get_media",
-    "instagram_get_account_info",
-    # TikTok Tool
-    "TikTokTool",
-    "tiktok_post_video",
-    "tiktok_post_photo",
-    "tiktok_get_creator_info",
-    "tiktok_get_post_status",
-    # Threads Tool
-    "ThreadsTool",
-    "threads_post_text",
-    "threads_post_image",
-    "threads_post_video",
-    "threads_get_threads",
-    "threads_get_profile",
-    # Pinterest Tool
-    "PinterestTool",
-    "pinterest_create_pin",
-    "pinterest_list_boards",
-    "pinterest_get_pin",
-    "pinterest_delete_pin",
-    "pinterest_get_account_info",
-    # Medium Tool
-    "MediumTool",
-    "medium_publish_post",
-    "medium_get_user",
-    "medium_list_publications",
-    "medium_publish_to_publication",
-    # n8n Tool
-    "N8nWorkflowTool",
-    "n8n_workflow",
-    "n8n_list_workflows",
-    # Langextract Tool
-    "LangExtractTool",
-    "langextract_extract",
-    "langextract_render_file",
-    # NEXUS Prediction Market Tool
-    "NexusPredictionMarketTool",
-    "nexus_prediction_market_tool",
-    # Inkog Security Tool
-    "InkogTool",
-    "scan_agent_code",
-    "scan_skill_package",
-    "scan_mcp_server",
 ]
+
+# Build the discovery manifest once at import time. This only reads/parses
+# source files (via AST) - it does NOT import any tool module, so lazy loading
+# of heavy optional dependencies is preserved.
+_TOOL_MANIFEST, _COLLISIONS = build_manifest(os.path.dirname(__file__))
+
+# Backward-compatible alias. The catalogue/discovery contract in
+# ``praisonai_tools.catalogue`` enumerates shipped tools via ``_TOOL_MAP``
+# (name -> module). It is now derived from the auto-discovered manifest so the
+# two can never drift apart.
+_TOOL_MAP = _TOOL_MANIFEST
+
+
+
+def __getattr__(name):
+    """Lazily import a discovered tool symbol on first access."""
+    module_name = _TOOL_MANIFEST.get(name)
+    if module_name is not None:
+        from importlib import import_module
+
+        if module_name.startswith("praisonai_tools."):
+            module = import_module(module_name)
+        else:
+            module = import_module(f".{module_name}", __package__)
+        return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(_BASE_EXPORTS) | set(_TOOL_MANIFEST))
+
+
+# ``__all__`` is derived from the same manifest as ``__getattr__`` so the two
+# can never drift apart.
+__all__ = sorted(set(_BASE_EXPORTS) | set(_TOOL_MANIFEST))

praisonai_tools/tools/_discovery.py

@@ -0,0 +1,208 @@
+"""Automatic tool discovery for praisonai_tools.tools.
+
+Builds a ``name -> module`` manifest by scanning the source of every tool
+module in this package *without importing it*. Public top-level classes and
+functions (names not starting with ``_``) become part of the public surface.
+
+This preserves the per-symbol lazy import behaviour of the old hand-maintained
+``tool_map`` while eliminating the three-place bookkeeping (the map plus two
+``__all__`` blocks) that previously had to stay in lock-step. Adding a tool is
+now just adding one module under ``praisonai_tools/tools/``.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import logging
+import os
+from typing import Dict, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Cache file name written alongside the tools package. Bumping ``_CACHE_VERSION``
+# invalidates all previously written caches after a discovery-format change.
+_CACHE_VERSION = 1
+_CACHE_FILENAME = f"._discovery_cache_v{_CACHE_VERSION}.json"
+
+# Modules in *this* package directory that are infrastructure, not tools.
+# Their public symbols are exported explicitly by ``tools/__init__.py`` and
+# must not be treated as discovered tools.
+_SKIP_MODULES = {"__init__", "base", "decorator", "_discovery"}
+
+# Tools that physically live outside ``praisonai_tools/tools/`` but have always
+# been importable from it. Maps public symbol -> absolute module path.
+_EXTERNAL_SYMBOLS: Dict[str, str] = {
+    "N8nWorkflowTool": "praisonai_tools.n8n.n8n_workflow",
+    "n8n_workflow": "praisonai_tools.n8n.n8n_workflow",
+    "n8n_list_workflows": "praisonai_tools.n8n.n8n_workflow",
+}
+
+
+def _extract_all(tree: ast.Module) -> List[str] | None:
+    """Return the names listed in a module-level ``__all__``, if declared.
+
+    Only literal string entries are honoured. Returns ``None`` when the module
+    does not declare ``__all__`` at the top level.
+    """
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, ast.AnnAssign) and node.value is not None:
+            targets = [node.target]
+        else:
+            continue
+        for target in targets:
+            if isinstance(target, ast.Name) and target.id == "__all__":
+                if isinstance(node.value, (ast.List, ast.Tuple, ast.Set)):
+                    names: List[str] = []
+                    for elt in node.value.elts:
+                        if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                            names.append(elt.value)
+                    return names
+    return None
+
+
+def _iter_public_symbols(source: str, module_name: str = "<unknown>") -> List[str]:
+    """Return the public top-level symbol names exported by ``source``.
+
+    Uses AST parsing so the module body is never executed (its heavy/optional
+    dependencies are not imported at discovery time).
+
+    Resolution order:
+    1. If the module declares ``__all__``, honour it verbatim (author intent).
+       This lets a module opt its module-level re-export aliases into the public
+       surface (e.g. ``read_yaml = _yaml_tools.read_yaml``) or, conversely,
+       narrow what is exported.
+    2. Otherwise, collect public top-level classes and functions. Bare
+       assignment aliases are intentionally *not* auto-exported without an
+       explicit ``__all__``: several ``*_tools.py`` modules bind the same
+       helper names (``read_csv``/``read_excel``/…) that would otherwise
+       collide across modules and were never part of the historical public API.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:  # pragma: no cover - defensive
+        logger.warning(
+            "Tool discovery: could not parse %r (%s); its tools will not be "
+            "discoverable. Fix the syntax error to restore them.",
+            module_name, exc,
+        )
+        return []
+
+    explicit = _extract_all(tree)
+    if explicit is not None:
+        return [name for name in explicit if not name.startswith("_")]
+
+    symbols: List[str] = []
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            if not node.name.startswith("_"):
+                symbols.append(node.name)
+    return symbols
+
+
+def _fingerprint(package_dir: str) -> str:
+    """Cheap directory fingerprint used to validate the discovery cache.
+
+    Reflects the set of ``.py`` files and their size/mtime, so any edit,
+    addition, or removal of a tool module invalidates the cache (keeping
+    discovery fully automatic) without re-parsing on every import.
+    """
+    parts: List[str] = [f"v{_CACHE_VERSION}"]
+    for filename in sorted(os.listdir(package_dir)):
+        if not filename.endswith(".py"):
+            continue
+        try:
+            st = os.stat(os.path.join(package_dir, filename))
+        except OSError:  # pragma: no cover - defensive
+            continue
+        parts.append(f"{filename}:{st.st_size}:{st.st_mtime_ns}")
+    return "|".join(parts)
+
+
+def build_manifest(package_dir: str) -> Tuple[Dict[str, str], Dict[str, List[str]]]:
+    """Return the discovery manifest for ``package_dir``, using a disk cache.
+
+    The manifest is expensive to compute (it AST-parses every tool module), so
+    the result is memoised in a small JSON file next to the package and reused
+    while the directory fingerprint is unchanged. The cache is best-effort:
+    any read/write/validation failure falls back to a live scan, so behaviour
+    is always correct even on read-only installs.
+    """
+    cache_path = os.path.join(package_dir, _CACHE_FILENAME)
+    fingerprint = _fingerprint(package_dir)
+
+    try:
+        with open(cache_path, "r", encoding="utf-8") as fh:
+            cached = json.load(fh)
+        if cached.get("fingerprint") == fingerprint:
+            return cached["manifest"], cached["collisions"]
+    except (OSError, ValueError, KeyError):
+        pass  # No/invalid cache -> scan below.
+
+    manifest, collisions = _scan_manifest(package_dir)
+
+    try:
+        tmp_path = f"{cache_path}.{os.getpid()}.tmp"
+        with open(tmp_path, "w", encoding="utf-8") as fh:
+            json.dump(
+                {
+                    "fingerprint": fingerprint,
+                    "manifest": manifest,
+                    "collisions": collisions,
+                },
+                fh,
+            )
+        os.replace(tmp_path, cache_path)
+    except OSError:  # pragma: no cover - read-only install, cache disabled.
+        pass
+
+    return manifest, collisions
+
+
+def _scan_manifest(package_dir: str) -> Tuple[Dict[str, str], Dict[str, List[str]]]:
+    """AST-scan ``package_dir`` and build the discovery manifest.
+
+    Returns a tuple ``(manifest, collisions)`` where ``manifest`` maps each
+    public symbol name to the module it should be imported from, and
+    ``collisions`` maps any symbol defined in more than one module to the list
+    of modules that define it (first one wins in the manifest).
+    """
+    manifest: Dict[str, str] = {}
+    collisions: Dict[str, List[str]] = {}
+
+    for filename in sorted(os.listdir(package_dir)):
+        if not filename.endswith(".py"):
+            continue
+        module_name = filename[:-3]
+        # Skip infrastructure modules and any private (underscore-prefixed)
+        # module so internal/experimental code does not leak into the public
+        # surface by convention.
+        if module_name in _SKIP_MODULES or module_name.startswith("_"):
+            continue
+
+        path = os.path.join(package_dir, filename)
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                source = fh.read()
+        except OSError:  # pragma: no cover - defensive
+            continue
+
+        for symbol in _iter_public_symbols(source, module_name):
+            if symbol in manifest and manifest[symbol] != module_name:
+                collisions.setdefault(symbol, [manifest[symbol]])
+                collisions[symbol].append(module_name)
+                logger.warning(
+                    "Tool discovery: symbol %r defined in both %r and %r; "
+                    "keeping %r. Rename one to avoid shadowing.",
+                    symbol, manifest[symbol], module_name, manifest[symbol],
+                )
+                continue
+            manifest[symbol] = module_name
+
+    # External tools that live in sibling packages but are re-exported here.
+    for symbol, module in _EXTERNAL_SYMBOLS.items():
+        manifest.setdefault(symbol, module)
+
+    return manifest, collisions

praisonai_tools/tools/agentfolio_tool.py

@@ -261,7 +261,17 @@ def check_behavioral_trust(
     min_trust_score: float = 50.0,
     organization_filter: Optional[str] = None
 ) -> Dict[str, Any]:
-    """Check an agent's behavioral trust score across organizations using SATP protocol."""
+    """Check an agent's behavioral trust score across organizations using SATP protocol.
+
+    Args:
+        agent_name: Name/identifier of the agent to check.
+        task_class: Type of task for scoped trust (e.g., "code_review").
+        min_trust_score: Minimum trust score threshold (0-100, default: 50.0).
+        organization_filter: Optional filter for specific organization history.
+
+    Returns:
+        Dictionary with behavioral trust data.
+    """
     return AgentFolioTool().check_behavioral_trust(
         agent_name=agent_name,
         task_class=task_class,
@@ -276,7 +286,17 @@ def verify_task_delegation_safety(
     task_description: str,
     required_trust_level: float = 70.0
 ) -> Dict[str, Any]:
-    """Comprehensive safety check before delegating tasks using all trust layers."""
+    """Comprehensive safety check before delegating tasks using all trust layers.
+
+    Args:
+        agent_name: Name/identifier of the agent to check.
+        task_class: Type of task for scoped trust (e.g., "code_review").
+        task_description: Natural-language description of the task to delegate.
+        required_trust_level: Minimum trust level required (0-100, default: 70.0).
+
+    Returns:
+        Dictionary with safety assessment and recommendations.
+    """
     return AgentFolioTool().verify_delegation_safety(
         agent_name=agent_name,
         task_class=task_class,

praisonai_tools/tools/agentid_tool.py

@@ -130,5 +130,15 @@ class AgentIDTool(BaseTool):
 
 
 def verify_agent_identity(agent_url: str) -> Dict[str, Any]:
-    """Verify an external agent's identity using AgentID certificates."""
+    """Verify an external agent's identity using AgentID certificates.
+
+    Args:
+        agent_url: URL of the agent to verify.
+
+    Returns:
+        Dictionary with verification result. Always includes ``verified``,
+        ``trust_score``, ``certificate``, ``agent_url`` and ``error``.
+        Successful verifications also include a ``timestamp`` field; failures
+        populate ``error`` with a human-readable message.
+    """
     return AgentIDTool().verify(agent_url=agent_url)

praisonai_tools/tools/decorator.py

@@ -17,8 +17,51 @@ Usage:
         return [...]
 """
 
+import logging as _logging
+
+
+class _SuppressRegistryNoneWarning(_logging.Filter):
+    """Drop the benign "Registry is None for tool …" WARNING.
+
+    ``praisonaiagents.tools.decorator`` logs a WARNING for every ``@tool``
+    decorated function when no global tool registry exists yet. On a bare
+    ``import`` (library use, scripts, pytest collection) that is the normal
+    state, not an anomaly - registration happens lazily once an agent/registry
+    comes up. The message fires once per decorated function, so the noise scales
+    with the tool catalogue and is the first thing every consumer sees. We drop
+    only that specific record and leave all other logging untouched.
+    """
+
+    def filter(self, record: _logging.LogRecord) -> bool:
+        return not record.getMessage().startswith("Registry is None for tool")
+
+
+def _silence_registry_none_warning() -> None:
+    """Install the filter so bare imports stay quiet at default log levels.
+
+    The upstream code emits the record via ``logging.warning`` (the root
+    logger), and ``praisonaiagents`` configures a handler on the root logger, so
+    the record surfaces there. We attach the filter to the root logger and its
+    handlers - it only drops the single "Registry is None for tool …" record and
+    passes everything else through, so user logging is unaffected. The proper fix
+    (defer registration / downgrade to debug) belongs in praisonaiagents core.
+    """
+    filt = _SuppressRegistryNoneWarning()
+    root = _logging.getLogger()
+    root.addFilter(filt)
+    for handler in root.handlers:
+        handler.addFilter(filt)
+
+
+# ``praisonaiagents`` configures root logging on import; do it first so its
+# handlers exist, then attach the filter before any module-level ``@tool``
+# decoration runs.
+import praisonaiagents  # noqa: E402,F401  (import for logging side effects only)
+
+_silence_registry_none_warning()
+
 # Import from praisonaiagents - single source of truth
-from praisonaiagents.tools.decorator import (
+from praisonaiagents.tools.decorator import (  # noqa: E402
     tool,
     FunctionTool,
     is_tool,

praisonai_tools/tools/pinchwork_tool.py

@@ -97,5 +97,18 @@ class PinchworkTool(BaseTool):
 
 
 def pinchwork_delegate(task: str, skills_required: Optional[List[str]] = None, budget: float = 0.0) -> str:
-    """Delegate a task to the Pinchwork agent marketplace."""
+    """Delegate a task to the Pinchwork agent marketplace.
+
+    Args:
+        task: Description of the task to delegate.
+        skills_required: List of required skills for the agent (optional).
+        budget: Maximum budget for the task (default: 0.0).
+
+    Returns:
+        On success, the result string from the marketplace agent that
+        completed the task. On failure, an ``"Error: ..."`` message string
+        describing the problem (missing task input, the ``httpx`` dependency
+        being unavailable, a connection or HTTP status error, or an
+        unexpected exception).
+    """
     return PinchworkTool().delegate(task=task, skills_required=skills_required, budget=budget)

praisonai_tools/video/motion_graphics/team.py

@@ -35,6 +35,11 @@ def motion_graphics_team(
     - Researcher: Optional web search for content research  
     - CodeExplorer: Optional git repository exploration
     - Animator: HTML/GSAP composition authoring and rendering
+
+    The team runs with ``process="hierarchical"``: the ``manager_llm``
+    orchestrates the worker agents at runtime rather than exposing a static
+    ``leader`` reference. The coordinator is the semantic leader and is always
+    the first agent in ``team.agents``.
     
     Args:
         research: Include research specialist
@@ -46,6 +51,12 @@ def motion_graphics_team(
         
     Returns:
         AgentTeam configured for motion graphics creation
+
+    Note:
+        The team uses ``process="hierarchical"`` where the ``manager_llm``
+        orchestrates the worker agents at runtime. The coordinator is the
+        semantic leader and is always the first agent (``team.agents[0]``);
+        there is no static ``team.leader`` reference in this mode.
     """
     if AgentTeam is None:
         raise ImportError(

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "praisonai-tools"
-version = "0.2.34"
+version = "0.2.37"
 description = "Extended tools for PraisonAI Agents"
 authors = [
     {name = "Mervin Praison"}
@@ -27,6 +27,14 @@ dependencies = [
 [project.scripts]
 praisonai-tools = "praisonai_tools.cli:main"
 
+# Discovery contract for third-party tool packages. They register agent-callable
+# tools under the ``praisonai.tools`` entry-point group so that
+# ``pip install some-praisonai-tool`` makes them discoverable via
+# ``praisonai_tools.list_tools()`` without editing core, e.g.:
+#
+#   [project.entry-points."praisonai.tools"]
+#   my_tool = "my_pkg:MyTool"
+
 [project.optional-dependencies]
 
 dev = [
@@ -56,6 +64,9 @@ agentfolio = [
 n8n = [
     "httpx>=0.27.0",
 ]
+registry-proxy = [
+    "httpx>=0.24.0",
+]
 langextract = [
     "langextract>=0.1.0",
 ]
@@ -91,4 +102,4 @@ asyncio_mode = "auto"
 # Pin the rule set to the historical default (Pyflakes + a subset of
 # pycodestyle) so an unpinned ruff upgrade does not spuriously fail CI by
 # enabling thousands of new default rules across the pre-existing codebase.
-select = ["E4", "E7", "E9", "F"]
+select = ["E4", "E7", "E9", "F"]

scripts/generate_reference_docs.py

@@ -0,0 +1,55 @@
+"""Compatibility shim for the reference docs generator.
+
+The canonical implementation lives in
+``praisonai_tools/docs_generator/generator.py``. This module re-exports the MDX
+escaping / validation helpers so that test suites and tooling which import from
+``scripts/generate_reference_docs.py`` resolve the same, single source of truth.
+
+The generator module only depends on the Python standard library, so it is
+loaded directly by file path. This avoids importing the top-level
+``praisonai_tools`` package (which eagerly pulls in optional heavy
+dependencies such as ``praisonaiagents``) and keeps this shim usable in a
+lightweight docs/CI environment.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+_GENERATOR_PATH = (
+    Path(__file__).resolve().parent.parent
+    / "praisonai_tools"
+    / "docs_generator"
+    / "generator.py"
+)
+
+_spec = importlib.util.spec_from_file_location(
+    "praisonai_tools_docs_generator", _GENERATOR_PATH
+)
+_generator = importlib.util.module_from_spec(_spec)
+# Register before executing so dataclasses can resolve the module namespace.
+import sys as _sys  # noqa: E402
+
+_sys.modules[_spec.name] = _generator
+_spec.loader.exec_module(_generator)
+
+ICON_MAP = _generator.ICON_MAP
+VALID_MDX_TAGS = _generator.VALID_MDX_TAGS
+escape_for_table = _generator.escape_for_table
+escape_mdx = _generator.escape_mdx
+sanitize_description = _generator.sanitize_description
+sanitize_type_for_mdx = _generator.sanitize_type_for_mdx
+validate_docs_json_structure = _generator.validate_docs_json_structure
+validate_mdx = _generator.validate_mdx
+
+__all__ = [
+    "ICON_MAP",
+    "VALID_MDX_TAGS",
+    "escape_for_table",
+    "escape_mdx",
+    "sanitize_description",
+    "sanitize_type_for_mdx",
+    "validate_docs_json_structure",
+    "validate_mdx",
+]

tests/integration/test_motion_graphics_team.py

@@ -164,8 +164,11 @@ class TestMotionGraphicsTeam:
                 custom_param="test"
             )
             
-            # Check that custom parameters are passed through
-            assert team.kwargs == {"custom_param": "test"}
+            # Hierarchical teams forward process + manager_llm alongside
+            # any user-supplied kwargs, so assert individual entries.
+            assert team.kwargs["custom_param"] == "test"
+            assert team.kwargs["process"] == "hierarchical"
+            assert team.kwargs["manager_llm"] == "gpt-4"
             
             # Check that workspace is set
             assert team._motion_graphics_workspace == Path(tmpdir)
@@ -209,15 +212,20 @@ class TestMotionGraphicsTeam:
     @patch('praisonai_tools.video.motion_graphics.team.search_web', MockSearch())
     @patch('praisonai_tools.video.motion_graphics.team.create_motion_graphics_agent')
     def test_coordinator_is_leader(self, mock_create_agent):
-        """Test that coordinator is set as team leader."""
+        """Test that coordinator is the semantic leader (first agent).
+
+        In hierarchical process mode the manager LLM orchestrates workers,
+        so the coordinator is the first agent rather than a static
+        ``team.leader`` reference.
+        """
         mock_animator = MockAgent(name="animator")
         mock_create_agent.return_value = mock_animator
         
         with tempfile.TemporaryDirectory() as tmpdir:
             team = motion_graphics_team(workspace=tmpdir)
             
-            assert team.leader is not None
-            assert team.leader.name == "coordinator"
+            coordinator = team.agents[0]
+            assert coordinator.name == "coordinator"
     
     @patch('praisonai_tools.video.motion_graphics.team.AgentTeam', MockAgentTeam)
     @patch('praisonai_tools.video.motion_graphics.team.Agent', MockAgent)
@@ -278,7 +286,7 @@ class TestMotionGraphicsTeam:
         with tempfile.TemporaryDirectory() as tmpdir:
             team = motion_graphics_team(workspace=tmpdir)
             
-            coordinator = team.leader
+            coordinator = team.agents[0]
             instructions = coordinator.instructions.lower()
             
             assert "coordinator" in instructions

tests/test_catalogue.py

@@ -0,0 +1,79 @@
+"""Tests for the tool discovery / catalogue contract."""
+
+
+def test_list_tools_importable_from_top_level():
+    from praisonai_tools import list_tools, ToolCatalogueEntry, get_tool_names
+
+    assert callable(list_tools)
+    assert callable(get_tool_names)
+    assert ToolCatalogueEntry is not None
+
+
+def test_list_tools_returns_entries():
+    from praisonai_tools import list_tools
+    from praisonai_tools.catalogue import ToolCatalogueEntry
+
+    entries = list_tools()
+    assert isinstance(entries, list)
+    assert len(entries) > 100  # ships a large catalogue
+    assert all(isinstance(e, ToolCatalogueEntry) for e in entries)
+
+
+def test_entries_only_expose_tool_classes():
+    from praisonai_tools import list_tools
+
+    for entry in list_tools():
+        assert entry.name.endswith("Tool"), entry.name
+
+
+def test_entries_are_sorted_and_unique():
+    from praisonai_tools import list_tools
+
+    names = [e.name for e in list_tools()]
+    assert names == sorted(names)
+    assert len(names) == len(set(names))
+
+
+def test_catalogue_derived_from_tool_map_source_of_truth():
+    from praisonai_tools import list_tools
+    from praisonai_tools.tools import _TOOL_MAP
+
+    expected = {name for name in _TOOL_MAP if name.endswith("Tool")}
+    actual = {e.name for e in list_tools()}
+    # Every class in the map must be catalogued (third-party EPs may add more).
+    assert expected <= actual
+
+
+def test_previously_missing_optional_tool_is_now_discoverable():
+    # QdrantTool was a valid tool absent from the wrapper's hand-maintained
+    # allowlist; it must now be discoverable via the catalogue.
+    from praisonai_tools import get_tool_names
+
+    names = get_tool_names()
+    assert "QdrantTool" in names
+
+
+def test_extras_are_populated_for_optional_tools():
+    from praisonai_tools import list_tools
+
+    by_name = {e.name for e in list_tools()}
+    entries = {e.name: e for e in list_tools()}
+
+    assert "SwarmScoreTool" in by_name
+    assert "swarmscore" in entries["SwarmScoreTool"].extras
+
+
+def test_entries_have_summary_and_module():
+    from praisonai_tools import list_tools
+
+    for entry in list_tools():
+        assert entry.module
+        assert entry.summary
+
+
+def test_list_tools_does_not_require_optional_deps():
+    # Building the catalogue must not import any tool module / optional dep.
+    from praisonai_tools import list_tools
+
+    entries = list_tools()
+    assert entries  # smoke: no ImportError raised

tests/test_catalogue_no_phantoms.py

@@ -0,0 +1,109 @@
+"""CI guard: the catalogue must never advertise a phantom tool.
+
+A "phantom" is a tool name surfaced by ``get_tool_names()`` / ``list_tools()``
+whose class cannot be resolved because no implementation file (or class) exists.
+Because the catalogue is now source-derived (see ``praisonai_tools.catalogue``),
+phantoms should be impossible by construction; this test enforces that during
+any future refactor.
+
+Missing *optional dependencies* are explicitly tolerated: a tool whose file and
+class exist but which needs an un-installed extra will raise ``ImportError`` /
+``ModuleNotFoundError`` for the extra, not an ``AttributeError``. Only the
+latter (name resolves to nothing) counts as a phantom.
+"""
+
+import importlib
+
+import praisonai_tools
+from praisonai_tools import get_tool_names, list_tools
+from praisonai_tools.catalogue import _scan_source_tree
+
+
+def _is_missing_optional_dependency(exc: BaseException, tool_module: str) -> bool:
+    """True if the import failure is due to a missing *optional* dependency.
+
+    A missing optional dependency raises ``ModuleNotFoundError`` for a module
+    that is *not* the tool's own module. If the tool's own file were missing the
+    name would simply not resolve (``AttributeError``) rather than importing and
+    then failing on a third-party import.
+    """
+    if not isinstance(exc, ModuleNotFoundError):
+        return False
+    missing = getattr(exc, "name", "") or ""
+    # ``tool_module`` may be relative (flat ``*_tool.py`` under
+    # ``praisonai_tools.tools``) or already absolute (nested subpackages such as
+    # ``praisonai_tools.n8n.n8n_workflow``). Resolve to the tool's own dotted
+    # module either way so a *missing first-party* module is treated as a
+    # phantom, not an optional dependency.
+    own = (
+        tool_module
+        if tool_module.startswith("praisonai_tools.")
+        else f"praisonai_tools.tools.{tool_module}"
+    )
+    return missing != own and not own.startswith(f"{missing}.")
+
+
+def test_every_catalogue_name_resolves_or_needs_optional_dep():
+    entries = {e.name: e for e in list_tools()}
+    phantoms = []
+    for name in sorted(get_tool_names()):
+        module = entries.get(name).module if name in entries else ""
+        try:
+            getattr(praisonai_tools, name)
+        except AttributeError as exc:
+            phantoms.append((name, module, repr(exc)))
+        except Exception as exc:  # ImportError / ModuleNotFoundError, etc.
+            if not _is_missing_optional_dependency(exc, module):
+                phantoms.append((name, module, repr(exc)))
+    assert not phantoms, f"catalogue advertises unresolvable (phantom) tools: {phantoms}"
+
+
+def test_no_phantom_modules_in_scan():
+    """Every source-derived tool maps to a file that actually exists on disk."""
+    import os
+
+    tools_dir = os.path.join(os.path.dirname(praisonai_tools.__file__), "tools")
+    for name, (module, _summary) in _scan_source_tree().items():
+        path = os.path.join(tools_dir, f"{module}.py")
+        assert os.path.isfile(path), f"{name} maps to missing file {module}.py"
+
+
+def test_dropping_a_tool_file_is_auto_discovered():
+    """Files on disk defining a *Tool class are catalogued without _TOOL_MAP edits.
+
+    Guards the core promise of the issue: adding a tool is a single-file change.
+    ``ClaudeMemoryTool``/``CrowPayTool``/``NightmarketTool`` exist on disk but
+    were historically absent from ``_TOOL_MAP``; they must still be discoverable.
+    """
+    names = get_tool_names()
+    for expected in ("ClaudeMemoryTool", "CrowPayTool", "NightmarketTool"):
+        # Only assert for the ones whose files are present in this checkout.
+        derived = _scan_source_tree()
+        if expected in derived:
+            assert expected in names, f"{expected} exists on disk but is not catalogued"
+
+
+def test_summaries_come_from_real_description():
+    entries = {e.name: e for e in list_tools()}
+    # CalculatorTool declares a literal description; the summary must match it,
+    # not the name-synthesised fallback ("Calculator integration tool").
+    calc = entries.get("CalculatorTool")
+    assert calc is not None
+    assert calc.summary == "Perform mathematical calculations."
+    assert "integration tool" not in calc.summary
+
+
+def test_annotated_description_summaries_are_extracted():
+    """Tools declaring ``description: str = "..."`` must surface the real text.
+
+    ``CapsuleTool`` and ``NexusPredictionMarketTool`` use annotated assignments;
+    their catalogue summaries must come from the literal, not the name-based
+    fallback.
+    """
+    entries = {e.name: e for e in list_tools()}
+    for name in ("CapsuleTool", "NexusPredictionMarketTool"):
+        entry = entries.get(name)
+        if entry is None:
+            continue
+        assert entry.summary
+        assert "integration tool" not in entry.summary

tests/test_langextract_tool.py

@@ -1,15 +1,15 @@
 """Tests for LangExtract Tool."""
 
-import tempfile
 import os
+import tempfile
 from unittest.mock import Mock, patch
 
 from praisonai_tools.tools.langextract_tool import (
     LangExtractTool,
+    _create_annotated_document,
+    _get_langextract,
     langextract_extract,
     langextract_render_file,
-    _get_langextract,
-    _create_annotated_document
 )
 
 
@@ -96,19 +96,19 @@ class TestLangExtractTool:
             mock_lx.io.save_annotated_documents = Mock()
             mock_lx.visualize = Mock(return_value="<html>mock visualization</html>")
             
-            with patch('webbrowser.open') as mock_open:
-                with tempfile.TemporaryDirectory() as temp_dir:
-                    output_path = os.path.join(temp_dir, "test.html")
-                    
-                    result = self.tool.extract(
-                        text="test text",
-                        auto_open=True,
-                        output_path=output_path
-                    )
-                    
-                    assert result["success"] is True
-                    assert "auto_opened" in result
-                    mock_open.assert_called_once()
+            with patch('webbrowser.open') as mock_open, \
+                    tempfile.TemporaryDirectory() as temp_dir:
+                output_path = os.path.join(temp_dir, "test.html")
+
+                result = self.tool.extract(
+                    text="test text",
+                    auto_open=True,
+                    output_path=output_path
+                )
+
+                assert result["success"] is True
+                assert "auto_opened" in result
+                mock_open.assert_called_once()
     
     def test_render_file_missing_path(self):
         """Test render_file with missing file_path."""
@@ -144,13 +144,17 @@ class TestLangExtractTool:
             temp_file_path = temp_file.name
         
         try:
-            result = self.tool.render_file(
-                file_path=temp_file_path,
-                extractions=["important terms"]
-            )
-            
-            assert result["success"] is True
-            assert result["text_length"] > 0
+            with tempfile.TemporaryDirectory() as temp_dir:
+                output_path = os.path.join(temp_dir, "render.html")
+                
+                result = self.tool.render_file(
+                    file_path=temp_file_path,
+                    extractions=["important terms"],
+                    output_path=output_path
+                )
+                
+                assert result["success"] is True
+                assert result["text_length"] > 0
             
         finally:
             os.unlink(temp_file_path)
@@ -161,10 +165,10 @@ class TestHelperFunctions:
     
     def test_get_langextract_not_installed(self):
         """Test _get_langextract when module not installed."""
-        with patch.dict('sys.modules', {'langextract': None}):
-            with patch('builtins.__import__', side_effect=ImportError):
-                result = _get_langextract()
-                assert result is None
+        with patch.dict('sys.modules', {'langextract': None}), \
+                patch('builtins.__import__', side_effect=ImportError):
+            result = _get_langextract()
+            assert result is None
     
     @patch('praisonai_tools.tools.langextract_tool._get_langextract')
     def test_create_annotated_document(self, mock_get_lx):
@@ -265,19 +269,32 @@ class TestIntegration:
         
         key_terms = ["John Doe", "OpenAI Corporation", "January 1, 2024", "Net 30 days"]
         
-        result = langextract_extract(
-            text=contract_text,
-            extractions=key_terms,
-            document_id="contract-001",
-            auto_open=False
-        )
-        
-        assert result["success"] is True
-        assert result["document_id"] == "contract-001"
-        assert result["extractions_count"] == len(key_terms)
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output_path = os.path.join(temp_dir, "contract-001.html")
+            
+            result = langextract_extract(
+                text=contract_text,
+                extractions=key_terms,
+                document_id="contract-001",
+                output_path=output_path,
+                auto_open=False
+            )
+            
+            assert result["success"] is True
+            assert result["document_id"] == "contract-001"
+            assert result["extractions_count"] == len(key_terms)
     
-    def test_agent_usage_pattern(self):
+    @patch('praisonai_tools.tools.langextract_tool._get_langextract')
+    @patch('praisonai_tools.tools.langextract_tool._create_annotated_document')
+    def test_agent_usage_pattern(self, mock_create_doc, mock_get_lx):
         """Test typical agent usage pattern."""
+        # Mock langextract so the test runs without the optional dependency
+        mock_lx = Mock()
+        mock_get_lx.return_value = mock_lx
+        mock_create_doc.return_value = Mock()
+        mock_lx.io.save_annotated_documents = Mock()
+        mock_lx.visualize = Mock(return_value="<html>mock visualization</html>")
+        
         # This would be how an agent uses the tool
         from praisonai_tools import langextract_extract
         
@@ -285,13 +302,17 @@ class TestIntegration:
         analysis_text = "The quarterly report shows revenue of $1.2M and profit of $300K."
         findings = ["$1.2M", "$300K", "quarterly report"]
         
-        result = langextract_extract(
-            text=analysis_text,
-            extractions=findings,
-            document_id="financial-analysis",
-            auto_open=False,
-        )
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output_path = os.path.join(temp_dir, "financial-analysis.html")
+            
+            result = langextract_extract(
+                text=analysis_text,
+                extractions=findings,
+                document_id="financial-analysis",
+                output_path=output_path,
+                auto_open=False,
+            )
 
-        assert result["success"] is True
-        assert result["document_id"] == "financial-analysis"
-        assert result["extractions_count"] == len(findings)
+            assert result["success"] is True
+            assert result["document_id"] == "financial-analysis"
+            assert result["extractions_count"] == len(findings)

tests/test_marketplace_tools.py

@@ -162,7 +162,7 @@ def test_trust_config_functions():
     config = get_trust_config()
     assert config.enabled is False
     assert config.provider == "joy"
-    assert config.min_score == 3.0
+    assert config.min_score == 1.5
     
     # Test with environment variables
     old_provider = os.environ.get('PRAISONAI_TRUST_PROVIDER')

tests/test_registry_proxy.py

@@ -0,0 +1,901 @@
+"""Unit tests for the tool-registry proxy connector."""
+
+import os
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+
+
+@pytest.fixture(autouse=True)
+def reset_session_spend():
+    """Isolate cumulative-spend state between tests."""
+    from praisonai_tools.registry_proxy import registry_proxy as mod
+
+    mod._SESSION_SPEND.clear()
+    yield
+    mod._SESSION_SPEND.clear()
+
+
+@pytest.fixture
+def mock_httpx():
+    """Mock httpx module with proper exception classes."""
+    mock_module = MagicMock()
+    mock_module.TimeoutException = type("TimeoutException", (Exception,), {})
+
+    class MockHTTPStatusError(Exception):
+        def __init__(self, message, request=None, response=None):
+            super().__init__(message)
+            self.request = request
+            self.response = response
+
+    mock_module.HTTPStatusError = MockHTTPStatusError
+    with patch.dict("sys.modules", {"httpx": mock_module}):
+        yield mock_module
+
+
+class TestConfiguration:
+    def test_disabled_when_unconfigured(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        with patch.dict(os.environ, {}, clear=True):
+            tool = RegistryProxyTool()
+            result = tool.search("backlinks for a domain")
+            assert "not configured" in result["error"]
+
+    def test_reads_env_vars(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        with patch.dict(os.environ, {
+            "TOOL_PROXY_URL": "https://registry.example.com/",
+            "TOOL_PROXY_TOKEN": "secret-token",
+        }):
+            tool = RegistryProxyTool()
+            assert tool.proxy_url == "https://registry.example.com"
+            assert tool.token == "secret-token"
+            assert tool._headers()["Authorization"] == "Bearer secret-token"
+
+    def test_explicit_args_override_env(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        tool = RegistryProxyTool(proxy_url="https://self.host/", token="tok")
+        assert tool.proxy_url == "https://self.host"
+        assert tool.token == "tok"
+
+    def test_env_token_not_leaked_to_supplied_url(self):
+        """Security: an agent-supplied proxy_url must not receive the env token."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        with patch.dict(os.environ, {
+            "TOOL_PROXY_URL": "https://trusted.example.com",
+            "TOOL_PROXY_TOKEN": "secret-token",
+        }):
+            tool = RegistryProxyTool(proxy_url="https://attacker.example.com")
+            assert tool.proxy_url == "https://attacker.example.com"
+            assert tool.token is None
+            assert "Authorization" not in tool._headers()
+
+    def test_env_token_used_for_env_url(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        with patch.dict(os.environ, {
+            "TOOL_PROXY_URL": "https://trusted.example.com",
+            "TOOL_PROXY_TOKEN": "secret-token",
+        }):
+            tool = RegistryProxyTool()
+            assert tool._headers()["Authorization"] == "Bearer secret-token"
+
+
+class TestAuthHeader:
+    def test_auth_header_configurable(self):
+        """Default sends Bearer; a custom header name sends the raw token."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        default = RegistryProxyTool(proxy_url="https://r.example.com", token="tok")
+        assert default._headers()["Authorization"] == "Bearer tok"
+        assert "X-Treg-Token" not in default._headers()
+
+        custom = RegistryProxyTool(
+            proxy_url="https://r.example.com", token="tok", auth_header="X-Treg-Token"
+        )
+        headers = custom._headers()
+        assert headers["X-Treg-Token"] == "tok"
+        assert "Authorization" not in headers
+
+    def test_auth_header_from_env(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        with patch.dict(os.environ, {
+            "TOOL_PROXY_URL": "https://trusted.example.com",
+            "TOOL_PROXY_TOKEN": "secret-token",
+            "TOOL_PROXY_AUTH_HEADER": "X-Treg-Token",
+        }):
+            tool = RegistryProxyTool()
+            headers = tool._headers()
+            assert headers["X-Treg-Token"] == "secret-token"
+            assert "Authorization" not in headers
+
+
+class TestSearch:
+    def test_search_success(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"matches": [{"id": "seo.backlinks"}]}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.search("backlinks for a domain")
+
+        assert result["matches"][0]["id"] == "seo.backlinks"
+        client.get.assert_called_once_with(
+            "https://r.example.com/catalog/search",
+            params={"q": "backlinks for a domain"},
+            headers={"Content-Type": "application/json", "Authorization": "Bearer t"},
+        )
+
+    def test_search_requires_query(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        assert tool.search("")["error"] == "query is required"
+
+
+class TestDescribe:
+    def test_describe_success(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"id": "seo.backlinks", "price_per_call": 0.01}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.describe("seo.backlinks")
+
+        assert result["price_per_call"] == 0.01
+        client.get.assert_called_once_with(
+            "https://r.example.com/catalog/endpoints/seo.backlinks",
+            headers={"Content-Type": "application/json"},
+        )
+
+    def test_describe_uses_endpoints_path(self, mock_httpx):
+        """The real registry route is /catalog/endpoints/{id}, not /catalog/{id}."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"id": "diffbot.people.enrich", "method": "GET"}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        tool.describe("diffbot.people.enrich")
+
+        client.get.assert_called_once_with(
+            "https://r.example.com/catalog/endpoints/diffbot.people.enrich",
+            headers={"Content-Type": "application/json", "Authorization": "Bearer t"},
+        )
+
+    def test_describe_path_configurable(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"id": "seo.backlinks"}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(
+            proxy_url="https://r.example.com",
+            describe_path="/catalog/{tool_id}",
+        )
+        tool.describe("seo.backlinks")
+
+        client.get.assert_called_once_with(
+            "https://r.example.com/catalog/seo.backlinks",
+            headers={"Content-Type": "application/json"},
+        )
+
+    def test_describe_path_from_env(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"id": "seo.backlinks"}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        with patch.dict(os.environ, {
+            "TOOL_PROXY_URL": "https://r.example.com",
+            "TOOL_PROXY_DESCRIBE_PATH": "/v2/endpoints/{tool_id}",
+        }):
+            tool = RegistryProxyTool()
+            tool.describe("seo.backlinks")
+
+        client.get.assert_called_once_with(
+            "https://r.example.com/v2/endpoints/seo.backlinks",
+            headers={"Content-Type": "application/json"},
+        )
+
+    def test_describe_path_missing_placeholder_errors(self, mock_httpx):
+        """A template lacking {tool_id} must return an error, not silently misroute."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        client = Mock()
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(
+            proxy_url="https://r.example.com",
+            describe_path="/catalog/static",
+        )
+        result = tool.describe("seo.backlinks")
+
+        assert "must contain '{tool_id}'" in result["error"]
+        client.get.assert_not_called()
+
+    def test_describe_path_malformed_template_errors(self, mock_httpx):
+        """A malformed template must return an error instead of raising."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        client = Mock()
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(
+            proxy_url="https://r.example.com",
+            describe_path="/catalog/{tool_id}/{unknown}",
+        )
+        result = tool.describe("seo.backlinks")
+
+        assert "Invalid describe path template" in result["error"]
+        client.get.assert_not_called()
+
+    def test_describe_encodes_tool_id(self, mock_httpx):
+        """A tool_id with path-changing characters is URL-encoded."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"id": "x"}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        tool.describe("../admin?x=1")
+
+        client.get.assert_called_once_with(
+            "https://r.example.com/catalog/endpoints/..%2Fadmin%3Fx%3D1",
+            headers={"Content-Type": "application/json"},
+        )
+
+
+class TestCall:
+    def test_call_success(self, mock_httpx):
+        """Explicit method=POST skips describe and posts a JSON body."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"data": {"backlinks": 42}}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.request.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.call("seo.backlinks", {"domain": "example.com"}, method="POST")
+
+        assert result["data"]["backlinks"] == 42
+        client.request.assert_called_once_with(
+            "POST",
+            "https://r.example.com/call/seo.backlinks",
+            json={"domain": "example.com"},
+            headers={"Content-Type": "application/json", "Authorization": "Bearer t"},
+        )
+        client.get.assert_not_called()
+
+    def test_call_requires_tool_id(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        assert tool.call("")["error"] == "tool_id is required"
+
+    def test_call_normalizes_explicit_method_whitespace(self, mock_httpx):
+        """An explicit method with whitespace/casing is normalized (GET -> query)."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"data": {"ok": True}}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.call("t.id", {"q": "x"}, method=" get ")
+
+        assert result["data"]["ok"] is True
+        client.get.assert_called_once_with(
+            "https://r.example.com/call/t.id",
+            params={"q": "x"},
+            headers={"Content-Type": "application/json"},
+        )
+        client.request.assert_not_called()
+
+    def test_call_rejects_unsupported_method(self, mock_httpx):
+        """An unsupported/mislabelled method is rejected before any request."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        client = Mock()
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.call("t.id", {}, method="TRACE")
+
+        assert "Unsupported HTTP method 'TRACE'" in result["error"]
+        client.get.assert_not_called()
+        client.request.assert_not_called()
+
+    def test_call_encodes_tool_id_in_url(self, mock_httpx):
+        """A tool_id with path-changing characters is URL-encoded on /call."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        response = Mock()
+        response.json.return_value = {"data": "ok"}
+        response.raise_for_status.return_value = None
+        client = Mock()
+        client.request.return_value = response
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        tool.call("../admin", {}, method="POST")
+
+        client.request.assert_called_once_with(
+            "POST",
+            "https://r.example.com/call/..%2Fadmin",
+            json={},
+            headers={"Content-Type": "application/json"},
+        )
+
+    def test_call_derives_post_method_from_describe(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"id": "seo.backlinks", "method": "POST"}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": {"backlinks": 42}}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.call("seo.backlinks", {"domain": "example.com"})
+
+        assert result["data"]["backlinks"] == 42
+        client.request.assert_called_once_with(
+            "POST",
+            "https://r.example.com/call/seo.backlinks",
+            json={"domain": "example.com"},
+            headers={"Content-Type": "application/json", "Authorization": "Bearer t"},
+        )
+
+    def test_call_uses_declared_method(self, mock_httpx):
+        """describe says GET -> GET with query params (no JSON body)."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {
+            "id": "diffbot.people.enrich", "method": "GET"
+        }
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": {"name": "Jane"}}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.side_effect = [describe_resp, call_resp]
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.call("diffbot.people.enrich", {"query": "type=email"})
+
+        assert result["data"]["name"] == "Jane"
+        client.request.assert_not_called()
+        # First get = describe, second get = the GET call with query params.
+        assert client.get.call_count == 2
+        call_args = client.get.call_args_list[1]
+        assert call_args.args[0] == "https://r.example.com/call/diffbot.people.enrich"
+        assert call_args.kwargs["params"] == {"query": "type=email"}
+
+    def test_call_explicit_get_skips_describe(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok"}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.call("diffbot.people.enrich", {"q": "x"}, method="GET")
+
+        assert result["data"] == "ok"
+        client.get.assert_called_once_with(
+            "https://r.example.com/call/diffbot.people.enrich",
+            params={"q": "x"},
+            headers={"Content-Type": "application/json", "Authorization": "Bearer t"},
+        )
+
+    def test_call_defaults_to_post_when_method_absent(self, mock_httpx):
+        """describe omits method -> default to POST with JSON body."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"id": "seo.backlinks"}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok"}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.call("seo.backlinks", {"domain": "x"})
+
+        assert result["data"] == "ok"
+        client.request.assert_called_once_with(
+            "POST",
+            "https://r.example.com/call/seo.backlinks",
+            json={"domain": "x"},
+            headers={"Content-Type": "application/json"},
+        )
+
+    def test_guarded_call_works_on_get_endpoint(self, mock_httpx):
+        """Regression: spend guard + GET endpoint end-to-end (describe fetched once)."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {
+            "id": "diffbot.people.enrich", "method": "GET", "price_per_call": 0.05
+        }
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok", "price_per_call": 0.05}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.side_effect = [describe_resp, call_resp]
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(
+            proxy_url="https://r.example.com", max_session_spend=1.0
+        )
+        result = tool.call("diffbot.people.enrich", {"query": "type=email"})
+
+        assert result["data"] == "ok"
+        assert tool._session_spend == pytest.approx(0.05)
+        client.request.assert_not_called()
+        # describe reused from the guard: exactly one describe + one GET call.
+        assert client.get.call_count == 2
+        assert client.get.call_args_list[1].kwargs["params"] == {"query": "type=email"}
+
+
+# The live registry (v0.11.0) nests the endpoint fields under an ``endpoint``
+# key and expresses cost as a structured object; fixtures mirror that shape so
+# unit tests exercise the real wire schema, not a flattened approximation.
+_LIVE_ENDPOINT_DOC = {
+    "endpoint": {
+        "id": "diffbot.people.enrich",
+        "method": "GET",
+        "cost": {
+            "type": "per_call",
+            "value": 25,
+            "currency": "credit",
+            "per": 1,
+            "usd": 0.0299,
+        },
+    },
+    "provider": {},
+    "siblings": [],
+    "call_template": "…",
+    "example_response": {},
+    "hints": [],
+}
+
+
+class TestExtractors:
+    def test_extract_method_nested_endpoint_envelope(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        assert RegistryProxyTool._extract_method(
+            {"endpoint": {"method": "GET"}}
+        ) == "GET"
+        # Flat form still works.
+        assert RegistryProxyTool._extract_method({"method": "post"}) == "POST"
+        # Absent -> None (default POST applies downstream).
+        assert RegistryProxyTool._extract_method({"endpoint": {}}) is None
+        assert RegistryProxyTool._extract_method({}) is None
+
+    def test_extract_price_structured_cost_usd(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        # Nested endpoint.cost.usd is preferred (guard budgets are USD).
+        assert RegistryProxyTool._extract_price(_LIVE_ENDPOINT_DOC) == 0.0299
+        assert RegistryProxyTool._extract_price(
+            {"cost": {"usd": 0.0299, "value": 25}}
+        ) == 0.0299
+        # Flat numeric forms unchanged.
+        assert RegistryProxyTool._extract_price({"price_per_call": 0.05}) == 0.05
+        assert RegistryProxyTool._extract_price({"price": 0.02}) == 0.02
+        assert RegistryProxyTool._extract_price({"cost": 0.03}) == 0.03
+        # Nested flat number under the envelope.
+        assert RegistryProxyTool._extract_price(
+            {"endpoint": {"price_per_call": 0.07}}
+        ) == 0.07
+        # Non-numeric/absent -> None (fail-closed downstream).
+        assert RegistryProxyTool._extract_price({"cost": {"value": 25}}) is None
+        assert RegistryProxyTool._extract_price({}) is None
+
+
+class TestLiveEnvelope:
+    def test_call_auto_derives_get_from_live_shape(self, mock_httpx):
+        """The live nested envelope must yield an auto-derived GET (no method=)."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = _LIVE_ENDPOINT_DOC
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": {"name": "Jane"}}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.side_effect = [describe_resp, call_resp]
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="t")
+        result = tool.call("diffbot.people.enrich", {"query": "type=email"})
+
+        assert result["data"]["name"] == "Jane"
+        client.request.assert_not_called()
+        assert client.get.call_count == 2
+        call_args = client.get.call_args_list[1]
+        assert call_args.args[0] == "https://r.example.com/call/diffbot.people.enrich"
+        assert call_args.kwargs["params"] == {"query": "type=email"}
+
+    def test_guard_quotes_real_price_from_live_shape(self, mock_httpx):
+        """Guard must quote the structured cost's usd, not fail-closed."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = _LIVE_ENDPOINT_DOC
+        describe_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(
+            proxy_url="https://r.example.com", max_cost_per_call=0.01
+        )
+        result = tool.call("diffbot.people.enrich", {"query": "type=email"})
+
+        assert "exceeds max_cost_per_call" in result["error"]
+        assert "0.0299" in result["error"]
+        assert "cannot enforce" not in result["error"]
+        client.request.assert_not_called()
+
+
+class TestErrorTaxonomy:
+    def test_auth_error(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        resp = Mock()
+        resp.status_code = 401
+        resp.text = "Unauthorized"
+        client = Mock()
+        client.get.side_effect = mock_httpx.HTTPStatusError("401", response=resp)
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", token="bad")
+        result = tool.search("x")
+        assert "Authentication failed" in result["error"]
+
+    def test_insufficient_balance_error(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        resp = Mock()
+        resp.status_code = 402
+        resp.text = "Payment Required"
+        client = Mock()
+        client.request.side_effect = mock_httpx.HTTPStatusError("402", response=resp)
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.call("seo.backlinks", {}, method="POST")
+        assert "Insufficient balance" in result["error"]
+
+    def test_upstream_4xx_passthrough(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        resp = Mock()
+        resp.status_code = 404
+        resp.text = "Not Found"
+        client = Mock()
+        client.request.side_effect = mock_httpx.HTTPStatusError("404", response=resp)
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        result = tool.call("seo.backlinks", {}, method="POST")
+        assert "HTTP 404" in result["error"]
+
+    def test_timeout_error(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        client = Mock()
+        client.get.side_effect = mock_httpx.TimeoutException("timed out")
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", timeout=5.0)
+        result = tool.search("x")
+        assert "timed out after 5.0" in result["error"]
+
+    def test_missing_httpx(self):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com")
+        with patch.dict("sys.modules", {"httpx": None}):
+            with patch("builtins.__import__", side_effect=ImportError("no httpx")):
+                result = tool.search("x")
+                assert "httpx not installed" in result["error"]
+                assert "praisonai-tools[registry-proxy]" in result["error"]
+
+
+class TestSpendGuards:
+    def test_max_cost_per_call_denies(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"id": "seo.backlinks", "price_per_call": 0.50}
+        describe_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_cost_per_call=0.10)
+        result = tool.call("seo.backlinks", {})
+        assert "exceeds max_cost_per_call" in result["error"]
+        client.request.assert_not_called()
+
+    def test_max_session_spend_denies(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"price_per_call": 0.60}
+        describe_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_session_spend=1.0)
+        tool._session_spend = 0.50
+        result = tool.call("seo.backlinks", {})
+        assert "max_session_spend" in result["error"]
+        client.request.assert_not_called()
+
+    def test_within_budget_allows_and_tracks_spend(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"price_per_call": 0.05}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok", "price_per_call": 0.05}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_session_spend=1.0)
+        result = tool.call("seo.backlinks", {})
+        assert result["data"] == "ok"
+        assert tool._session_spend == pytest.approx(0.05)
+
+    @pytest.mark.parametrize("field", ["price_per_call", "price", "cost"])
+    def test_budget_check_accepts_price_and_cost_fields(self, mock_httpx, field):
+        """Budget check tolerates price_per_call/price/cost, matching recording."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"id": "seo.backlinks", field: 0.05}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok", field: 0.05}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_session_spend=1.0)
+        result = tool.call("seo.backlinks", {})
+        assert result["data"] == "ok"
+        assert tool._session_spend == pytest.approx(0.05)
+
+    def test_missing_price_fails_closed(self, mock_httpx):
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"id": "seo.backlinks"}
+        describe_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_cost_per_call=0.10)
+        result = tool.call("seo.backlinks", {})
+        assert "cannot enforce" in result["error"]
+        client.request.assert_not_called()
+
+    @pytest.mark.parametrize("bad_price", ["NaN", "Infinity", "-Infinity", -0.01])
+    def test_non_finite_or_negative_price_fails_closed(self, mock_httpx, bad_price):
+        """NaN/inf/negative prices must be rejected, not silently bypass the guard."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"price_per_call": bad_price}
+        describe_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_cost_per_call=0.10)
+        result = tool.call("seo.backlinks", {})
+        assert "cannot enforce" in result["error"]
+        client.request.assert_not_called()
+
+    def test_non_finite_response_charge_does_not_corrupt_spend(self, mock_httpx):
+        """A NaN/inf charge in the call response must not poison cumulative spend."""
+        from praisonai_tools.registry_proxy import RegistryProxyTool
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"price_per_call": 0.20}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok", "price_per_call": "NaN"}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        tool = RegistryProxyTool(proxy_url="https://r.example.com", max_session_spend=1.0)
+        result = tool.call("seo.backlinks", {})
+        assert result["data"] == "ok"
+        assert tool._session_spend == 0.20
+
+    def test_session_spend_persists_across_registry_call(self, mock_httpx):
+        """max_session_spend must accumulate across separate registry_call calls."""
+        from praisonai_tools.registry_proxy import registry_call
+
+        describe_resp = Mock()
+        describe_resp.json.return_value = {"price_per_call": 0.60}
+        describe_resp.raise_for_status.return_value = None
+        call_resp = Mock()
+        call_resp.json.return_value = {"data": "ok", "price_per_call": 0.60}
+        call_resp.raise_for_status.return_value = None
+        client = Mock()
+        client.get.return_value = describe_resp
+        client.request.return_value = call_resp
+        mock_httpx.Client.return_value.__enter__.return_value = client
+
+        first = registry_call(
+            "seo.backlinks", {},
+            proxy_url="https://r.example.com", token="t",
+            max_session_spend=1.0,
+        )
+        assert first["data"] == "ok"
+
+        second = registry_call(
+            "seo.backlinks", {},
+            proxy_url="https://r.example.com", token="t",
+            max_session_spend=1.0,
+        )
+        assert "max_session_spend" in second["error"]
+
+
+class TestDecoratedFunctions:
+    @patch("praisonai_tools.registry_proxy.registry_proxy.RegistryProxyTool")
+    def test_registry_search_function(self, mock_cls):
+        from praisonai_tools.registry_proxy import registry_search
+
+        instance = Mock()
+        instance.search.return_value = {"matches": []}
+        mock_cls.return_value = instance
+
+        registry_search("q", proxy_url="https://r", token="t")
+        mock_cls.assert_called_once_with(
+            proxy_url="https://r", token="t", auth_header=None
+        )
+        instance.search.assert_called_once_with("q")
+
+    @patch("praisonai_tools.registry_proxy.registry_proxy.RegistryProxyTool")
+    def test_registry_call_function_passes_guards(self, mock_cls):
+        from praisonai_tools.registry_proxy import registry_call
+
+        instance = Mock()
+        instance.call.return_value = {"data": "ok"}
+        mock_cls.return_value = instance
+
+        registry_call(
+            "seo.backlinks",
+            {"domain": "x"},
+            proxy_url="https://r",
+            token="t",
+            max_cost_per_call=0.1,
+            max_session_spend=1.0,
+        )
+        mock_cls.assert_called_once_with(
+            proxy_url="https://r",
+            token="t",
+            max_cost_per_call=0.1,
+            max_session_spend=1.0,
+            auth_header=None,
+            describe_path=None,
+        )
+        instance.call.assert_called_once_with("seo.backlinks", {"domain": "x"}, None)
+
+    @patch("praisonai_tools.registry_proxy.registry_proxy.RegistryProxyTool")
+    def test_registry_call_function_passes_method(self, mock_cls):
+        from praisonai_tools.registry_proxy import registry_call
+
+        instance = Mock()
+        instance.call.return_value = {"data": "ok"}
+        mock_cls.return_value = instance
+
+        registry_call(
+            "diffbot.people.enrich",
+            {"query": "type=email"},
+            proxy_url="https://r",
+            token="t",
+            method="GET",
+        )
+        instance.call.assert_called_once_with(
+            "diffbot.people.enrich", {"query": "type=email"}, "GET"
+        )
+
+
+def test_smoke_import():
+    from praisonai_tools.registry_proxy import (
+        RegistryProxyTool,
+        registry_search,
+        registry_describe,
+        registry_call,
+    )
+
+    assert callable(registry_search)
+    assert callable(registry_describe)
+    assert callable(registry_call)
+    assert RegistryProxyTool().name == "registry_proxy"
+
+
+@pytest.mark.integration
+def test_live_smoke():
+    """Gated live smoke test; skipped unless TOOL_PROXY_URL is configured."""
+    proxy_url = os.getenv("TOOL_PROXY_URL")
+    if not proxy_url:
+        pytest.skip("TOOL_PROXY_URL not set")
+    from praisonai_tools.registry_proxy import registry_search
+
+    result = registry_search("backlinks for a domain")
+    assert isinstance(result, dict)
+    assert "error" not in result

tests/test_registry_skills_compat.py

@@ -0,0 +1,25 @@
+"""Tier 0: pin that registry-installed skills (./.claude/skills/) are discoverable.
+
+Registries that expose ``skill install <name>`` install into ``./.claude/skills/``.
+PraisonAI's skill discovery already scans that directory, so registry-installed
+skills are discoverable with zero connector code. This test pins that contract.
+"""
+
+import os
+import pytest
+
+
+def test_claude_skills_dir_is_scanned(tmp_path, monkeypatch):
+    discovery = pytest.importorskip("praisonaiagents.skills.discovery")
+
+    skills_dir = tmp_path / ".claude" / "skills" / "my-registry-skill"
+    skills_dir.mkdir(parents=True)
+
+    monkeypatch.chdir(tmp_path)
+    dirs = discovery.get_default_skill_dirs()
+
+    claude_skills = tmp_path / ".claude" / "skills"
+    assert any(os.path.samefile(str(d), str(claude_skills)) for d in dirs), (
+        "PraisonAI must scan ./.claude/skills/ so registry-installed skills are "
+        "discoverable with zero connector code."
+    )

tests/test_tool_discovery.py

@@ -0,0 +1,185 @@
+"""Regression tests for automatic tool discovery.
+
+These guard the "shipped but not importable" gap: every public tool symbol that
+ships under ``praisonai_tools/tools/`` must be reachable through both public
+import surfaces, and adding a new tool module must require no other edits.
+"""
+
+import ast
+import importlib
+import os
+
+import pytest
+
+import praisonai_tools
+from praisonai_tools import tools as tools_pkg
+from praisonai_tools.tools._discovery import (
+    build_manifest,
+    _iter_public_symbols,
+    _SKIP_MODULES,
+)
+
+TOOLS_DIR = os.path.dirname(tools_pkg.__file__)
+
+
+def _public_symbols(path):
+    with open(path, "r", encoding="utf-8") as fh:
+        source = fh.read()
+    return _iter_public_symbols(source, os.path.basename(path)[:-3])
+
+
+def _tool_modules():
+    for filename in sorted(os.listdir(TOOLS_DIR)):
+        module_name = filename[:-3]
+        if (
+            filename.endswith(".py")
+            and module_name not in _SKIP_MODULES
+            and not module_name.startswith("_")
+        ):
+            yield module_name
+
+
+def test_no_discovery_collisions():
+    _, collisions = build_manifest(TOOLS_DIR)
+    assert collisions == {}, f"Colliding tool symbols across modules: {collisions}"
+
+
+def test_every_shipped_module_parses():
+    """Every shipped tool module must parse.
+
+    Discovery deliberately swallows a per-module ``SyntaxError`` (logging a
+    warning) so one broken module cannot break the whole package import. The
+    downside is that a broken module silently drops out of the manifest and its
+    tools resolve as ``AttributeError`` rather than surfacing the real parse
+    error. This test closes that gap loudly at CI time: it parses each module
+    directly (not via the swallowing discovery helper) so a genuinely broken
+    shipped module fails here with the pointing ``SyntaxError``.
+    """
+    for module in _tool_modules():
+        path = os.path.join(TOOLS_DIR, module + ".py")
+        with open(path, "r", encoding="utf-8") as fh:
+            source = fh.read()
+        try:
+            ast.parse(source)
+        except SyntaxError as exc:  # pragma: no cover - fails only if a module breaks
+            pytest.fail(f"tools/{module}.py has a syntax error: {exc}")
+
+
+def test_manifest_covers_every_shipped_symbol():
+    manifest, _ = build_manifest(TOOLS_DIR)
+    for module in _tool_modules():
+        path = os.path.join(TOOLS_DIR, module + ".py")
+        for symbol in _public_symbols(path):
+            assert symbol in manifest, (
+                f"{symbol!r} defined in tools/{module}.py is not discoverable"
+            )
+
+
+def test_all_matches_manifest():
+    manifest, _ = build_manifest(TOOLS_DIR)
+    base = {
+        "BaseTool", "ToolResult", "ToolValidationError", "validate_tool",
+        "tool", "FunctionTool", "is_tool", "get_tool_schema",
+    }
+    expected = base | set(manifest)
+    assert set(tools_pkg.__all__) == expected
+    # The top-level package mirrors the tools package surface and additionally
+    # exposes the catalogue/discovery helpers (which are not tool symbols).
+    catalogue_exports = {"ToolCatalogueEntry", "list_tools", "get_tool_names"}
+    assert set(praisonai_tools.__all__) == set(tools_pkg.__all__) | catalogue_exports
+
+
+@pytest.mark.parametrize("name", [
+    "EmailTool", "SlackTool", "GitHubTool", "WeatherTool", "YouTubeTool",
+    "send_email", "get_weather", "search_youtube",
+    # Symbol from a module that declares an explicit __all__ (author intent).
+    "NexusPredictionMarketTool",
+    # External symbol living outside tools/ (exercises the absolute-path
+    # import branch in __getattr__ and the _EXTERNAL_SYMBOLS mapping).
+    "N8nWorkflowTool",
+])
+def test_known_symbols_resolve_both_surfaces(name):
+    assert getattr(tools_pkg, name) is getattr(praisonai_tools, name)
+
+
+def test_explicit_all_is_respected():
+    """A module declaring __all__ contributes exactly those public names."""
+    manifest, _ = build_manifest(TOOLS_DIR)
+    # nexus_prediction_market_tool.py declares __all__ with these two names.
+    assert manifest.get("NexusPredictionMarketTool") == "nexus_prediction_market_tool"
+    assert manifest.get("nexus_prediction_market_tool") == "nexus_prediction_market_tool"
+
+
+def test_lazy_import_not_eager(monkeypatch):
+    """Importing the package must not eagerly import a heavy tool module."""
+    import sys
+
+    # A representative heavy/optional tool module should not be imported until
+    # one of its symbols is accessed.
+    target = "praisonai_tools.tools.docker_tool"
+    sys.modules.pop(target, None)
+    importlib.reload(tools_pkg)
+    assert target not in sys.modules
+    # Accessing a symbol triggers the lazy import.
+    _ = tools_pkg.DockerTool
+    assert target in sys.modules
+
+
+def test_drop_in_new_tool(tmp_path, monkeypatch):
+    """A new module dropped into tools/ is importable with no other edits."""
+    if not os.access(TOOLS_DIR, os.W_OK):
+        pytest.skip("TOOLS_DIR is not writable (read-only install)")
+    echo_path = os.path.join(TOOLS_DIR, "echo_discovery_probe.py")
+    source = (
+        "from praisonai_tools.tools.decorator import tool\n\n\n"
+        "@tool\n"
+        "def echo_discovery_probe(text: str) -> str:\n"
+        "    '''Echo the given text.'''\n"
+        "    return text\n"
+    )
+    with open(echo_path, "w", encoding="utf-8") as fh:
+        fh.write(source)
+    try:
+        importlib.reload(tools_pkg)
+        fn = tools_pkg.echo_discovery_probe
+        assert fn("hi") == "hi"
+        assert "echo_discovery_probe" in tools_pkg.__all__
+    finally:
+        os.remove(echo_path)
+        importlib.reload(tools_pkg)
+
+
+def test_manifest_cache_roundtrip(tmp_path):
+    """The disk cache is written, reused, and invalidated on directory change."""
+    from praisonai_tools.tools import _discovery
+
+    pkg = tmp_path / "toolsdir"
+    pkg.mkdir()
+    (pkg / "sample_tool.py").write_text("class SampleTool:\n    pass\n")
+
+    manifest, _ = _discovery.build_manifest(str(pkg))
+    assert manifest.get("SampleTool") == "sample_tool"
+    cache_file = pkg / _discovery._CACHE_FILENAME
+    assert cache_file.exists(), "cache should be written after first scan"
+
+    # Second call must serve from cache (fingerprint unchanged) and match.
+    manifest2, _ = _discovery.build_manifest(str(pkg))
+    assert manifest2 == manifest
+
+    # Adding a module changes the fingerprint -> cache is rebuilt automatically.
+    (pkg / "second_tool.py").write_text("def second_tool():\n    return 1\n")
+    manifest3, _ = _discovery.build_manifest(str(pkg))
+    assert "second_tool" in manifest3
+
+
+def test_manifest_cache_corrupt_falls_back(tmp_path):
+    """A corrupt cache file must not break discovery."""
+    from praisonai_tools.tools import _discovery
+
+    pkg = tmp_path / "toolsdir"
+    pkg.mkdir()
+    (pkg / "sample_tool.py").write_text("class SampleTool:\n    pass\n")
+    (pkg / _discovery._CACHE_FILENAME).write_text("{ not valid json")
+
+    manifest, _ = _discovery.build_manifest(str(pkg))
+    assert manifest.get("SampleTool") == "sample_tool"

tests/unit/tools/test_tool_discovery_ci.py

@@ -0,0 +1,50 @@
+"""CI-covered guard for automatic tool discovery.
+
+The full discovery regression suite lives at ``tests/test_tool_discovery.py``,
+but the CI workflow only runs ``pytest tests/unit --ignore=tests/unit/video``.
+That means the most important safety net there - proving every shipped tool
+module actually parses (so discovery never silently drops a tool) - would not
+execute in CI. This thin module re-runs that guard from inside the CI-covered
+path so a syntactically broken shipped module fails loudly at CI time with the
+pointing ``SyntaxError`` instead of surfacing later as a mystery
+``AttributeError`` on ``from praisonai_tools import SomeTool``.
+"""
+
+import ast
+import os
+
+import pytest
+
+from praisonai_tools import tools as tools_pkg
+from praisonai_tools.tools._discovery import _SKIP_MODULES, build_manifest
+
+TOOLS_DIR = os.path.dirname(tools_pkg.__file__)
+
+
+def _tool_modules():
+    for filename in sorted(os.listdir(TOOLS_DIR)):
+        module_name = filename[:-3]
+        if (
+            filename.endswith(".py")
+            and module_name not in _SKIP_MODULES
+            and not module_name.startswith("_")
+        ):
+            yield module_name
+
+
+def test_every_shipped_module_parses_in_ci():
+    """Every shipped tool module must parse under the running interpreter."""
+    for module in _tool_modules():
+        path = os.path.join(TOOLS_DIR, module + ".py")
+        with open(path, "r", encoding="utf-8") as fh:
+            source = fh.read()
+        try:
+            ast.parse(source)
+        except SyntaxError as exc:  # pragma: no cover - fails only if a module breaks
+            pytest.fail(f"tools/{module}.py has a syntax error: {exc}")
+
+
+def test_no_discovery_collisions_in_ci():
+    """No public tool symbol may be defined in two shipped modules."""
+    _, collisions = build_manifest(TOOLS_DIR)
+    assert collisions == {}, f"Colliding tool symbols across modules: {collisions}"

tests/unit/video/test_html_backend.py

@@ -1,10 +1,11 @@
 """Unit tests for HTML render backend."""
 
-import pytest
-import tempfile
 import asyncio
+import tempfile
 from pathlib import Path
-from unittest.mock import Mock, patch, AsyncMock
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
 
 from praisonai_tools.video.motion_graphics.backend_html import HtmlRenderBackend
 from praisonai_tools.video.motion_graphics.protocols import RenderOpts
@@ -16,20 +17,29 @@ class TestHtmlRenderBackend:
     @pytest.mark.requires_video_deps
     def test_import_error_handling(self):
         """Test that import errors are handled properly."""
-        with patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', None):
-            with pytest.raises(ImportError, match="Playwright not installed"):
-                HtmlRenderBackend()
-        
-        with patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', None):
-            with pytest.raises(ImportError, match="imageio-ffmpeg not installed"):
-                HtmlRenderBackend()
+        with (
+            patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', None),
+            pytest.raises(ImportError, match="Playwright not installed"),
+        ):
+            HtmlRenderBackend()
+
+        # Ensure the playwright guard passes so the imageio-ffmpeg guard is the
+        # one under test, regardless of whether the optional deps are installed.
+        with (
+            patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()),
+            patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', None),
+            pytest.raises(ImportError, match="imageio-ffmpeg not installed"),
+        ):
+            HtmlRenderBackend()
     
     def test_init_success(self):
         """Test successful initialization."""
-        with patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()):
-            with patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()):
-                backend = HtmlRenderBackend()
-                assert backend is not None
+        with (
+            patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()),
+            patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()),
+        ):
+            backend = HtmlRenderBackend()
+            assert backend is not None
 
 
 class TestLinting:
@@ -37,9 +47,11 @@ class TestLinting:
     
     def setup_method(self):
         """Set up test fixtures."""
-        with patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()):
-            with patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()):
-                self.backend = HtmlRenderBackend()
+        with (
+            patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()),
+            patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()),
+        ):
+            self.backend = HtmlRenderBackend()
     
     @pytest.mark.asyncio
     async def test_lint_missing_index_html(self):
@@ -199,9 +211,11 @@ class TestRendering:
     
     def setup_method(self):
         """Set up test fixtures."""
-        with patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()):
-            with patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()):
-                self.backend = HtmlRenderBackend()
+        with (
+            patch('praisonai_tools.video.motion_graphics.backend_html.async_playwright', Mock()),
+            patch('praisonai_tools.video.motion_graphics.backend_html.imageio_ffmpeg', Mock()),
+        ):
+            self.backend = HtmlRenderBackend()
     
     @pytest.mark.asyncio
     async def test_render_missing_index_html(self):
@@ -322,8 +336,10 @@ class TestRendering:
         mock_process.returncode = 0
         mock_subprocess.return_value = mock_process
         
-        with patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'):
-            with tempfile.TemporaryDirectory() as tmpdir:
+        with (
+            patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'),
+            tempfile.TemporaryDirectory() as tmpdir,
+        ):
                 # Create fake frame files
                 frame_dir = Path(tmpdir)
                 frame_paths = []
@@ -358,8 +374,10 @@ class TestRendering:
         mock_process.returncode = 1
         mock_subprocess.return_value = mock_process
         
-        with patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'):
-            with tempfile.TemporaryDirectory() as tmpdir:
+        with (
+            patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'),
+            tempfile.TemporaryDirectory() as tmpdir,
+        ):
                 frame_path = Path(tmpdir) / "frame_000000.png"
                 frame_path.write_bytes(b"fake")
                 
@@ -379,8 +397,10 @@ class TestRendering:
         mock_process.kill = Mock()
         mock_subprocess.return_value = mock_process
         
-        with patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'):
-            with tempfile.TemporaryDirectory() as tmpdir:
+        with (
+            patch.object(self.backend, '_get_ffmpeg_path', return_value='ffmpeg'),
+            tempfile.TemporaryDirectory() as tmpdir,
+        ):
                 frame_path = Path(tmpdir) / "frame_000000.png"
                 frame_path.write_bytes(b"fake")
                 

tests/unit/video/test_motion_graphics_agent.py

@@ -6,11 +6,11 @@ from pathlib import Path
 from unittest.mock import patch
 
 from praisonai_tools.video.motion_graphics.agent import (
-    create_motion_graphics_agent,
     RenderTools,
-    _resolve_backend
+    _resolve_backend,
+    create_motion_graphics_agent,
 )
-from praisonai_tools.video.motion_graphics.protocols import RenderResult, LintResult
+from praisonai_tools.video.motion_graphics.protocols import LintResult, RenderResult
 
 
 class MockAgent:

tests/unit/video/test_motion_graphics_protocols.py

@@ -3,10 +3,10 @@
 import pytest
 from pathlib import Path
 from praisonai_tools.video.motion_graphics.protocols import (
+    LintResult,
+    RenderBackendProtocol,
     RenderOpts,
-    LintResult, 
     RenderResult,
-    RenderBackendProtocol
 )
 
 

tests/unit/video/test_render_retries.py

@@ -1,12 +1,13 @@
 """Tests for render retry functionality."""
 
-import pytest
 import tempfile
 from pathlib import Path
 
+import pytest
+
 try:
     from praisonai_tools.video.motion_graphics.agent import RenderTools
-    from praisonai_tools.video.motion_graphics.protocols import RenderResult, RenderOpts
+    from praisonai_tools.video.motion_graphics.protocols import RenderOpts, RenderResult
     AGENT_AVAILABLE = True
 except ImportError:
     AGENT_AVAILABLE = False

tmpc8_hvm6m.html

@@ -1 +0,0 @@
-<html>mock visualization</html>