jaf-py 2.5.9__py3-none-any.whl → 2.5.11__py3-none-any.whl

jaf/visualization/__init__.py

@@ -7,7 +7,7 @@ and system relationships.
 
 Core functionality:
 - Agent architecture visualization
-- Tool ecosystem diagrams  
+- Tool ecosystem diagrams
 - Runner system visualization
 - Multiple output formats (PNG, SVG, PDF)
 - Customizable color schemes and layouts

jaf/visualization/example.py

@@ -17,9 +17,11 @@ from .types import GraphOptions
 
 # ========== Example Tool Implementations ==========
 
+
 @dataclass
 class CalculateArgs:
     """Arguments for calculator tool."""
+
     expression: str
 
 
@@ -30,9 +32,9 @@ class ExampleCalculatorTool:
     def schema(self) -> ToolSchema[CalculateArgs]:
         """Tool schema including name, description, and parameter validation."""
         return ToolSchema(
-            name='calculator',
-            description='Performs basic arithmetic operations',
-            parameters=CalculateArgs
+            name="calculator",
+            description="Performs basic arithmetic operations",
+            parameters=CalculateArgs,
         )
 
     async def execute(self, args: CalculateArgs, context: Any) -> str:
@@ -48,6 +50,7 @@ class ExampleCalculatorTool:
 @dataclass
 class WeatherArgs:
     """Arguments for weather tool."""
+
     location: str
 
 
@@ -58,9 +61,9 @@ class ExampleWeatherTool:
     def schema(self) -> ToolSchema[WeatherArgs]:
         """Tool schema including name, description, and parameter validation."""
         return ToolSchema(
-            name='weather',
-            description='Gets current weather for a location',
-            parameters=WeatherArgs
+            name="weather",
+            description="Gets current weather for a location",
+            parameters=WeatherArgs,
         )
 
     async def execute(self, args: WeatherArgs, context: Any) -> str:
@@ -72,6 +75,7 @@ class ExampleWeatherTool:
 @dataclass
 class SearchArgs:
     """Arguments for search tool."""
+
     query: str
 
 
@@ -82,9 +86,7 @@ class ExampleSearchTool:
     def schema(self) -> ToolSchema[SearchArgs]:
         """Tool schema including name, description, and parameter validation."""
         return ToolSchema(
-            name='search',
-            description='Searches the web for information',
-            parameters=SearchArgs
+            name="search", description="Searches the web for information", parameters=SearchArgs
         )
 
     async def execute(self, args: SearchArgs, context: Any) -> str:
@@ -94,6 +96,7 @@ class ExampleSearchTool:
 
 # ========== Example Agent Definitions ==========
 
+
 def create_example_agent() -> Agent:
     """Create a multi-purpose example assistant agent."""
     calculator_tool = ExampleCalculatorTool()
@@ -101,15 +104,17 @@ def create_example_agent() -> Agent:
     search_tool = ExampleSearchTool()
 
     def instructions(state: RunState[Any]) -> str:
-        return ("I am a helpful assistant that can perform calculations, "
-                "check weather, and search for information.")
+        return (
+            "I am a helpful assistant that can perform calculations, "
+            "check weather, and search for information."
+        )
 
     return Agent(
-        name='ExampleAssistant',
+        name="ExampleAssistant",
         instructions=instructions,
         tools=[calculator_tool, weather_tool, search_tool],
-        model_config=ModelConfig(name='gpt-4'),
-        handoffs=['MathSpecialist', 'WeatherBot']
+        model_config=ModelConfig(name="gpt-4"),
+        handoffs=["MathSpecialist", "WeatherBot"],
     )
 
 
@@ -121,10 +126,10 @@ def create_math_specialist() -> Agent:
         return "I specialize in mathematical calculations and problem solving."
 
     return Agent(
-        name='MathSpecialist',
+        name="MathSpecialist",
         instructions=instructions,
         tools=[calculator_tool],
-        model_config=ModelConfig(name='gpt-3.5-turbo')
+        model_config=ModelConfig(name="gpt-3.5-turbo"),
     )
 
 
@@ -136,10 +141,10 @@ def create_weather_bot() -> Agent:
         return "I provide weather information and forecasts."
 
     return Agent(
-        name='WeatherBot',
+        name="WeatherBot",
         instructions=instructions,
         tools=[weather_tool],
-        model_config=ModelConfig(name='gpt-3.5-turbo')
+        model_config=ModelConfig(name="gpt-3.5-turbo"),
     )
 
 
@@ -151,21 +156,22 @@ def create_search_specialist() -> Agent:
         return "I specialize in finding and retrieving information from various sources."
 
     return Agent(
-        name='SearchSpecialist',
+        name="SearchSpecialist",
         instructions=instructions,
         tools=[search_tool],
-        model_config=ModelConfig(name='gpt-4')
+        model_config=ModelConfig(name="gpt-4"),
     )
 
 
 # ========== Example Functions ==========
 
+
 async def run_visualization_examples() -> None:
     """Run comprehensive visualization examples."""
-    print('🎨 Running JAF Visualization Examples...\n')
+    print("🎨 Running JAF Visualization Examples...\n")
 
     # Ensure output directory exists
-    os.makedirs('./examples', exist_ok=True)
+    os.makedirs("./examples", exist_ok=True)
 
     try:
         # Create example agents
@@ -177,152 +183,148 @@ async def run_visualization_examples() -> None:
         agents = [example_agent, math_specialist, weather_bot, search_specialist]
 
         # 1. Generate Agent Graph
-        print('📊 Generating agent visualization...')
+        print("📊 Generating agent visualization...")
         agent_result = await generate_agent_graph(
             agents,
             GraphOptions(
-                title='JAF Agent System',
-                output_path='./examples/agent-graph.png',
-                output_format='png',
+                title="JAF Agent System",
+                output_path="./examples/agent-graph.png",
+                output_format="png",
                 show_tool_details=True,
                 show_sub_agents=True,
-                color_scheme='modern'
-            )
+                color_scheme="modern",
+            ),
         )
 
         if agent_result.success:
-            print(f'✅ Agent graph generated: {agent_result.output_path}')
+            print(f"✅ Agent graph generated: {agent_result.output_path}")
         else:
-            print(f'❌ Agent graph failed: {agent_result.error}')
+            print(f"❌ Agent graph failed: {agent_result.error}")
 
         # 2. Generate Tool Graph
-        print('\n🔧 Generating tool visualization...')
-        all_tools = [
-            ExampleCalculatorTool(),
-            ExampleWeatherTool(),
-            ExampleSearchTool()
-        ]
+        print("\n🔧 Generating tool visualization...")
+        all_tools = [ExampleCalculatorTool(), ExampleWeatherTool(), ExampleSearchTool()]
 
         tool_result = await generate_tool_graph(
             all_tools,
             GraphOptions(
-                title='JAF Tool Ecosystem',
-                output_path='./examples/tool-graph.png',
-                output_format='png',
-                layout='circo',
-                color_scheme='default'
-            )
+                title="JAF Tool Ecosystem",
+                output_path="./examples/tool-graph.png",
+                output_format="png",
+                layout="circo",
+                color_scheme="default",
+            ),
         )
 
         if tool_result.success:
-            print(f'✅ Tool graph generated: {tool_result.output_path}')
+            print(f"✅ Tool graph generated: {tool_result.output_path}")
         else:
-            print(f'❌ Tool graph failed: {tool_result.error}')
+            print(f"❌ Tool graph failed: {tool_result.error}")
 
         # 3. Generate Runner Visualization
-        print('\n🏃 Generating runner visualization...')
+        print("\n🏃 Generating runner visualization...")
         agent_registry = {agent.name: agent for agent in agents}
 
         runner_result = await generate_runner_graph(
             agent_registry,
             GraphOptions(
-                title='JAF Runner Architecture',
-                output_path='./examples/runner-architecture.png',
-                output_format='png',
-                color_scheme='modern'
-            )
+                title="JAF Runner Architecture",
+                output_path="./examples/runner-architecture.png",
+                output_format="png",
+                color_scheme="modern",
+            ),
         )
 
         if runner_result.success:
-            print(f'✅ Runner graph generated: {runner_result.output_path}')
+            print(f"✅ Runner graph generated: {runner_result.output_path}")
         else:
-            print(f'❌ Runner graph failed: {runner_result.error}')
+            print(f"❌ Runner graph failed: {runner_result.error}")
 
         # 4. Generate different color schemes
-        print('\n🎨 Generating alternative color schemes...')
+        print("\n🎨 Generating alternative color schemes...")
 
-        for scheme in ['default', 'modern', 'minimal']:
+        for scheme in ["default", "modern", "minimal"]:
             scheme_result = await generate_agent_graph(
                 [example_agent],
                 GraphOptions(
-                    title=f'JAF Agent ({scheme} theme)',
-                    output_path=f'./examples/agent-{scheme}.png',
-                    output_format='png',
+                    title=f"JAF Agent ({scheme} theme)",
+                    output_path=f"./examples/agent-{scheme}.png",
+                    output_format="png",
                     color_scheme=scheme,
-                    show_tool_details=True
-                )
+                    show_tool_details=True,
+                ),
             )
 
             if scheme_result.success:
-                print(f'✅ {scheme} theme generated: {scheme_result.output_path}')
+                print(f"✅ {scheme} theme generated: {scheme_result.output_path}")
             else:
-                print(f'❌ {scheme} theme failed: {scheme_result.error}')
+                print(f"❌ {scheme} theme failed: {scheme_result.error}")
 
         # 5. Generate different formats
-        print('\n📄 Generating different output formats...')
+        print("\n📄 Generating different output formats...")
 
-        for fmt in ['png', 'svg', 'pdf']:
+        for fmt in ["png", "svg", "pdf"]:
             format_result = await generate_agent_graph(
                 [example_agent, math_specialist],
                 GraphOptions(
-                    title='JAF Multi-Format Example',
-                    output_path=f'./examples/multi-format.{fmt}',
+                    title="JAF Multi-Format Example",
+                    output_path=f"./examples/multi-format.{fmt}",
                     output_format=fmt,
-                    color_scheme='modern'
-                )
+                    color_scheme="modern",
+                ),
             )
 
             if format_result.success:
-                print(f'✅ {fmt.upper()} format generated: {format_result.output_path}')
+                print(f"✅ {fmt.upper()} format generated: {format_result.output_path}")
             else:
-                print(f'❌ {fmt.upper()} format failed: {format_result.error}')
-
-        print('\n🎉 All visualization examples completed!')
-        print('\n📁 Generated files:')
-        print('   - ./examples/agent-graph.png')
-        print('   - ./examples/tool-graph.png')
-        print('   - ./examples/runner-architecture.png')
-        print('   - ./examples/agent-default.png')
-        print('   - ./examples/agent-modern.png')
-        print('   - ./examples/agent-minimal.png')
-        print('   - ./examples/multi-format.png')
-        print('   - ./examples/multi-format.svg')
-        print('   - ./examples/multi-format.pdf')
+                print(f"❌ {fmt.upper()} format failed: {format_result.error}")
+
+        print("\n🎉 All visualization examples completed!")
+        print("\n📁 Generated files:")
+        print("   - ./examples/agent-graph.png")
+        print("   - ./examples/tool-graph.png")
+        print("   - ./examples/runner-architecture.png")
+        print("   - ./examples/agent-default.png")
+        print("   - ./examples/agent-modern.png")
+        print("   - ./examples/agent-minimal.png")
+        print("   - ./examples/multi-format.png")
+        print("   - ./examples/multi-format.svg")
+        print("   - ./examples/multi-format.pdf")
 
     except Exception as error:
-        print(f'❌ Error running visualization examples: {error}')
+        print(f"❌ Error running visualization examples: {error}")
 
 
 async def quick_start_visualization(agent: Agent, output_path: str = None) -> None:
     """
     Quick start function for visualizing a single agent.
-    
+
     Args:
         agent: Agent to visualize
         output_path: Optional custom output path
     """
-    print(f'🚀 Quick visualization for agent: {agent.name}')
+    print(f"🚀 Quick visualization for agent: {agent.name}")
 
     result = await generate_agent_graph(
         [agent],
         GraphOptions(
-            output_path=output_path or f'./agent-{agent.name.lower()}.png',
-            output_format='png',
-            color_scheme='modern',
+            output_path=output_path or f"./agent-{agent.name.lower()}.png",
+            output_format="png",
+            color_scheme="modern",
             show_tool_details=True,
-            show_sub_agents=True
-        )
+            show_sub_agents=True,
+        ),
     )
 
     if result.success:
-        print(f'✅ Visualization saved to: {result.output_path}')
+        print(f"✅ Visualization saved to: {result.output_path}")
     else:
-        print(f'❌ Visualization failed: {result.error}')
+        print(f"❌ Visualization failed: {result.error}")
 
 
 async def demo_basic_usage() -> None:
     """Demonstrate basic usage patterns."""
-    print('📚 JAF Visualization - Basic Usage Demo\n')
+    print("📚 JAF Visualization - Basic Usage Demo\n")
 
     # Create a simple agent
     calculator_tool = ExampleCalculatorTool()
@@ -331,54 +333,53 @@ async def demo_basic_usage() -> None:
         return "I am a simple calculator agent."
 
     simple_agent = Agent(
-        name='SimpleCalculator',
+        name="SimpleCalculator",
         instructions=simple_instructions,
         tools=[calculator_tool],
-        model_config=ModelConfig(name='gpt-3.5-turbo')
+        model_config=ModelConfig(name="gpt-3.5-turbo"),
     )
 
     # Generate basic visualization
     result = await generate_agent_graph(
         [simple_agent],
-        GraphOptions(
-            title='Simple Calculator Agent',
-            output_path='./simple-agent.png'
-        )
+        GraphOptions(title="Simple Calculator Agent", output_path="./simple-agent.png"),
     )
 
     if result.success:
-        print(f'✅ Basic visualization created: {result.output_path}')
-        print('📄 DOT source preview:')
-        print(result.graph_dot[:200] + '...' if result.graph_dot else 'No DOT source available')
+        print(f"✅ Basic visualization created: {result.output_path}")
+        print("📄 DOT source preview:")
+        print(result.graph_dot[:200] + "..." if result.graph_dot else "No DOT source available")
     else:
-        print(f'❌ Basic visualization failed: {result.error}')
+        print(f"❌ Basic visualization failed: {result.error}")
 
 
 # ========== CLI Integration ==========
 
+
 async def main() -> None:
     """Main function for CLI execution."""
-    print('🎨 JAF Visualization Examples\n')
+    print("🎨 JAF Visualization Examples\n")
 
     # Check if graphviz is available
     try:
         from graphviz import Digraph
+
         test_graph = Digraph()
-        print('✅ Graphviz Python package available')
+        print("✅ Graphviz Python package available")
     except ImportError:
-        print('❌ Graphviz Python package not installed')
+        print("❌ Graphviz Python package not installed")
         print('   Install with: pip install "jaf-py[visualization]"')
         return
 
     try:
         # Test basic Graphviz system dependency
         test_graph = Digraph()
-        test_graph.node('test', 'Test Node')
+        test_graph.node("test", "Test Node")
         test_graph.source  # This will work if graphviz is available
-        print('✅ Graphviz system dependency available')
+        print("✅ Graphviz system dependency available")
     except Exception:
-        print('❌ Graphviz system dependency not found')
-        print('   Install with: brew install graphviz (macOS) or apt-get install graphviz (Ubuntu)')
+        print("❌ Graphviz system dependency not found")
+        print("   Install with: brew install graphviz (macOS) or apt-get install graphviz (Ubuntu)")
         return
 
     # Run examples
@@ -387,5 +388,5 @@ async def main() -> None:
     await run_visualization_examples()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     asyncio.run(main())