fluxloop 0.1.2__tar.gz → 0.1.3__tar.gz

fluxloop-0.1.3/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: fluxloop
+Version: 0.1.3
+Summary: FluxLoop SDK for agent instrumentation and tracing
+Author-email: FluxLoop Team <team@fluxloop.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/chuckgu/fluxloop
+Project-URL: Documentation, https://docs.fluxloop.dev
+Project-URL: Repository, https://github.com/chuckgu/fluxloop
+Project-URL: Issues, https://github.com/chuckgu/fluxloop/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.0.20; extra == "langgraph"
+
+# FluxLoop SDK
+
+FluxLoop SDK for agent instrumentation and tracing.
+
+## Installation
+
+```bash
+pip install fluxloop
+```
+
+## Quick Start
+
+```python
+from fluxloop import trace, FluxLoopClient
+
+# Initialize the client
+client = FluxLoopClient()
+
+# Use the trace decorator
+@trace()
+def my_agent_function(prompt: str):
+    # Your agent logic here
+    return result
+```
+
+## Features
+
+- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
+- 📊 **Rich Context**: Capture inputs, outputs, and metadata
+- 🔄 **Async Support**: Works with both sync and async functions
+- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
+
+## Documentation
+
+For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
+
+## License
+
+Apache License 2.0 - see LICENSE file for details
+
+
+## Framework Integration: Decorator Ordering and Safe Instrumentation
+
+When integrating FluxLoop with external agent frameworks (e.g., ChatKit, LangChain), follow these rules to avoid type conflicts and ensure observations are captured reliably.
+
+- Outermost framework wrapper: If a framework provides its own decorator/wrapper that transforms a plain function into a framework-specific object (e.g., a Tool), that decorator MUST be the outermost (top) decorator. This preserves the type the framework expects.
+- FluxLoop instrumentation inside: Place FluxLoop decorators inside (below) the framework decorator, or instrument from within the function body using the SDK context APIs.
+
+Two safe patterns:
+
+- Pattern A (safest, framework-agnostic): instrument inside the function body
+  - Use `get_current_context()` and push/pop an `ObservationData` manually around your logic. This keeps signatures and framework typing unchanged.
+  - Example (tool function):
+
+    ```python
+    from fluxloop import get_current_context
+    from fluxloop.models import ObservationData, ObservationType
+
+    async def my_tool(param: str) -> dict:
+        fl_ctx = get_current_context()
+        obs = None
+        if fl_ctx and fl_ctx.is_enabled():
+            obs = ObservationData(
+                type=ObservationType.TOOL,
+                name="tool.my_tool",
+                input={"args": {"param": param}},
+            )
+            fl_ctx.push_observation(obs)
+
+        try:
+            result = {"result": do_work(param)}
+            if obs:
+                obs.output = result
+            return result
+        except Exception as e:
+            if obs:
+                obs.error = str(e)
+            raise
+        finally:
+            if fl_ctx and obs:
+                fl_ctx.pop_observation()
+    ```
+
+- Pattern B (stacking decorators): framework outermost, FluxLoop inside
+  - Example with a framework tool decorator:
+
+    ```python
+    @framework_tool_decorator(...)
+    @fluxloop.tool(name="tool.my_tool")
+    async def my_tool(...):
+        ...
+    ```
+
+  - Important: If you reverse the order (FluxLoop outside), the framework may see a plain function instead of its expected type and raise errors like "Unknown tool type".
+
+LLM/streaming calls:
+
+- For LLM calls (including async generators/streams), either:
+  - Wrap the call site in a small helper decorated with `@fluxloop.prompt(...)`, or
+  - Use `with fluxloop.instrument("prompt.name"):` around the portion that produces model output, ensuring it runs inside the current FluxLoop context.
+
+These patterns guarantee observations are captured (`tool`, `generation`) while keeping the external framework’s type system intact.
+

fluxloop-0.1.3/README.md

@@ -0,0 +1,103 @@
+# FluxLoop SDK
+
+FluxLoop SDK for agent instrumentation and tracing.
+
+## Installation
+
+```bash
+pip install fluxloop
+```
+
+## Quick Start
+
+```python
+from fluxloop import trace, FluxLoopClient
+
+# Initialize the client
+client = FluxLoopClient()
+
+# Use the trace decorator
+@trace()
+def my_agent_function(prompt: str):
+    # Your agent logic here
+    return result
+```
+
+## Features
+
+- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
+- 📊 **Rich Context**: Capture inputs, outputs, and metadata
+- 🔄 **Async Support**: Works with both sync and async functions
+- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
+
+## Documentation
+
+For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
+
+## License
+
+Apache License 2.0 - see LICENSE file for details
+
+
+## Framework Integration: Decorator Ordering and Safe Instrumentation
+
+When integrating FluxLoop with external agent frameworks (e.g., ChatKit, LangChain), follow these rules to avoid type conflicts and ensure observations are captured reliably.
+
+- Outermost framework wrapper: If a framework provides its own decorator/wrapper that transforms a plain function into a framework-specific object (e.g., a Tool), that decorator MUST be the outermost (top) decorator. This preserves the type the framework expects.
+- FluxLoop instrumentation inside: Place FluxLoop decorators inside (below) the framework decorator, or instrument from within the function body using the SDK context APIs.
+
+Two safe patterns:
+
+- Pattern A (safest, framework-agnostic): instrument inside the function body
+  - Use `get_current_context()` and push/pop an `ObservationData` manually around your logic. This keeps signatures and framework typing unchanged.
+  - Example (tool function):
+
+    ```python
+    from fluxloop import get_current_context
+    from fluxloop.models import ObservationData, ObservationType
+
+    async def my_tool(param: str) -> dict:
+        fl_ctx = get_current_context()
+        obs = None
+        if fl_ctx and fl_ctx.is_enabled():
+            obs = ObservationData(
+                type=ObservationType.TOOL,
+                name="tool.my_tool",
+                input={"args": {"param": param}},
+            )
+            fl_ctx.push_observation(obs)
+
+        try:
+            result = {"result": do_work(param)}
+            if obs:
+                obs.output = result
+            return result
+        except Exception as e:
+            if obs:
+                obs.error = str(e)
+            raise
+        finally:
+            if fl_ctx and obs:
+                fl_ctx.pop_observation()
+    ```
+
+- Pattern B (stacking decorators): framework outermost, FluxLoop inside
+  - Example with a framework tool decorator:
+
+    ```python
+    @framework_tool_decorator(...)
+    @fluxloop.tool(name="tool.my_tool")
+    async def my_tool(...):
+        ...
+    ```
+
+  - Important: If you reverse the order (FluxLoop outside), the framework may see a plain function instead of its expected type and raise errors like "Unknown tool type".
+
+LLM/streaming calls:
+
+- For LLM calls (including async generators/streams), either:
+  - Wrap the call site in a small helper decorated with `@fluxloop.prompt(...)`, or
+  - Use `with fluxloop.instrument("prompt.name"):` around the portion that produces model output, ensuring it runs inside the current FluxLoop context.
+
+These patterns guarantee observations are captured (`tool`, `generation`) while keeping the external framework’s type system intact.
+

{fluxloop-0.1.2 → fluxloop-0.1.3}/fluxloop/__init__.py

@@ -21,7 +21,7 @@ from .client import FluxLoopClient
 from .config import configure, get_config, reset_config, load_env
 from .recording import disable_recording, enable_recording, record_call_args, set_recording_options
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
     # Decorators

{fluxloop-0.1.2 → fluxloop-0.1.3}/fluxloop/config.py

@@ -104,7 +104,7 @@ class SDKConfig(BaseModel):
         default_factory=lambda: os.getenv("FLUXLOOP_OFFLINE_ENABLED", "true").lower() == "true"
     )
     offline_store_dir: str = Field(
-        default_factory=lambda: os.getenv("FLUXLOOP_OFFLINE_DIR", "./fluxloop_artifacts")
+        default_factory=lambda: os.getenv("FLUXLOOP_OFFLINE_DIR", "./experiments/artifacts")
     )
 
     # Argument recording (disabled by default)

{fluxloop-0.1.2 → fluxloop-0.1.3}/fluxloop/schemas/config.py

@@ -4,7 +4,7 @@ Configuration schemas for experiments and simulations.
 
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field, PrivateAttr, field_validator, model_validator
 
@@ -163,8 +163,19 @@ class RunnerConfig(BaseModel):
     
     # Execution environment
     working_directory: Optional[str] = None
-    python_path: Optional[str] = None
+    python_path: List[str] = Field(default_factory=list)
     environment_vars: Dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("python_path", mode="before")
+    @classmethod
+    def _coerce_python_path(cls, value: Union[None, str, List[str], tuple]) -> List[str]:
+        if value is None:
+            return []
+        if isinstance(value, str):
+            return [value]
+        if isinstance(value, (list, tuple)):
+            return [str(item) for item in value]
+        return [str(value)]
     
     # Dependencies
     requirements_file: Optional[str] = None

fluxloop-0.1.3/fluxloop.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: fluxloop
+Version: 0.1.3
+Summary: FluxLoop SDK for agent instrumentation and tracing
+Author-email: FluxLoop Team <team@fluxloop.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/chuckgu/fluxloop
+Project-URL: Documentation, https://docs.fluxloop.dev
+Project-URL: Repository, https://github.com/chuckgu/fluxloop
+Project-URL: Issues, https://github.com/chuckgu/fluxloop/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.0.20; extra == "langgraph"
+
+# FluxLoop SDK
+
+FluxLoop SDK for agent instrumentation and tracing.
+
+## Installation
+
+```bash
+pip install fluxloop
+```
+
+## Quick Start
+
+```python
+from fluxloop import trace, FluxLoopClient
+
+# Initialize the client
+client = FluxLoopClient()
+
+# Use the trace decorator
+@trace()
+def my_agent_function(prompt: str):
+    # Your agent logic here
+    return result
+```
+
+## Features
+
+- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
+- 📊 **Rich Context**: Capture inputs, outputs, and metadata
+- 🔄 **Async Support**: Works with both sync and async functions
+- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
+
+## Documentation
+
+For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
+
+## License
+
+Apache License 2.0 - see LICENSE file for details
+
+
+## Framework Integration: Decorator Ordering and Safe Instrumentation
+
+When integrating FluxLoop with external agent frameworks (e.g., ChatKit, LangChain), follow these rules to avoid type conflicts and ensure observations are captured reliably.
+
+- Outermost framework wrapper: If a framework provides its own decorator/wrapper that transforms a plain function into a framework-specific object (e.g., a Tool), that decorator MUST be the outermost (top) decorator. This preserves the type the framework expects.
+- FluxLoop instrumentation inside: Place FluxLoop decorators inside (below) the framework decorator, or instrument from within the function body using the SDK context APIs.
+
+Two safe patterns:
+
+- Pattern A (safest, framework-agnostic): instrument inside the function body
+  - Use `get_current_context()` and push/pop an `ObservationData` manually around your logic. This keeps signatures and framework typing unchanged.
+  - Example (tool function):
+
+    ```python
+    from fluxloop import get_current_context
+    from fluxloop.models import ObservationData, ObservationType
+
+    async def my_tool(param: str) -> dict:
+        fl_ctx = get_current_context()
+        obs = None
+        if fl_ctx and fl_ctx.is_enabled():
+            obs = ObservationData(
+                type=ObservationType.TOOL,
+                name="tool.my_tool",
+                input={"args": {"param": param}},
+            )
+            fl_ctx.push_observation(obs)
+
+        try:
+            result = {"result": do_work(param)}
+            if obs:
+                obs.output = result
+            return result
+        except Exception as e:
+            if obs:
+                obs.error = str(e)
+            raise
+        finally:
+            if fl_ctx and obs:
+                fl_ctx.pop_observation()
+    ```
+
+- Pattern B (stacking decorators): framework outermost, FluxLoop inside
+  - Example with a framework tool decorator:
+
+    ```python
+    @framework_tool_decorator(...)
+    @fluxloop.tool(name="tool.my_tool")
+    async def my_tool(...):
+        ...
+    ```
+
+  - Important: If you reverse the order (FluxLoop outside), the framework may see a plain function instead of its expected type and raise errors like "Unknown tool type".
+
+LLM/streaming calls:
+
+- For LLM calls (including async generators/streams), either:
+  - Wrap the call site in a small helper decorated with `@fluxloop.prompt(...)`, or
+  - Use `with fluxloop.instrument("prompt.name"):` around the portion that produces model output, ensuring it runs inside the current FluxLoop context.
+
+These patterns guarantee observations are captured (`tool`, `generation`) while keeping the external framework’s type system intact.
+

{fluxloop-0.1.2 → fluxloop-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fluxloop"
-version = "0.1.2"
+version = "0.1.3"
 description = "FluxLoop SDK for agent instrumentation and tracing"
 authors = [
     {name = "FluxLoop Team", email = "team@fluxloop.dev"}
@@ -49,10 +49,10 @@ langgraph = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/fluxloop/fluxloop"
+Homepage = "https://github.com/chuckgu/fluxloop"
 Documentation = "https://docs.fluxloop.dev"
-Repository = "https://github.com/fluxloop/fluxloop"
-Issues = "https://github.com/fluxloop/fluxloop/issues"
+Repository = "https://github.com/chuckgu/fluxloop"
+Issues = "https://github.com/chuckgu/fluxloop/issues"
 
 [tool.setuptools.packages.find]
 where = ["."]

fluxloop-0.1.2/PKG-INFO

@@ -1,76 +0,0 @@
-Metadata-Version: 2.4
-Name: fluxloop
-Version: 0.1.2
-Summary: FluxLoop SDK for agent instrumentation and tracing
-Author-email: FluxLoop Team <team@fluxloop.dev>
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/fluxloop/fluxloop
-Project-URL: Documentation, https://docs.fluxloop.dev
-Project-URL: Repository, https://github.com/fluxloop/fluxloop
-Project-URL: Issues, https://github.com/fluxloop/fluxloop/issues
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: pydantic>=2.0
-Requires-Dist: httpx>=0.24.0
-Requires-Dist: python-dotenv>=1.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Requires-Dist: mypy>=1.0; extra == "dev"
-Requires-Dist: black>=23.0; extra == "dev"
-Provides-Extra: langchain
-Requires-Dist: langchain>=0.1.0; extra == "langchain"
-Provides-Extra: langgraph
-Requires-Dist: langgraph>=0.0.20; extra == "langgraph"
-
-# FluxLoop SDK
-
-FluxLoop SDK for agent instrumentation and tracing.
-
-## Installation
-
-```bash
-pip install fluxloop
-```
-
-## Quick Start
-
-```python
-from fluxloop import trace, FluxLoopClient
-
-# Initialize the client
-client = FluxLoopClient()
-
-# Use the trace decorator
-@trace()
-def my_agent_function(prompt: str):
-    # Your agent logic here
-    return result
-```
-
-## Features
-
-- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
-- 📊 **Rich Context**: Capture inputs, outputs, and metadata
-- 🔄 **Async Support**: Works with both sync and async functions
-- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
-
-## Documentation
-
-For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
-
-## License
-
-Apache License 2.0 - see LICENSE file for details
-

fluxloop-0.1.2/README.md

@@ -1,40 +0,0 @@
-# FluxLoop SDK
-
-FluxLoop SDK for agent instrumentation and tracing.
-
-## Installation
-
-```bash
-pip install fluxloop
-```
-
-## Quick Start
-
-```python
-from fluxloop import trace, FluxLoopClient
-
-# Initialize the client
-client = FluxLoopClient()
-
-# Use the trace decorator
-@trace()
-def my_agent_function(prompt: str):
-    # Your agent logic here
-    return result
-```
-
-## Features
-
-- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
-- 📊 **Rich Context**: Capture inputs, outputs, and metadata
-- 🔄 **Async Support**: Works with both sync and async functions
-- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
-
-## Documentation
-
-For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
-
-## License
-
-Apache License 2.0 - see LICENSE file for details
-

fluxloop-0.1.2/fluxloop.egg-info/PKG-INFO

@@ -1,76 +0,0 @@
-Metadata-Version: 2.4
-Name: fluxloop
-Version: 0.1.2
-Summary: FluxLoop SDK for agent instrumentation and tracing
-Author-email: FluxLoop Team <team@fluxloop.dev>
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/fluxloop/fluxloop
-Project-URL: Documentation, https://docs.fluxloop.dev
-Project-URL: Repository, https://github.com/fluxloop/fluxloop
-Project-URL: Issues, https://github.com/fluxloop/fluxloop/issues
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: pydantic>=2.0
-Requires-Dist: httpx>=0.24.0
-Requires-Dist: python-dotenv>=1.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Requires-Dist: mypy>=1.0; extra == "dev"
-Requires-Dist: black>=23.0; extra == "dev"
-Provides-Extra: langchain
-Requires-Dist: langchain>=0.1.0; extra == "langchain"
-Provides-Extra: langgraph
-Requires-Dist: langgraph>=0.0.20; extra == "langgraph"
-
-# FluxLoop SDK
-
-FluxLoop SDK for agent instrumentation and tracing.
-
-## Installation
-
-```bash
-pip install fluxloop
-```
-
-## Quick Start
-
-```python
-from fluxloop import trace, FluxLoopClient
-
-# Initialize the client
-client = FluxLoopClient()
-
-# Use the trace decorator
-@trace()
-def my_agent_function(prompt: str):
-    # Your agent logic here
-    return result
-```
-
-## Features
-
-- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
-- 📊 **Rich Context**: Capture inputs, outputs, and metadata
-- 🔄 **Async Support**: Works with both sync and async functions
-- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
-
-## Documentation
-
-For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
-
-## License
-
-Apache License 2.0 - see LICENSE file for details
-