refactor: updated docs to new wrapper API

Author: javidsegura

.github/workflows/continuous_integration.yml

@@ -3,11 +3,11 @@ on: [push, pull_request]
 
 jobs:
       lint_and_format:
-            runs-on: ubuntu-latest 
+            runs-on: ubuntu-latest
             steps:
                   - name: Fetch code
                     uses: actions/checkout@v3
-                  # - name: Check linting 
+                  # - name: Check linting
                   #   uses: astral-sh/ruff-action@v1
                   #   with:
                   #       args: "check"
@@ -19,27 +19,27 @@ jobs:
           needs: lint_and_format
           steps:
                 - name: Fetch code
-                  uses: actions/checkout@v3 
+                  uses: actions/checkout@v3
                 - name: "Install dependecies"
                   run: pip install bandit
                 - name: "Check with bandit"
                   run: bandit -r src/
       tests:
-        runs-on: ubuntu-latest 
+        runs-on: ubuntu-latest
         needs: lint_and_format
         strategy:
           matrix:
             python-version: ['3.10', '3.11']
         steps:
           - name: Fetch code
-            uses: actions/checkout@v3 
-          
+            uses: actions/checkout@v3
+
           - name: Set up python ${{ matrix.python-version }}
             uses: actions/setup-python@v4
             with:
               python-version: ${{ matrix.python-version }}
               cache: 'pip'
-          
+
           - name: Cache pip dependencies
             uses: actions/cache@v3
             with:
@@ -48,27 +48,20 @@ jobs:
               restore-keys: |
                 ${{ runner.os }}-pip-${{ matrix.python-version }}-
                 ${{ runner.os }}-pip-
-          
-          - name: "Install graphviz"
-            run: |
-              sudo apt-get update
-              sudo apt-get install -y graphviz graphviz-dev
-            shell: bash
-          
+
           - name: "Create virtual environment"
             run: |
               python -m venv .venv
             shell: bash
-          
+
           - name: "Install dependencies"
             run: |
               source .venv/bin/activate
               pip install -e ".[dev]"
-              pip install pygraphviz
             shell: bash
-          
+
           - name: Run python tests with coverage
-            env: 
+            env:
                 OPEN_ROUTER_API_KEY: ${{ secrets.OPEN_ROUTER_API_KEY }}
             run: |
               source .venv/bin/activate
@@ -79,13 +72,13 @@ jobs:
                 --cov-report=term:skip-covered \
                 tests/
             shell: bash
-          
+
           - name: "Show coverage summary"
             if: always()
             run: |
                 echo "=== Coverage Summary ==="
                 coverage report || echo "Coverage report not available"
-          
+
           - name: Upload results of test coverage
             uses: actions/upload-artifact@v4
             if: always()

.gitignore

@@ -41,4 +41,11 @@ logs/
 # Temporary files
 *.tmp
 
-uv.lock
+uv.lock
+
+#Ignore vscode AI rules
+.github/instructions/codacy.instructions.md
+.venv/
+
+
+tests/benchmark/results/

Makefile

@@ -20,9 +20,15 @@ VENV_ACTIVATE = source $(VENV_PATH)/bin/activate
 help: ## Show this help message
 	@printf "$(BLUE) Available commands: $(RESET)\n"
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  $(GREEN)%-15s$(RESET) %s\n", $$1, $$2}' $(MAKEFILE_LIST)
-install: ## Installation
+install: ## Install core dev dependencies
 	uv venv $(VENV_PATH) --python 3.10
 	uv pip install -e ".[dev]"
+install-benchmark: ## Install dev + benchmark dependencies (langgraph + asyncflow)
+	uv venv $(VENV_PATH) --python 3.10
+	uv pip install -e ".[langgraph,asyncflow,dev]"
+install-all: ## Install all dependencies (frameworks + runtimes + dev)
+	uv venv $(VENV_PATH) --python 3.10
+	uv pip install -e ".[all,dev]"
 
 # 2) Examples
 examples-lg-asyncflow:  ## Langgraph + Asyncflow
@@ -40,5 +46,5 @@ examples-ag-parsl:  ## AutoGen + Parsl
 benchmark: ## Run the experiments in the benchmarking
 	$(VENV_ACTIVATE) && python3 -m tests.benchmark.data_generation.run_experiments
 
-benchmark-suite: ## Run the full benchmark suite with multiple configs
+benchmark-multiple-workloads: ## Run the full benchmark suite with multiple configs
 	$(VENV_ACTIVATE) && python3 -m tests.benchmark.run_benchmark_suite

pyproject.toml

@@ -10,25 +10,48 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "pydantic>=2.0.0",
+    "python-json-logger>=2.0.0",
+    "python-dotenv",
+    "cloudpickle>=3.1.2",
+]
+
+[project.optional-dependencies]
+# --- Per-component extras (pick only what you need) ---
+langgraph = [
     "langgraph>=0.6.6",
-    "radical-asyncflow",
     "langchain-openai",
     "langchain",
     "langchain-ollama",
     "langchain-core",
     "langchain-community",
     "langchain-mcp-adapters",
-    "python-dotenv",
-    "academy-py",
-    "pydantic>=2.0.0",
-    "python-json-logger>=2.0.0",
+]
+crewai = [
     "crewai[google-genai]",
+]
+autogen = [
     "autogen>=0.10.4",
+]
+asyncflow = [
+    "radical-asyncflow",
+]
+parsl = [
     "parsl>=2026.1.19",
-    "cloudpickle>=3.1.2",
 ]
-
-[project.optional-dependencies]
+academy = [
+    "academy-py",
+]
+# --- Convenience bundles ---
+frameworks = [
+    "flowgentic[langgraph,crewai,autogen]",
+]
+runtime = [
+    "flowgentic[asyncflow,parsl,academy]",
+]
+all = [
+    "flowgentic[frameworks,runtime]",
+]
 dev = [
     "ruff>=0.12.11",
     "pre-commit",
@@ -41,10 +64,9 @@ dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "uv>=0.1.0",
-    "pytest-asyncio>=0.21.0",
     "pytest-cov",
     "matplotlib",
-    "cloudpickle"
+    "cloudpickle",
 ]
 
 [project.scripts]
@@ -102,3 +124,10 @@ radical-asyncflow = { git = "https://github.com/radical-cybertools/radical.async
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+# Exclude tests whose modules no longer exist on this branch
+addopts = [
+    "--ignore=tests/integration",
+    "--ignore=tests/unit/test_generator.py",
+    "--ignore=tests/unit/test_introspection.py",
+    "--ignore=tests/unit/test_memory.py",
+]

src/flowgentic/agent_orchestration_frameworks/langgraph.py

@@ -1,10 +1,22 @@
-from functools import wraps
 import time
 import uuid
+from functools import wraps
 from typing import Any, Callable, Optional
+
 from flowgentic.agent_orchestration_frameworks.base import AgentOrchestrator
 from flowgentic.backend_engines.base import BaseEngine
-from langchain_core.tools import tool as langchain_tool
+
+
+def _langchain_tool(func: Callable) -> Callable:
+	"""Lazy wrapper so langchain-core is only imported when actually used."""
+	try:
+		from langchain_core.tools import tool as _tool
+	except ModuleNotFoundError as exc:
+		raise ImportError(
+			"langchain-core is required for LanGraphOrchestrator. "
+			'Install it with: pip install "flowgentic[langgraph]"'
+		) from exc
+	return _tool(func)
 
 
 class LanGraphOrchestrator(AgentOrchestrator):
@@ -21,27 +33,55 @@ def deco(f: Callable):
 			# Emit setup start event
 			self.engine.emit(
 				{
-					"event": "task_wrap_start",
+					"event": "tool_wrap_start",
 					"ts": time.perf_counter(),
-					"task_name": task_name,
+					"tool_name": task_name,
 					"wrap_id": wrap_id,
 				}
 			)
 
 			@wraps(f)
 			async def wrapper(*args, **kwargs):
-				return await self.engine.execute_tool(
-					f, *args, task_kwargs=task_kwargs, **kwargs
+				invocation_id = str(uuid.uuid4())
+
+				# Ts_invoke_start: LangGraph calls tool, FlowGentic intercepts
+				self.engine.emit(
+					{
+						"event": "tool_invoke_start",
+						"ts": time.perf_counter(),
+						"tool_name": task_name,
+						"invocation_id": invocation_id,
+					}
 				)
 
-			wrapped_tool = langchain_tool(wrapper)
+				result = await self.engine.execute_tool(
+					f,
+					*args,
+					task_kwargs=task_kwargs,
+					invocation_id=invocation_id,
+					**kwargs,
+				)
+
+				# Ts_collect_end: Result returned to LangGraph
+				self.engine.emit(
+					{
+						"event": "tool_invoke_end",
+						"ts": time.perf_counter(),
+						"tool_name": task_name,
+						"invocation_id": invocation_id,
+					}
+				)
+
+				return result
+
+			wrapped_tool = _langchain_tool(wrapper)
 
 			# Emit setup end event
 			self.engine.emit(
 				{
-					"event": "task_wrap_end",
+					"event": "tool_wrap_end",
 					"ts": time.perf_counter(),
-					"task_name": task_name,
+					"tool_name": task_name,
 					"wrap_id": wrap_id,
 				}
 			)

src/flowgentic/backend_engines/base.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any, Callable, List, Optional, Tuple, Dict
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 
 class BaseEngine(ABC):
@@ -22,6 +22,7 @@ async def execute_tool(
 		func: Callable,
 		*args,
 		task_kwargs: Optional[Dict[str, Any]] = None,
+		invocation_id: Optional[str] = None,
 		**kwargs,
 	) -> Dict[str, Any]:
 		pass

src/flowgentic/backend_engines/parsl.py

@@ -1,16 +1,24 @@
 import asyncio
+import time
+from typing import Any, Callable, Dict, Optional
+
 import parsl
 from parsl.app.app import python_app
-from typing import Callable, Dict, Any
 from parsl.config import Config
+
 from flowgentic.backend_engines.base import BaseEngine
 
 
 class ParslEngine(BaseEngine):
-	def __init__(self, config: Config = None):
+	def __init__(
+		self,
+		config: Config = None,
+		observer: Optional[Callable[[Dict[str, Any]], None]] = None,
+	):
+		super().__init__(observer=observer)
 		parsl.load(config)
 
-		self._task_registry = {}
+		self._task_registry: Dict[str, Any] = {}
 
 	def _make_parsl_app(self, func: Callable):
 		if asyncio.iscoroutinefunction(func):
@@ -21,15 +29,48 @@ def wrapper(*args, **kwargs):
 			return python_app(wrapper)
 		return python_app(func)
 
-	async def execute_tool(self, func: Callable, *args, **kwargs) -> Dict[str, Any]:
-		if func.__name__ not in self._task_registry:
-			self._task_registry[func.__name__] = self._make_parsl_app(func)
+	async def execute_tool(
+		self,
+		func: Callable,
+		*args,
+		task_kwargs: Optional[Dict[str, Any]] = None,
+		invocation_id: Optional[str] = None,
+		**kwargs,
+	) -> Dict[str, Any]:
+		task_name = getattr(func, "__name__", str(func))
+
+		# Track whether the task app was already cached
+		cache_hit = task_name in self._task_registry
+		if not cache_hit:
+			self._task_registry[task_name] = self._make_parsl_app(func)
 
-		task_app = self._task_registry[func.__name__]
+		task_app = self._task_registry[task_name]
+
+		# Ts_resolve_end: Task descriptor resolved, about to enter Parsl
+		self.emit(
+			{
+				"event": "tool_resolve_end",
+				"ts": time.perf_counter(),
+				"tool_name": task_name,
+				"invocation_id": invocation_id,
+				"cache_hit": cache_hit,
+			}
+		)
 
 		future = task_app(*args, **kwargs)
+		result = await asyncio.to_thread(future.result)
+
+		# Ts_collect_start: Result received from Parsl
+		self.emit(
+			{
+				"event": "tool_collect_start",
+				"ts": time.perf_counter(),
+				"tool_name": task_name,
+				"invocation_id": invocation_id,
+			}
+		)
 
-		return await asyncio.to_thread(future.result)
+		return result
 
 	def wrap_node(self, node_func: Callable):
 		node_app = self._make_parsl_app(node_func)