jaf-py 2.3.0__py3-none-any.whl → 2.4.1__py3-none-any.whl

jaf/core/engine.py

@@ -36,6 +36,8 @@ from .types import (
     LLMCallEndEventData,
     LLMCallStartEvent,
     LLMCallStartEventData,
+    AssistantMessageEvent,
+    AssistantMessageEventData,
     MaxTurnsExceeded,
     Message,
     ModelBehaviorError,
@@ -300,8 +302,115 @@ async def _run_internal(
             messages=state.messages
         ))))
 
-    # Get completion from model provider
-    llm_response = await config.model_provider.get_completion(state, current_agent, config)
+    # Get completion from model provider, prefer streaming if available
+    llm_response: Dict[str, Any]
+    assistant_event_streamed = False
+
+    get_stream = getattr(config.model_provider, "get_completion_stream", None)
+    if callable(get_stream):
+        try:
+            aggregated_text = ""
+            # Working array of partial tool calls
+            partial_tool_calls: List[Dict[str, Any]] = []
+
+            async for chunk in get_stream(state, current_agent, config):  # type: ignore[arg-type]
+                # Text deltas
+                delta_text = getattr(chunk, "delta", None)
+                if delta_text:
+                    aggregated_text += delta_text
+
+                # Tool call deltas
+                tcd = getattr(chunk, "tool_call_delta", None)
+                if tcd is not None:
+                    idx = getattr(tcd, "index", 0) or 0
+                    # Ensure slot exists
+                    while len(partial_tool_calls) <= idx:
+                        partial_tool_calls.append({
+                            "id": None,
+                            "type": "function",
+                            "function": {"name": None, "arguments": ""}
+                        })
+                    target = partial_tool_calls[idx]
+                    # id
+                    tc_id = getattr(tcd, "id", None)
+                    if tc_id:
+                        target["id"] = tc_id
+                    # function fields
+                    fn = getattr(tcd, "function", None)
+                    if fn is not None:
+                        fn_name = getattr(fn, "name", None)
+                        if fn_name:
+                            target["function"]["name"] = fn_name
+                        args_delta = getattr(fn, "arguments_delta", None)
+                        if args_delta:
+                            target["function"]["arguments"] += args_delta
+
+                # Emit partial assistant message when something changed
+                if delta_text or tcd is not None:
+                    assistant_event_streamed = True
+                    # Normalize tool_calls for message
+                    message_tool_calls = None
+                    if len(partial_tool_calls) > 0:
+                        message_tool_calls = []
+                        for i, tc in enumerate(partial_tool_calls):
+                            message_tool_calls.append({
+                                "id": tc["id"] or f"call_{i}",
+                                "type": "function",
+                                "function": {
+                                    "name": tc["function"]["name"] or "",
+                                    "arguments": tc["function"]["arguments"]
+                                }
+                            })
+
+                    partial_msg = Message(
+                        role=ContentRole.ASSISTANT,
+                        content=aggregated_text or "",
+                        tool_calls=None if not message_tool_calls else [
+                            ToolCall(
+                                id=mc["id"],
+                                type="function",
+                                function=ToolCallFunction(
+                                    name=mc["function"]["name"],
+                                    arguments=mc["function"]["arguments"],
+                                ),
+                            ) for mc in message_tool_calls
+                        ],
+                    )
+                    try:
+                        if config.on_event:
+                            config.on_event(AssistantMessageEvent(data=to_event_data(
+                                AssistantMessageEventData(message=partial_msg)
+                            )))
+                    except Exception as _e:
+                        # Do not fail the run on callback errors
+                        pass
+
+            # Build final response object compatible with downstream logic
+            final_tool_calls = None
+            if len(partial_tool_calls) > 0:
+                final_tool_calls = []
+                for i, tc in enumerate(partial_tool_calls):
+                    final_tool_calls.append({
+                        "id": tc["id"] or f"call_{i}",
+                        "type": "function",
+                        "function": {
+                            "name": tc["function"]["name"] or "",
+                            "arguments": tc["function"]["arguments"]
+                        }
+                    })
+
+            llm_response = {
+                "message": {
+                    "content": aggregated_text or None,
+                    "tool_calls": final_tool_calls
+                }
+            }
+        except Exception:
+            # Fallback to non-streaming on error
+            assistant_event_streamed = False
+            llm_response = await config.model_provider.get_completion(state, current_agent, config)
+    else:
+        llm_response = await config.model_provider.get_completion(state, current_agent, config)
 
     # Emit LLM call end event
     if config.on_event:

jaf/core/tools.py

@@ -89,14 +89,12 @@ def create_function_tool(config: FunctionToolConfig) -> Tool:
     # Validate schema generation (cached for performance)
     if not hasattr(parameters, '_schema_validated'):
         try:
+            # Generate schema once to validate the model is well-formed.
+            # Allow empty object schemas (no parameters) for tools that take no args.
             if hasattr(parameters, 'model_json_schema'):
-                test_schema = parameters.model_json_schema()
-                if not test_schema.get('properties'):
-                    raise ValueError(f"Tool '{tool_name}' has no properties in schema. Check your Pydantic model fields.")
+                _ = parameters.model_json_schema()
             elif hasattr(parameters, 'schema'):
-                test_schema = parameters.schema()
-                if not test_schema.get('properties'):
-                    raise ValueError(f"Tool '{tool_name}' has no properties in schema. Check your Pydantic model fields.")
+                _ = parameters.schema()
             parameters._schema_validated = True
         except Exception as e:
             logger.error(f"Tool {tool_name} schema generation failed: {e}")

jaf/core/tracing.py

@@ -364,7 +364,6 @@ class LangfuseTraceCollector:
                 user_id = None
                 
                 # Debug: Print the event data structure to understand what we're working with
-                print(f"[LANGFUSE DEBUG] Event data keys: {list(event.data.keys()) if event.data else 'No data'}")
                 if event.data.get("context"):
                     context = event.data["context"]
                     print(f"[LANGFUSE DEBUG] Context type: {type(context)}")
@@ -649,7 +648,6 @@ class LangfuseTraceCollector:
                 return TraceId(event.data['runId'])
         
         # Debug: print what's actually in the event data
-        print(f"[LANGFUSE] Event data keys: {list(event.data.keys()) if hasattr(event, 'data') and event.data else 'No data'}")
         return None
 
     def _get_span_id(self, event: TraceEvent) -> str:

jaf/core/types.py

@@ -5,7 +5,7 @@ This module defines all the fundamental data structures and types used throughou
 the framework, maintaining immutability and type safety.
 """
 
-from collections.abc import Awaitable
+from collections.abc import Awaitable, AsyncIterator
 
 # ReadOnly is only available in Python 3.13+, so we'll use a simpler approach
 from dataclasses import dataclass, field
@@ -416,6 +416,15 @@ class LLMCallEndEvent:
     data: LLMCallEndEventData = field(default_factory=lambda: LLMCallEndEventData(None, TraceId(""), RunId("")))
 
 @dataclass(frozen=True)
+class AssistantMessageEventData:
+    """Data for assistant message events (partial or complete)."""
+    message: Message
+
+@dataclass(frozen=True)
+class AssistantMessageEvent:
+    type: Literal['assistant_message'] = 'assistant_message'
+    data: AssistantMessageEventData = field(default_factory=lambda: AssistantMessageEventData(Message(role=ContentRole.ASSISTANT, content="")))
+@dataclass(frozen=True)
 class ToolCallStartEventData:
     """Data for tool call start events."""
     tool_name: str
@@ -515,6 +524,7 @@ TraceEvent = Union[
     OutputParseEvent,
     LLMCallStartEvent,
     LLMCallEndEvent,
+    AssistantMessageEvent,
     ToolCallStartEvent,
     ToolCallEndEvent,
     HandoffEvent,
@@ -532,6 +542,30 @@ class ModelCompletionResponse:
     """Response structure from model completion."""
     message: Optional[ModelCompletionMessage] = None
 
+# Streaming chunk structures for provider-level streaming support
+@dataclass(frozen=True)
+class ToolCallFunctionDelta:
+    """Function fields that may stream as deltas."""
+    name: Optional[str] = None
+    arguments_delta: Optional[str] = None
+
+@dataclass(frozen=True)
+class ToolCallDelta:
+    """Represents a partial tool call delta in a streamed response."""
+    index: int
+    id: Optional[str] = None
+    type: Literal['function'] = 'function'
+    function: Optional[ToolCallFunctionDelta] = None
+
+@dataclass(frozen=True)
+class CompletionStreamChunk:
+    """A streamed chunk from the model provider."""
+    delta: Optional[str] = None
+    tool_call_delta: Optional[ToolCallDelta] = None
+    is_done: Optional[bool] = False
+    finish_reason: Optional[str] = None
+    raw: Optional[Any] = None
+
 @runtime_checkable
 class ModelProvider(Protocol[Ctx]):
     """Protocol for model providers."""
@@ -545,6 +579,15 @@ class ModelProvider(Protocol[Ctx]):
         """Get completion from the model."""
         ...
 
+    async def get_completion_stream(
+        self,
+        state: RunState[Ctx],
+        agent: Agent[Ctx, Any],
+        config: 'RunConfig[Ctx]'
+    ) -> AsyncIterator[CompletionStreamChunk]:
+        """Optional streaming API: yields incremental deltas while generating."""
+        ...
+
 @dataclass(frozen=True)
 class RunConfig(Generic[Ctx]):
     """Configuration for running agents."""

jaf/providers/model.py

@@ -5,13 +5,14 @@ This module provides model providers that integrate with various LLM services,
 starting with LiteLLM for multi-provider support.
 """
 
-from typing import Any, Dict, Optional, TypeVar
+from typing import Any, Dict, Optional, TypeVar, AsyncIterator, List
+import asyncio
 import httpx
 
 from openai import OpenAI
 from pydantic import BaseModel
 
-from ..core.types import Agent, ContentRole, Message, ModelProvider, RunConfig, RunState
+from ..core.types import Agent, ContentRole, Message, ModelProvider, RunConfig, RunState, CompletionStreamChunk, ToolCallDelta, ToolCallFunctionDelta
 from ..core.proxy import ProxyConfig
 
 Ctx = TypeVar('Ctx')
@@ -169,6 +170,168 @@ def make_litellm_provider(
                 'prompt': messages
             }
 
+        async def get_completion_stream(
+            self,
+            state: RunState[Ctx],
+            agent: Agent[Ctx, Any],
+            config: RunConfig[Ctx]
+        ) -> AsyncIterator[CompletionStreamChunk]:
+            """
+            Stream completion chunks from the model provider, yielding text deltas and tool-call deltas.
+            Uses OpenAI-compatible streaming via LiteLLM endpoint.
+            """
+            # Determine model to use
+            model = (config.model_override or
+                     (agent.model_config.name if agent.model_config else "gpt-4o"))
+
+            # Create system message
+            system_message = {
+                "role": "system",
+                "content": agent.instructions(state)
+            }
+
+            # Convert messages to OpenAI format
+            messages = [system_message] + [
+                _convert_message(msg) for msg in state.messages
+            ]
+
+            # Convert tools to OpenAI format
+            tools = None
+            if agent.tools:
+                tools = [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": tool.schema.name,
+                            "description": tool.schema.description,
+                            "parameters": _pydantic_to_json_schema(tool.schema.parameters),
+                        }
+                    }
+                    for tool in agent.tools
+                ]
+
+            # Determine tool choice behavior
+            last_message = state.messages[-1] if state.messages else None
+            is_after_tool_call = last_message and (last_message.role == ContentRole.TOOL or last_message.role == 'tool')
+
+            # Prepare request parameters
+            request_params: Dict[str, Any] = {
+                "model": model,
+                "messages": messages,
+            }
+
+            # Add optional parameters
+            if agent.model_config:
+                if agent.model_config.temperature is not None:
+                    request_params["temperature"] = agent.model_config.temperature
+                if agent.model_config.max_tokens is not None:
+                    request_params["max_tokens"] = agent.model_config.max_tokens
+
+            if tools:
+                request_params["tools"] = tools
+                # Set tool_choice to auto when tools are available
+                request_params["tool_choice"] = "auto"
+
+            if agent.output_codec:
+                request_params["response_format"] = {"type": "json_object"}
+
+            # Enable streaming
+            request_params["stream"] = True
+
+            loop = asyncio.get_running_loop()
+            queue: asyncio.Queue = asyncio.Queue(maxsize=256)
+            SENTINEL = object()
+
+            def _put(item: CompletionStreamChunk):
+                try:
+                    asyncio.run_coroutine_threadsafe(queue.put(item), loop)
+                except RuntimeError:
+                    # Event loop closed; drop silently
+                    pass
+
+            def _producer():
+                try:
+                    stream = self.client.chat.completions.create(**request_params)
+                    for chunk in stream:
+                        try:
+                            # Best-effort extraction of raw for debugging
+                            try:
+                                raw_obj = chunk.model_dump()  # pydantic BaseModel
+                            except Exception:
+                                raw_obj = None
+
+                            choice = None
+                            if getattr(chunk, "choices", None):
+                                choice = chunk.choices[0]
+
+                            if choice is None:
+                                continue
+
+                            delta = getattr(choice, "delta", None)
+                            finish_reason = getattr(choice, "finish_reason", None)
+
+                            # Text content delta
+                            if delta is not None:
+                                content_delta = getattr(delta, "content", None)
+                                if content_delta:
+                                    _put(CompletionStreamChunk(delta=content_delta, raw=raw_obj))
+
+                                # Tool call deltas
+                                tool_calls = getattr(delta, "tool_calls", None)
+                                if isinstance(tool_calls, list):
+                                    for tc in tool_calls:
+                                        # Each tc is likely a pydantic model with .index/.id/.function
+                                        try:
+                                            idx = getattr(tc, "index", 0) or 0
+                                            tc_id = getattr(tc, "id", None)
+                                            fn = getattr(tc, "function", None)
+                                            fn_name = getattr(fn, "name", None) if fn is not None else None
+                                            # OpenAI streams "arguments" as incremental deltas
+                                            args_delta = getattr(fn, "arguments", None) if fn is not None else None
+
+                                            _put(CompletionStreamChunk(
+                                                tool_call_delta=ToolCallDelta(
+                                                    index=idx,
+                                                    id=tc_id,
+                                                    type='function',
+                                                    function=ToolCallFunctionDelta(
+                                                        name=fn_name,
+                                                        arguments_delta=args_delta
+                                                    )
+                                                ),
+                                                raw=raw_obj
+                                            ))
+                                        except Exception:
+                                            # Skip malformed tool-call deltas
+                                            continue
+
+                            # Completion ended
+                            if finish_reason:
+                                _put(CompletionStreamChunk(is_done=True, finish_reason=finish_reason, raw=raw_obj))
+                        except Exception:
+                            # Skip individual chunk errors, keep streaming
+                            continue
+                except Exception:
+                    # On top-level stream error, signal done
+                    pass
+                finally:
+                    try:
+                        asyncio.run_coroutine_threadsafe(queue.put(SENTINEL), loop)
+                    except RuntimeError:
+                        pass
+
+            # Start producer in background
+            loop.run_in_executor(None, _producer)
+
+            # Consume queue and yield
+            while True:
+                item = await queue.get()
+                if item is SENTINEL:
+                    break
+                # Guarantee type for consumers
+                if isinstance(item, CompletionStreamChunk):
+                    yield item
+
     return LiteLLMProvider()
 
 def _convert_message(msg: Message) -> Dict[str, Any]:

{jaf_py-2.3.0.dist-info → jaf_py-2.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaf-py
-Version: 2.3.0
+Version: 2.4.1
 Summary: A purely functional agent framework with immutable state and composable tools - Python implementation
 Author: JAF Contributors
 Maintainer: JAF Contributors
@@ -73,67 +73,67 @@ Dynamic: license-file
 
 <!-- ![JAF Banner](docs/cover.png) -->
 
-[![Version](https://img.shields.io/badge/version-2.2.3-blue.svg)](https://github.com/xynehq/jaf-py)
+[![Version](https://img.shields.io/badge/version-2.3.1-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/)
 
 A purely functional agent framework with immutable state and composable tools, professionally converted from TypeScript to Python. JAF enables building production-ready AI agent systems with built-in security, observability, and error handling.
 
-**🎯 Production Ready**: Complete feature parity with TypeScript version, comprehensive test suite, and production deployment support.
-
-## 📚 **[Read the Full Documentation](https://xynehq.github.io/jaf-py/)**
-
-**[🚀 Get Started →](https://xynehq.github.io/jaf-py/getting-started/)** | **[📖 API Reference →](https://xynehq.github.io/jaf-py/api-reference/)** | **[🎮 Examples →](https://xynehq.github.io/jaf-py/examples/)**
-
-## ✨ Key Features
-
-### 🏗️ **Complete TypeScript Conversion**
-- ✅ **Full Feature Parity**: All TypeScript functionality converted to Python
-- ✅ **Type Safety**: Pydantic models with runtime validation
-- ✅ **Immutable State**: Functional programming principles preserved
-- ✅ **Tool Integration**: Complete tool calling and execution system
-
-### 🚀 **Production Ready Server**
-- ✅ **FastAPI Server**: High-performance async HTTP API
-- ✅ **Auto Documentation**: Interactive API docs at `/docs`
-- ✅ **Health Monitoring**: Built-in health checks and metrics
-- ✅ **CORS Support**: Ready for browser integration
-
-### 🔌 **Model Context Protocol (MCP)**
-- ✅ **MCP Client**: Full MCP specification support
-- ✅ **Stdio & SSE**: Multiple transport protocols
-- ✅ **Tool Integration**: Seamless MCP tool integration
-- ✅ **Auto Discovery**: Dynamic tool loading from MCP servers
-
-### 🛡️ **Enterprise Security**
-- ✅ **Input Guardrails**: Content filtering and validation
-- ✅ **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, agent-as-tool, and server demos
-- ✅ **Visual Architecture**: Graphviz-powered agent and tool diagrams
-
-## 🎯 Core Philosophy
+**Production Ready**: Complete feature parity with TypeScript version, comprehensive test suite, and production deployment support.
+
+##  **[Read the Full Documentation](https://xynehq.github.io/jaf-py/)**
+
+**[ Get Started →](https://xynehq.github.io/jaf-py/getting-started/)** | **[ API Reference →](https://xynehq.github.io/jaf-py/api-reference/)** | **[ Examples →](https://xynehq.github.io/jaf-py/examples/)**
+
+## Key Features
+
+###  **Complete TypeScript Conversion**
+-  **Full Feature Parity**: All TypeScript functionality converted to Python
+-  **Type Safety**: Pydantic models with runtime validation
+-  **Immutable State**: Functional programming principles preserved
+-  **Tool Integration**: Complete tool calling and execution system
+
+###  **Production Ready Server**
+-  **FastAPI Server**: High-performance async HTTP API
+-  **Auto Documentation**: Interactive API docs at `/docs`
+-  **Health Monitoring**: Built-in health checks and metrics
+-  **CORS Support**: Ready for browser integration
+
+###  **Model Context Protocol (MCP)**
+-  **MCP Client**: Full MCP specification support
+-  **Stdio & SSE**: Multiple transport protocols
+-  **Tool Integration**: Seamless MCP tool integration
+-  **Auto Discovery**: Dynamic tool loading from MCP servers
+
+###  **Enterprise Security**
+-  **Input Guardrails**: Content filtering and validation
+-  **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, agent-as-tool, and server demos
+-  **Visual Architecture**: Graphviz-powered agent and tool diagrams
+
+##  Core Philosophy
 
 - **Immutability**: All core data structures are deeply immutable
 - **Pure Functions**: Core logic expressed as pure, predictable functions
@@ -141,7 +141,7 @@ A purely functional agent framework with immutable state and composable tools, p
 - **Composition over Configuration**: Build complex behavior by composing simple functions
 - **Type-Safe by Design**: Leverages Python's type system with Pydantic for runtime safety
 
-## 🚀 Quick Start
+##  Quick Start
 
 ### Installation
 
@@ -197,37 +197,37 @@ pip install -r requirements-docs.txt
 ./docs.sh deploy # Deploy to GitHub Pages
 ```
 
-## 📖 Documentation
+##  Documentation
 
-### 🌐 **[Official Documentation Website](https://xynehq.github.io/jaf-py/)**
+###  **[Official Documentation Website](https://xynehq.github.io/jaf-py/)**
 
 The complete, searchable documentation is available at **[xynehq.github.io/jaf-py](https://xynehq.github.io/jaf-py/)** with:
 
-- ✅ **Interactive navigation** with search and filtering
-- ✅ **Dark/light mode** with automatic system preference detection  
-- ✅ **Mobile-responsive design** for documentation on any device
-- ✅ **Live code examples** with syntax highlighting
-- ✅ **API reference** with auto-generated documentation
-- ✅ **Always up-to-date** with automatic deployments
+-  **Interactive navigation** with search and filtering
+-  **Dark/light mode** with automatic system preference detection  
+-  **Mobile-responsive design** for documentation on any device
+-  **Live code examples** with syntax highlighting
+-  **API reference** with auto-generated documentation
+-  **Always up-to-date** with automatic deployments
 
-### 📁 **Local Documentation**
+###  **Local Documentation**
 
 For offline access, documentation is also available in the [`docs/`](docs/) directory:
 
-- **[📚 Documentation Hub](docs/README.md)** - Your starting point for all documentation
-- **[🚀 Getting Started](docs/getting-started.md)** - Installation and first agent tutorial
-- **[🏗️ Core Concepts](docs/core-concepts.md)** - JAF's functional architecture principles
-- **[📋 API Reference](docs/api-reference.md)** - Complete Python API documentation
-- **[🔧 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
-- **[🔧 Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-
-## 📁 Project Structure
+- **[ Documentation Hub](docs/README.md)** - Your starting point for all documentation
+- **[ Getting Started](docs/getting-started.md)** - Installation and first agent tutorial
+- **[ Core Concepts](docs/core-concepts.md)** - JAF's functional architecture principles
+- **[ API Reference](docs/api-reference.md)** - Complete Python API documentation
+- **[ 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
+- **[ Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
+
+##  Project Structure
 
 ```
 jaf-py/
@@ -243,7 +243,7 @@ jaf-py/
 └── tests/                  # Test suite
 ```
 
-## 🎨 Architectural Visualization
+##  Architectural Visualization
 
 JAF includes powerful visualization capabilities to help you understand and document your agent systems.
 
@@ -295,7 +295,7 @@ async def main():
     )
     
     if result.success:
-        print(f"✅ Visualization saved to: {result.output_path}")
+        print(f" Visualization saved to: {result.output_path}")
     else:
         print(f"❌ Error: {result.error}")
 
@@ -304,12 +304,12 @@ asyncio.run(main())
 
 ### Features
 
-- **🎨 Multiple Color Schemes**: Choose from `default`, `modern`, or `minimal` themes
-- **📊 Agent Architecture**: Visualize agents, tools, and handoff relationships  
-- **🔧 Tool Ecosystems**: Generate dedicated tool interaction diagrams
-- **🏃 Runner Architecture**: Show complete system architecture with session layers
-- **📄 Multiple Formats**: Export as PNG, SVG, or PDF
-- **⚙️ Customizable Layouts**: Support for various Graphviz layouts (`dot`, `circo`, `neato`, etc.)
+- **Multiple Color Schemes**: Choose from `default`, `modern`, or `minimal` themes
+- **Agent Architecture**: Visualize agents, tools, and handoff relationships  
+- **Tool Ecosystems**: Generate dedicated tool interaction diagrams
+- **Runner Architecture**: Show complete system architecture with session layers
+- **Multiple Formats**: Export as PNG, SVG, or PDF
+- **Customizable Layouts**: Support for various Graphviz layouts (`dot`, `circo`, `neato`, etc.)
 
 ### Example Output
 
@@ -336,7 +336,7 @@ await run_visualization_examples()
 # - ./examples/agent-modern.png (modern color scheme)
 ```
 
-## 🏗️ Key Components
+##  Key Components
 
 ### Core Types
 
@@ -414,7 +414,7 @@ async def main():
 asyncio.run(main())
 ```
 
-## 🛡️ Security & Validation
+##  Security & Validation
 
 ### Composable Validation Policies
 
@@ -449,7 +449,7 @@ config = RunConfig(
 )
 ```
 
-## 🤖 Agent-as-Tool Functionality
+##  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:
 
@@ -528,7 +528,7 @@ def create_triage_agent():
     )
 ```
 
-## 📊 Observability
+##  Observability
 
 ### Real-time Tracing
 
@@ -605,7 +605,7 @@ if result.outcome.status == 'error':
     print(f"[{severity}] {formatted_error} (retryable: {is_retryable})")
 ```
 
-## 🔌 Provider Integrations
+##  Provider Integrations
 
 ### A2A (Agent-to-Agent) Communication
 
@@ -672,7 +672,7 @@ from jaf.providers.mcp import create_mcp_sse_client
 sse_client = create_mcp_sse_client('http://localhost:8080/sse')
 ```
 
-## 🚀 Development Server
+##  Development Server
 
 JAF includes a built-in development server for testing agents locally via HTTP endpoints:
 
@@ -706,7 +706,7 @@ Server provides RESTful endpoints:
 - `POST /chat` - General chat endpoint
 - `POST /agents/{name}/chat` - Agent-specific endpoint
 
-## 🔧 Function Composition
+##  Function Composition
 
 JAF supports functional composition patterns for building complex behaviors from simple, reusable functions:
 
@@ -742,7 +742,7 @@ enhanced_tool = create_function_tool({
 - **Type Safety**: Full type checking support
 - **Performance**: Optimize individual pieces independently
 
-## 🎮 Example Applications
+##  Example Applications
 
 Explore the example applications to see the framework in action:
 
@@ -754,12 +754,12 @@ python server_example.py
 ```
 
 **Features demonstrated:**
-- ✅ Multiple specialized agents (math, weather, general)
-- ✅ Tool integration (calculator, weather API)
-- ✅ Agent handoffs and routing
-- ✅ RESTful API with auto-documentation
-- ✅ Real-time tracing and error handling
-- ✅ Production-ready server configuration
+-  Multiple specialized agents (math, weather, general)
+-  Tool integration (calculator, weather API)
+-  Agent handoffs and routing
+-  RESTful API with auto-documentation
+-  Real-time tracing and error handling
+-  Production-ready server configuration
 
 **Available endpoints:**
 - `GET /health` - Server health check
@@ -778,11 +778,11 @@ 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
+-  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
 
@@ -796,10 +796,10 @@ python langfuse_tracing_demo.py
 ```
 
 **Features demonstrated:**
-- ✅ OpenTelemetry distributed tracing setup
-- ✅ Langfuse LLM observability integration
-- ✅ Composite trace collectors
-- ✅ Real-time monitoring and analytics
+-  OpenTelemetry distributed tracing setup
+-  Langfuse LLM observability integration
+-  Composite trace collectors
+-  Real-time monitoring and analytics
 
 ### 4. MCP Integration Demo
 
@@ -809,12 +809,12 @@ python main.py
 ```
 
 **Features demonstrated:**
-- ✅ Model Context Protocol integration
-- ✅ Dynamic tool loading from MCP servers
-- ✅ Secure filesystem operations
-- ✅ MCP client configuration and management
+-  Model Context Protocol integration
+-  Dynamic tool loading from MCP servers
+-  Secure filesystem operations
+-  MCP client configuration and management
 
-## 🧪 Testing
+##  Testing
 
 ```bash
 pytest          # Run tests
@@ -823,7 +823,7 @@ mypy .          # Type checking
 black .         # Format code
 ```
 
-## 🏛️ Architecture Principles
+##  Architecture Principles
 
 ### Immutable State Machine
 - All state transformations create new state objects
@@ -859,4 +859,4 @@ MIT
 
 ---
 
-**JAF (Juspay Agentic Framework) v2.2** - 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.3.0.dist-info → jaf_py-2.4.1.dist-info}/RECORD

@@ -42,16 +42,16 @@ jaf/core/__init__.py,sha256=rBvP_7TGbJICDJnA7a3qyX8yQErCDWaGAn5WzpyH4gU,1339
 jaf/core/agent_tool.py,sha256=8TcBuSxGmDTW5F_GhBU_m5S43nYqkjO4qTrNERraAig,11656
 jaf/core/analytics.py,sha256=NrUfOLLTDIhOzdfc65ZqS9AJ4ZAP9BtNtga69q0YdYw,23265
 jaf/core/composition.py,sha256=IVxRO1Q9nK7JRH32qQ4p8WMIUu66BhqPNrlTNMGFVwE,26317
-jaf/core/engine.py,sha256=v6yXp-zJF9Cj_9qlaW1rmCz7_N3YuDU02xxlzl-howM,27122
+jaf/core/engine.py,sha256=lsmvVDpmuyo7akALplvJvZvOonSzClCG-0EGbc7o5yQ,32061
 jaf/core/errors.py,sha256=5fwTNhkojKRQ4wZj3lZlgDnAsrYyjYOwXJkIr5EGNUc,5539
 jaf/core/performance.py,sha256=jedQmTEkrKMD6_Aw1h8PdG-5TsdYSFFT7Or6k5dmN2g,9974
 jaf/core/proxy.py,sha256=_WM3cpRlSQLYpgSBrnY30UPMe2iZtlqDQ65kppE-WY0,4609
 jaf/core/proxy_helpers.py,sha256=i7a5fAX9rLmO4FMBX51-yRkTFwfWedzQNgnLmeLUd_A,4370
 jaf/core/streaming.py,sha256=c5o9iqpjoYV2LrUpG6qLWCYrWcP-DCcZsvMbyqKunp8,16089
 jaf/core/tool_results.py,sha256=-bTOqOX02lMyslp5Z4Dmuhx0cLd5o7kgR88qK2HO_sw,11323
-jaf/core/tools.py,sha256=SbJRRr4y_xxNYNTulZg6OiyNaHBlo_qXWYY510jxQEs,16489
-jaf/core/tracing.py,sha256=1g5n-jRkSVSuQNONIgip0j3pHOfOnu2CBzoYhiknGo8,31902
-jaf/core/types.py,sha256=9UXrPkepw7opgv1VGbPAC1Zx80RP4-ouRxtb6kVTA-A,17063
+jaf/core/tools.py,sha256=84N9A7QQ3xxcOs2eUUot3nmCnt5i7iZT9VwkuzuFBxQ,16274
+jaf/core/tracing.py,sha256=3ByTbpYMWHJku-NEasK5ncyMOdv7vHwmG6ybJP19pxE,31659
+jaf/core/types.py,sha256=SdtvjBNdjyvKGvGpGeUMUnYVGMpriy3QnCHUwPkz3Sg,18596
 jaf/core/workflows.py,sha256=Ul-82gzjIXtkhnSMSPv-8igikjkMtW1EBo9yrfodtvI,26294
 jaf/memory/__init__.py,sha256=-L98xlvihurGAzF0DnXtkueDVvO_wV2XxxEwAWdAj50,1400
 jaf/memory/factory.py,sha256=Fh6JyvQtCKe38DZV5-NnC9vPRCvzBgSSPFIGaX7Nt5E,2958
@@ -68,7 +68,7 @@ jaf/policies/handoff.py,sha256=KJYYuL9T6v6DECRhnsS2Je6q4Aj9_zC5d_KBnvEnZNE,8318
 jaf/policies/validation.py,sha256=wn-7ynH10E5nk-_r1_kHIYHrBGmLX0EFr-FUTHrsxvc,10903
 jaf/providers/__init__.py,sha256=j_o-Rubr8d9tNYlFWb6fvzkxIBl3JKK_iabj9wTFia0,2114
 jaf/providers/mcp.py,sha256=WxcC8gUFpDBBYyhorMcc1jHq3xMDMBtnwyRPthfL0S0,13074
-jaf/providers/model.py,sha256=9w2mph6g1TaLOFp3t0VtN2kYEfTa-lyYAVjAqQg3wrU,7748
+jaf/providers/model.py,sha256=nulXAItAptJX6andlZWWGw19iVaqgloVkRzGNRvIKPk,15137
 jaf/server/__init__.py,sha256=K0vSgTfzn3oM54UX9BeAROpaksYY43mFtfjSXoQrhXA,339
 jaf/server/main.py,sha256=CTb0ywbPIq9ELfay5MKChVR7BpIQOoEbPjPfpzo2aBQ,2152
 jaf/server/server.py,sha256=o-n6dPWmlu4_v5ozVW3BTOm1b5kHBQhqRYlHh5sXL-k,8048
@@ -79,9 +79,9 @@ jaf/visualization/functional_core.py,sha256=zedMDZbvjuOugWwnh6SJ2stvRNQX1Hlkb9Ab
 jaf/visualization/graphviz.py,sha256=WTOM6UP72-lVKwI4_SAr5-GCC3ouckxHv88ypCDQWJ0,12056
 jaf/visualization/imperative_shell.py,sha256=GpMrAlMnLo2IQgyB2nardCz09vMvAzaYI46MyrvJ0i4,2593
 jaf/visualization/types.py,sha256=QQcbVeQJLuAOXk8ynd08DXIS-PVCnv3R-XVE9iAcglw,1389
-jaf_py-2.3.0.dist-info/licenses/LICENSE,sha256=LXUQBJxdyr-7C4bk9cQBwvsF_xwA-UVstDTKabpcjlI,1063
-jaf_py-2.3.0.dist-info/METADATA,sha256=_MyYA624bGLW5kwGHSXg4jNrbD_PJEd7UGwr2_JTkdA,27613
-jaf_py-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-jaf_py-2.3.0.dist-info/entry_points.txt,sha256=OtIJeNJpb24kgGrqRx9szGgDx1vL9ayq8uHErmu7U5w,41
-jaf_py-2.3.0.dist-info/top_level.txt,sha256=Xu1RZbGaM4_yQX7bpalo881hg7N_dybaOW282F15ruE,4
-jaf_py-2.3.0.dist-info/RECORD,,
+jaf_py-2.4.1.dist-info/licenses/LICENSE,sha256=LXUQBJxdyr-7C4bk9cQBwvsF_xwA-UVstDTKabpcjlI,1063
+jaf_py-2.4.1.dist-info/METADATA,sha256=F38_7dDyrX_DFA71FLRmSkqzfoubdyGqUT_iKAjEF5w,27216
+jaf_py-2.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+jaf_py-2.4.1.dist-info/entry_points.txt,sha256=OtIJeNJpb24kgGrqRx9szGgDx1vL9ayq8uHErmu7U5w,41
+jaf_py-2.4.1.dist-info/top_level.txt,sha256=Xu1RZbGaM4_yQX7bpalo881hg7N_dybaOW282F15ruE,4
+jaf_py-2.4.1.dist-info/RECORD,,