jaf-py 2.2.3__tar.gz → 2.3.0__tar.gz

{jaf_py-2.2.3 → jaf_py-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaf-py
-Version: 2.2.3
+Version: 2.3.0
 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/)
 
@@ -114,15 +114,23 @@ A purely functional agent framework with immutable state and composable tools, p
 
 ### 📊 **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
@@ -148,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
 ```
 
@@ -212,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
@@ -439,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
@@ -488,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
@@ -663,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  
@@ -721,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.3 → jaf_py-2.3.0}/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/)
 
@@ -43,15 +43,23 @@ A purely functional agent framework with immutable state and composable tools, p
 
 ### 📊 **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
@@ -77,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
 ```
 
@@ -141,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
@@ -368,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
@@ -417,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
@@ -592,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  
@@ -650,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.3 → jaf_py-2.3.0}/jaf/core/engine.py

@@ -91,7 +91,13 @@ 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,
+                context=initial_state.context,
+                messages=initial_state.messages
+            ))))
 
         state_with_memory = await _load_conversation_history(initial_state, config)
         result = await _run_internal(state_with_memory, config)
@@ -289,7 +295,9 @@ async def _run_internal(
             agent_name=current_agent.name,
             model=model,
             trace_id=state.trace_id,
-            run_id=state.run_id
+            run_id=state.run_id,
+            context=state.context,
+            messages=state.messages
         ))))
 
     # Get completion from model provider