fluxloop-cli 0.2.3__tar.gz → 0.2.4__tar.gz

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: FluxLoop CLI for running agent simulations
 Author-email: FluxLoop Team <team@fluxloop.dev>
 License: Apache-2.0
@@ -71,6 +71,18 @@ The legacy `setting.yaml` is still supported, but new projects created with
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Runner Integration Patterns
+
+Configure how FluxLoop calls your code in `configs/simulation.yaml`:
+
+- Module + function: `module_path`/`function_name` or `target: "module:function"`
+- Class.method (zero-arg ctor): `target: "module:Class.method"`
+- Module-scoped instance method: `target: "module:instance.method"`
+- Class.method with factory: add `factory: "module:make_instance"` (+ `factory_kwargs`)
+- Async generators: set `runner.stream_output_path` if your streamed event shape differs (default `message.delta`).
+
+See full examples: `packages/website/docs-cli/configuration/runner-targets.md`.
+
 ## Developing
 
 Install dependencies and run tests:

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/README.md

@@ -31,6 +31,18 @@ The legacy `setting.yaml` is still supported, but new projects created with
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Runner Integration Patterns
+
+Configure how FluxLoop calls your code in `configs/simulation.yaml`:
+
+- Module + function: `module_path`/`function_name` or `target: "module:function"`
+- Class.method (zero-arg ctor): `target: "module:Class.method"`
+- Module-scoped instance method: `target: "module:instance.method"`
+- Class.method with factory: add `factory: "module:make_instance"` (+ `factory_kwargs`)
+- Async generators: set `runner.stream_output_path` if your streamed event shape differs (default `message.delta`).
+
+See full examples: `packages/website/docs-cli/configuration/runner-targets.md`.
+
 ## Developing
 
 Install dependencies and run tests:

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/fluxloop_cli/__init__.py

@@ -2,7 +2,7 @@
 FluxLoop CLI - Command-line interface for running agent simulations.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 from .main import app
 

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/fluxloop_cli/runner.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import inspect
 import time
 from datetime import datetime
 from pathlib import Path
@@ -397,11 +398,20 @@ class ExperimentRunner:
             if callable(error_cb) and hasattr(error_cb, "errors"):
                 callback_store["error"] = error_cb.errors
 
+        if inspect.isasyncgenfunction(agent_func):
+            return await self._consume_async_gen(agent_func, kwargs)
+
         if asyncio.iscoroutinefunction(agent_func):
-            return await agent_func(**kwargs)
+            result = await agent_func(**kwargs)
+        else:
+            loop = asyncio.get_event_loop()
+            result = await loop.run_in_executor(None, lambda: agent_func(**kwargs))
 
-        loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(None, lambda: agent_func(**kwargs))
+        # If an async generator/iterable is returned, consume it into a string
+        if inspect.isasyncgen(result) or hasattr(result, "__aiter__"):
+            return await self._consume_async_iterable(result)
+
+        return result
 
     async def _wait_for_callbacks(
         self,
@@ -464,6 +474,33 @@ class ExperimentRunner:
 
         return None
 
+    async def _consume_async_gen(self, func: Callable, kwargs: Dict[str, Any]) -> Any:
+        """Consume an async generator function by joining text chunks resolved from events."""
+        gen = func(**kwargs)
+        return await self._consume_async_iterable(gen)
+
+    async def _consume_async_iterable(self, agen: Any) -> Any:
+        """Consume async iterable items, extracting text via runner.stream_output_path."""
+        path = (getattr(self.config.runner, "stream_output_path", None) or "message.delta").split(".")
+        chunks: List[str] = []
+        async for item in agen:
+            val = self._get_by_path(item, path)
+            if isinstance(val, str) and val:
+                chunks.append(val)
+        return "".join(chunks) if chunks else None
+
+    @staticmethod
+    def _get_by_path(obj: Any, parts: List[str]) -> Any:
+        cur: Any = obj
+        for key in parts:
+            if cur is None:
+                return None
+            if isinstance(cur, dict):
+                cur = cur.get(key)
+            else:
+                cur = getattr(cur, key, None)
+        return cur
+
     @staticmethod
     def _extract_payload(args: Sequence[Any], kwargs: Dict[str, Any]) -> Any:
         if kwargs:

fluxloop_cli-0.2.4/fluxloop_cli/target_loader.py

@@ -0,0 +1,135 @@
+"""Utilities for dynamically loading experiment targets."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from fluxloop.schemas import RunnerConfig
+
+
+class TargetLoader:
+    """Load callables defined by an experiment runner configuration."""
+
+    def __init__(self, config: RunnerConfig, source_dir: Optional[Path] = None) -> None:
+        self.config = config
+        self.source_dir = source_dir
+
+    def load(self) -> Callable:
+        """Return a callable based on the configured target."""
+
+        work_dir = self._resolve_working_directory()
+        remove_path = False
+
+        if work_dir and work_dir not in sys.path:
+            sys.path.insert(0, work_dir)
+            remove_path = True
+
+        try:
+            if self.config.target:
+                return self._load_from_target(self.config.target)
+
+            module = importlib.import_module(self.config.module_path)
+            return getattr(module, self.config.function_name)
+        finally:
+            if remove_path:
+                sys.path.remove(work_dir)
+
+    def _resolve_working_directory(self) -> str | None:
+        if not self.config.working_directory:
+            return None
+
+        raw_path = Path(self.config.working_directory)
+        if not raw_path.is_absolute() and self.source_dir:
+            raw_path = (self.source_dir / raw_path).resolve()
+        else:
+            raw_path = raw_path.expanduser().resolve()
+
+        path = raw_path
+        return str(path)
+
+    def _load_from_target(self, target: str) -> Callable:
+        """Resolve a callable from target string.
+
+        Supports:
+          - module:function
+          - module:variable
+          - module:Class.method
+          - module:variable.method
+        If the first attribute is a class, attempts to construct an instance via:
+          - runner.factory if provided (module:callable)
+          - zero-argument constructor fallback
+        """
+
+        if ":" not in target:
+            raise ValueError(
+                "Invalid runner.target format. Expected 'module:symbol[.attr]'."
+            )
+
+        module_name, attribute_chain = target.split(":", 1)
+
+        try:
+            module = importlib.import_module(module_name)
+        except ImportError as exc:
+            raise ValueError(
+                f"Failed to import module '{module_name}' for target '{target}': {exc}"
+            )
+
+        parts = attribute_chain.split(".") if attribute_chain else []
+        if not parts:
+            raise ValueError(f"Invalid target '{target}': missing attribute path")
+
+        # Resolve first symbol from module
+        try:
+            obj: Any = getattr(module, parts[0])
+        except AttributeError as exc:
+            raise ValueError(
+                f"Symbol '{parts[0]}' not found in module '{module_name}' for target '{target}'."
+            ) from exc
+
+        # If it's a class, construct instance
+        if isinstance(obj, type):
+            factory = getattr(self.config, "factory", None)
+            factory_kwargs = getattr(self.config, "factory_kwargs", {}) or {}
+            if factory:
+                if ":" not in factory:
+                    raise ValueError("runner.factory must be in 'module:callable' format")
+                fmod, fname = factory.split(":", 1)
+                try:
+                    fac_mod = importlib.import_module(fmod)
+                    fac = getattr(fac_mod, fname)
+                except Exception as exc:
+                    raise ValueError(
+                        f"Failed to import factory '{factory}' for target '{target}': {exc}"
+                    ) from exc
+                try:
+                    obj = fac(**factory_kwargs)
+                except Exception as exc:
+                    raise ValueError(
+                        f"Factory '{factory}' failed to construct instance: {exc}"
+                    ) from exc
+            else:
+                try:
+                    obj = obj()
+                except TypeError as exc:
+                    raise ValueError(
+                        "Cannot construct class without zero-argument constructor. "
+                        "Provide runner.factory to construct the instance."
+                    ) from exc
+
+        # Traverse remaining attributes
+        for attr in parts[1:]:
+            try:
+                obj = getattr(obj, attr)
+            except AttributeError as exc:
+                raise ValueError(
+                    f"Attribute '{attr}' not found while resolving target '{target}'."
+                ) from exc
+
+        if not callable(obj):
+            raise ValueError(f"Resolved target '{target}' is not callable.")
+
+        return obj
+

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/fluxloop_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: FluxLoop CLI for running agent simulations
 Author-email: FluxLoop Team <team@fluxloop.dev>
 License: Apache-2.0
@@ -71,6 +71,18 @@ The legacy `setting.yaml` is still supported, but new projects created with
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Runner Integration Patterns
+
+Configure how FluxLoop calls your code in `configs/simulation.yaml`:
+
+- Module + function: `module_path`/`function_name` or `target: "module:function"`
+- Class.method (zero-arg ctor): `target: "module:Class.method"`
+- Module-scoped instance method: `target: "module:instance.method"`
+- Class.method with factory: add `factory: "module:make_instance"` (+ `factory_kwargs`)
+- Async generators: set `runner.stream_output_path` if your streamed event shape differs (default `message.delta`).
+
+See full examples: `packages/website/docs-cli/configuration/runner-targets.md`.
+
 ## Developing
 
 Install dependencies and run tests:

{fluxloop_cli-0.2.3 → fluxloop_cli-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fluxloop-cli"
-version = "0.2.3"
+version = "0.2.4"
 description = "FluxLoop CLI for running agent simulations"
 authors = [
     {name = "FluxLoop Team", email = "team@fluxloop.dev"}

fluxloop_cli-0.2.3/fluxloop_cli/target_loader.py

@@ -1,95 +0,0 @@
-"""Utilities for dynamically loading experiment targets."""
-
-from __future__ import annotations
-
-import importlib
-import sys
-from pathlib import Path
-from typing import Callable, Optional
-
-from fluxloop.schemas import RunnerConfig
-
-
-class TargetLoader:
-    """Load callables defined by an experiment runner configuration."""
-
-    def __init__(self, config: RunnerConfig, source_dir: Optional[Path] = None) -> None:
-        self.config = config
-        self.source_dir = source_dir
-
-    def load(self) -> Callable:
-        """Return a callable based on the configured target."""
-
-        work_dir = self._resolve_working_directory()
-        remove_path = False
-
-        if work_dir and work_dir not in sys.path:
-            sys.path.insert(0, work_dir)
-            remove_path = True
-
-        try:
-            if self.config.target:
-                return self._load_from_target(self.config.target)
-
-            module = importlib.import_module(self.config.module_path)
-            return getattr(module, self.config.function_name)
-        finally:
-            if remove_path:
-                sys.path.remove(work_dir)
-
-    def _resolve_working_directory(self) -> str | None:
-        if not self.config.working_directory:
-            return None
-
-        raw_path = Path(self.config.working_directory)
-        if not raw_path.is_absolute() and self.source_dir:
-            raw_path = (self.source_dir / raw_path).resolve()
-        else:
-            raw_path = raw_path.expanduser().resolve()
-
-        path = raw_path
-        return str(path)
-
-    def _load_from_target(self, target: str) -> Callable:
-        if ":" not in target:
-            raise ValueError(
-                "Invalid runner.target format. Expected 'module:function' or 'module:Class.method'."
-            )
-
-        module_name, attribute_part = target.split(":", 1)
-
-        try:
-            module = importlib.import_module(module_name)
-        except ImportError as exc:
-            raise ValueError(f"Failed to import module '{module_name}' for target '{target}': {exc}")
-
-        if "." in attribute_part:
-            class_name, method_name = attribute_part.split(".", 1)
-            try:
-                cls = getattr(module, class_name)
-            except AttributeError as exc:
-                raise ValueError(
-                    f"Class '{class_name}' not found in module '{module_name}' for target '{target}'."
-                ) from exc
-
-            try:
-                instance = cls()
-            except TypeError as exc:
-                raise ValueError(
-                    "MVP limitation: only classes with zero-argument constructors are supported."
-                ) from exc
-
-            try:
-                return getattr(instance, method_name)
-            except AttributeError as exc:
-                raise ValueError(
-                    f"Method '{method_name}' not found on class '{class_name}' for target '{target}'."
-                ) from exc
-
-        try:
-            return getattr(module, attribute_part)
-        except AttributeError as exc:
-            raise ValueError(
-                f"Function or attribute '{attribute_part}' not found in module '{module_name}' for target '{target}'."
-            ) from exc
-