kailash 0.1.5__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. {kailash-0.1.5/src/kailash.egg-info → kailash-0.2.1}/PKG-INFO +259 -12
  2. {kailash-0.1.5 → kailash-0.2.1}/README.md +248 -11
  3. {kailash-0.1.5 → kailash-0.2.1}/pyproject.toml +11 -1
  4. {kailash-0.1.5 → kailash-0.2.1}/setup.py +1 -1
  5. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/__init__.py +1 -1
  6. kailash-0.2.1/src/kailash/access_control.py +740 -0
  7. kailash-0.2.1/src/kailash/api/__main__.py +6 -0
  8. kailash-0.2.1/src/kailash/api/auth.py +668 -0
  9. kailash-0.2.1/src/kailash/api/custom_nodes.py +285 -0
  10. kailash-0.2.1/src/kailash/api/custom_nodes_secure.py +377 -0
  11. kailash-0.2.1/src/kailash/api/database.py +620 -0
  12. kailash-0.2.1/src/kailash/api/studio.py +915 -0
  13. kailash-0.2.1/src/kailash/api/studio_secure.py +893 -0
  14. kailash-0.2.1/src/kailash/mcp/__init__.py +53 -0
  15. kailash-0.2.1/src/kailash/mcp/__main__.py +13 -0
  16. kailash-0.2.1/src/kailash/mcp/ai_registry_server.py +712 -0
  17. kailash-0.2.1/src/kailash/mcp/client.py +447 -0
  18. kailash-0.2.1/src/kailash/mcp/client_new.py +334 -0
  19. kailash-0.2.1/src/kailash/mcp/server.py +293 -0
  20. kailash-0.2.1/src/kailash/mcp/server_new.py +336 -0
  21. kailash-0.2.1/src/kailash/mcp/servers/__init__.py +12 -0
  22. kailash-0.2.1/src/kailash/mcp/servers/ai_registry.py +289 -0
  23. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/__init__.py +4 -2
  24. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/__init__.py +2 -0
  25. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/a2a.py +714 -67
  26. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/intelligent_agent_orchestrator.py +31 -37
  27. kailash-0.2.1/src/kailash/nodes/ai/iterative_llm_agent.py +1280 -0
  28. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/llm_agent.py +324 -1
  29. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/self_organizing.py +5 -6
  30. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/base.py +15 -2
  31. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/base_async.py +45 -0
  32. kailash-0.2.1/src/kailash/nodes/base_cycle_aware.py +374 -0
  33. kailash-0.2.1/src/kailash/nodes/base_with_acl.py +338 -0
  34. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/code/python.py +135 -27
  35. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/__init__.py +1 -2
  36. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/readers.py +16 -6
  37. kailash-0.2.1/src/kailash/nodes/data/sql.py +823 -0
  38. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/writers.py +16 -6
  39. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/logic/__init__.py +8 -0
  40. kailash-0.2.1/src/kailash/nodes/logic/convergence.py +642 -0
  41. kailash-0.2.1/src/kailash/nodes/logic/loop.py +153 -0
  42. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/logic/operations.py +187 -27
  43. kailash-0.2.1/src/kailash/nodes/mixins/__init__.py +11 -0
  44. kailash-0.2.1/src/kailash/nodes/mixins/mcp.py +228 -0
  45. kailash-0.2.1/src/kailash/nodes/mixins.py +387 -0
  46. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/__init__.py +2 -1
  47. kailash-0.2.1/src/kailash/runtime/access_controlled.py +458 -0
  48. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/local.py +106 -33
  49. kailash-0.2.1/src/kailash/runtime/parallel_cyclic.py +529 -0
  50. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/sdk_exceptions.py +90 -5
  51. kailash-0.2.1/src/kailash/security.py +845 -0
  52. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/manager.py +38 -15
  53. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/models.py +1 -1
  54. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/storage/filesystem.py +30 -2
  55. kailash-0.2.1/src/kailash/utils/__init__.py +8 -0
  56. kailash-0.2.1/src/kailash/workflow/__init__.py +33 -0
  57. kailash-0.2.1/src/kailash/workflow/convergence.py +270 -0
  58. kailash-0.2.1/src/kailash/workflow/cycle_analyzer.py +889 -0
  59. kailash-0.2.1/src/kailash/workflow/cycle_builder.py +579 -0
  60. kailash-0.2.1/src/kailash/workflow/cycle_config.py +725 -0
  61. kailash-0.2.1/src/kailash/workflow/cycle_debugger.py +860 -0
  62. kailash-0.2.1/src/kailash/workflow/cycle_exceptions.py +615 -0
  63. kailash-0.2.1/src/kailash/workflow/cycle_profiler.py +741 -0
  64. kailash-0.2.1/src/kailash/workflow/cycle_state.py +338 -0
  65. kailash-0.2.1/src/kailash/workflow/cyclic_runner.py +985 -0
  66. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/graph.py +500 -39
  67. kailash-0.2.1/src/kailash/workflow/migration.py +809 -0
  68. kailash-0.2.1/src/kailash/workflow/safety.py +365 -0
  69. kailash-0.2.1/src/kailash/workflow/templates.py +763 -0
  70. kailash-0.2.1/src/kailash/workflow/validation.py +751 -0
  71. {kailash-0.1.5 → kailash-0.2.1/src/kailash.egg-info}/PKG-INFO +259 -12
  72. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/SOURCES.txt +41 -4
  73. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/requires.txt +10 -0
  74. kailash-0.1.5/src/kailash/nodes/data/sql.py +0 -380
  75. kailash-0.1.5/src/kailash/nodes/mcp/__init__.py +0 -11
  76. kailash-0.1.5/src/kailash/nodes/mcp/client.py +0 -554
  77. kailash-0.1.5/src/kailash/nodes/mcp/resource.py +0 -682
  78. kailash-0.1.5/src/kailash/nodes/mcp/server.py +0 -577
  79. kailash-0.1.5/src/kailash/utils/__init__.py +0 -0
  80. kailash-0.1.5/src/kailash/workflow/__init__.py +0 -15
  81. {kailash-0.1.5 → kailash-0.2.1}/LICENSE +0 -0
  82. {kailash-0.1.5 → kailash-0.2.1}/MANIFEST.in +0 -0
  83. {kailash-0.1.5 → kailash-0.2.1}/setup.cfg +0 -0
  84. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/__main__.py +0 -0
  85. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/api/__init__.py +0 -0
  86. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/api/gateway.py +0 -0
  87. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/api/mcp_integration.py +0 -0
  88. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/api/workflow_api.py +0 -0
  89. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/cli/__init__.py +0 -0
  90. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/cli/commands.py +0 -0
  91. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/manifest.py +0 -0
  92. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/agents.py +0 -0
  93. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/ai_providers.py +0 -0
  94. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/embedding_generator.py +0 -0
  95. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/ai/models.py +0 -0
  96. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/__init__.py +0 -0
  97. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/auth.py +0 -0
  98. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/graphql.py +0 -0
  99. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/http.py +0 -0
  100. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/rate_limiting.py +0 -0
  101. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/api/rest.py +0 -0
  102. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/code/__init__.py +0 -0
  103. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/retrieval.py +0 -0
  104. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/sharepoint_graph.py +0 -0
  105. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/sources.py +0 -0
  106. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/streaming.py +0 -0
  107. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/data/vector_db.py +0 -0
  108. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/logic/async_operations.py +0 -0
  109. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/logic/workflow.py +0 -0
  110. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/transform/__init__.py +0 -0
  111. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/transform/chunkers.py +0 -0
  112. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/transform/formatters.py +0 -0
  113. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/nodes/transform/processors.py +0 -0
  114. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/async_local.py +0 -0
  115. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/docker.py +0 -0
  116. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/parallel.py +0 -0
  117. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/runner.py +0 -0
  118. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/runtime/testing.py +0 -0
  119. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/__init__.py +0 -0
  120. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/metrics_collector.py +0 -0
  121. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/storage/__init__.py +0 -0
  122. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/storage/base.py +0 -0
  123. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/tracking/storage/database.py +0 -0
  124. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/utils/export.py +0 -0
  125. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/utils/templates.py +0 -0
  126. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/visualization/__init__.py +0 -0
  127. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/visualization/api.py +0 -0
  128. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/visualization/dashboard.py +0 -0
  129. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/visualization/performance.py +0 -0
  130. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/visualization/reports.py +0 -0
  131. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/builder.py +0 -0
  132. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/mermaid_visualizer.py +0 -0
  133. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/mock_registry.py +0 -0
  134. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/runner.py +0 -0
  135. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/state.py +0 -0
  136. {kailash-0.1.5 → kailash-0.2.1}/src/kailash/workflow/visualization.py +0 -0
  137. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/dependency_links.txt +0 -0
  138. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/entry_points.txt +0 -0
  139. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/not-zip-safe +0 -0
  140. {kailash-0.1.5 → kailash-0.2.1}/src/kailash.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: kailash
3
- Version: 0.1.5
3
+ Version: 0.2.1
4
4
  Summary: Python SDK for the Kailash container-node architecture
5
5
  Home-page: https://github.com/integrum/kailash-python-sdk
6
6
  Author: Integrum
@@ -47,6 +47,16 @@ Requires-Dist: pytest-asyncio>=1.0.0
47
47
  Requires-Dist: pre-commit>=4.2.0
48
48
  Requires-Dist: twine>=6.1.0
49
49
  Requires-Dist: ollama>=0.5.1
50
+ Requires-Dist: sqlalchemy>=2.0.0
51
+ Requires-Dist: psycopg2-binary>=2.9.0
52
+ Requires-Dist: pymysql>=1.1.0
53
+ Requires-Dist: aiosqlite>=0.19.0
54
+ Requires-Dist: websockets>=12.0
55
+ Requires-Dist: httpx>=0.25.0
56
+ Requires-Dist: python-jose>=3.5.0
57
+ Requires-Dist: pytest-xdist>=3.6.0
58
+ Requires-Dist: pytest-timeout>=2.3.0
59
+ Requires-Dist: pytest-split>=0.9.0
50
60
  Provides-Extra: dev
51
61
  Requires-Dist: pytest>=7.0; extra == "dev"
52
62
  Requires-Dist: pytest-cov>=3.0; extra == "dev"
@@ -66,7 +76,7 @@ Dynamic: requires-python
66
76
  <a href="https://pepy.tech/project/kailash"><img src="https://static.pepy.tech/badge/kailash" alt="Downloads"></a>
67
77
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
68
78
  <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
69
- <img src="https://img.shields.io/badge/tests-753%20passing-brightgreen.svg" alt="Tests: 753 passing">
79
+ <img src="https://img.shields.io/badge/tests-734%20passing-brightgreen.svg" alt="Tests: 734 passing">
70
80
  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%">
71
81
  </p>
72
82
 
@@ -94,6 +104,11 @@ Dynamic: requires-python
94
104
  - 🚪 **Multi-Workflow Gateway**: Manage multiple workflows through unified API with MCP integration
95
105
  - 🤖 **Self-Organizing Agents**: Autonomous agent pools with intelligent team formation and convergence detection
96
106
  - 🧠 **Agent-to-Agent Communication**: Shared memory pools and intelligent caching for coordinated multi-agent systems
107
+ - 🔒 **Production Security**: Comprehensive security framework with path traversal prevention, code sandboxing, and audit logging
108
+ - 🎨 **Visual Workflow Builder**: Kailash Workflow Studio - drag-and-drop interface for creating and managing workflows (coming soon)
109
+ - 🔁 **Cyclic Workflows (v0.2.0)**: Universal Hybrid Cyclic Graph Architecture with 30,000+ iterations/second performance
110
+ - 🛠️ **Developer Tools**: CycleAnalyzer, CycleDebugger, CycleProfiler for production-ready cyclic workflows
111
+ - 📈 **High Performance**: Optimized execution engine supporting 100,000+ iteration workflows
97
112
 
98
113
  ## 🎯 Who Is This For?
99
114
 
@@ -278,6 +293,141 @@ results, run_id = runtime.execute(workflow)
278
293
  print("RAG Response:", results["llm_agent"]["response"])
279
294
  ```
280
295
 
296
+ ### Cyclic Workflows - Iterative Processing with Convergence
297
+
298
+ Build workflows that iterate until a condition is met, perfect for optimization, retries, and ML training:
299
+
300
+ ```python
301
+ from kailash.workflow import Workflow
302
+ from kailash.nodes.base_cycle_aware import CycleAwareNode
303
+ from kailash.nodes.base import NodeParameter
304
+ from kailash.runtime.local import LocalRuntime
305
+ from typing import Any, Dict
306
+
307
+ # Create a custom cycle-aware node for data quality improvement
308
+ class DataQualityImproverNode(CycleAwareNode):
309
+ def get_parameters(self) -> Dict[str, NodeParameter]:
310
+ return {
311
+ "data": NodeParameter(name="data", type=list, required=True),
312
+ "target_quality": NodeParameter(name="target_quality", type=float, required=False, default=0.95)
313
+ }
314
+
315
+ def run(self, context: Dict[str, Any], **kwargs) -> Dict[str, Any]:
316
+ """Iteratively improve data quality."""
317
+ data = kwargs["data"]
318
+ target_quality = kwargs.get("target_quality", 0.95)
319
+
320
+ # Get current iteration and previous state
321
+ iteration = self.get_iteration(context)
322
+ prev_state = self.get_previous_state(context)
323
+
324
+ # Calculate current quality
325
+ quality = prev_state.get("quality", 0.5) + 0.1 # Improve by 10% each iteration
326
+ quality = min(quality, 1.0)
327
+
328
+ # Process data (simplified)
329
+ processed_data = [item for item in data if item is not None]
330
+
331
+ # Track quality history
332
+ quality_history = self.accumulate_values(context, "quality_history", quality, max_history=10)
333
+
334
+ # Detect convergence trend
335
+ trend = self.detect_convergence_trend(context, "quality_history", window_size=5)
336
+ converged = quality >= target_quality or (trend and trend["slope"] < 0.01)
337
+
338
+ # Log progress
339
+ self.log_cycle_info(context, f"Iteration {iteration}: Quality={quality:.2%}")
340
+
341
+ # Save state for next iteration
342
+ self.set_cycle_state({"quality": quality, "processed_count": len(processed_data)})
343
+
344
+ return {
345
+ "data": processed_data,
346
+ "quality": quality,
347
+ "converged": converged,
348
+ "iteration": iteration,
349
+ "history": quality_history
350
+ }
351
+
352
+ # Build cyclic workflow
353
+ workflow = Workflow("quality_improvement", "Iterative Data Quality")
354
+ workflow.add_node("improver", DataQualityImproverNode())
355
+
356
+ # Create a cycle - node connects to itself!
357
+ workflow.connect("improver", "improver",
358
+ mapping={"data": "data"}, # Pass data to next iteration
359
+ cycle=True, # This is a cycle
360
+ max_iterations=20, # Safety limit
361
+ convergence_check="converged == True") # Stop condition
362
+
363
+ # Execute with automatic iteration management
364
+ runtime = LocalRuntime()
365
+ results, run_id = runtime.execute(workflow, parameters={
366
+ "improver": {
367
+ "data": [1, None, 3, None, 5, 6, None, 8, 9, 10],
368
+ "target_quality": 0.9
369
+ }
370
+ })
371
+
372
+ print(f"Converged after {results['improver']['iteration']} iterations")
373
+ print(f"Final quality: {results['improver']['quality']:.2%}")
374
+ print(f"Quality history: {results['improver']['history']}")
375
+ ```
376
+
377
+ ### NEW in v0.2.0: CycleBuilder API
378
+
379
+ The new CycleBuilder API provides a fluent interface for creating cyclic workflows:
380
+
381
+ ```python
382
+ # Modern approach with CycleBuilder
383
+ workflow.create_cycle("optimization_loop")
384
+ .connect("gradient", "optimizer")
385
+ .connect("optimizer", "evaluator")
386
+ .connect("evaluator", "gradient")
387
+ .max_iterations(100)
388
+ .converge_when("loss < 0.01")
389
+ .early_stop_when("gradient_norm < 1e-6")
390
+ .checkpoint_every(10)
391
+ .build()
392
+
393
+ # Developer tools for production workflows
394
+ from kailash.workflow import CycleAnalyzer, CycleDebugger, CycleProfiler
395
+
396
+ # Analyze cycle patterns
397
+ analyzer = CycleAnalyzer(workflow)
398
+ report = analyzer.analyze()
399
+ print(f"Found {len(report.cycles)} cycles")
400
+ print(f"Max depth: {report.max_cycle_depth}")
401
+
402
+ # Debug with breakpoints
403
+ debugger = CycleDebugger(workflow)
404
+ debugger.set_breakpoint("optimizer", iteration=50)
405
+ debugger.set_trace("gradient_norm", lambda x: x < 0.001)
406
+
407
+ # Profile performance
408
+ profiler = CycleProfiler(workflow)
409
+ profile_data = profiler.profile(runtime, parameters)
410
+ print(f"Bottleneck: {profile_data.bottleneck_node}")
411
+ print(f"Iterations/sec: {profile_data.iterations_per_second}")
412
+ ```
413
+
414
+ #### Cyclic Workflow Features
415
+
416
+ - **Built-in Iteration Management**: No manual loops or recursion needed
417
+ - **State Persistence**: Maintain state across iterations with `get_previous_state()` and `set_cycle_state()`
418
+ - **Convergence Detection**: Automatic trend analysis with `detect_convergence_trend()`
419
+ - **Value Accumulation**: Track metrics over time with `accumulate_values()`
420
+ - **Safety Limits**: Max iterations prevent infinite loops
421
+ - **Performance**: Optimized execution with ~30,000 iterations/second
422
+ - **Developer Tools**: CycleAnalyzer, CycleDebugger, CycleProfiler for production workflows
423
+
424
+ Common cyclic patterns include:
425
+ - **Retry with Backoff**: ETL pipelines with automatic retry
426
+ - **Optimization Loops**: Iterative parameter tuning
427
+ - **ML Training**: Training until accuracy threshold
428
+ - **Polling**: API polling with rate limiting
429
+ - **Stream Processing**: Windowed data processing
430
+
281
431
  ### Workflow API Wrapper - Expose Workflows as REST APIs
282
432
 
283
433
  Transform any Kailash workflow into a production-ready REST API in just 3 lines of code:
@@ -1102,6 +1252,95 @@ This example demonstrates:
1102
1252
  - **Context formatting** for LLM input
1103
1253
  - **Answer generation** using Ollama's llama3.2 model
1104
1254
 
1255
+ ### 🔒 Access Control and Security
1256
+
1257
+ Kailash SDK provides comprehensive access control and security features for enterprise deployments:
1258
+
1259
+ #### Role-Based Access Control (RBAC)
1260
+ ```python
1261
+ from kailash.access_control import UserContext, PermissionRule, NodePermission
1262
+ from kailash.runtime.access_controlled import AccessControlledRuntime
1263
+
1264
+ # Define user with roles
1265
+ user = UserContext(
1266
+ user_id="analyst_001",
1267
+ tenant_id="company_abc",
1268
+ email="analyst@company.com",
1269
+ roles=["analyst", "viewer"]
1270
+ )
1271
+
1272
+ # Create secure runtime
1273
+ runtime = AccessControlledRuntime(user_context=user)
1274
+
1275
+ # Execute workflow with automatic permission checks
1276
+ results, run_id = runtime.execute(workflow, parameters={})
1277
+ ```
1278
+
1279
+ #### Multi-Tenant Isolation
1280
+ ```python
1281
+ from kailash.access_control import get_access_control_manager, PermissionEffect, WorkflowPermission
1282
+
1283
+ # Configure tenant-based access rules
1284
+ acm = get_access_control_manager()
1285
+ acm.enabled = True
1286
+
1287
+ # Tenant isolation rule
1288
+ acm.add_rule(PermissionRule(
1289
+ id="tenant_isolation",
1290
+ resource_type="workflow",
1291
+ resource_id="customer_analytics",
1292
+ permission=WorkflowPermission.EXECUTE,
1293
+ effect=PermissionEffect.ALLOW,
1294
+ tenant_id="company_abc" # Only this tenant can access
1295
+ ))
1296
+ ```
1297
+
1298
+ #### Data Masking and Field Protection
1299
+ ```python
1300
+ from kailash.nodes.base_with_acl import add_access_control
1301
+
1302
+ # Add access control to sensitive data nodes
1303
+ secure_reader = add_access_control(
1304
+ CSVReaderNode(file_path="customers.csv"),
1305
+ enable_access_control=True,
1306
+ required_permission=NodePermission.READ_OUTPUT,
1307
+ mask_output_fields=["ssn", "phone"] # Mask for non-admin users
1308
+ )
1309
+
1310
+ workflow.add_node("secure_data", secure_reader)
1311
+ ```
1312
+
1313
+ #### Permission-Based Routing
1314
+ ```python
1315
+ # Different execution paths based on user permissions
1316
+ from kailash.access_control import NodePermission
1317
+
1318
+ # Admin users get full processing
1319
+ admin_processor = PythonCodeNode.from_function(
1320
+ lambda data: {"result": process_all_data(data)},
1321
+ name="admin_processor"
1322
+ )
1323
+
1324
+ # Analyst users get limited processing
1325
+ analyst_processor = PythonCodeNode.from_function(
1326
+ lambda data: {"result": process_limited_data(data)},
1327
+ name="analyst_processor"
1328
+ )
1329
+
1330
+ # Runtime automatically routes based on user permissions
1331
+ workflow.add_node("admin_path", admin_processor)
1332
+ workflow.add_node("analyst_path", analyst_processor)
1333
+ ```
1334
+
1335
+ **Security Features:**
1336
+ - 🔐 **JWT Authentication**: Token-based authentication with refresh support
1337
+ - 👥 **Multi-Tenant Isolation**: Complete data separation between tenants
1338
+ - 🛡️ **Field-Level Security**: Mask sensitive data based on user roles
1339
+ - 📊 **Audit Logging**: Complete access attempt logging for compliance
1340
+ - 🚫 **Path Traversal Prevention**: Built-in protection against directory attacks
1341
+ - 🏗️ **Backward Compatibility**: Existing workflows work unchanged
1342
+ - ⚡ **Performance Optimized**: Minimal overhead with caching
1343
+
1105
1344
  ## 💻 CLI Commands
1106
1345
 
1107
1346
  The SDK includes a comprehensive CLI for workflow management:
@@ -1298,6 +1537,10 @@ pre-commit run pytest-check
1298
1537
  - Immutable state management
1299
1538
  - API integration with rate limiting
1300
1539
  - OAuth 2.0 authentication
1540
+ - Production security framework
1541
+ - Path traversal prevention
1542
+ - Code execution sandboxing
1543
+ - Comprehensive security testing
1301
1544
  - SharePoint Graph API integration
1302
1545
  - **Self-organizing agent pools with 13 specialized nodes**
1303
1546
  - **Agent-to-agent communication and shared memory**
@@ -1308,16 +1551,19 @@ pre-commit run pytest-check
1308
1551
  - **Performance visualization dashboards**
1309
1552
  - **Real-time monitoring dashboard with WebSocket streaming**
1310
1553
  - **Comprehensive performance reports (HTML, Markdown, JSON)**
1311
- - **89% test coverage (571 tests)**
1312
- - **15 test categories all passing**
1313
- - 37 working examples
1554
+ - **100% test coverage (591 tests)**
1555
+ - **All test categories passing**
1556
+ - 68 working examples
1314
1557
 
1315
1558
  </td>
1316
1559
  <td width="30%">
1317
1560
 
1318
1561
  ### 🚧 In Progress
1319
- - Comprehensive API documentation
1320
- - Security audit & hardening
1562
+ - **Kailash Workflow Studio** - Visual workflow builder UI
1563
+ - React-based drag-and-drop interface
1564
+ - Multi-tenant architecture with Docker
1565
+ - WorkflowStudioAPI backend
1566
+ - Real-time execution monitoring
1321
1567
  - Performance optimizations
1322
1568
  - Docker runtime finalization
1323
1569
 
@@ -1335,11 +1581,12 @@ pre-commit run pytest-check
1335
1581
  </table>
1336
1582
 
1337
1583
  ### 🎯 Test Suite Status
1338
- - **Total Tests**: 571 passing (89%)
1339
- - **Test Categories**: 15/15 at 100%
1340
- - **Integration Tests**: 65 passing
1341
- - **Examples**: 37/37 working
1342
- - **Code Coverage**: 89%
1584
+ - **Total Tests**: 591 passing (100%)
1585
+ - **Test Categories**: All passing
1586
+ - **Integration Tests**: All passing
1587
+ - **Security Tests**: 10 consolidated comprehensive tests
1588
+ - **Examples**: 68/68 working
1589
+ - **Code Coverage**: 100%
1343
1590
 
1344
1591
  ## ⚠️ Known Issues
1345
1592
 
@@ -6,7 +6,7 @@
6
6
  <a href="https://pepy.tech/project/kailash"><img src="https://static.pepy.tech/badge/kailash" alt="Downloads"></a>
7
7
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
8
8
  <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
9
- <img src="https://img.shields.io/badge/tests-753%20passing-brightgreen.svg" alt="Tests: 753 passing">
9
+ <img src="https://img.shields.io/badge/tests-734%20passing-brightgreen.svg" alt="Tests: 734 passing">
10
10
  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%">
11
11
  </p>
12
12
 
@@ -34,6 +34,11 @@
34
34
  - 🚪 **Multi-Workflow Gateway**: Manage multiple workflows through unified API with MCP integration
35
35
  - 🤖 **Self-Organizing Agents**: Autonomous agent pools with intelligent team formation and convergence detection
36
36
  - 🧠 **Agent-to-Agent Communication**: Shared memory pools and intelligent caching for coordinated multi-agent systems
37
+ - 🔒 **Production Security**: Comprehensive security framework with path traversal prevention, code sandboxing, and audit logging
38
+ - 🎨 **Visual Workflow Builder**: Kailash Workflow Studio - drag-and-drop interface for creating and managing workflows (coming soon)
39
+ - 🔁 **Cyclic Workflows (v0.2.0)**: Universal Hybrid Cyclic Graph Architecture with 30,000+ iterations/second performance
40
+ - 🛠️ **Developer Tools**: CycleAnalyzer, CycleDebugger, CycleProfiler for production-ready cyclic workflows
41
+ - 📈 **High Performance**: Optimized execution engine supporting 100,000+ iteration workflows
37
42
 
38
43
  ## 🎯 Who Is This For?
39
44
 
@@ -218,6 +223,141 @@ results, run_id = runtime.execute(workflow)
218
223
  print("RAG Response:", results["llm_agent"]["response"])
219
224
  ```
220
225
 
226
+ ### Cyclic Workflows - Iterative Processing with Convergence
227
+
228
+ Build workflows that iterate until a condition is met, perfect for optimization, retries, and ML training:
229
+
230
+ ```python
231
+ from kailash.workflow import Workflow
232
+ from kailash.nodes.base_cycle_aware import CycleAwareNode
233
+ from kailash.nodes.base import NodeParameter
234
+ from kailash.runtime.local import LocalRuntime
235
+ from typing import Any, Dict
236
+
237
+ # Create a custom cycle-aware node for data quality improvement
238
+ class DataQualityImproverNode(CycleAwareNode):
239
+ def get_parameters(self) -> Dict[str, NodeParameter]:
240
+ return {
241
+ "data": NodeParameter(name="data", type=list, required=True),
242
+ "target_quality": NodeParameter(name="target_quality", type=float, required=False, default=0.95)
243
+ }
244
+
245
+ def run(self, context: Dict[str, Any], **kwargs) -> Dict[str, Any]:
246
+ """Iteratively improve data quality."""
247
+ data = kwargs["data"]
248
+ target_quality = kwargs.get("target_quality", 0.95)
249
+
250
+ # Get current iteration and previous state
251
+ iteration = self.get_iteration(context)
252
+ prev_state = self.get_previous_state(context)
253
+
254
+ # Calculate current quality
255
+ quality = prev_state.get("quality", 0.5) + 0.1 # Improve by 10% each iteration
256
+ quality = min(quality, 1.0)
257
+
258
+ # Process data (simplified)
259
+ processed_data = [item for item in data if item is not None]
260
+
261
+ # Track quality history
262
+ quality_history = self.accumulate_values(context, "quality_history", quality, max_history=10)
263
+
264
+ # Detect convergence trend
265
+ trend = self.detect_convergence_trend(context, "quality_history", window_size=5)
266
+ converged = quality >= target_quality or (trend and trend["slope"] < 0.01)
267
+
268
+ # Log progress
269
+ self.log_cycle_info(context, f"Iteration {iteration}: Quality={quality:.2%}")
270
+
271
+ # Save state for next iteration
272
+ self.set_cycle_state({"quality": quality, "processed_count": len(processed_data)})
273
+
274
+ return {
275
+ "data": processed_data,
276
+ "quality": quality,
277
+ "converged": converged,
278
+ "iteration": iteration,
279
+ "history": quality_history
280
+ }
281
+
282
+ # Build cyclic workflow
283
+ workflow = Workflow("quality_improvement", "Iterative Data Quality")
284
+ workflow.add_node("improver", DataQualityImproverNode())
285
+
286
+ # Create a cycle - node connects to itself!
287
+ workflow.connect("improver", "improver",
288
+ mapping={"data": "data"}, # Pass data to next iteration
289
+ cycle=True, # This is a cycle
290
+ max_iterations=20, # Safety limit
291
+ convergence_check="converged == True") # Stop condition
292
+
293
+ # Execute with automatic iteration management
294
+ runtime = LocalRuntime()
295
+ results, run_id = runtime.execute(workflow, parameters={
296
+ "improver": {
297
+ "data": [1, None, 3, None, 5, 6, None, 8, 9, 10],
298
+ "target_quality": 0.9
299
+ }
300
+ })
301
+
302
+ print(f"Converged after {results['improver']['iteration']} iterations")
303
+ print(f"Final quality: {results['improver']['quality']:.2%}")
304
+ print(f"Quality history: {results['improver']['history']}")
305
+ ```
306
+
307
+ ### NEW in v0.2.0: CycleBuilder API
308
+
309
+ The new CycleBuilder API provides a fluent interface for creating cyclic workflows:
310
+
311
+ ```python
312
+ # Modern approach with CycleBuilder
313
+ workflow.create_cycle("optimization_loop")
314
+ .connect("gradient", "optimizer")
315
+ .connect("optimizer", "evaluator")
316
+ .connect("evaluator", "gradient")
317
+ .max_iterations(100)
318
+ .converge_when("loss < 0.01")
319
+ .early_stop_when("gradient_norm < 1e-6")
320
+ .checkpoint_every(10)
321
+ .build()
322
+
323
+ # Developer tools for production workflows
324
+ from kailash.workflow import CycleAnalyzer, CycleDebugger, CycleProfiler
325
+
326
+ # Analyze cycle patterns
327
+ analyzer = CycleAnalyzer(workflow)
328
+ report = analyzer.analyze()
329
+ print(f"Found {len(report.cycles)} cycles")
330
+ print(f"Max depth: {report.max_cycle_depth}")
331
+
332
+ # Debug with breakpoints
333
+ debugger = CycleDebugger(workflow)
334
+ debugger.set_breakpoint("optimizer", iteration=50)
335
+ debugger.set_trace("gradient_norm", lambda x: x < 0.001)
336
+
337
+ # Profile performance
338
+ profiler = CycleProfiler(workflow)
339
+ profile_data = profiler.profile(runtime, parameters)
340
+ print(f"Bottleneck: {profile_data.bottleneck_node}")
341
+ print(f"Iterations/sec: {profile_data.iterations_per_second}")
342
+ ```
343
+
344
+ #### Cyclic Workflow Features
345
+
346
+ - **Built-in Iteration Management**: No manual loops or recursion needed
347
+ - **State Persistence**: Maintain state across iterations with `get_previous_state()` and `set_cycle_state()`
348
+ - **Convergence Detection**: Automatic trend analysis with `detect_convergence_trend()`
349
+ - **Value Accumulation**: Track metrics over time with `accumulate_values()`
350
+ - **Safety Limits**: Max iterations prevent infinite loops
351
+ - **Performance**: Optimized execution with ~30,000 iterations/second
352
+ - **Developer Tools**: CycleAnalyzer, CycleDebugger, CycleProfiler for production workflows
353
+
354
+ Common cyclic patterns include:
355
+ - **Retry with Backoff**: ETL pipelines with automatic retry
356
+ - **Optimization Loops**: Iterative parameter tuning
357
+ - **ML Training**: Training until accuracy threshold
358
+ - **Polling**: API polling with rate limiting
359
+ - **Stream Processing**: Windowed data processing
360
+
221
361
  ### Workflow API Wrapper - Expose Workflows as REST APIs
222
362
 
223
363
  Transform any Kailash workflow into a production-ready REST API in just 3 lines of code:
@@ -1042,6 +1182,95 @@ This example demonstrates:
1042
1182
  - **Context formatting** for LLM input
1043
1183
  - **Answer generation** using Ollama's llama3.2 model
1044
1184
 
1185
+ ### 🔒 Access Control and Security
1186
+
1187
+ Kailash SDK provides comprehensive access control and security features for enterprise deployments:
1188
+
1189
+ #### Role-Based Access Control (RBAC)
1190
+ ```python
1191
+ from kailash.access_control import UserContext, PermissionRule, NodePermission
1192
+ from kailash.runtime.access_controlled import AccessControlledRuntime
1193
+
1194
+ # Define user with roles
1195
+ user = UserContext(
1196
+ user_id="analyst_001",
1197
+ tenant_id="company_abc",
1198
+ email="analyst@company.com",
1199
+ roles=["analyst", "viewer"]
1200
+ )
1201
+
1202
+ # Create secure runtime
1203
+ runtime = AccessControlledRuntime(user_context=user)
1204
+
1205
+ # Execute workflow with automatic permission checks
1206
+ results, run_id = runtime.execute(workflow, parameters={})
1207
+ ```
1208
+
1209
+ #### Multi-Tenant Isolation
1210
+ ```python
1211
+ from kailash.access_control import get_access_control_manager, PermissionEffect, WorkflowPermission
1212
+
1213
+ # Configure tenant-based access rules
1214
+ acm = get_access_control_manager()
1215
+ acm.enabled = True
1216
+
1217
+ # Tenant isolation rule
1218
+ acm.add_rule(PermissionRule(
1219
+ id="tenant_isolation",
1220
+ resource_type="workflow",
1221
+ resource_id="customer_analytics",
1222
+ permission=WorkflowPermission.EXECUTE,
1223
+ effect=PermissionEffect.ALLOW,
1224
+ tenant_id="company_abc" # Only this tenant can access
1225
+ ))
1226
+ ```
1227
+
1228
+ #### Data Masking and Field Protection
1229
+ ```python
1230
+ from kailash.nodes.base_with_acl import add_access_control
1231
+
1232
+ # Add access control to sensitive data nodes
1233
+ secure_reader = add_access_control(
1234
+ CSVReaderNode(file_path="customers.csv"),
1235
+ enable_access_control=True,
1236
+ required_permission=NodePermission.READ_OUTPUT,
1237
+ mask_output_fields=["ssn", "phone"] # Mask for non-admin users
1238
+ )
1239
+
1240
+ workflow.add_node("secure_data", secure_reader)
1241
+ ```
1242
+
1243
+ #### Permission-Based Routing
1244
+ ```python
1245
+ # Different execution paths based on user permissions
1246
+ from kailash.access_control import NodePermission
1247
+
1248
+ # Admin users get full processing
1249
+ admin_processor = PythonCodeNode.from_function(
1250
+ lambda data: {"result": process_all_data(data)},
1251
+ name="admin_processor"
1252
+ )
1253
+
1254
+ # Analyst users get limited processing
1255
+ analyst_processor = PythonCodeNode.from_function(
1256
+ lambda data: {"result": process_limited_data(data)},
1257
+ name="analyst_processor"
1258
+ )
1259
+
1260
+ # Runtime automatically routes based on user permissions
1261
+ workflow.add_node("admin_path", admin_processor)
1262
+ workflow.add_node("analyst_path", analyst_processor)
1263
+ ```
1264
+
1265
+ **Security Features:**
1266
+ - 🔐 **JWT Authentication**: Token-based authentication with refresh support
1267
+ - 👥 **Multi-Tenant Isolation**: Complete data separation between tenants
1268
+ - 🛡️ **Field-Level Security**: Mask sensitive data based on user roles
1269
+ - 📊 **Audit Logging**: Complete access attempt logging for compliance
1270
+ - 🚫 **Path Traversal Prevention**: Built-in protection against directory attacks
1271
+ - 🏗️ **Backward Compatibility**: Existing workflows work unchanged
1272
+ - ⚡ **Performance Optimized**: Minimal overhead with caching
1273
+
1045
1274
  ## 💻 CLI Commands
1046
1275
 
1047
1276
  The SDK includes a comprehensive CLI for workflow management:
@@ -1238,6 +1467,10 @@ pre-commit run pytest-check
1238
1467
  - Immutable state management
1239
1468
  - API integration with rate limiting
1240
1469
  - OAuth 2.0 authentication
1470
+ - Production security framework
1471
+ - Path traversal prevention
1472
+ - Code execution sandboxing
1473
+ - Comprehensive security testing
1241
1474
  - SharePoint Graph API integration
1242
1475
  - **Self-organizing agent pools with 13 specialized nodes**
1243
1476
  - **Agent-to-agent communication and shared memory**
@@ -1248,16 +1481,19 @@ pre-commit run pytest-check
1248
1481
  - **Performance visualization dashboards**
1249
1482
  - **Real-time monitoring dashboard with WebSocket streaming**
1250
1483
  - **Comprehensive performance reports (HTML, Markdown, JSON)**
1251
- - **89% test coverage (571 tests)**
1252
- - **15 test categories all passing**
1253
- - 37 working examples
1484
+ - **100% test coverage (591 tests)**
1485
+ - **All test categories passing**
1486
+ - 68 working examples
1254
1487
 
1255
1488
  </td>
1256
1489
  <td width="30%">
1257
1490
 
1258
1491
  ### 🚧 In Progress
1259
- - Comprehensive API documentation
1260
- - Security audit & hardening
1492
+ - **Kailash Workflow Studio** - Visual workflow builder UI
1493
+ - React-based drag-and-drop interface
1494
+ - Multi-tenant architecture with Docker
1495
+ - WorkflowStudioAPI backend
1496
+ - Real-time execution monitoring
1261
1497
  - Performance optimizations
1262
1498
  - Docker runtime finalization
1263
1499
 
@@ -1275,11 +1511,12 @@ pre-commit run pytest-check
1275
1511
  </table>
1276
1512
 
1277
1513
  ### 🎯 Test Suite Status
1278
- - **Total Tests**: 571 passing (89%)
1279
- - **Test Categories**: 15/15 at 100%
1280
- - **Integration Tests**: 65 passing
1281
- - **Examples**: 37/37 working
1282
- - **Code Coverage**: 89%
1514
+ - **Total Tests**: 591 passing (100%)
1515
+ - **Test Categories**: All passing
1516
+ - **Integration Tests**: All passing
1517
+ - **Security Tests**: 10 consolidated comprehensive tests
1518
+ - **Examples**: 68/68 working
1519
+ - **Code Coverage**: 100%
1283
1520
 
1284
1521
  ## ⚠️ Known Issues
1285
1522
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "kailash"
7
- version = "0.1.5"
7
+ version = "0.2.1"
8
8
  description = "Python SDK for the Kailash container-node architecture"
9
9
  authors = [
10
10
  {name = "Integrum", email = "info@integrum.com"}
@@ -51,6 +51,16 @@ dependencies = [
51
51
  "pre-commit>=4.2.0",
52
52
  "twine>=6.1.0",
53
53
  "ollama>=0.5.1",
54
+ "sqlalchemy>=2.0.0",
55
+ "psycopg2-binary>=2.9.0",
56
+ "pymysql>=1.1.0",
57
+ "aiosqlite>=0.19.0",
58
+ "websockets>=12.0",
59
+ "httpx>=0.25.0",
60
+ "python-jose>=3.5.0",
61
+ "pytest-xdist>=3.6.0",
62
+ "pytest-timeout>=2.3.0",
63
+ "pytest-split>=0.9.0",
54
64
  ]
55
65
 
56
66
  [project.optional-dependencies]
@@ -13,7 +13,7 @@ with open(os.path.join(this_directory, "README.md"), encoding="utf-8") as f:
13
13
  # Package configuration
14
14
  setup(
15
15
  name="kailash",
16
- version="0.1.4",
16
+ version="0.2.1",
17
17
  author="Integrum",
18
18
  author_email="info@integrum.com",
19
19
  description="Python SDK for the Kailash container-node architecture",
@@ -15,7 +15,7 @@ from kailash.workflow.visualization import WorkflowVisualizer
15
15
  # For backward compatibility
16
16
  WorkflowGraph = Workflow
17
17
 
18
- __version__ = "0.1.4"
18
+ __version__ = "0.2.0"
19
19
 
20
20
  __all__ = [
21
21
  "Workflow",