fix: resolve three high-impact gaps in praisonai wrapper layer

src/praisonai/praisonai/auto.py

@@ -14,6 +14,7 @@
 from typing import Any, Dict, List, Optional, Type, TypeVar
 import os
 import json
+import asyncio
 import yaml
 import threading
 from rich import print
@@ -423,12 +424,13 @@ def __init__(self, config_list: Optional[List[Dict]] = None):
             }
         ]
         self._openai_client = None  # lazy, per-instance
-        self._openai_client_lock = threading.Lock()
+        self._async_openai_client = None  # lazy, per-instance async client
+        self._client_lock = threading.Lock()
 
     def _get_openai_client(self):
         """Get or create the OpenAI client for this instance."""
         if self._openai_client is None:
-            with self._openai_client_lock:
+            with self._client_lock:
                 if self._openai_client is None:
                     try:
                         from openai import OpenAI
@@ -442,18 +444,43 @@ def _get_openai_client(self):
         return self._openai_client
 
     def close(self):
-        """Close the OpenAI client if it exists."""
-        if not hasattr(self, '_openai_client_lock'):
+        """Close the sync OpenAI client if it exists."""
+        if not hasattr(self, '_client_lock'):
             return  # Object was never fully initialized
-        with self._openai_client_lock:
+        with self._client_lock:
             client = getattr(self, '_openai_client', None)
             self._openai_client = None
         if client is not None:
             client.close()
-
-    def __del__(self):
-        """Best-effort cleanup, but the canonical path is explicit close()."""
+
+    async def aclose(self):
+        """Close both sync and async OpenAI clients if they exist."""
+        if not hasattr(self, '_client_lock'):
+            return  # Object was never fully initialized
+        with self._client_lock:
+            sync_client = getattr(self, '_openai_client', None)
+            self._openai_client = None
+            async_client = getattr(self, '_async_openai_client', None)
+            self._async_openai_client = None
+        if sync_client is not None:
+            await asyncio.to_thread(sync_client.close)
+        if async_client is not None:
+            await async_client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
         self.close()
+        return False
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.aclose()
+        return False
+
 
     def _structured_completion(self, response_model: Type[T], messages: List[Dict], **kwargs) -> T:
         """
@@ -505,6 +532,68 @@ def _structured_completion(self, response_model: Type[T], messages: List[Dict],
             "Install with: pip install litellm  OR  pip install openai"
         )
 
+    async def _astructured_completion(self, response_model: Type[T], messages: List[Dict], **kwargs) -> T:
+        """
+        Make an async structured LLM completion with provider fallback.
+
+        Priority:
+        1. LiteLLM async (if available) - supports 100+ LLM providers
+        2. OpenAI AsyncSDK (fallback) - uses beta.chat.completions.parse
+
+        Args:
+            response_model: Pydantic model class for structured output
+            messages: List of message dicts for the LLM
+            **kwargs: Additional arguments passed to the LLM
+
+        Returns:
+            Instance of response_model with parsed response
+
+        Raises:
+            ImportError: If neither litellm nor openai is installed
+        """
+        model_name = self.config_list[0]['model']
+
+        # Try LiteLLM async first (preferred - supports 100+ providers)
+        if _check_litellm_available():
+            litellm = _get_litellm()
+            response = await litellm.acompletion(
+                model=model_name,
+                messages=messages,
+                response_format=response_model,
+                **kwargs
+            )
+            content = response.choices[0].message.content
+            return response_model.model_validate_json(content)
+
+        # Fallback to OpenAI AsyncSDK (uses beta.chat.completions.parse)
+        if _check_openai_available():
+            if self._async_openai_client is None:
+                with self._client_lock:
+                    if self._async_openai_client is None:
+                        try:
+                            from openai import AsyncOpenAI
+                        except ImportError as e:
+                            raise ImportError("Install with: pip install openai") from e
+                        cfg = self.config_list[0]
+                        self._async_openai_client = AsyncOpenAI(
+                            api_key=cfg.get("api_key") or os.environ.get("OPENAI_API_KEY"),
+                            base_url=cfg.get("base_url"),
+                        )
+
+            response = await self._async_openai_client.beta.chat.completions.parse(
+                model=model_name,
+                messages=messages,
+                response_format=response_model,
+                **kwargs
+            )
+            return response.choices[0].message.parsed
+
+        # Neither available - raise helpful error
+        raise ImportError(
+            "Structured output requires either litellm or openai. "
+            "Install with: pip install litellm  OR  pip install openai"
+        )
+
     @staticmethod
     def get_available_tools() -> List[str]:
         """Return list of available tools for agent assignment."""
@@ -708,6 +797,36 @@ def generate(self, merge=False):
         self.convert_and_save(json_data, merge=merge)
         full_path = os.path.abspath(self.agent_file)
         return full_path
+
+    async def agenerate(self, merge=False):
+        """
+        Async version of generate() - generates a team structure for the specified topic.
+
+        Args:
+            merge (bool): Whether to merge with existing agents.yaml file instead of overwriting.
+
+        Returns:
+            str: The full path of the YAML file containing the generated team structure.
+
+        Raises:
+            Exception: If the generation process fails.
+
+        Usage:
+            async with AutoGenerator(framework="crewai", topic="Create a movie script about Cat in Mars") as gen:
+                path = await gen.agenerate()
+                print(path)
+        """
+        response = await self._astructured_completion(
+            response_model=TeamStructure,
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant designed to output complex team structures."},
+                {"role": "user", "content": self.get_user_content()}
+            ]
+        )
+        json_data = json.loads(response.model_dump_json())
+        self.convert_and_save(json_data, merge=merge)
+        full_path = os.path.abspath(self.agent_file)
+        return full_path
 
     def convert_and_save(self, json_data, merge=False):
         """Converts the provided JSON data into the desired YAML format and saves it to a file.
@@ -1121,6 +1240,32 @@ def generate(self, pattern: str = "sequential", merge: bool = False) -> str:
             return self._save_workflow(self.merge_with_existing_workflow(json_data), pattern)
         return self._save_workflow(json_data, pattern)
 
+    async def agenerate(self, pattern: str = "sequential", merge: bool = False) -> str:
+        """
+        Async version of generate() - Generate a workflow YAML file.
+
+        Args:
+            pattern: Workflow pattern - "sequential", "routing", "parallel", "loop",
+                     "orchestrator-workers", "evaluator-optimizer"
+            merge: If True, merge with existing workflow file instead of overwriting
+
+        Returns:
+            Path to the generated workflow file
+        """
+        response = await self._astructured_completion(
+            response_model=WorkflowStructure,
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant that designs workflow structures."},
+                {"role": "user", "content": self._get_prompt(pattern)}
+            ]
+        )
+
+        json_data = json.loads(response.model_dump_json())
+
+        if merge and os.path.exists(self.workflow_file):
+            return self._save_workflow(self.merge_with_existing_workflow(json_data), pattern)
+        return self._save_workflow(json_data, pattern)
+
     def merge_with_existing_workflow(self, new_data: Dict) -> Dict:
         """
         Merge new workflow data with existing workflow file.
@@ -1421,6 +1566,29 @@ def generate(self, include_judge: bool = True, include_approve: bool = False) ->
 
         return self._save_workflow(response)
 
+    async def agenerate(self, include_judge: bool = True, include_approve: bool = False) -> str:
+        """
+        Async version of generate() - Generate a job workflow YAML file.
+
+        Args:
+            include_judge: Include a judge step for quality gating
+            include_approve: Include an approve step for human approval
+
+        Returns:
+            Path to the generated workflow file
+        """
+        prompt = self._get_prompt(include_judge, include_approve)
+
+        response = await self._astructured_completion(
+            response_model=JobWorkflowStructure,
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant that designs job workflow structures with AI agent steps."},
+                {"role": "user", "content": prompt}
+            ]
+        )
+
+        return self._save_workflow(response)
+
     def _get_prompt(self, include_judge: bool, include_approve: bool) -> str:
         """Generate the prompt for job workflow generation."""
         tools_list = ", ".join(self.get_available_tools())

src/praisonai/praisonai/tool_resolver.py

@@ -64,7 +64,9 @@ def __init__(
             tools_py_path: Optional path to tools.py. If None, uses ./tools.py
             registry: Optional ToolRegistry to include in resolution chain
         """
-        self._tools_py_path = tools_py_path or "tools.py"
+        from pathlib import Path
+        # Resolve path eagerly in constructor to make binding explicit and inspectable
+        self._tools_py_path = str(Path(tools_py_path or "tools.py").resolve())
         self._local_tools_cache: Mapping[str, Callable] = MappingProxyType({})
         self._local_tools_loaded: bool = False
         self._praisonai_tools_available: Optional[bool] = None
@@ -577,3 +579,17 @@ def validate_yaml_tools(yaml_config: Dict[str, Any], resolver: Optional[ToolReso
         List of missing tool names
     """
     return (resolver or _get_default_resolver()).validate_yaml_tools(yaml_config)
+
+
+def reset_default_resolver() -> None:
+    """Clear the process-default resolver.
+
+    Call this between tenants, on CWD change, or in test setup to ensure
+    that local tools.py resolution is not affected by previous calls.
+
+    This follows the same pattern as _framework_availability.invalidate()
+    for resetting cached state.
+    """
+    global _default_resolver
+    with _default_resolver_lock:
+        _default_resolver = None

src/praisonai/praisonai/train.py

@@ -549,12 +549,13 @@ def prepare_modelfile_content(self):
     """
 
     def create_and_push_ollama_model(self):
+        from ._ollama import create_and_push_ollama_model
         modelfile_content = self.prepare_modelfile_content()
-        with open("Modelfile", "w") as file:
-            file.write(modelfile_content)
-        subprocess.run(["ollama", "serve"])
-        subprocess.run(["ollama", "create", f"{self.config['ollama_model']}:{self.config['model_parameters']}", "-f", "Modelfile"])
-        subprocess.run(["ollama", "push", f"{self.config['ollama_model']}:{self.config['model_parameters']}"])
+        create_and_push_ollama_model(
+            self.config['ollama_model'], 
+            self.config['model_parameters'], 
+            modelfile_content
+        )
 
     def run(self):
         self.print_system_info()

src/praisonai/praisonai/train/_ollama.py

@@ -0,0 +1,97 @@
+"""Shared Ollama daemon management utilities.
+
+This module provides utilities to start and check Ollama daemon status,
+fixing the blocking subprocess.run(["ollama", "serve"]) issue present
+in multiple files.
+"""
+import contextlib
+import shutil
+import socket
+import subprocess
+import time
+from typing import Optional
+
+
+def _ollama_ready(host: str = "127.0.0.1", port: int = 11434, timeout: float = 0.2) -> bool:
+    """Check if Ollama daemon is ready to accept connections.
+
+    Args:
+        host: Ollama host (default 127.0.0.1)
+        port: Ollama port (default 11434)
+        timeout: Connection timeout in seconds
+
+    Returns:
+        True if Ollama is ready, False otherwise
+    """
+    with contextlib.suppress(OSError):
+        with socket.create_connection((host, port), timeout):
+            return True
+    return False
+
+
+def ensure_ollama_running(max_wait_seconds: float = 5.0) -> Optional[subprocess.Popen]:
+    """Ensure Ollama daemon is running, start it if necessary.
+
+    Args:
+        max_wait_seconds: Maximum time to wait for daemon to become ready
+
+    Returns:
+        Process object if we started the daemon, None if it was already running
+
+    Raises:
+        RuntimeError: If ollama CLI not found or daemon doesn't become ready
+    """
+    # Check if already running
+    if _ollama_ready():
+        return None
+
+    # Check if ollama CLI is available
+    if shutil.which("ollama") is None:
+        raise RuntimeError("`ollama` CLI not found; install from https://ollama.com")
+
+    # Start daemon in detached mode
+    proc = subprocess.Popen(
+        ["ollama", "serve"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,  # Detach from parent
+    )
+
+    # Poll until ready or timeout
+    wait_interval = 0.1
+    max_polls = int(max_wait_seconds / wait_interval)
+
+    for _ in range(max_polls):
+        if _ollama_ready():
+            return proc
+        time.sleep(wait_interval)
+
+    # If we get here, daemon didn't become ready in time
+    proc.terminate()
+    raise RuntimeError(f"ollama serve did not become ready in {max_wait_seconds} seconds")
+
+
+def create_and_push_ollama_model(ollama_model: str, model_parameters: str, modelfile_content: str) -> None:
+    """Create and push an Ollama model with proper daemon management.
+
+    Args:
+        ollama_model: Name of the Ollama model
+        model_parameters: Model parameters/tag
+        modelfile_content: Content for the Modelfile
+
+    Raises:
+        RuntimeError: If ollama operations fail
+        subprocess.CalledProcessError: If create/push commands fail
+    """
+    # Write Modelfile
+    with open("Modelfile", "w") as f:
+        f.write(modelfile_content)
+
+    # Ensure daemon is running
+    ensure_ollama_running()
+
+    # Create and push model
+    tag = f"{ollama_model}:{model_parameters}"
+
+    subprocess.run(["ollama", "create", tag, "-f", "Modelfile"], check=True)
+    subprocess.run(["ollama", "push", tag], check=True)