PraisonAI 4.7.11__tar.gz → 4.7.12__tar.gz

{praisonai-4.7.11 → praisonai-4.7.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.7.11
+Version: 4.7.12
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,14 +11,14 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.7.9
-Requires-Dist: praisonai-code>=0.1.8
-Requires-Dist: praisonai-bot>=0.1.8
-Requires-Dist: praisonai-train>=0.1.8
-Requires-Dist: praisonai-browser>=0.1.8
-Requires-Dist: praisonai-mcp>=0.1.10
-Requires-Dist: praisonai-sandbox>=0.1.8
-Requires-Dist: praisonai-deploy>=0.1.8
+Requires-Dist: praisonaiagents>=1.7.10
+Requires-Dist: praisonai-code>=0.1.9
+Requires-Dist: praisonai-bot>=0.1.9
+Requires-Dist: praisonai-train>=0.1.9
+Requires-Dist: praisonai-browser>=0.1.9
+Requires-Dist: praisonai-mcp>=0.1.11
+Requires-Dist: praisonai-sandbox>=0.1.9
+Requires-Dist: praisonai-deploy>=0.1.9
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -182,7 +182,7 @@ Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgresql"
 Provides-Extra: dynamodb
 Requires-Dist: boto3>=1.35.0; extra == "dynamodb"
 Provides-Extra: valkey
-Requires-Dist: valkey-glide-sync>=2.3.1; extra == "valkey"
+Requires-Dist: valkey-glide-sync>=2.5.2; extra == "valkey"
 Provides-Extra: neon
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "neon"
 Provides-Extra: turso

{praisonai-4.7.11 → praisonai-4.7.12}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.7.11
+Version: 4.7.12
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,14 +11,14 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.7.9
-Requires-Dist: praisonai-code>=0.1.8
-Requires-Dist: praisonai-bot>=0.1.8
-Requires-Dist: praisonai-train>=0.1.8
-Requires-Dist: praisonai-browser>=0.1.8
-Requires-Dist: praisonai-mcp>=0.1.10
-Requires-Dist: praisonai-sandbox>=0.1.8
-Requires-Dist: praisonai-deploy>=0.1.8
+Requires-Dist: praisonaiagents>=1.7.10
+Requires-Dist: praisonai-code>=0.1.9
+Requires-Dist: praisonai-bot>=0.1.9
+Requires-Dist: praisonai-train>=0.1.9
+Requires-Dist: praisonai-browser>=0.1.9
+Requires-Dist: praisonai-mcp>=0.1.11
+Requires-Dist: praisonai-sandbox>=0.1.9
+Requires-Dist: praisonai-deploy>=0.1.9
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -182,7 +182,7 @@ Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgresql"
 Provides-Extra: dynamodb
 Requires-Dist: boto3>=1.35.0; extra == "dynamodb"
 Provides-Extra: valkey
-Requires-Dist: valkey-glide-sync>=2.3.1; extra == "valkey"
+Requires-Dist: valkey-glide-sync>=2.5.2; extra == "valkey"
 Provides-Extra: neon
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "neon"
 Provides-Extra: turso

{praisonai-4.7.11 → praisonai-4.7.12}/PraisonAI.egg-info/requires.txt

@@ -1,14 +1,14 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.7.9
-praisonai-code>=0.1.8
-praisonai-bot>=0.1.8
-praisonai-train>=0.1.8
-praisonai-browser>=0.1.8
-praisonai-mcp>=0.1.10
-praisonai-sandbox>=0.1.8
-praisonai-deploy>=0.1.8
+praisonaiagents>=1.7.10
+praisonai-code>=0.1.9
+praisonai-bot>=0.1.9
+praisonai-train>=0.1.9
+praisonai-browser>=0.1.9
+praisonai-mcp>=0.1.11
+praisonai-sandbox>=0.1.9
+praisonai-deploy>=0.1.9
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0
@@ -249,7 +249,7 @@ libsql-experimental>=0.0.50
 aiui<0.4,>=0.3.121
 
 [valkey]
-valkey-glide-sync>=2.3.1
+valkey-glide-sync>=2.5.2
 
 [xata]
 psycopg2-binary>=2.9.0

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/_api_auth.py

@@ -15,8 +15,11 @@ def build_api_key_middleware(api_key: str, public_paths: Optional[Iterable[str]]
         api_key: The expected API key; requests must present it via a
             ``Bearer`` ``Authorization`` header or ``X-API-Key`` header.
         public_paths: Paths that bypass authentication. Any request whose path
-            is in this set, or starts with ``/__praisonai__/``, is allowed
-            through without a token.
+            is in this set, or is exactly ``/__praisonai__/discovery`` (the
+            unauthenticated capability document), is allowed through without a
+            token. The discovery path is matched exactly -- never by prefix --
+            so a server whose ``api_prefix`` happens to sit under
+            ``/__praisonai__`` does not silently expose its routes.
 
     Imports of ``hmac``/``starlette`` are kept inside this function so callers
     stay lazy-import friendly.
@@ -26,11 +29,12 @@ def build_api_key_middleware(api_key: str, public_paths: Optional[Iterable[str]]
     from starlette.responses import JSONResponse
 
     public = set(public_paths or ())
+    public.add("/__praisonai__/discovery")
 
     class _APIKeyMiddleware(BaseHTTPMiddleware):
         async def dispatch(self, request, call_next):
             path = request.url.path
-            if path in public or path.startswith("/__praisonai__/"):
+            if path in public:
                 return await call_next(request)
             auth = request.headers.get("Authorization", "")
             header_key = request.headers.get("X-API-Key", "")

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/_async_bridge.py

@@ -384,6 +384,37 @@ def run_sync(coro: Awaitable[T], *, timeout: "float | None | _Unset" = _UNSET) -
     return _default_bridge().run_sync(coro, timeout=timeout)
 
 
+def run_cli_coro(coro: Awaitable[T], *, timeout: "float | None | _Unset" = None) -> T:
+    """Preferred entry point for CLI subcommands running a coroutine.
+
+    Routes through the shared :class:`AsyncBridge` (via :func:`run_sync`) so
+    per-loop connection pools survive across calls, any embedder-installed
+    ``scoped_bridge()`` is honoured, and a fresh event loop is NOT spawned on
+    every invocation. This replaces bare ``asyncio.run(...)`` at CLI leaves,
+    which tears down the loop each call and breaks per-loop cached clients
+    (e.g. ``httpx.AsyncClient``) with ``RuntimeError: Event loop is closed``.
+
+    Timeout defaults to ``None`` (**unbounded**) to preserve the prior
+    ``asyncio.run(...)`` semantics these leaves replaced: CLI commands own their
+    own runtime (an interactive sandbox shell, a multi-artifact ``standardise``
+    run, or a long background job must not be aborted by the 300s ``run_sync``
+    default). Callers that want a deadline pass an explicit ``timeout=``.
+
+    Sync context  -> :func:`run_sync` on the shared background loop.
+    Async context -> ``RuntimeError``; the caller must ``await coro`` directly.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return run_sync(coro, timeout=timeout)
+    with contextlib.suppress(Exception):
+        coro.close()  # type: ignore[attr-defined]
+    raise RuntimeError(
+        "run_cli_coro() cannot be called from within a running event loop; "
+        "await the coroutine directly instead."
+    )
+
+
 def run_sync_or_offload(
     coro: Awaitable[T],
     *,

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/_entrypoint.py

@@ -100,14 +100,9 @@ def run(agent_file: str,
     """
     from .agents_generator import AgentsGenerator
 
-    # Wire the built-in readers/retrievers/rerankers into the core-SDK
-    # registries so YAML/CLI declarations (e.g. `retriever: fusion`,
-    # `reranker: llm`) resolve. Idempotent + thread-safe, and register-only-if-
-    # absent: a custom adapter already registered under a built-in name (e.g. a
-    # multi-tenant host's own `fusion`) is preserved, never overwritten.
-    from .adapters import register_default_adapters
-    register_default_adapters()
-
+    # Adapter wiring (readers/retrievers/rerankers) is single-sourced in
+    # AgentsGenerator.__init__ so every launch path (CLI, serve, eval, Python)
+    # is covered identically.
     adapter, config_list = _resolve_run_inputs(framework)
     _apply_model_override(config_list, kwargs)
     cli_config = _merge_cli_config(cli_config, kwargs)
@@ -142,11 +137,11 @@ async def arun(agent_file: str,
 
     from .agents_generator import AgentsGenerator
 
-    # Wire the built-in readers/retrievers/rerankers into the core-SDK
-    # registries so YAML/CLI declarations resolve. Run off the event loop since
-    # registration performs lazy imports. Idempotent + thread-safe, and
-    # register-only-if-absent: a custom adapter already registered under a
-    # built-in name is preserved, never overwritten.
+    # Adapter wiring (readers/retrievers/rerankers) is single-sourced in
+    # AgentsGenerator.__init__. Pre-warm it off the caller's event loop here so
+    # the (lazy-import) registration does not run on the loop when the generator
+    # is constructed synchronously below. Idempotent: __init__ then hits the fast
+    # path. Every launch path is covered identically via __init__.
     from .adapters import register_default_adapters
     await asyncio.to_thread(register_default_adapters)
 
@@ -159,7 +154,8 @@ async def arun(agent_file: str,
 
     # Own the generator's lifecycle so its lazily-allocated tool-timeout
     # executor is released once the single run completes, instead of leaking
-    # daemon threads per call in long-lived async server workers.
+    # daemon threads per call in long-lived async server workers. Adapter wiring
+    # was pre-warmed above, so __init__ hits the fast path without blocking loop.
     with AgentsGenerator(
         agent_file=agent_file,
         framework=adapter.name,

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/agents_generator.py

@@ -599,6 +599,15 @@ class AgentsGenerator:
             task_callback (callable, optional): A callback function to be executed after each tool run.
             tools (dict): A dictionary containing the tools to be used for the agents.
         """
+        # Wire the built-in readers/retrievers/rerankers into the core-SDK
+        # registries so YAML `retriever:` / `reader:` / `reranker:` declarations
+        # resolve identically on every launch path (CLI, serve, eval, Python).
+        # Single-sourced here so surfaces that construct AgentsGenerator directly
+        # (praisonai <file.yaml>, serve, eval) get the same wiring as run()/arun().
+        # Idempotent + thread-safe + register-only-if-absent; safe to call again.
+        from .adapters import register_default_adapters
+        register_default_adapters()
+
         self.agent_file = agent_file
         self.framework = framework
         self.config_list = config_list
@@ -964,9 +973,23 @@ class AgentsGenerator:
         # Canonical format conversion: 'agents' -> 'roles', 'instructions' -> 'backstory'
         # Treat an empty ``roles: {}`` the same as a missing one so populated
         # ``agents:`` is still promoted instead of running with zero agents.
-        if 'agents' in config and not config.get('roles'):
-            config['roles'] = {}
+        #
+        # Promotion is *authoritative*: the shorthand ``agents:`` bucket is
+        # removed after merging into ``roles:`` so downstream validators and the
+        # executor read a single source of truth. Leaving ``agents:`` in place
+        # let validators see a merged ``{**roles, **agents}`` view the executor
+        # (which reads only ``roles:``) never runs — causing double-fired
+        # warnings, false-positive validation rejections, and silently dropped
+        # ``tool_timeout``/handoff knobs for agents that never became roles.
+        if 'agents' in config and isinstance(config['agents'], dict):
+            config.setdefault('roles', {})
+            if not isinstance(config['roles'], dict):
+                config['roles'] = {}
             for agent_name, agent_config in config['agents'].items():
+                # An entry already present under ``roles:`` is canonical and
+                # wins; only agents-only entries are promoted.
+                if agent_name in config['roles']:
+                    continue
                 role_config = dict(agent_config) if agent_config else {}
                 # Convert 'instructions' to 'backstory' if present
                 if 'instructions' in role_config and 'backstory' not in role_config:
@@ -979,6 +1002,8 @@ class AgentsGenerator:
                 if 'backstory' not in role_config:
                     role_config['backstory'] = f'You are a {role_config["role"]}'
                 config['roles'][agent_name] = role_config
+            # Drop the shorthand bucket so validators and the executor agree.
+            del config['agents']
 
         # Get workflow input: 'input' is canonical, 'topic' is alias for backward compatibility
         topic = config.get('input', config.get('topic', ''))

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/api/agent_invoke.py

@@ -697,7 +697,11 @@ if FASTAPI_AVAILABLE and APIRouter is not None:
         if hasattr(agent, 'name'):
             info["name"] = agent.name
         if hasattr(agent, 'instructions'):
-            info["instructions"] = agent.instructions[:200] + "..." if len(agent.instructions) > 200 else agent.instructions
+            instructions = agent.instructions
+            if isinstance(instructions, str) and len(instructions) > 200:
+                info["instructions"] = instructions[:200] + "..."
+            else:
+                info["instructions"] = instructions
         if hasattr(agent, 'tools') and agent.tools:
             info["tools"] = [getattr(tool, 'name', str(tool)) for tool in agent.tools[:5]]  # First 5 tools
             if len(agent.tools) > 5:

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/api/call.py

@@ -10,7 +10,7 @@ import importlib.util
 import threading
 import time
 from typing import Optional
-from collections import defaultdict
+from collections import OrderedDict
 
 # Heavy, optional dependencies (websockets, fastapi, twilio, uvicorn, pyngrok,
 # rich) are imported lazily inside the functions that need them. Importing this
@@ -93,15 +93,6 @@ MAX_CONCURRENT_CONNECTIONS = int(os.getenv('MAX_CONCURRENT_CONNECTIONS', '5'))
 MAX_REQUESTS_PER_WINDOW = int(os.getenv('MAX_REQUESTS_PER_WINDOW', '100'))
 RATE_LIMIT_WINDOW = 3600
 
-active_connections = 0
-client_ips = defaultdict(list)
-
-# Guard the shared, async-mutated counters so concurrent WebSocket handlers
-# can't over-commit MAX_CONCURRENT_CONNECTIONS / MAX_REQUESTS_PER_WINDOW via a
-# check-then-mutate TOCTOU across ``await`` points.
-_conn_lock = asyncio.Lock()
-_ips_lock = asyncio.Lock()
-
 # One-shot, short-lived session tokens handed to the Twilio media-stream client
 # so the shared server secret is never embedded in a URL (which leaks into
 # access logs / referrers / history).
@@ -114,16 +105,69 @@ class CallAppState:
     Replaces the previous module-level ``tools`` / ``_pending_stream_sessions``
     globals so co-hosted / multi-tenant ``build_call_app()`` instances in one
     process never share a tool schema or cross-consume each other's stream
-    tokens. FastAPI hands this to handlers via ``request.app.state`` /
-    ``websocket.app.state``.
+    tokens. The rate-limit / capacity primitives (``active_connections``,
+    ``client_ips``) live here too so co-hosted tenants never cross-consume each
+    other's connection budget, and the IP map is LRU-bounded so a caller behind
+    rotating IPs cannot grow it without bound. FastAPI hands this to handlers via
+    ``request.app.state`` / ``websocket.app.state``.
     """
 
-    __slots__ = ("tools", "pending_sessions", "_lock")
+    __slots__ = (
+        "tools", "pending_sessions", "_lock",
+        "active_connections", "conn_lock",
+        "client_ips", "ips_lock", "max_ips",
+    )
 
-    def __init__(self):
+    def __init__(self, max_tracked_ips: int = 10_000):
         self.tools: list = []
         self.pending_sessions: "dict[str, float]" = {}
         self._lock = threading.Lock()
+        self.active_connections = 0
+        self.conn_lock = asyncio.Lock()
+        self.client_ips: "OrderedDict[str, list[float]]" = OrderedDict()
+        self.ips_lock = asyncio.Lock()
+        self.max_ips = max_tracked_ips
+
+    def touch_ip(self, ip: str, now: float) -> "list[float]":
+        """Return this IP's live request timestamps (window), LRU-bounded.
+
+        Only prunes expired timestamps out of the returned window — it does NOT
+        record the current request. The caller inspects the returned window
+        against ``MAX_REQUESTS_PER_WINDOW`` and, if admitted, calls
+        :meth:`record_ip` to append the new timestamp. Empty entries are dropped
+        eagerly so the map cannot grow from IPs whose windows have all expired.
+        Callers hold ``ips_lock`` across ``touch_ip`` + ``record_ip`` so the
+        check-then-record stays atomic across ``await`` points.
+        """
+        window = [t for t in self.client_ips.get(ip, ()) if now - t < RATE_LIMIT_WINDOW]
+        if window:
+            self.client_ips[ip] = window
+            self.client_ips.move_to_end(ip)
+        else:
+            # No live timestamps: drop the stale entry now. It is only re-added
+            # by record_ip() if this request is admitted, so a rejected caller
+            # never leaves a residue.
+            self.client_ips.pop(ip, None)
+        return window
+
+    def record_ip(self, ip: str, window: "list[float]", now: float) -> None:
+        """Append ``now`` to this IP's admitted-request window and enforce the cap.
+
+        Pins ``ip`` as the most-recently-used entry, then evicts the oldest
+        entries so the map holds at most ``max_ips`` keys *after* this insert.
+        Eviction runs post-insert so the live caller is never the victim and the
+        map never transiently exceeds ``max_ips`` — the cap it promises. Because
+        eviction can drop another IP whose window is still open, ``max_ips``
+        should be provisioned above the realistic distinct-IP working set (the
+        10k default), so eviction only bites under a rotating-IP flood — exactly
+        the unbounded-growth case the bound exists to contain.
+        """
+        window.append(now)
+        self.client_ips[ip] = window
+        self.client_ips.move_to_end(ip)
+        while len(self.client_ips) > self.max_ips:
+            # last=False evicts the oldest (LRU); the just-touched ip is MRU.
+            self.client_ips.popitem(last=False)
 
     def mint_stream_token(self) -> str:
         """Create a single-use, TTL-bound token for the media-stream handshake."""
@@ -456,8 +500,6 @@ async def handle_media_stream(websocket):
     import websockets
     from fastapi.websockets import WebSocketDisconnect
 
-    global active_connections
-    
     # 1. Authentication — accept a one-shot, per-connection session token
     #    (from the ``session`` query param minted by the incoming-call handler,
     #    or an ``x-call-token`` header). The shared CALL_SERVER_TOKEN is never
@@ -481,22 +523,20 @@ async def handle_media_stream(websocket):
     #    over-commit the window via a check-then-mutate race across ``await``.
     client_ip = websocket.client.host if websocket.client else "unknown"
     now = time.time()
-    async with _ips_lock:
-        window = [t for t in client_ips[client_ip] if now - t < RATE_LIMIT_WINDOW]
+    async with state.ips_lock:
+        window = state.touch_ip(client_ip, now)
         if len(window) >= MAX_REQUESTS_PER_WINDOW:
-            client_ips[client_ip] = window
             await websocket.close(code=4029, reason="Rate limit exceeded")
             return
-        window.append(now)
-        client_ips[client_ip] = window
+        state.record_ip(client_ip, window, now)
 
     # 3. Connection Limiting — atomically check-and-increment under the lock so
     #    MAX_CONCURRENT_CONNECTIONS is never over-committed.
-    async with _conn_lock:
-        if active_connections >= MAX_CONCURRENT_CONNECTIONS:
+    async with state.conn_lock:
+        if state.active_connections >= MAX_CONCURRENT_CONNECTIONS:
             await websocket.close(code=1013, reason="Server busy")
             return
-        active_connections += 1
+        state.active_connections += 1
     try:
         print("Client connected")
         await websocket.accept()
@@ -570,8 +610,8 @@ async def handle_media_stream(websocket):
 
             await asyncio.gather(receive_from_twilio(), send_to_twilio())
     finally:
-        async with _conn_lock:
-            active_connections -= 1
+        async with state.conn_lock:
+            state.active_connections -= 1
 
 async def handle_response_done(state, response, openai_ws):
     """Handle the response.done event and process any function calls."""

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/app/agentos.py

@@ -128,22 +128,8 @@ class AgentOS:
 
         launch_token = self.config.api_key or os.environ.get("PRAISONAI_AGENTOS_API_KEY")
         if launch_token:
-            from starlette.middleware.base import BaseHTTPMiddleware
-            from starlette.responses import JSONResponse
-
-            expected = launch_token
-
-            class _AgentOSAuthMiddleware(BaseHTTPMiddleware):
-                async def dispatch(self, request, call_next):
-                    if request.url.path in ("/health", "/"):
-                        return await call_next(request)
-                    auth = request.headers.get("Authorization", "")
-                    token = auth[7:] if auth.startswith("Bearer ") else request.headers.get("X-API-Key", "")
-                    if token != expected:
-                        return JSONResponse({"error": "Unauthorized"}, status_code=401)
-                    return await call_next(request)
-
-            app.add_middleware(_AgentOSAuthMiddleware)
+            from .._api_auth import build_api_key_middleware
+            app.add_middleware(build_api_key_middleware(launch_token, {"/health", "/"}))
         
         return app
     

{praisonai-4.7.11 → praisonai-4.7.12}/praisonai/auto.py

@@ -16,6 +16,7 @@ import json
 import re
 import asyncio
 import threading
+import warnings
 from praisonai._logging import get_logger
 
 # Type variable for Pydantic models - will be bound at runtime
@@ -1046,7 +1047,9 @@ class AutoGenerator(BaseAutoGenerator):
                 generate → run round-trip agrees on defaults.
             config_list: Optional LLM configuration
             pattern: Workflow pattern (sequential, parallel, routing, orchestrator-workers, evaluator-optimizer)
-            single_agent: If True, generate a single agent instead of a team
+            single_agent: Deprecated and inert. Single-agent generation is not
+                implemented; a team structure is always generated. Passing a
+                truthy value emits a ``DeprecationWarning``.
         
         Note: autogen framework is different from this AutoGenerator class.
         """
@@ -1077,6 +1080,12 @@ class AutoGenerator(BaseAutoGenerator):
         # Authoritative framework name comes from the resolved adapter.
         self.framework = adapter.name
         self.pattern = pattern
+        if single_agent:
+            warnings.warn(
+                "single_agent generation is not implemented; a team structure "
+                "is generated instead. This parameter is deprecated and inert.",
+                DeprecationWarning, stacklevel=2,
+            )
         self.single_agent = single_agent
     
 
@@ -1638,7 +1647,9 @@ class WorkflowAutoGenerator(BaseAutoGenerator):
                 the generate → run round-trip agrees on defaults. The adapter
                 is validated here rather than deferring the failure to a later
                 ``praisonai run`` invocation.
-            single_agent: If True, generate a single agent workflow
+            single_agent: Deprecated and inert. Single-agent workflow generation
+                is not implemented; a workflow structure is always generated.
+                Passing a truthy value emits a ``DeprecationWarning``.
             workspace: Optional workspace root; when set, ``workflow_file`` is
                 contained to it to reject path traversal (see BaseAutoGenerator).
         """
@@ -1657,6 +1668,13 @@ class WorkflowAutoGenerator(BaseAutoGenerator):
         self.topic = topic
         self.workflow_file = self._safe_join(workflow_file)
         self.framework = adapter.name
+        if single_agent:
+            warnings.warn(
+                "single_agent generation is not implemented; a workflow "
+                "structure is generated instead. This parameter is deprecated "
+                "and inert.",
+                DeprecationWarning, stacklevel=2,
+            )
         self.single_agent = single_agent
     
     def recommend_pattern_llm(self, topic: Optional[str] = None) -> Any: