kailash 0.2.2__py3-none-any.whl โ†’ 0.3.1__py3-none-any.whl

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 (117) hide show
  1. kailash/__init__.py +1 -1
  2. kailash/access_control.py +40 -39
  3. kailash/api/auth.py +26 -32
  4. kailash/api/custom_nodes.py +29 -29
  5. kailash/api/custom_nodes_secure.py +35 -35
  6. kailash/api/database.py +17 -17
  7. kailash/api/gateway.py +19 -19
  8. kailash/api/mcp_integration.py +24 -23
  9. kailash/api/studio.py +45 -45
  10. kailash/api/workflow_api.py +8 -8
  11. kailash/cli/commands.py +5 -8
  12. kailash/manifest.py +42 -42
  13. kailash/mcp/__init__.py +1 -1
  14. kailash/mcp/ai_registry_server.py +20 -20
  15. kailash/mcp/client.py +9 -11
  16. kailash/mcp/client_new.py +10 -10
  17. kailash/mcp/server.py +1 -2
  18. kailash/mcp/server_enhanced.py +449 -0
  19. kailash/mcp/servers/ai_registry.py +6 -6
  20. kailash/mcp/utils/__init__.py +31 -0
  21. kailash/mcp/utils/cache.py +267 -0
  22. kailash/mcp/utils/config.py +263 -0
  23. kailash/mcp/utils/formatters.py +293 -0
  24. kailash/mcp/utils/metrics.py +418 -0
  25. kailash/nodes/ai/agents.py +9 -9
  26. kailash/nodes/ai/ai_providers.py +33 -34
  27. kailash/nodes/ai/embedding_generator.py +31 -32
  28. kailash/nodes/ai/intelligent_agent_orchestrator.py +62 -66
  29. kailash/nodes/ai/iterative_llm_agent.py +48 -48
  30. kailash/nodes/ai/llm_agent.py +32 -33
  31. kailash/nodes/ai/models.py +13 -13
  32. kailash/nodes/ai/self_organizing.py +44 -44
  33. kailash/nodes/api/__init__.py +5 -0
  34. kailash/nodes/api/auth.py +11 -11
  35. kailash/nodes/api/graphql.py +13 -13
  36. kailash/nodes/api/http.py +19 -19
  37. kailash/nodes/api/monitoring.py +463 -0
  38. kailash/nodes/api/rate_limiting.py +9 -13
  39. kailash/nodes/api/rest.py +29 -29
  40. kailash/nodes/api/security.py +819 -0
  41. kailash/nodes/base.py +24 -26
  42. kailash/nodes/base_async.py +7 -7
  43. kailash/nodes/base_cycle_aware.py +12 -12
  44. kailash/nodes/base_with_acl.py +5 -5
  45. kailash/nodes/code/python.py +56 -55
  46. kailash/nodes/data/__init__.py +6 -0
  47. kailash/nodes/data/directory.py +6 -6
  48. kailash/nodes/data/event_generation.py +297 -0
  49. kailash/nodes/data/file_discovery.py +598 -0
  50. kailash/nodes/data/readers.py +8 -8
  51. kailash/nodes/data/retrieval.py +10 -10
  52. kailash/nodes/data/sharepoint_graph.py +17 -17
  53. kailash/nodes/data/sources.py +5 -5
  54. kailash/nodes/data/sql.py +13 -13
  55. kailash/nodes/data/streaming.py +25 -25
  56. kailash/nodes/data/vector_db.py +22 -22
  57. kailash/nodes/data/writers.py +7 -7
  58. kailash/nodes/logic/async_operations.py +17 -17
  59. kailash/nodes/logic/convergence.py +11 -11
  60. kailash/nodes/logic/loop.py +4 -4
  61. kailash/nodes/logic/operations.py +11 -11
  62. kailash/nodes/logic/workflow.py +8 -9
  63. kailash/nodes/mixins/mcp.py +17 -17
  64. kailash/nodes/mixins.py +8 -10
  65. kailash/nodes/transform/chunkers.py +3 -3
  66. kailash/nodes/transform/formatters.py +7 -7
  67. kailash/nodes/transform/processors.py +11 -11
  68. kailash/runtime/access_controlled.py +18 -18
  69. kailash/runtime/async_local.py +18 -20
  70. kailash/runtime/docker.py +24 -26
  71. kailash/runtime/local.py +55 -31
  72. kailash/runtime/parallel.py +25 -25
  73. kailash/runtime/parallel_cyclic.py +29 -29
  74. kailash/runtime/runner.py +6 -6
  75. kailash/runtime/testing.py +22 -22
  76. kailash/sdk_exceptions.py +0 -58
  77. kailash/security.py +14 -26
  78. kailash/tracking/manager.py +38 -38
  79. kailash/tracking/metrics_collector.py +15 -14
  80. kailash/tracking/models.py +53 -53
  81. kailash/tracking/storage/base.py +7 -17
  82. kailash/tracking/storage/database.py +22 -23
  83. kailash/tracking/storage/filesystem.py +38 -40
  84. kailash/utils/export.py +21 -21
  85. kailash/utils/templates.py +8 -9
  86. kailash/visualization/api.py +30 -34
  87. kailash/visualization/dashboard.py +17 -17
  88. kailash/visualization/performance.py +32 -19
  89. kailash/visualization/reports.py +30 -28
  90. kailash/workflow/builder.py +8 -8
  91. kailash/workflow/convergence.py +13 -12
  92. kailash/workflow/cycle_analyzer.py +38 -33
  93. kailash/workflow/cycle_builder.py +12 -12
  94. kailash/workflow/cycle_config.py +16 -15
  95. kailash/workflow/cycle_debugger.py +40 -40
  96. kailash/workflow/cycle_exceptions.py +29 -29
  97. kailash/workflow/cycle_profiler.py +21 -21
  98. kailash/workflow/cycle_state.py +20 -22
  99. kailash/workflow/cyclic_runner.py +45 -45
  100. kailash/workflow/graph.py +57 -45
  101. kailash/workflow/mermaid_visualizer.py +9 -11
  102. kailash/workflow/migration.py +22 -22
  103. kailash/workflow/mock_registry.py +6 -6
  104. kailash/workflow/runner.py +9 -9
  105. kailash/workflow/safety.py +12 -13
  106. kailash/workflow/state.py +8 -11
  107. kailash/workflow/templates.py +19 -19
  108. kailash/workflow/validation.py +14 -14
  109. kailash/workflow/visualization.py +32 -24
  110. kailash-0.3.1.dist-info/METADATA +476 -0
  111. kailash-0.3.1.dist-info/RECORD +136 -0
  112. kailash-0.2.2.dist-info/METADATA +0 -121
  113. kailash-0.2.2.dist-info/RECORD +0 -126
  114. {kailash-0.2.2.dist-info โ†’ kailash-0.3.1.dist-info}/WHEEL +0 -0
  115. {kailash-0.2.2.dist-info โ†’ kailash-0.3.1.dist-info}/entry_points.txt +0 -0
  116. {kailash-0.2.2.dist-info โ†’ kailash-0.3.1.dist-info}/licenses/LICENSE +0 -0
  117. {kailash-0.2.2.dist-info โ†’ kailash-0.3.1.dist-info}/top_level.txt +0 -0
@@ -4,7 +4,7 @@ import matplotlib
4
4
 
5
5
  matplotlib.use("Agg") # Use non-interactive backend
6
6
  from pathlib import Path
7
- from typing import Any, Dict, List, Optional, Tuple
7
+ from typing import Any
8
8
 
9
9
  import matplotlib.pyplot as plt
10
10
  import networkx as nx
@@ -19,8 +19,8 @@ class WorkflowVisualizer:
19
19
  def __init__(
20
20
  self,
21
21
  workflow: Workflow,
22
- node_colors: Optional[Dict[str, str]] = None,
23
- edge_colors: Optional[Dict[str, str]] = None,
22
+ node_colors: dict[str, str] | None = None,
23
+ edge_colors: dict[str, str] | None = None,
24
24
  layout: str = "hierarchical",
25
25
  ):
26
26
  """Initialize visualizer.
@@ -36,7 +36,7 @@ class WorkflowVisualizer:
36
36
  self.edge_colors = edge_colors or self._default_edge_colors()
37
37
  self.layout = layout
38
38
 
39
- def _default_node_colors(self) -> Dict[str, str]:
39
+ def _default_node_colors(self) -> dict[str, str]:
40
40
  """Get default node color map."""
41
41
  return {
42
42
  "data": "lightblue",
@@ -46,7 +46,7 @@ class WorkflowVisualizer:
46
46
  "default": "lightgray",
47
47
  }
48
48
 
49
- def _default_edge_colors(self) -> Dict[str, str]:
49
+ def _default_edge_colors(self) -> dict[str, str]:
50
50
  """Get default edge color map."""
51
51
  return {"default": "gray", "error": "red", "conditional": "orange"}
52
52
 
@@ -66,7 +66,7 @@ class WorkflowVisualizer:
66
66
  return self.node_colors["ai"]
67
67
  return self.node_colors["default"]
68
68
 
69
- def _get_node_colors(self) -> List[str]:
69
+ def _get_node_colors(self) -> list[str]:
70
70
  """Get colors for all nodes in workflow."""
71
71
  colors = []
72
72
  for node_id in self.workflow.graph.nodes():
@@ -75,7 +75,7 @@ class WorkflowVisualizer:
75
75
  colors.append(self._get_node_color(node_type))
76
76
  return colors
77
77
 
78
- def _get_node_labels(self) -> Dict[str, str]:
78
+ def _get_node_labels(self) -> dict[str, str]:
79
79
  """Get labels for nodes in workflow."""
80
80
  labels = {}
81
81
  for node_id in self.workflow.graph.nodes():
@@ -93,7 +93,7 @@ class WorkflowVisualizer:
93
93
  labels[node_id] = node_id
94
94
  return labels
95
95
 
96
- def _get_edge_labels(self) -> Dict[Tuple[str, str], str]:
96
+ def _get_edge_labels(self) -> dict[tuple[str, str], str]:
97
97
  """Get labels for edges in workflow."""
98
98
  edge_labels = {}
99
99
 
@@ -119,7 +119,7 @@ class WorkflowVisualizer:
119
119
 
120
120
  return edge_labels
121
121
 
122
- def _calculate_layout(self) -> Dict[str, Tuple[float, float]]:
122
+ def _calculate_layout(self) -> dict[str, tuple[float, float]]:
123
123
  """Calculate node positions for visualization."""
124
124
  # Try to use stored positions first
125
125
  pos = {}
@@ -148,7 +148,7 @@ class WorkflowVisualizer:
148
148
 
149
149
  return pos
150
150
 
151
- def _create_layers(self) -> Dict[int, list]:
151
+ def _create_layers(self) -> dict[int, list]:
152
152
  """Create layers of nodes for hierarchical layout."""
153
153
  layers = {}
154
154
  remaining = set(self.workflow.graph.nodes())
@@ -173,8 +173,8 @@ class WorkflowVisualizer:
173
173
  return layers
174
174
 
175
175
  def _hierarchical_layout(
176
- self, layers: Dict[int, list]
177
- ) -> Dict[str, Tuple[float, float]]:
176
+ self, layers: dict[int, list]
177
+ ) -> dict[str, tuple[float, float]]:
178
178
  """Create hierarchical layout from layers."""
179
179
  pos = {}
180
180
  layer_height = 2.0
@@ -196,8 +196,8 @@ class WorkflowVisualizer:
196
196
 
197
197
  def _draw_graph(
198
198
  self,
199
- pos: Dict[str, Tuple[float, float]],
200
- node_colors: List[str],
199
+ pos: dict[str, tuple[float, float]],
200
+ node_colors: list[str],
201
201
  show_labels: bool,
202
202
  show_connections: bool,
203
203
  ) -> None:
@@ -235,9 +235,9 @@ class WorkflowVisualizer:
235
235
 
236
236
  def visualize(
237
237
  self,
238
- output_path: Optional[str] = None,
239
- figsize: Tuple[int, int] = (12, 8),
240
- title: Optional[str] = None,
238
+ output_path: str | None = None,
239
+ figsize: tuple[int, int] = (12, 8),
240
+ title: str | None = None,
241
241
  show_labels: bool = True,
242
242
  show_connections: bool = True,
243
243
  dpi: int = 300,
@@ -303,7 +303,7 @@ class WorkflowVisualizer:
303
303
  self.visualize(output_path=output_path, **kwargs)
304
304
 
305
305
  def create_execution_graph(
306
- self, run_id: str, task_manager: Any, output_path: Optional[str] = None
306
+ self, run_id: str, task_manager: Any, output_path: str | None = None
307
307
  ) -> str:
308
308
  """Create a Mermaid visualization showing execution status.
309
309
 
@@ -399,8 +399,16 @@ class WorkflowVisualizer:
399
399
 
400
400
  # Determine output path
401
401
  if output_path is None:
402
- # Create default directory if it doesn't exist
403
- output_dir = Path.cwd() / "outputs" / "workflow_executions"
402
+ # Use centralized output directory
403
+ # Get project root and use data/outputs/visualizations
404
+ project_root = Path(__file__).parent.parent.parent.parent
405
+ output_dir = (
406
+ project_root
407
+ / "data"
408
+ / "outputs"
409
+ / "visualizations"
410
+ / "workflow_executions"
411
+ )
404
412
  output_dir.mkdir(parents=True, exist_ok=True)
405
413
  output_path = output_dir / f"execution_{run_id}.md"
406
414
  else:
@@ -415,8 +423,8 @@ class WorkflowVisualizer:
415
423
  return str(output_path)
416
424
 
417
425
  def create_performance_dashboard(
418
- self, run_id: str, task_manager: TaskManager, output_dir: Optional[Path] = None
419
- ) -> Dict[str, Path]:
426
+ self, run_id: str, task_manager: TaskManager, output_dir: Path | None = None
427
+ ) -> dict[str, Path]:
420
428
  """Create integrated performance dashboard with workflow visualization.
421
429
 
422
430
  Args:
@@ -453,7 +461,7 @@ class WorkflowVisualizer:
453
461
  return outputs
454
462
 
455
463
  def _create_dashboard_html(
456
- self, run_id: str, outputs: Dict[str, Path], dashboard_path: Path
464
+ self, run_id: str, outputs: dict[str, Path], dashboard_path: Path
457
465
  ) -> None:
458
466
  """Create HTML dashboard integrating all visualizations."""
459
467
  html_content = f"""
@@ -570,7 +578,7 @@ class WorkflowVisualizer:
570
578
  def add_visualization_to_workflow():
571
579
  """Add visualization method to Workflow class."""
572
580
 
573
- def visualize(self, output_path: Optional[str] = None, **kwargs) -> None:
581
+ def visualize(self, output_path: str | None = None, **kwargs) -> None:
574
582
  """Visualize the workflow.
575
583
 
576
584
  Args:
@@ -0,0 +1,476 @@
1
+ Metadata-Version: 2.4
2
+ Name: kailash
3
+ Version: 0.3.1
4
+ Summary: Python SDK for the Kailash container-node architecture
5
+ Home-page: https://github.com/integrum/kailash-python-sdk
6
+ Author: Integrum
7
+ Author-email: Integrum <info@integrum.com>
8
+ Project-URL: Homepage, https://github.com/integrum/kailash-python-sdk
9
+ Project-URL: Bug Tracker, https://github.com/integrum/kailash-python-sdk/issues
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Requires-Python: >=3.11
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: networkx>=2.7
19
+ Requires-Dist: pydantic>=1.9
20
+ Requires-Dist: matplotlib>=3.5
21
+ Requires-Dist: pyyaml>=6.0
22
+ Requires-Dist: click>=8.0
23
+ Requires-Dist: pytest>=8.3.5
24
+ Requires-Dist: mcp[cli]>=1.9.2
25
+ Requires-Dist: pandas>=2.2.3
26
+ Requires-Dist: numpy>=2.2.5
27
+ Requires-Dist: scipy>=1.15.3
28
+ Requires-Dist: scikit-learn>=1.6.1
29
+ Requires-Dist: requests>=2.32.3
30
+ Requires-Dist: pytest-cov>=6.1.1
31
+ Requires-Dist: isort>=6.0.1
32
+ Requires-Dist: aiohttp>=3.12.4
33
+ Requires-Dist: ruff>=0.11.12
34
+ Requires-Dist: msal>=1.32.3
35
+ Requires-Dist: sphinx>=8.2.3
36
+ Requires-Dist: sphinx-rtd-theme>=3.0.2
37
+ Requires-Dist: sphinx-copybutton>=0.5.2
38
+ Requires-Dist: sphinxcontrib-mermaid>=1.0.0
39
+ Requires-Dist: sphinx-autobuild>=2024.10.3
40
+ Requires-Dist: autodoc>=0.5.0
41
+ Requires-Dist: myst-parser>=4.0.1
42
+ Requires-Dist: black>=25.1.0
43
+ Requires-Dist: psutil>=7.0.0
44
+ Requires-Dist: fastapi>=0.115.12
45
+ Requires-Dist: uvicorn[standard]>=0.31.0
46
+ Requires-Dist: pytest-asyncio>=1.0.0
47
+ Requires-Dist: pre-commit>=4.2.0
48
+ Requires-Dist: twine>=6.1.0
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
60
+ Provides-Extra: dev
61
+ Requires-Dist: pytest>=7.0; extra == "dev"
62
+ Requires-Dist: pytest-cov>=3.0; extra == "dev"
63
+ Requires-Dist: black>=22.0; extra == "dev"
64
+ Requires-Dist: isort>=5.10; extra == "dev"
65
+ Requires-Dist: mypy>=0.9; extra == "dev"
66
+ Dynamic: author
67
+ Dynamic: home-page
68
+ Dynamic: license-file
69
+ Dynamic: requires-python
70
+
71
+ # Kailash Python SDK
72
+
73
+ <p align="center">
74
+ <a href="https://pypi.org/project/kailash/"><img src="https://img.shields.io/pypi/v/kailash.svg" alt="PyPI version"></a>
75
+ <a href="https://pypi.org/project/kailash/"><img src="https://img.shields.io/pypi/pyversions/kailash.svg" alt="Python versions"></a>
76
+ <a href="https://pepy.tech/project/kailash"><img src="https://static.pepy.tech/badge/kailash" alt="Downloads"></a>
77
+ <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
78
+ <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
79
+ <img src="https://img.shields.io/badge/tests-751%20passing-brightgreen.svg" alt="Tests: 751 passing">
80
+ <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%">
81
+ </p>
82
+
83
+ <p align="center">
84
+ <strong>A Pythonic SDK for the Kailash container-node architecture</strong>
85
+ </p>
86
+
87
+ <p align="center">
88
+ Build workflows that seamlessly integrate with Kailash's production environment while maintaining the flexibility to prototype quickly and iterate locally.
89
+ </p>
90
+
91
+ ---
92
+
93
+ ## โœจ Highlights
94
+
95
+ - ๐Ÿš€ **Rapid Prototyping**: Create and test workflows locally without containerization
96
+ - ๐Ÿ—๏ธ **Architecture-Aligned**: Automatically ensures compliance with Kailash standards
97
+ - ๐Ÿ”„ **Seamless Handoff**: Export prototypes directly to production-ready formats
98
+ - ๐Ÿ“Š **Real-time Monitoring**: Live dashboards with WebSocket streaming and performance metrics
99
+ - ๐Ÿงฉ **Extensible**: Easy to create custom nodes for domain-specific operations
100
+ - โšก **Fast Installation**: Uses `uv` for lightning-fast Python package management
101
+ - ๐Ÿค– **AI-Powered**: Complete LLM agents, embeddings, and hierarchical RAG architecture
102
+ - ๐Ÿง  **Retrieval-Augmented Generation**: Full RAG pipeline with intelligent document processing
103
+ - ๐ŸŒ **REST API Wrapper**: Expose any workflow as a production-ready API in 3 lines
104
+ - ๐Ÿšช **Multi-Workflow Gateway**: Manage multiple workflows through unified API with MCP integration
105
+ - ๐Ÿค– **Self-Organizing Agents**: Autonomous agent pools with intelligent team formation and convergence detection
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
112
+ - ๐Ÿ“ **Complete Finance Workflow Library (v0.3.1)**: Production-ready financial workflows with AI analysis
113
+ - ๐Ÿ’ผ **Enterprise Workflow Patterns**: Credit risk, portfolio optimization, trading signals, fraud detection
114
+
115
+ ## ๐ŸŽฏ Who Is This For?
116
+
117
+ The Kailash Python SDK is designed for:
118
+
119
+ - **AI Business Coaches (ABCs)** who need to prototype workflows quickly
120
+ - **Data Scientists** building ML pipelines compatible with production infrastructure
121
+ - **Engineers** who want to test Kailash workflows locally before deployment
122
+ - **Teams** looking to standardize their workflow development process
123
+
124
+ ## ๐Ÿš€ Quick Start
125
+
126
+ ### Installation
127
+
128
+ **Requirements:** Python 3.11 or higher
129
+
130
+ ```bash
131
+ # Install uv if you haven't already
132
+ curl -LsSf https://astral.sh/uv/install.sh | sh
133
+
134
+ # For users: Install from PyPI
135
+ pip install kailash
136
+
137
+ # For developers: Clone and sync
138
+ git clone https://github.com/integrum/kailash-python-sdk.git
139
+ cd kailash-python-sdk
140
+ uv sync
141
+
142
+ # Set up SDK development infrastructure (optional but recommended)
143
+ ./scripts/setup-sdk-environment.sh
144
+ ```
145
+
146
+ ### Your First Workflow
147
+
148
+ ```python
149
+ from kailash.workflow import Workflow
150
+ from kailash.nodes.data import CSVReaderNode
151
+ from kailash.nodes.code import PythonCodeNode
152
+ from kailash.runtime.local import LocalRuntime
153
+ import pandas as pd
154
+
155
+ # Create a workflow
156
+ workflow = Workflow("customer_analysis", name="customer_analysis")
157
+
158
+ # Add data reader
159
+ reader = CSVReaderNode(file_path="customers.csv")
160
+ workflow.add_node("read_customers", reader)
161
+
162
+ # Add custom processing using Python code
163
+ def analyze_customers(data):
164
+ """Analyze customer data and compute metrics."""
165
+ df = pd.DataFrame(data)
166
+ # Convert total_spent to numeric
167
+ df['total_spent'] = pd.to_numeric(df['total_spent'])
168
+ return {
169
+ "result": {
170
+ "total_customers": len(df),
171
+ "avg_spend": df["total_spent"].mean(),
172
+ "top_customers": df.nlargest(10, "total_spent").to_dict("records")
173
+ }
174
+ }
175
+
176
+ processor = PythonCodeNode(code=analyze_customers)
177
+ workflow.add_node("analyze", processor)
178
+
179
+ # Connect nodes
180
+ workflow.connect("read_customers", "analyze", mapping={"data": "data"})
181
+
182
+ # Run locally
183
+ runtime = LocalRuntime()
184
+ results, run_id = runtime.execute(workflow, parameters={
185
+ "read_customers": {"file_path": "customers.csv"}
186
+ })
187
+
188
+ print(f"Total customers: {results['analyze']['result']['total_customers']}")
189
+ print(f"Average spend: ${results['analyze']['result']['avg_spend']:.2f}")
190
+ ```
191
+
192
+ ### Export to Production
193
+
194
+ ```python
195
+ # Export to Kailash container format
196
+ from kailash.utils.export import export_workflow
197
+
198
+ export_workflow(workflow, "customer_analysis.yaml")
199
+ ```
200
+
201
+ ## ๐Ÿ’ผ Finance Workflow Library (New in v0.3.1)
202
+
203
+ Complete production-ready financial workflows using AI and modern quantitative methods:
204
+
205
+ ### Credit Risk Assessment
206
+
207
+ ```python
208
+ from kailash.workflow import Workflow
209
+ from kailash.nodes.data import CSVReaderNode
210
+ from kailash.nodes.code import PythonCodeNode
211
+ from kailash.nodes.ai import LLMAgentNode
212
+
213
+ def calculate_risk_metrics(customers, transactions):
214
+ """Calculate comprehensive risk metrics."""
215
+ # Modern risk scoring with AI analysis
216
+ # 100+ lines of production risk calculation
217
+ return {"result": risk_scores}
218
+
219
+ workflow = Workflow("credit-risk", "Credit Risk Assessment")
220
+ workflow.add_node("customer_reader", CSVReaderNode())
221
+ workflow.add_node("risk_calculator", PythonCodeNode.from_function(func=calculate_risk_metrics))
222
+ workflow.add_node("ai_analyzer", LLMAgentNode(model="gpt-4",
223
+ system_prompt="You are a financial risk expert..."))
224
+ ```
225
+
226
+ ### Portfolio Optimization
227
+
228
+ ```python
229
+ def optimize_portfolio(holdings, market_data, risk_profile="moderate"):
230
+ """Modern Portfolio Theory optimization with rebalancing."""
231
+ # Sharpe ratio optimization, correlation analysis
232
+ # Risk-adjusted returns with AI market insights
233
+ return {"result": optimization_plan}
234
+
235
+ workflow = Workflow("portfolio-opt", "Portfolio Optimization")
236
+ workflow.add_node("optimizer", PythonCodeNode.from_function(func=optimize_portfolio))
237
+ # Generates rebalancing trades, risk metrics, AI market analysis
238
+ ```
239
+
240
+ ### Trading Signals & Fraud Detection
241
+
242
+ - **Trading Signals**: Technical indicators (RSI, MACD, Bollinger Bands) + AI sentiment
243
+ - **Fraud Detection**: Real-time transaction monitoring with velocity analysis
244
+
245
+ **See complete examples**: `sdk-users/workflows/by-industry/finance/`
246
+
247
+ ## ๐Ÿ“š Documentation
248
+
249
+ ### For SDK Users
250
+
251
+ **Build solutions with the SDK:**
252
+ - `sdk-users/` - Everything you need to build with Kailash
253
+ - `developer/` - Node creation patterns and troubleshooting
254
+ - `workflows/` - Complete production workflow library (v0.3.1)
255
+ - Finance workflows: Credit risk, portfolio optimization, trading signals, fraud detection
256
+ - Quick-start patterns (30-second workflows)
257
+ - Industry-specific solutions by vertical
258
+ - Enterprise integration patterns
259
+ - `essentials/` - Quick reference and cheatsheets
260
+ - `nodes/` - Comprehensive node catalog (66+ nodes)
261
+ - `patterns/` - Architectural patterns
262
+
263
+ ### For SDK Contributors
264
+
265
+ **Develop the SDK itself:**
266
+ - `sdk-contributors/` - Internal SDK development resources
267
+ - `architecture/` - ADRs and design decisions
268
+ - `project/` - TODOs and development tracking
269
+ - `training/` - LLM training examples
270
+
271
+ ### Shared Resources
272
+
273
+ - `shared/` - Resources for both users and contributors
274
+ - `mistakes/` - Common error patterns and solutions
275
+ - `frontend/` - UI development resources
276
+
277
+ ### Quick Links
278
+
279
+ - [SDK User Guide](sdk-users/README.md) - Build with the SDK
280
+ - [SDK Contributor Guide](sdk-contributors/README.md) - Develop the SDK
281
+ - [API Documentation](https://integrum.github.io/kailash-python-sdk)
282
+ - [Examples](examples/)
283
+ - [Release Notes](CHANGELOG.md)
284
+
285
+ ## ๐Ÿ”ฅ Advanced Features
286
+
287
+ ### Cyclic Workflows (Enhanced in v0.2.2)
288
+
289
+ Build iterative workflows with the new CycleBuilder API:
290
+
291
+ ```python
292
+ # Create an optimization cycle
293
+ workflow.create_cycle("optimization_loop")
294
+ .connect("processor", "processor")
295
+ .max_iterations(100)
296
+ .converge_when("quality >= 0.95")
297
+ .timeout(30)
298
+ .build()
299
+ ```
300
+
301
+ ### Self-Organizing Agent Pools
302
+
303
+ Create teams of AI agents that autonomously coordinate:
304
+
305
+ ```python
306
+ from kailash.nodes.ai import SelfOrganizingAgentPoolNode
307
+
308
+ agent_pool = SelfOrganizingAgentPoolNode(
309
+ formation_strategy="capability_matching",
310
+ convergence_strategy="quality_voting",
311
+ min_agents=3,
312
+ max_agents=10
313
+ )
314
+ workflow.add_node("agent_team", agent_pool)
315
+ ```
316
+
317
+ ### Hierarchical RAG Pipeline
318
+
319
+ Build sophisticated document processing systems:
320
+
321
+ ```python
322
+ from kailash.nodes.data import DocumentSourceNode, HierarchicalChunkerNode
323
+ from kailash.nodes.ai import EmbeddingGeneratorNode
324
+
325
+ # Build a complete RAG pipeline
326
+ workflow.add_node("docs", DocumentSourceNode(directory="./knowledge"))
327
+ workflow.add_node("chunker", HierarchicalChunkerNode(chunk_size=512))
328
+ workflow.add_node("embedder", EmbeddingGeneratorNode(provider="openai"))
329
+ ```
330
+
331
+ ### REST API Wrapper
332
+
333
+ Transform any workflow into a production API:
334
+
335
+ ```python
336
+ from kailash.api import WorkflowAPI
337
+
338
+ # Create API from workflow
339
+ api = WorkflowAPI(workflow, host="0.0.0.0", port=8000)
340
+ api.run()
341
+
342
+ # Your workflow is now available at:
343
+ # POST http://localhost:8000/execute
344
+ # GET http://localhost:8000/workflow/info
345
+ ```
346
+
347
+ ## ๐Ÿ—๏ธ Key Components
348
+
349
+ ### Nodes (60+ built-in)
350
+
351
+ - **Data**: CSVReaderNode, JSONReaderNode, SQLDatabaseNode, DirectoryReaderNode
352
+ - **Transform**: DataTransformer, DataFrameFilter, DataFrameJoiner
353
+ - **AI/ML**: LLMAgentNode, EmbeddingGeneratorNode, A2ACoordinatorNode
354
+ - **API**: RESTClientNode, GraphQLNode, AuthNode
355
+ - **Logic**: SwitchNode, MergeNode, ConvergenceCheckerNode
356
+ - **Code**: PythonCodeNode, WorkflowNode
357
+
358
+ ### Runtimes
359
+
360
+ - **LocalRuntime**: Test workflows on your machine
361
+ - **DockerRuntime**: Run in containers (coming soon)
362
+ - **ParallelRuntime**: Execute nodes concurrently
363
+ - **CyclicWorkflowExecutor**: Optimized for iterative workflows
364
+
365
+ ### Visualization
366
+
367
+ - **Mermaid diagrams**: Workflow structure visualization
368
+ - **Real-time dashboard**: Monitor execution with WebSocket streaming
369
+ - **Performance metrics**: Track execution time, resource usage
370
+
371
+ ## ๐Ÿงช Testing Your Workflows
372
+
373
+ ```python
374
+ # Use the testing runtime for unit tests
375
+ from kailash.runtime.testing import TestingRuntime
376
+
377
+ runtime = TestingRuntime()
378
+ runtime.set_mock_result("read_customers", {"data": test_data})
379
+ results, run_id = runtime.execute(workflow)
380
+ assert results["analyze"]["result"]["total_customers"] == len(test_data)
381
+ ```
382
+
383
+ ## ๐Ÿšข Production Deployment
384
+
385
+ 1. **Export your workflow**:
386
+ ```python
387
+ export_workflow(workflow, "workflow.yaml", format="kailash")
388
+ ```
389
+
390
+ 2. **Deploy to Kailash**:
391
+ ```bash
392
+ kailash deploy workflow.yaml --environment production
393
+ ```
394
+
395
+ 3. **Monitor in real-time**:
396
+ ```python
397
+ from kailash.visualization import DashboardServer
398
+
399
+ server = DashboardServer(port=8080)
400
+ server.start()
401
+ # Open http://localhost:8080 for live monitoring
402
+ ```
403
+
404
+ ## ๐Ÿค Contributing
405
+
406
+ We welcome contributions! We use a **Claude Code-driven workflow** for all team collaboration.
407
+
408
+ ### ๐Ÿš€ New Team Member?
409
+ **Start Here โ†’ [NEW_TEAM_MEMBER.md](NEW_TEAM_MEMBER.md)**
410
+
411
+ ### For Contributors
412
+ - **SDK Users**: See [sdk-users/CLAUDE.md](sdk-users/CLAUDE.md) for building with the SDK
413
+ - **SDK Contributors**: See [sdk-contributors/CLAUDE.md](sdk-contributors/CLAUDE.md) for SDK development
414
+ - **Team Collaboration**: Use [Claude Code Workflow System](sdk-contributors/operations/claude-code-workflows/) for all project management
415
+
416
+ ### Claude Code Workflow
417
+ All project management is done through conversational interaction with Claude Code:
418
+ - **No manual TODO editing** - Claude Code handles all updates
419
+ - **No direct GitHub issues** - Created through planning sessions
420
+ - **All progress tracked** - Through natural conversation
421
+
422
+ See [Contributing Guide](CONTRIBUTING.md) for complete details.
423
+
424
+ ### Development Setup
425
+
426
+ ```bash
427
+ # Clone the repository
428
+ git clone https://github.com/integrum/kailash-python-sdk.git
429
+ cd kailash-python-sdk
430
+
431
+ # Install with development dependencies
432
+ uv sync
433
+
434
+ # Run tests
435
+ pytest
436
+
437
+ # Run linting
438
+ black .
439
+ isort .
440
+ ruff check .
441
+
442
+ # Test all examples
443
+ python scripts/test-all-examples.py
444
+ ```
445
+
446
+ ## ๐Ÿ“ˆ Project Status
447
+
448
+ - โœ… Core workflow engine
449
+ - โœ… 60+ production-ready nodes
450
+ - โœ… Local and parallel runtimes
451
+ - โœ… Export to container format
452
+ - โœ… Real-time monitoring
453
+ - โœ… Comprehensive test suite (751 tests)
454
+ - โœ… Self-organizing agent systems
455
+ - โœ… Hierarchical RAG architecture
456
+ - โœ… REST API wrapper
457
+ - โœ… Cyclic workflow support with CycleBuilder API
458
+ - โœ… Production security framework
459
+ - โœ… Comprehensive workflow library (v0.2.2)
460
+ - ๐Ÿšง Visual workflow builder (in progress)
461
+ - ๐Ÿšง Docker runtime
462
+ - ๐Ÿšง Cloud deployment tools
463
+
464
+ ## ๐Ÿ“„ License
465
+
466
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
467
+
468
+ ## ๐Ÿ™ Acknowledgments
469
+
470
+ Built with โค๏ธ by the Integrum team for the Kailash ecosystem.
471
+
472
+ ---
473
+
474
+ <p align="center">
475
+ <strong>Ready to build your first workflow? Check out our <a href="examples/">examples</a> or dive into the <a href="sdk-users/README.md">documentation</a>!</strong>
476
+ </p>