kailash 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

kailash/nodes/data/readers.py

@@ -12,9 +12,9 @@ Design Philosophy:
 5. Type-safe parameter validation
 
 Node Categories:
-- CSVReader: Tabular data from CSV files
-- JSONReader: Structured data from JSON files
-- TextReader: Raw text from any text file
+- CSVReaderNode: Tabular data from CSV files
+- JSONReaderNode: Structured data from JSON files
+- TextReaderNode: Raw text from any text file
 
 Upstream Components:
 - FileSystem: Provides files to read
@@ -36,61 +36,113 @@ from kailash.nodes.base import Node, NodeParameter, register_node
 
 
 @register_node()
-class CSVReader(Node):
-    """Reads data from a CSV file.
-
-    This node provides robust CSV file reading capabilities with support for
-    various delimiters, header detection, and encoding options. It's designed
-    to handle common CSV formats and edge cases.
-
-    Design Features:
-    1. Automatic header detection
-    2. Configurable delimiters
-    3. Memory-efficient line-by-line reading
-    4. Consistent dictionary output format
-    5. Unicode support through encoding parameter
-
-    Data Flow:
-    - Input: File path and configuration parameters
-    - Processing: Reads CSV line by line, converting to dictionaries
-    - Output: List of dictionaries (with headers) or list of lists
-
-    Common Usage Patterns:
-    1. Reading data exports from databases
-    2. Processing spreadsheet data
-    3. Loading configuration from CSV
-    4. Ingesting sensor data logs
-
-    Upstream Sources:
-    - File system paths from user input
-    - Output paths from previous nodes
-    - Configuration management systems
+class CSVReaderNode(Node):
+    """
+    Reads data from CSV files with automatic header detection and type inference.
+
+    This node provides comprehensive CSV file reading capabilities, handling various
+    formats, encodings, and edge cases. It automatically detects headers, infers data
+    types, and provides consistent structured output for downstream processing in
+    Kailash workflows.
+
+    Design Philosophy:
+        The CSVReaderNode embodies the principle of "data accessibility without
+        complexity." It abstracts the intricacies of CSV parsing while providing
+        flexibility for various formats. The design prioritizes memory efficiency,
+        automatic format detection, and consistent output structure, making it easy
+        to integrate diverse CSV data sources into workflows.
+
+    Upstream Dependencies:
+        - File system providing CSV files
+        - Workflow orchestrators specifying file paths
+        - Configuration systems providing parsing options
+        - Previous nodes generating CSV file paths
+        - User inputs defining data sources
 
     Downstream Consumers:
-    - DataTransformer: Processes tabular data
-    - Aggregator: Summarizes data
-    - CSVWriter: Reformats and saves
-    - Visualizer: Creates charts from data
+        - DataTransformNode: Processes tabular data
+        - FilterNode: Applies row/column filtering
+        - AggregatorNode: Summarizes data
+        - PythonCodeNode: Custom data processing
+        - WriterNodes: Exports to other formats
+        - Visualization nodes: Creates charts
+        - ML nodes: Uses as training data
+
+    Configuration:
+        The node supports extensive CSV parsing options:
+        - Delimiter detection (comma, tab, pipe, etc.)
+        - Header row identification
+        - Encoding specification (UTF-8, Latin-1, etc.)
+        - Quote character handling
+        - Skip rows/comments functionality
+        - Column type inference
+        - Missing value handling
+
+    Implementation Details:
+        - Uses Python's csv module for robust parsing
+        - Implements streaming for large files
+        - Automatic delimiter detection when not specified
+        - Header detection based on first row analysis
+        - Type inference for numeric/date columns
+        - Memory-efficient processing with generators
+        - Unicode normalization for consistent encoding
 
     Error Handling:
-    - FileNotFoundError: Invalid file path
-    - PermissionError: Insufficient read permissions
-    - UnicodeDecodeError: Encoding mismatch
-    - csv.Error: Malformed CSV data
-
-    Example::
-
-        # Read customer data with headers
-        reader = CSVReader(
-            file_path='customers.csv',
-            headers=True,
-            delimiter=','
-        )
-        result = reader.execute()
-        # result['data'] = [
-        #     {'id': '1', 'name': 'John', 'age': '30'},
-        #     {'id': '2', 'name': 'Jane', 'age': '25'}
-        # ]
+        - FileNotFoundError: Clear message with path
+        - PermissionError: Access rights guidance
+        - UnicodeDecodeError: Encoding detection hints
+        - csv.Error: Malformed data diagnostics
+        - EmptyFileError: Handles zero-byte files
+        - Partial read recovery for corrupted files
+
+    Side Effects:
+        - Reads from file system
+        - May consume significant memory for large files
+        - Creates file handles (properly closed)
+        - Updates internal read statistics
+
+    Examples:
+        >>> # Basic CSV reading with headers
+        >>> reader = CSVReaderNode()
+        >>> result = reader.run(
+        ...     file_path="customers.csv",
+        ...     headers=True
+        ... )
+        >>> assert isinstance(result["data"], list)
+        >>> assert all(isinstance(row, dict) for row in result["data"])
+        >>> # Example output:
+        >>> # result["data"] = [
+        >>> #     {"id": "1", "name": "John Doe", "age": "30"},
+        >>> #     {"id": "2", "name": "Jane Smith", "age": "25"}
+        >>> # ]
+        >>>
+        >>> # Reading with custom delimiter
+        >>> result = reader.run(
+        ...     file_path="data.tsv",
+        ...     delimiter="\\t",
+        ...     headers=True
+        ... )
+        >>>
+        >>> # Reading without headers (returns list of lists)
+        >>> result = reader.run(
+        ...     file_path="data.csv",
+        ...     headers=False
+        ... )
+        >>> assert all(isinstance(row, list) for row in result["data"])
+        >>>
+        >>> # Reading with specific encoding
+        >>> result = reader.run(
+        ...     file_path="european_data.csv",
+        ...     encoding="iso-8859-1",
+        ...     headers=True
+        ... )
+        >>>
+        >>> # Handling quoted fields
+        >>> result = reader.run(
+        ...     file_path="complex.csv",
+        ...     headers=True,
+        ...     quotechar='"'
+        ... )
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -235,7 +287,7 @@ class CSVReader(Node):
 
 
 @register_node()
-class JSONReader(Node):
+class JSONReaderNode(Node):
     """Reads data from a JSON file.
 
     This node handles JSON file reading with support for complex nested
@@ -280,7 +332,7 @@ class JSONReader(Node):
 
     Example:
         # Read API response data
-        reader = JSONReader(file_path='api_response.json')
+        reader = JSONReaderNode(file_path='api_response.json')
         result = reader.execute()
         # result['data'] = {
         #     'status': 'success',
@@ -359,7 +411,7 @@ class JSONReader(Node):
 
 
 @register_node()
-class TextReader(Node):
+class TextReaderNode(Node):
     """Reads text from a file.
 
     This node provides simple text file reading with encoding support.
@@ -403,15 +455,14 @@ class TextReader(Node):
     - UnicodeDecodeError: Wrong encoding
     - MemoryError: File too large
 
-    Example::
-
-        # Read a log file
-        reader = TextReader(
-            file_path='application.log',
-            encoding='utf-8'
-        )
-        result = reader.execute()
-        # result['text'] = "2024-01-01 INFO: Application started\\n..."
+    Example:
+        >>> # Read a log file
+        >>> reader = TextReaderNode(
+        ...     file_path='application.log',
+        ...     encoding='utf-8'
+        ... )
+        >>> result = reader.execute()
+        >>> # result['text'] = "2024-01-01 INFO: Application started\\n..."
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/data/retrieval.py

@@ -102,7 +102,7 @@ class RelevanceScorerNode(Node):
     ) -> List[Dict]:
         """Score chunks using cosine similarity."""
         # Extract actual embedding vectors from the embedding objects
-        # EmbeddingGenerator returns embeddings in format: {"embedding": [...], "text": "...", "dimensions": X}
+        # EmbeddingGeneratorNode returns embeddings in format: {"embedding": [...], "text": "...", "dimensions": X}
 
         # Handle query embedding - should be the first (and only) embedding in the list
         query_embedding_obj = query_embeddings[0] if query_embeddings else {}

kailash/nodes/data/sharepoint_graph.py

@@ -56,18 +56,17 @@ class SharePointGraphReader(Node):
     3. Search for files by name
     4. Navigate folder structures
 
-    Example::
-
-        reader = SharePointGraphReader()
-        result = reader.execute(
-            tenant_id="your-tenant-id",
-            client_id="your-client-id",
-            client_secret="your-secret",
-            site_url="https://company.sharepoint.com/sites/project",
-            operation="list_files",
-            library_name="Documents",
-            folder_path="Reports/2024"
-        )
+    Example:
+        >>> reader = SharePointGraphReader()
+        >>> result = reader.execute(
+        ...     tenant_id="your-tenant-id",
+        ...     client_id="your-client-id",
+        ...     client_secret="your-secret",
+        ...     site_url="https://company.sharepoint.com/sites/project",
+        ...     operation="list_files",
+        ...     library_name="Documents",
+        ...     folder_path="Reports/2024"
+        ... )
     """
 
     def get_metadata(self) -> NodeMetadata:
@@ -471,19 +470,18 @@ class SharePointGraphWriter(Node):
     This node handles file uploads to SharePoint document libraries,
     supporting folder structures and metadata.
 
-    Example::
-
-        writer = SharePointGraphWriter()
-        result = writer.execute(
-            tenant_id="your-tenant-id",
-            client_id="your-client-id",
-            client_secret="your-secret",
-            site_url="https://company.sharepoint.com/sites/project",
-            local_path="report.pdf",
-            library_name="Documents",
-            folder_path="Reports/2024",
-            sharepoint_name="Q4_Report_2024.pdf"
-        )
+    Example:
+        >>> writer = SharePointGraphWriter()
+        >>> result = writer.execute(
+        ...     tenant_id="your-tenant-id",
+        ...     client_id="your-client-id",
+        ...     client_secret="your-secret",
+        ...     site_url="https://company.sharepoint.com/sites/project",
+        ...     local_path="report.pdf",
+        ...     library_name="Documents",
+        ...     folder_path="Reports/2024",
+        ...     sharepoint_name="Q4_Report_2024.pdf"
+        ... )
     """
 
     def get_metadata(self) -> NodeMetadata:

kailash/nodes/data/sql.py

@@ -63,20 +63,19 @@ class SQLDatabaseNode(Node):
     - TimeoutError: Query execution timeout
     - PermissionError: Access denied
 
-    Example::
-
-        # Query customer data
-        sql_node = SQLDatabaseNode(
-            connection_string='postgresql://user:pass@host/db',
-            query='SELECT * FROM customers WHERE active = ?',
-            parameters=[True],
-            result_format='dict'
-        )
-        result = sql_node.execute()
-        # result['data'] = [
-        #     {'id': 1, 'name': 'John', 'active': True},
-        #     {'id': 2, 'name': 'Jane', 'active': True}
-        # ]
+    Example:
+        >>> # Query customer data
+        >>> sql_node = SQLDatabaseNode(
+        ...     connection_string='postgresql://user:pass@host/db',
+        ...     query='SELECT * FROM customers WHERE active = ?',
+        ...     parameters=[True],
+        ...     result_format='dict'
+        ... )
+        >>> result = sql_node.execute()
+        >>> # result['data'] = [
+        >>> #     {'id': 1, 'name': 'John', 'active': True},
+        >>> #     {'id': 2, 'name': 'Jane', 'active': True}
+        >>> # ]
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -259,18 +258,17 @@ class SQLQueryBuilderNode(Node):
     3. Multi-table joins
     4. Aggregation queries
 
-    Example::
-
-        builder = SQLQueryBuilderNode(
-            table='customers',
-            select=['name', 'email'],
-            where={'active': True, 'country': 'USA'},
-            order_by=['name'],
-            limit=100
-        )
-        result = builder.execute()
-        # result['query'] = 'SELECT name, email FROM customers WHERE active = ? AND country = ? ORDER BY name LIMIT 100'
-        # result['parameters'] = [True, 'USA']
+    Example:
+        >>> builder = SQLQueryBuilderNode(
+        ...     table='customers',
+        ...     select=['name', 'email'],
+        ...     where={'active': True, 'country': 'USA'},
+        ...     order_by=['name'],
+        ...     limit=100
+        ... )
+        >>> result = builder.execute()
+        >>> # result['query'] = 'SELECT name, email FROM customers WHERE active = ? AND country = ? ORDER BY name LIMIT 100'
+        >>> # result['parameters'] = [True, 'USA']
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/data/writers.py

@@ -12,9 +12,9 @@ Design Philosophy:
 5. Progress tracking and feedback
 
 Node Categories:
-- CSVWriter: Tabular data to CSV files
-- JSONWriter: Structured data to JSON files
-- TextWriter: Raw text to any text file
+- CSVWriterNode: Tabular data to CSV files
+- JSONWriterNode: Structured data to JSON files
+- TextWriterNode: Raw text to any text file
 
 Upstream Components:
 - Reader nodes: Provide data to transform
@@ -37,7 +37,7 @@ from kailash.nodes.base import Node, NodeParameter, register_node
 
 
 @register_node()
-class CSVWriter(Node):
+class CSVWriterNode(Node):
     """Writes data to a CSV file.
 
     This node handles CSV file writing with support for both dictionary
@@ -81,19 +81,18 @@ class CSVWriter(Node):
     - TypeError: Invalid data structure
     - UnicodeEncodeError: Encoding issues
 
-    Example::
-
-        # Write customer data
-        writer = CSVWriter(
-            file_path='output.csv',
-            data=[
-                {'id': 1, 'name': 'John', 'age': 30},
-                {'id': 2, 'name': 'Jane', 'age': 25}
-            ],
-            delimiter=','
-        )
-        result = writer.execute()
-        # result = {'rows_written': 2, 'file_path': 'output.csv'}
+    Example:
+        >>> # Write customer data
+        >>> writer = CSVWriterNode(
+        ...     file_path='output.csv',
+        ...     data=[
+        ...         {'id': 1, 'name': 'John', 'age': 30},
+        ...         {'id': 2, 'name': 'Jane', 'age': 25}
+        ...     ],
+        ...     delimiter=','
+        ... )
+        >>> result = writer.execute()
+        >>> # result = {'rows_written': 2, 'file_path': 'output.csv'}
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -218,7 +217,7 @@ class CSVWriter(Node):
 
 
 @register_node()
-class JSONWriter(Node):
+class JSONWriterNode(Node):
     """Writes data to a JSON file.
 
     This node handles JSON serialization with support for complex
@@ -262,20 +261,19 @@ class JSONWriter(Node):
     - OSError: Path or disk issues
     - JSONEncodeError: Encoding problems
 
-    Example::
-
-        # Write API response
-        writer = JSONWriter(
-            file_path='response.json',
-            data={
-                'status': 'success',
-                'results': [1, 2, 3],
-                'metadata': {'version': '1.0'}
-            },
-            indent=2
-        )
-        result = writer.execute()
-        # result = {'file_path': 'response.json'}
+    Example:
+        >>> # Write API response
+        >>> writer = JSONWriterNode(
+        ...     file_path='response.json',
+        ...     data={
+        ...         'status': 'success',
+        ...         'results': [1, 2, 3],
+        ...         'metadata': {'version': '1.0'}
+        ...     },
+        ...     indent=2
+        ... )
+        >>> result = writer.execute()
+        >>> # result = {'file_path': 'response.json'}
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -370,7 +368,7 @@ class JSONWriter(Node):
 
 
 @register_node()
-class TextWriter(Node):
+class TextWriterNode(Node):
     """Writes text to a file.
 
     This node provides flexible text file writing with support for
@@ -414,17 +412,16 @@ class TextWriter(Node):
     - UnicodeEncodeError: Encoding mismatch
     - MemoryError: Text too large
 
-    Example::
-
-        # Append to log file
-        writer = TextWriter(
-            file_path='app.log',
-            text='ERROR: Connection failed\\n',
-            encoding='utf-8',
-            append=True
-        )
-        result = writer.execute()
-        # result = {'file_path': 'app.log', 'bytes_written': 25}
+    Example:
+        >>> # Append to log file
+        >>> writer = TextWriterNode(
+        ...     file_path='app.log',
+        ...     text='ERROR: Connection failed\\n',
+        ...     encoding='utf-8',
+        ...     append=True
+        ... )
+        >>> result = writer.execute()
+        >>> # result = {'file_path': 'app.log', 'bytes_written': 25}
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/logic/__init__.py

@@ -1,7 +1,13 @@
 """Logic operation nodes for the Kailash SDK."""
 
-from kailash.nodes.logic.async_operations import AsyncMerge, AsyncSwitch
-from kailash.nodes.logic.operations import Merge, Switch
+from kailash.nodes.logic.async_operations import AsyncMergeNode, AsyncSwitchNode
+from kailash.nodes.logic.operations import MergeNode, SwitchNode
 from kailash.nodes.logic.workflow import WorkflowNode
 
-__all__ = ["Switch", "Merge", "AsyncSwitch", "AsyncMerge", "WorkflowNode"]
+__all__ = [
+    "SwitchNode",
+    "MergeNode",
+    "AsyncSwitchNode",
+    "AsyncMergeNode",
+    "WorkflowNode",
+]