jaf-py 2.2.2__tar.gz → 2.2.4__tar.gz

{jaf_py-2.2.2 → jaf_py-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaf-py
-Version: 2.2.2
+Version: 2.2.4
 Summary: A purely functional agent framework with immutable state and composable tools - Python implementation
 Author: JAF Contributors
 Maintainer: JAF Contributors
@@ -73,7 +73,7 @@ Dynamic: license-file
 
 <!-- ![JAF Banner](docs/cover.png) -->
 
-[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/xynehq/jaf-py)
+[![Version](https://img.shields.io/badge/version-2.2.3-blue.svg)](https://github.com/xynehq/jaf-py)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![Docs](https://img.shields.io/badge/Docs-Live-brightgreen)](https://xynehq.github.io/jaf-py/)
 
@@ -110,18 +110,27 @@ A purely functional agent framework with immutable state and composable tools, p
 - ✅ **Output Guardrails**: Response sanitization
 - ✅ **Permission System**: Role-based access control
 - ✅ **Audit Logging**: Complete interaction tracing
+- ✅ **Proxy Support**: Corporate proxy integration with authentication
 
 ### 📊 **Observability & Monitoring**
 - ✅ **Real-time Tracing**: Event-driven observability
+- ✅ **OpenTelemetry Integration**: Distributed tracing with OTLP
+- ✅ **Langfuse Tracing**: LLM observability and analytics
 - ✅ **Structured Logging**: JSON-formatted logs
 - ✅ **Error Handling**: Comprehensive error types and recovery
 - ✅ **Performance Metrics**: Built-in timing and counters
 
+### 🤖 **Agent-as-Tool Architecture**
+- ✅ **Hierarchical Orchestration**: Use agents as tools in other agents
+- ✅ **Conditional Tool Enabling**: Enable/disable agent tools based on context
+- ✅ **Session Management**: Configurable session inheritance for sub-agents
+- ✅ **Flexible Output Extraction**: Custom extractors for agent tool outputs
+
 ### 🔧 **Developer Experience**
 - ✅ **CLI Tools**: Project initialization and management
 - ✅ **Hot Reload**: Development server with auto-reload
 - ✅ **Type Hints**: Full mypy compatibility
-- ✅ **Rich Examples**: RAG, multi-agent, and server demos
+- ✅ **Rich Examples**: RAG, multi-agent, agent-as-tool, and server demos
 - ✅ **Visual Architecture**: Graphviz-powered agent and tool diagrams
 
 ## 🎯 Core Philosophy
@@ -147,6 +156,7 @@ pip install "jaf-py[all] @ git+https://github.com/xynehq/jaf-py.git"
 pip install "jaf-py[server] @ git+https://github.com/xynehq/jaf-py.git"        # FastAPI server support
 pip install "jaf-py[memory] @ git+https://github.com/xynehq/jaf-py.git"        # Redis/PostgreSQL memory providers
 pip install "jaf-py[visualization] @ git+https://github.com/xynehq/jaf-py.git" # Graphviz visualization tools
+pip install "jaf-py[tracing] @ git+https://github.com/xynehq/jaf-py.git"       # OpenTelemetry and Langfuse tracing
 pip install "jaf-py[dev] @ git+https://github.com/xynehq/jaf-py.git"           # Development tools
 ```
 
@@ -211,6 +221,7 @@ For offline access, documentation is also available in the [`docs/`](docs/) dire
 - **[🔧 Tools Guide](docs/tools.md)** - Creating and using tools
 - **[💾 Memory System](docs/memory-system.md)** - Persistence and memory providers
 - **[🤖 Model Providers](docs/model-providers.md)** - LiteLLM integration
+- **[📊 Monitoring](docs/monitoring.md)** - Observability, metrics, and alerting
 - **[🌐 Server API](docs/server-api.md)** - FastAPI endpoints reference
 - **[📦 Deployment](docs/deployment.md)** - Production deployment guide
 - **[🎮 Examples](docs/examples.md)** - Detailed example walkthroughs
@@ -438,6 +449,58 @@ config = RunConfig(
 )
 ```
 
+## 🤖 Agent-as-Tool Functionality
+
+JAF 2.2+ introduces powerful agent-as-tool capabilities, allowing you to use agents as tools within other agents for hierarchical orchestration:
+
+```python
+from jaf.core.agent_tool import create_agent_tool
+from jaf.core.types import create_json_output_extractor
+
+# Create specialized agents
+spanish_agent = Agent(
+    name="spanish_translator",
+    instructions=lambda state: "Translate text to Spanish",
+    output_codec=TranslationOutput
+)
+
+french_agent = Agent(
+    name="french_translator", 
+    instructions=lambda state: "Translate text to French",
+    output_codec=TranslationOutput
+)
+
+# Convert agents to tools with conditional enabling
+spanish_tool = spanish_agent.as_tool(
+    tool_name="translate_to_spanish",
+    tool_description="Translate text to Spanish",
+    max_turns=3,
+    custom_output_extractor=create_json_output_extractor(),
+    is_enabled=True  # Always enabled
+)
+
+french_tool = french_agent.as_tool(
+    tool_name="translate_to_french", 
+    tool_description="Translate text to French",
+    max_turns=3,
+    custom_output_extractor=create_json_output_extractor(),
+    is_enabled=lambda context, agent: context.language_preference == "french_spanish"
+)
+
+# Create orchestrator agent using agent tools
+orchestrator = Agent(
+    name="translation_orchestrator",
+    instructions=lambda state: "Use translation tools to respond in multiple languages",
+    tools=[spanish_tool, french_tool]
+)
+```
+
+### Key Features:
+- **Conditional Enabling**: Enable/disable agent tools based on runtime context
+- **Session Management**: Configure whether sub-agents inherit parent session state
+- **Custom Output Extraction**: Define how to extract and format agent tool outputs
+- **Error Handling**: Robust error handling for failed agent tool executions
+
 ## 🔗 Agent Handoffs
 
 ```python
@@ -487,6 +550,48 @@ config = RunConfig(
 )
 ```
 
+### OpenTelemetry Integration
+
+JAF 2.2+ includes built-in OpenTelemetry support for distributed tracing:
+
+```python
+import os
+from jaf.core.tracing import create_composite_trace_collector, ConsoleTraceCollector
+
+# Configure OpenTelemetry endpoint
+os.environ["TRACE_COLLECTOR_URL"] = "http://localhost:4318/v1/traces"
+
+# Tracing will be automatically configured when creating a composite collector
+trace_collector = create_composite_trace_collector(ConsoleTraceCollector())
+
+config = RunConfig(
+    # ... other config
+    on_event=trace_collector.collect,
+)
+```
+
+### Langfuse Integration
+
+For LLM-specific observability and analytics:
+
+```python
+import os
+from jaf.core.tracing import create_composite_trace_collector, ConsoleTraceCollector
+
+# Configure Langfuse credentials
+os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-your-public-key"
+os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-your-secret-key" 
+os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"  # or your self-hosted instance
+
+# Langfuse tracing will be automatically configured
+trace_collector = create_composite_trace_collector(ConsoleTraceCollector())
+
+config = RunConfig(
+    # ... other config
+    on_event=trace_collector.collect,
+)
+```
+
 ### Error Handling
 
 ```python
@@ -662,7 +767,41 @@ python server_example.py
 - `POST /chat` - Chat with any agent
 - `GET /docs` - Interactive API documentation
 
-### 2. MCP Integration Demo
+### 2. Agent-as-Tool Demo
+
+```bash
+cd examples
+python agent_as_tool_example.py
+
+# Or start as server
+python agent_as_tool_example.py --server
+```
+
+**Features demonstrated:**
+- ✅ Hierarchical agent orchestration
+- ✅ Conditional tool enabling based on context
+- ✅ Custom output extraction from agent tools
+- ✅ Session management for sub-agents
+- ✅ Translation agents working together
+
+### 3. Tracing Integration Demos
+
+```bash
+# OpenTelemetry tracing example
+cd examples
+python otel_tracing_demo.py
+
+# Langfuse tracing example  
+python langfuse_tracing_demo.py
+```
+
+**Features demonstrated:**
+- ✅ OpenTelemetry distributed tracing setup
+- ✅ Langfuse LLM observability integration
+- ✅ Composite trace collectors
+- ✅ Real-time monitoring and analytics
+
+### 4. MCP Integration Demo
 
 ```bash
 cd examples/mcp_demo  
@@ -720,4 +859,4 @@ MIT
 
 ---
 
-**JAF (Juspay Agentic Framework) v2.0** - Building the future of functional AI agent systems 🚀
+**JAF (Juspay Agentic Framework) v2.2** - Building the future of functional AI agent systems 🚀

{jaf_py-2.2.2 → jaf_py-2.2.4}/README.md

@@ -2,7 +2,7 @@
 
 <!-- ![JAF Banner](docs/cover.png) -->
 
-[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/xynehq/jaf-py)
+[![Version](https://img.shields.io/badge/version-2.2.3-blue.svg)](https://github.com/xynehq/jaf-py)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![Docs](https://img.shields.io/badge/Docs-Live-brightgreen)](https://xynehq.github.io/jaf-py/)
 
@@ -39,18 +39,27 @@ A purely functional agent framework with immutable state and composable tools, p
 - ✅ **Output Guardrails**: Response sanitization
 - ✅ **Permission System**: Role-based access control
 - ✅ **Audit Logging**: Complete interaction tracing
+- ✅ **Proxy Support**: Corporate proxy integration with authentication
 
 ### 📊 **Observability & Monitoring**
 - ✅ **Real-time Tracing**: Event-driven observability
+- ✅ **OpenTelemetry Integration**: Distributed tracing with OTLP
+- ✅ **Langfuse Tracing**: LLM observability and analytics
 - ✅ **Structured Logging**: JSON-formatted logs
 - ✅ **Error Handling**: Comprehensive error types and recovery
 - ✅ **Performance Metrics**: Built-in timing and counters
 
+### 🤖 **Agent-as-Tool Architecture**
+- ✅ **Hierarchical Orchestration**: Use agents as tools in other agents
+- ✅ **Conditional Tool Enabling**: Enable/disable agent tools based on context
+- ✅ **Session Management**: Configurable session inheritance for sub-agents
+- ✅ **Flexible Output Extraction**: Custom extractors for agent tool outputs
+
 ### 🔧 **Developer Experience**
 - ✅ **CLI Tools**: Project initialization and management
 - ✅ **Hot Reload**: Development server with auto-reload
 - ✅ **Type Hints**: Full mypy compatibility
-- ✅ **Rich Examples**: RAG, multi-agent, and server demos
+- ✅ **Rich Examples**: RAG, multi-agent, agent-as-tool, and server demos
 - ✅ **Visual Architecture**: Graphviz-powered agent and tool diagrams
 
 ## 🎯 Core Philosophy
@@ -76,6 +85,7 @@ pip install "jaf-py[all] @ git+https://github.com/xynehq/jaf-py.git"
 pip install "jaf-py[server] @ git+https://github.com/xynehq/jaf-py.git"        # FastAPI server support
 pip install "jaf-py[memory] @ git+https://github.com/xynehq/jaf-py.git"        # Redis/PostgreSQL memory providers
 pip install "jaf-py[visualization] @ git+https://github.com/xynehq/jaf-py.git" # Graphviz visualization tools
+pip install "jaf-py[tracing] @ git+https://github.com/xynehq/jaf-py.git"       # OpenTelemetry and Langfuse tracing
 pip install "jaf-py[dev] @ git+https://github.com/xynehq/jaf-py.git"           # Development tools
 ```
 
@@ -140,6 +150,7 @@ For offline access, documentation is also available in the [`docs/`](docs/) dire
 - **[🔧 Tools Guide](docs/tools.md)** - Creating and using tools
 - **[💾 Memory System](docs/memory-system.md)** - Persistence and memory providers
 - **[🤖 Model Providers](docs/model-providers.md)** - LiteLLM integration
+- **[📊 Monitoring](docs/monitoring.md)** - Observability, metrics, and alerting
 - **[🌐 Server API](docs/server-api.md)** - FastAPI endpoints reference
 - **[📦 Deployment](docs/deployment.md)** - Production deployment guide
 - **[🎮 Examples](docs/examples.md)** - Detailed example walkthroughs
@@ -367,6 +378,58 @@ config = RunConfig(
 )
 ```
 
+## 🤖 Agent-as-Tool Functionality
+
+JAF 2.2+ introduces powerful agent-as-tool capabilities, allowing you to use agents as tools within other agents for hierarchical orchestration:
+
+```python
+from jaf.core.agent_tool import create_agent_tool
+from jaf.core.types import create_json_output_extractor
+
+# Create specialized agents
+spanish_agent = Agent(
+    name="spanish_translator",
+    instructions=lambda state: "Translate text to Spanish",
+    output_codec=TranslationOutput
+)
+
+french_agent = Agent(
+    name="french_translator", 
+    instructions=lambda state: "Translate text to French",
+    output_codec=TranslationOutput
+)
+
+# Convert agents to tools with conditional enabling
+spanish_tool = spanish_agent.as_tool(
+    tool_name="translate_to_spanish",
+    tool_description="Translate text to Spanish",
+    max_turns=3,
+    custom_output_extractor=create_json_output_extractor(),
+    is_enabled=True  # Always enabled
+)
+
+french_tool = french_agent.as_tool(
+    tool_name="translate_to_french", 
+    tool_description="Translate text to French",
+    max_turns=3,
+    custom_output_extractor=create_json_output_extractor(),
+    is_enabled=lambda context, agent: context.language_preference == "french_spanish"
+)
+
+# Create orchestrator agent using agent tools
+orchestrator = Agent(
+    name="translation_orchestrator",
+    instructions=lambda state: "Use translation tools to respond in multiple languages",
+    tools=[spanish_tool, french_tool]
+)
+```
+
+### Key Features:
+- **Conditional Enabling**: Enable/disable agent tools based on runtime context
+- **Session Management**: Configure whether sub-agents inherit parent session state
+- **Custom Output Extraction**: Define how to extract and format agent tool outputs
+- **Error Handling**: Robust error handling for failed agent tool executions
+
 ## 🔗 Agent Handoffs
 
 ```python
@@ -416,6 +479,48 @@ config = RunConfig(
 )
 ```
 
+### OpenTelemetry Integration
+
+JAF 2.2+ includes built-in OpenTelemetry support for distributed tracing:
+
+```python
+import os
+from jaf.core.tracing import create_composite_trace_collector, ConsoleTraceCollector
+
+# Configure OpenTelemetry endpoint
+os.environ["TRACE_COLLECTOR_URL"] = "http://localhost:4318/v1/traces"
+
+# Tracing will be automatically configured when creating a composite collector
+trace_collector = create_composite_trace_collector(ConsoleTraceCollector())
+
+config = RunConfig(
+    # ... other config
+    on_event=trace_collector.collect,
+)
+```
+
+### Langfuse Integration
+
+For LLM-specific observability and analytics:
+
+```python
+import os
+from jaf.core.tracing import create_composite_trace_collector, ConsoleTraceCollector
+
+# Configure Langfuse credentials
+os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-your-public-key"
+os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-your-secret-key" 
+os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"  # or your self-hosted instance
+
+# Langfuse tracing will be automatically configured
+trace_collector = create_composite_trace_collector(ConsoleTraceCollector())
+
+config = RunConfig(
+    # ... other config
+    on_event=trace_collector.collect,
+)
+```
+
 ### Error Handling
 
 ```python
@@ -591,7 +696,41 @@ python server_example.py
 - `POST /chat` - Chat with any agent
 - `GET /docs` - Interactive API documentation
 
-### 2. MCP Integration Demo
+### 2. Agent-as-Tool Demo
+
+```bash
+cd examples
+python agent_as_tool_example.py
+
+# Or start as server
+python agent_as_tool_example.py --server
+```
+
+**Features demonstrated:**
+- ✅ Hierarchical agent orchestration
+- ✅ Conditional tool enabling based on context
+- ✅ Custom output extraction from agent tools
+- ✅ Session management for sub-agents
+- ✅ Translation agents working together
+
+### 3. Tracing Integration Demos
+
+```bash
+# OpenTelemetry tracing example
+cd examples
+python otel_tracing_demo.py
+
+# Langfuse tracing example  
+python langfuse_tracing_demo.py
+```
+
+**Features demonstrated:**
+- ✅ OpenTelemetry distributed tracing setup
+- ✅ Langfuse LLM observability integration
+- ✅ Composite trace collectors
+- ✅ Real-time monitoring and analytics
+
+### 4. MCP Integration Demo
 
 ```bash
 cd examples/mcp_demo  
@@ -649,4 +788,4 @@ MIT
 
 ---
 
-**JAF (Juspay Agentic Framework) v2.0** - Building the future of functional AI agent systems 🚀
+**JAF (Juspay Agentic Framework) v2.2** - Building the future of functional AI agent systems 🚀

{jaf_py-2.2.2 → jaf_py-2.2.4}/jaf/core/__init__.py

@@ -13,6 +13,7 @@ from .agent_tool import (
     get_current_run_config,
     set_current_run_config,
 )
+from .proxy import ProxyConfig, ProxyAuth, create_proxy_config, get_default_proxy_config
 
 __all__ = [
     "Agent",
@@ -22,6 +23,8 @@ __all__ = [
     "Message",
     "ModelConfig",
     "ModelProvider",
+    "ProxyAuth",
+    "ProxyConfig",
     "RunConfig",
     "RunId",
     "RunResult",
@@ -39,9 +42,11 @@ __all__ = [
     "create_conditional_enabler",
     "create_default_output_extractor",
     "create_json_output_extractor",
+    "create_proxy_config",
     "create_run_id",
     "create_trace_id",
     "get_current_run_config",
+    "get_default_proxy_config",
     "require_permissions",
     "run",
     "set_current_run_config",

{jaf_py-2.2.2 → jaf_py-2.2.4}/jaf/core/engine.py

@@ -91,7 +91,11 @@ async def run(
         set_current_run_config(config)
         
         if config.on_event:
-            config.on_event(RunStartEvent(data=to_event_data(RunStartEventData(run_id=initial_state.run_id, trace_id=initial_state.trace_id))))
+            config.on_event(RunStartEvent(data=to_event_data(RunStartEventData(
+                run_id=initial_state.run_id,
+                trace_id=initial_state.trace_id,
+                session_id=config.conversation_id
+            ))))
 
         state_with_memory = await _load_conversation_history(initial_state, config)
         result = await _run_internal(state_with_memory, config)
@@ -631,7 +635,7 @@ async def _execute_tool_calls(
                     result=result_string,
                     trace_id=state.trace_id,
                     run_id=state.run_id,
-                    tool_result=tool_result_obj,
+                    tool_result=tool_result,
                     status='success'
                 ))))
 

jaf_py-2.2.4/jaf/core/proxy.py

@@ -0,0 +1,141 @@
+"""
+Proxy configuration for JAF agents and HTTP clients.
+
+This module provides unified proxy configuration that can be used across
+different HTTP clients (httpx, OpenAI, etc.) in the JAF framework.
+"""
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Dict, Any, Union
+from urllib.parse import urlparse
+
+
+@dataclass
+class ProxyAuth:
+    """Proxy authentication configuration."""
+    username: str
+    password: str
+
+
+@dataclass
+class ProxyConfig:
+    """Proxy configuration for HTTP clients."""
+    http_proxy: Optional[str] = None
+    https_proxy: Optional[str] = None
+    no_proxy: Optional[str] = None
+    auth: Optional[ProxyAuth] = None
+    
+    @classmethod
+    def from_environment(cls) -> 'ProxyConfig':
+        """Create proxy configuration from environment variables."""
+        return cls(
+            http_proxy=os.getenv('HTTP_PROXY') or os.getenv('http_proxy'),
+            https_proxy=os.getenv('HTTPS_PROXY') or os.getenv('https_proxy'),
+            no_proxy=os.getenv('NO_PROXY') or os.getenv('no_proxy'),
+            auth=ProxyAuth(
+                username=os.getenv('PROXY_USERNAME', ''),
+                password=os.getenv('PROXY_PASSWORD', '')
+            ) if os.getenv('PROXY_USERNAME') else None
+        )
+    
+    @classmethod
+    def from_url(cls, proxy_url: str, auth: Optional[ProxyAuth] = None) -> 'ProxyConfig':
+        """Create proxy configuration from a single URL."""
+        return cls(
+            http_proxy=proxy_url,
+            https_proxy=proxy_url,
+            auth=auth
+        )
+    
+    def to_httpx_proxies(self) -> Optional[Dict[str, str]]:
+        """Convert to httpx proxies format."""
+        if not self.http_proxy and not self.https_proxy:
+            return None
+        
+        proxies = {}
+        
+        if self.http_proxy:
+            proxies['http://'] = self._add_auth_to_url(self.http_proxy)
+        
+        if self.https_proxy:
+            proxies['https://'] = self._add_auth_to_url(self.https_proxy)
+        
+        return proxies if proxies else None
+    
+    def to_openai_proxies(self) -> Optional[Dict[str, str]]:
+        """Convert to OpenAI client proxies format."""
+        # OpenAI client supports httpx-style proxy configuration
+        return self.to_httpx_proxies()
+    
+    def _add_auth_to_url(self, url: str) -> str:
+        """Add authentication to proxy URL if configured."""
+        if not self.auth or not self.auth.username:
+            return url
+        
+        parsed = urlparse(url)
+        
+        # If URL already has auth, don't override
+        if '@' in parsed.netloc:
+            return url
+        
+        auth_string = f"{self.auth.username}:{self.auth.password}"
+        
+        # Reconstruct URL with auth
+        if parsed.port:
+            netloc = f"{auth_string}@{parsed.hostname}:{parsed.port}"
+        else:
+            netloc = f"{auth_string}@{parsed.hostname}"
+        
+        return f"{parsed.scheme}://{netloc}{parsed.path}"
+    
+    def should_bypass_proxy(self, host: str) -> bool:
+        """Check if a host should bypass the proxy based on no_proxy settings."""
+        if not self.no_proxy:
+            return False
+        
+        no_proxy_hosts = [h.strip() for h in self.no_proxy.split(',')]
+        
+        for no_proxy_host in no_proxy_hosts:
+            if not no_proxy_host:
+                continue
+            
+            # Exact match
+            if host == no_proxy_host:
+                return True
+            
+            # Wildcard match (e.g., *.example.com)
+            if no_proxy_host.startswith('*'):
+                suffix = no_proxy_host[1:]
+                if host.endswith(suffix):
+                    return True
+            
+            # Domain suffix match
+            if no_proxy_host.startswith('.'):
+                if host.endswith(no_proxy_host) or host == no_proxy_host[1:]:
+                    return True
+        
+        return False
+
+
+def create_proxy_config(
+    proxy_url: Optional[str] = None,
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    no_proxy: Optional[str] = None
+) -> ProxyConfig:
+    """Create a proxy configuration with optional parameters."""
+    auth = ProxyAuth(username, password) if username else None
+    
+    if proxy_url:
+        config = ProxyConfig.from_url(proxy_url, auth)
+        if no_proxy:
+            config.no_proxy = no_proxy
+        return config
+    
+    return ProxyConfig.from_environment()
+
+
+def get_default_proxy_config() -> ProxyConfig:
+    """Get the default proxy configuration from environment variables."""
+    return ProxyConfig.from_environment()