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

{kailash-0.1.1.dist-info → kailash-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kailash
-Version: 0.1.1
+Version: 0.1.3
 Summary: Python SDK for the Kailash container-node architecture
 Home-page: https://github.com/integrum/kailash-python-sdk
 Author: Integrum
@@ -10,9 +10,8 @@ Project-URL: Bug Tracker, https://github.com/integrum/kailash-python-sdk/issues
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -22,7 +21,7 @@ Requires-Dist: matplotlib>=3.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: click>=8.0
 Requires-Dist: pytest>=8.3.5
-Requires-Dist: mcp[cli]>=1.9.0
+Requires-Dist: mcp[cli]>=1.9.2
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: numpy>=2.2.5
 Requires-Dist: scipy>=1.15.3
@@ -42,10 +41,12 @@ Requires-Dist: autodoc>=0.5.0
 Requires-Dist: myst-parser>=4.0.1
 Requires-Dist: black>=25.1.0
 Requires-Dist: psutil>=7.0.0
-Requires-Dist: fastapi[all]>=0.115.12
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: uvicorn[standard]>=0.31.0
 Requires-Dist: pytest-asyncio>=1.0.0
 Requires-Dist: pre-commit>=4.2.0
 Requires-Dist: twine>=6.1.0
+Requires-Dist: ollama>=0.5.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=3.0; extra == "dev"
@@ -62,10 +63,10 @@ Dynamic: requires-python
 <p align="center">
   <a href="https://pypi.org/project/kailash/"><img src="https://img.shields.io/pypi/v/kailash.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/kailash/"><img src="https://img.shields.io/pypi/pyversions/kailash.svg" alt="Python versions"></a>
-  <a href="https://pypi.org/project/kailash/"><img src="https://img.shields.io/pypi/dm/kailash.svg" alt="Downloads"></a>
+  <a href="https://pepy.tech/project/kailash"><img src="https://static.pepy.tech/badge/kailash" alt="Downloads"></a>
   <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
   <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
-  <img src="https://img.shields.io/badge/tests-544%20passing-brightgreen.svg" alt="Tests: 544 passing">
+  <img src="https://img.shields.io/badge/tests-746%20passing-brightgreen.svg" alt="Tests: 746 passing">
   <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%">
 </p>
 
@@ -87,6 +88,9 @@ Dynamic: requires-python
 - 📊 **Real-time Monitoring**: Live dashboards with WebSocket streaming and performance metrics
 - 🧩 **Extensible**: Easy to create custom nodes for domain-specific operations
 - ⚡ **Fast Installation**: Uses `uv` for lightning-fast Python package management
+- 🤖 **AI-Powered**: Complete LLM agents, embeddings, and hierarchical RAG architecture
+- 🧠 **Retrieval-Augmented Generation**: Full RAG pipeline with intelligent document processing
+- 🌐 **REST API Wrapper**: Expose any workflow as a production-ready API in 3 lines
 
 ## 🎯 Who Is This For?
 
@@ -101,6 +105,8 @@ The Kailash Python SDK is designed for:
 
 ### Installation
 
+**Requirements:** Python 3.11 or higher
+
 ```bash
 # Install uv if you haven't already
 curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -137,9 +143,11 @@ def analyze_customers(data):
     # Convert total_spent to numeric
     df['total_spent'] = pd.to_numeric(df['total_spent'])
     return {
-        "total_customers": len(df),
-        "avg_spend": df["total_spent"].mean(),
-        "top_customers": df.nlargest(10, "total_spent").to_dict("records")
+        "result": {
+            "total_customers": len(df),
+            "avg_spend": df["total_spent"].mean(),
+            "top_customers": df.nlargest(10, "total_spent").to_dict("records")
+        }
     }
 
 analyzer = PythonCodeNode.from_function(analyze_customers, name="analyzer")
@@ -174,7 +182,7 @@ sharepoint = SharePointGraphReader()
 workflow.add_node("read_sharepoint", sharepoint)
 
 # Process downloaded files
-csv_writer = CSVWriter()
+csv_writer = CSVWriter(file_path="sharepoint_output.csv")
 workflow.add_node("save_locally", csv_writer)
 
 # Connect nodes
@@ -198,6 +206,135 @@ runtime = LocalRuntime()
 results, run_id = runtime.execute(workflow, inputs=inputs)
 ```
 
+### Hierarchical RAG Example
+
+```python
+from kailash.workflow import Workflow
+from kailash.nodes.ai.embedding_generator import EmbeddingGenerator
+from kailash.nodes.ai.llm_agent import LLMAgent
+from kailash.nodes.data.sources import DocumentSourceNode, QuerySourceNode
+from kailash.nodes.data.retrieval import RelevanceScorerNode
+from kailash.nodes.transform.chunkers import HierarchicalChunkerNode
+from kailash.nodes.transform.formatters import (
+    ChunkTextExtractorNode, QueryTextWrapperNode, ContextFormatterNode
+)
+
+# Create hierarchical RAG workflow
+workflow = Workflow("hierarchical_rag", name="Hierarchical RAG Workflow")
+
+# Data sources (autonomous - no external files needed)
+doc_source = DocumentSourceNode()
+query_source = QuerySourceNode()
+
+# Document processing pipeline
+chunker = HierarchicalChunkerNode()
+chunk_text_extractor = ChunkTextExtractorNode()
+query_text_wrapper = QueryTextWrapperNode()
+
+# AI processing with Ollama
+chunk_embedder = EmbeddingGenerator(
+    provider="ollama", model="nomic-embed-text", operation="embed_batch"
+)
+query_embedder = EmbeddingGenerator(
+    provider="ollama", model="nomic-embed-text", operation="embed_batch"
+)
+
+# Retrieval and response generation
+relevance_scorer = RelevanceScorerNode()
+context_formatter = ContextFormatterNode()
+llm_agent = LLMAgent(provider="ollama", model="llama3.2", temperature=0.7)
+
+# Add all nodes to workflow
+for name, node in {
+    "doc_source": doc_source, "query_source": query_source,
+    "chunker": chunker, "chunk_text_extractor": chunk_text_extractor,
+    "query_text_wrapper": query_text_wrapper, "chunk_embedder": chunk_embedder,
+    "query_embedder": query_embedder, "relevance_scorer": relevance_scorer,
+    "context_formatter": context_formatter, "llm_agent": llm_agent
+}.items():
+    workflow.add_node(name, node)
+
+# Connect the RAG pipeline
+workflow.connect("doc_source", "chunker", {"documents": "documents"})
+workflow.connect("chunker", "chunk_text_extractor", {"chunks": "chunks"})
+workflow.connect("chunk_text_extractor", "chunk_embedder", {"input_texts": "input_texts"})
+workflow.connect("query_source", "query_text_wrapper", {"query": "query"})
+workflow.connect("query_text_wrapper", "query_embedder", {"input_texts": "input_texts"})
+workflow.connect("chunker", "relevance_scorer", {"chunks": "chunks"})
+workflow.connect("query_embedder", "relevance_scorer", {"embeddings": "query_embedding"})
+workflow.connect("chunk_embedder", "relevance_scorer", {"embeddings": "chunk_embeddings"})
+workflow.connect("relevance_scorer", "context_formatter", {"relevant_chunks": "relevant_chunks"})
+workflow.connect("query_source", "context_formatter", {"query": "query"})
+workflow.connect("context_formatter", "llm_agent", {"messages": "messages"})
+
+# Execute the RAG workflow
+from kailash.runtime.local import LocalRuntime
+runtime = LocalRuntime()
+results, run_id = runtime.execute(workflow)
+
+print("RAG Response:", results["llm_agent"]["response"])
+```
+
+### Workflow API Wrapper - Expose Workflows as REST APIs
+
+Transform any Kailash workflow into a production-ready REST API in just 3 lines of code:
+
+```python
+from kailash.api.workflow_api import WorkflowAPI
+
+# Take any workflow and expose it as an API
+api = WorkflowAPI(workflow)
+api.run(port=8000)  # That's it! Your workflow is now a REST API
+```
+
+#### Features
+
+- **Automatic REST Endpoints**:
+  - `POST /execute` - Execute workflow with inputs
+  - `GET /workflow/info` - Get workflow metadata
+  - `GET /health` - Health check endpoint
+  - Automatic OpenAPI docs at `/docs`
+
+- **Multiple Execution Modes**:
+  ```python
+  # Synchronous execution (wait for results)
+  curl -X POST http://localhost:8000/execute \
+    -d '{"inputs": {...}, "mode": "sync"}'
+
+  # Asynchronous execution (get execution ID)
+  curl -X POST http://localhost:8000/execute \
+    -d '{"inputs": {...}, "mode": "async"}'
+
+  # Check async status
+  curl http://localhost:8000/status/{execution_id}
+  ```
+
+- **Specialized APIs** for specific domains:
+  ```python
+  from kailash.api.workflow_api import create_workflow_api
+
+  # Create a RAG-specific API with custom endpoints
+  api = create_workflow_api(rag_workflow, api_type="rag")
+  # Adds /documents and /query endpoints
+  ```
+
+- **Production Ready**:
+  ```python
+  # Development
+  api.run(reload=True, log_level="debug")
+
+  # Production with SSL
+  api.run(
+      host="0.0.0.0",
+      port=443,
+      ssl_keyfile="key.pem",
+      ssl_certfile="cert.pem",
+      workers=4
+  )
+  ```
+
+See the [API demo example](examples/integration_examples/integration_api_demo.py) for complete usage patterns.
+
 ## 📚 Documentation
 
 | Resource | Description |
@@ -221,6 +358,9 @@ The SDK includes a rich set of pre-built nodes for common operations:
 **Data Operations**
 - `CSVReader` - Read CSV files
 - `JSONReader` - Read JSON files
+- `DocumentSourceNode` - Sample document provider
+- `QuerySourceNode` - Sample query provider
+- `RelevanceScorerNode` - Multi-method similarity
 - `SQLDatabaseNode` - Query databases
 - `CSVWriter` - Write CSV files
 - `JSONWriter` - Write JSON files
@@ -228,12 +368,20 @@ The SDK includes a rich set of pre-built nodes for common operations:
 </td>
 <td width="50%">
 
-**Processing Nodes**
+**Transform Nodes**
 - `PythonCodeNode` - Custom Python logic
 - `DataTransformer` - Transform data
+- `HierarchicalChunkerNode` - Document chunking
+- `ChunkTextExtractorNode` - Extract chunk text
+- `QueryTextWrapperNode` - Wrap queries for processing
+- `ContextFormatterNode` - Format LLM context
 - `Filter` - Filter records
 - `Aggregator` - Aggregate data
-- `TextProcessor` - Process text
+
+**Logic Nodes**
+- `Switch` - Conditional routing
+- `Merge` - Combine multiple inputs
+- `WorkflowNode` - Wrap workflows as reusable nodes
 
 </td>
 </tr>
@@ -241,10 +389,12 @@ The SDK includes a rich set of pre-built nodes for common operations:
 <td width="50%">
 
 **AI/ML Nodes**
-- `EmbeddingNode` - Generate embeddings
-- `VectorDatabaseNode` - Vector search
-- `ModelPredictorNode` - ML predictions
-- `LLMNode` - LLM integration
+- `LLMAgent` - Multi-provider LLM with memory & tools
+- `EmbeddingGenerator` - Vector embeddings with caching
+- `MCPClient/MCPServer` - Model Context Protocol
+- `TextClassifier` - Text classification
+- `SentimentAnalyzer` - Sentiment analysis
+- `NamedEntityRecognizer` - NER extraction
 
 </td>
 <td width="50%">
@@ -280,25 +430,59 @@ The SDK includes a rich set of pre-built nodes for common operations:
 #### Workflow Management
 ```python
 from kailash.workflow import Workflow
+from kailash.nodes.logic import Switch
+from kailash.nodes.transform import DataTransformer
 
 # Create complex workflows with branching logic
 workflow = Workflow("data_pipeline", name="data_pipeline")
 
-# Add conditional branching
-validator = ValidationNode()
-workflow.add_node("validate", validator)
+# Add conditional branching with Switch node
+switch = Switch()
+workflow.add_node("route", switch)
 
 # Different paths based on validation
+processor_a = DataTransformer(transformations=["lambda x: x"])
+error_handler = DataTransformer(transformations=["lambda x: {'error': str(x)}"])
 workflow.add_node("process_valid", processor_a)
 workflow.add_node("handle_errors", error_handler)
 
-# Connect with conditions
-workflow.connect("validate", "process_valid", condition="is_valid")
-workflow.connect("validate", "handle_errors", condition="has_errors")
+# Connect with switch routing
+workflow.connect("route", "process_valid")
+workflow.connect("route", "handle_errors")
+```
+
+#### Hierarchical Workflow Composition
+```python
+from kailash.workflow import Workflow
+from kailash.nodes.logic import WorkflowNode
+from kailash.runtime.local import LocalRuntime
+
+# Create a reusable data processing workflow
+inner_workflow = Workflow("data_processor", name="Data Processor")
+# ... add nodes to inner workflow ...
+
+# Wrap the workflow as a node
+processor_node = WorkflowNode(
+    workflow=inner_workflow,
+    name="data_processor"
+)
+
+# Use in a larger workflow
+main_workflow = Workflow("main", name="Main Pipeline")
+main_workflow.add_node("process", processor_node)
+main_workflow.add_node("analyze", analyzer_node)
+
+# Connect workflows
+main_workflow.connect("process", "analyze")
+
+# Execute - parameters automatically mapped to inner workflow
+runtime = LocalRuntime()
+results, _ = runtime.execute(main_workflow)
 ```
 
 #### Immutable State Management
 ```python
+from kailash.workflow import Workflow
 from kailash.workflow.state import WorkflowStateWrapper
 from pydantic import BaseModel
 
@@ -308,6 +492,9 @@ class MyStateModel(BaseModel):
     status: str = "pending"
     nested: dict = {}
 
+# Create workflow
+workflow = Workflow("state_workflow", name="state_workflow")
+
 # Create and wrap state object
 state = MyStateModel()
 state_wrapper = workflow.create_state_wrapper(state)
@@ -324,8 +511,9 @@ updated_wrapper = state_wrapper.batch_update([
     (["status"], "processing")
 ])
 
-# Execute workflow with state management
-final_state, results = workflow.execute_with_state(state_model=state)
+# Access the updated state
+print(f"Updated counter: {updated_wrapper._state.counter}")
+print(f"Updated status: {updated_wrapper._state.status}")
 ```
 
 #### Task Tracking
@@ -342,45 +530,75 @@ workflow = Workflow("sample_workflow", name="Sample Workflow")
 # Run workflow with tracking
 from kailash.runtime.local import LocalRuntime
 runtime = LocalRuntime()
-results, run_id = runtime.execute(workflow, task_manager=task_manager)
+results, run_id = runtime.execute(workflow)
 
 # Query execution history
-runs = task_manager.list_runs(status="completed", limit=10)
-details = task_manager.get_run(run_id)
+# Note: list_runs() may fail with timezone comparison errors in some cases
+try:
+    # List all runs
+    all_runs = task_manager.list_runs()
+
+    # Filter by status
+    completed_runs = task_manager.list_runs(status="completed")
+    failed_runs = task_manager.list_runs(status="failed")
+
+    # Filter by workflow name
+    workflow_runs = task_manager.list_runs(workflow_name="sample_workflow")
+
+    # Process run information
+    for run in completed_runs[:5]:  # First 5 runs
+        print(f"Run {run.run_id[:8]}: {run.workflow_name} - {run.status}")
+
+except Exception as e:
+    print(f"Error listing runs: {e}")
+    # Fallback: Access run details directly if available
+    if hasattr(task_manager, 'storage'):
+        run = task_manager.get_run(run_id)
 ```
 
 #### Local Testing
 ```python
 from kailash.runtime.local import LocalRuntime
+from kailash.workflow import Workflow
+
+# Create a test workflow
+workflow = Workflow("test_workflow", name="test_workflow")
 
 # Create test runtime with debugging enabled
 runtime = LocalRuntime(debug=True)
 
 # Execute with test data
-test_data = {"customers": [...]}
-results = runtime.execute(workflow, inputs=test_data)
+results, run_id = runtime.execute(workflow)
 
 # Validate results
-assert results["node_id"]["output_key"] == expected_value
+assert isinstance(results, dict)
 ```
 
 #### Performance Monitoring & Real-time Dashboards
 ```python
 from kailash.visualization.performance import PerformanceVisualizer
 from kailash.visualization.dashboard import RealTimeDashboard, DashboardConfig
-from kailash.visualization.reports import WorkflowPerformanceReporter
+from kailash.visualization.reports import WorkflowPerformanceReporter, ReportFormat
 from kailash.tracking import TaskManager
 from kailash.runtime.local import LocalRuntime
+from kailash.workflow import Workflow
+from kailash.nodes.transform import DataTransformer
+
+# Create a workflow to monitor
+workflow = Workflow("monitored_workflow", name="monitored_workflow")
+node = DataTransformer(transformations=["lambda x: x"])
+workflow.add_node("transform", node)
 
 # Run workflow with task tracking
+# Note: Pass task_manager to execute() to enable performance tracking
 task_manager = TaskManager()
 runtime = LocalRuntime()
 results, run_id = runtime.execute(workflow, task_manager=task_manager)
 
 # Static performance analysis
+from pathlib import Path
 perf_viz = PerformanceVisualizer(task_manager)
-outputs = perf_viz.create_run_performance_summary(run_id, output_dir="performance_report")
-perf_viz.compare_runs([run_id_1, run_id_2], output_path="comparison.png")
+outputs = perf_viz.create_run_performance_summary(run_id, output_dir=Path("performance_report"))
 
 # Real-time monitoring dashboard
 config = DashboardConfig(
@@ -408,8 +626,7 @@ reporter = WorkflowPerformanceReporter(task_manager)
 report_path = reporter.generate_report(
     run_id,
     output_path="workflow_report.html",
-    format=ReportFormat.HTML,
-    compare_runs=[run_id_1, run_id_2]
+    format=ReportFormat.HTML
 )
 ```
 
@@ -466,6 +683,13 @@ api_client = RESTAPINode(
 #### Export Formats
 ```python
 from kailash.utils.export import WorkflowExporter, ExportConfig
+from kailash.workflow import Workflow
+from kailash.nodes.transform import DataTransformer
+
+# Create a workflow to export
+workflow = Workflow("export_example", name="export_example")
+node = DataTransformer(transformations=["lambda x: x"])
+workflow.add_node("transform", node)
 
 exporter = WorkflowExporter()
 
@@ -478,22 +702,147 @@ config = ExportConfig(
     include_metadata=True,
     container_tag="latest"
 )
-workflow.save("deployment.yaml", format="yaml")
+workflow.save("deployment.yaml")
 ```
 
 ### 🎨 Visualization
 
 ```python
+from kailash.workflow import Workflow
 from kailash.workflow.visualization import WorkflowVisualizer
+from kailash.nodes.transform import DataTransformer
+
+# Create a workflow to visualize
+workflow = Workflow("viz_example", name="viz_example")
+node = DataTransformer(transformations=["lambda x: x"])
+workflow.add_node("transform", node)
+
+# Generate Mermaid diagram (recommended for documentation)
+mermaid_code = workflow.to_mermaid()
+print(mermaid_code)
 
-# Visualize workflow structure
+# Save as Mermaid markdown file
+with open("workflow.md", "w") as f:
+    f.write(workflow.to_mermaid_markdown(title="My Workflow"))
+
+# Or use matplotlib visualization
 visualizer = WorkflowVisualizer(workflow)
-visualizer.visualize(output_path="workflow.png")
+visualizer.visualize()
+visualizer.save("workflow.png", dpi=300)  # Save as PNG
+```
+
+#### Hierarchical RAG (Retrieval-Augmented Generation)
+```python
+from kailash.workflow import Workflow
+from kailash.nodes.data.sources import DocumentSourceNode, QuerySourceNode
+from kailash.nodes.data.retrieval import RelevanceScorerNode
+from kailash.nodes.transform.chunkers import HierarchicalChunkerNode
+from kailash.nodes.transform.formatters import (
+    ChunkTextExtractorNode,
+    QueryTextWrapperNode,
+    ContextFormatterNode,
+)
+from kailash.nodes.ai.llm_agent import LLMAgent
+from kailash.nodes.ai.embedding_generator import EmbeddingGenerator
+
+# Create hierarchical RAG workflow
+workflow = Workflow(
+    workflow_id="hierarchical_rag_example",
+    name="Hierarchical RAG Workflow",
+    description="Complete RAG pipeline with embedding-based retrieval",
+    version="1.0.0"
+)
+
+# Create data source nodes
+doc_source = DocumentSourceNode()
+query_source = QuerySourceNode()
 
-# Show in Jupyter notebook
-visualizer.show()
+# Create document processing pipeline
+chunker = HierarchicalChunkerNode()
+chunk_text_extractor = ChunkTextExtractorNode()
+query_text_wrapper = QueryTextWrapperNode()
+
+# Create embedding generators
+chunk_embedder = EmbeddingGenerator(
+    provider="ollama",
+    model="nomic-embed-text",
+    operation="embed_batch"
+)
+
+query_embedder = EmbeddingGenerator(
+    provider="ollama",
+    model="nomic-embed-text",
+    operation="embed_batch"
+)
+
+# Create retrieval and formatting nodes
+relevance_scorer = RelevanceScorerNode(similarity_method="cosine")
+context_formatter = ContextFormatterNode()
+
+# Create LLM agent for final answer generation
+llm_agent = LLMAgent(
+    provider="ollama",
+    model="llama3.2",
+    temperature=0.7,
+    max_tokens=500
+)
+
+# Add all nodes to workflow
+for node_id, node in [
+    ("doc_source", doc_source),
+    ("chunker", chunker),
+    ("query_source", query_source),
+    ("chunk_text_extractor", chunk_text_extractor),
+    ("query_text_wrapper", query_text_wrapper),
+    ("chunk_embedder", chunk_embedder),
+    ("query_embedder", query_embedder),
+    ("relevance_scorer", relevance_scorer),
+    ("context_formatter", context_formatter),
+    ("llm_agent", llm_agent)
+]:
+    workflow.add_node(node_id, node)
+
+# Connect the workflow pipeline
+# Document processing: docs → chunks → text → embeddings
+workflow.connect("doc_source", "chunker", {"documents": "documents"})
+workflow.connect("chunker", "chunk_text_extractor", {"chunks": "chunks"})
+workflow.connect("chunk_text_extractor", "chunk_embedder", {"input_texts": "input_texts"})
+
+# Query processing: query → text wrapper → embeddings
+workflow.connect("query_source", "query_text_wrapper", {"query": "query"})
+workflow.connect("query_text_wrapper", "query_embedder", {"input_texts": "input_texts"})
+
+# Relevance scoring: chunks + embeddings → scored chunks
+workflow.connect("chunker", "relevance_scorer", {"chunks": "chunks"})
+workflow.connect("query_embedder", "relevance_scorer", {"embeddings": "query_embedding"})
+workflow.connect("chunk_embedder", "relevance_scorer", {"embeddings": "chunk_embeddings"})
+
+# Context formatting: relevant chunks + query → formatted context
+workflow.connect("relevance_scorer", "context_formatter", {"relevant_chunks": "relevant_chunks"})
+workflow.connect("query_source", "context_formatter", {"query": "query"})
+
+# Final answer generation: formatted context → LLM response
+workflow.connect("context_formatter", "llm_agent", {"messages": "messages"})
+
+# Execute workflow
+results, run_id = workflow.run()
+
+# Access results
+print("🎯 Top Relevant Chunks:")
+for chunk in results["relevance_scorer"]["relevant_chunks"]:
+    print(f"  - {chunk['document_title']}: {chunk['relevance_score']:.3f}")
+
+print("\n🤖 Final Answer:")
+print(results["llm_agent"]["response"]["content"])
 ```
 
+This example demonstrates:
+- **Document chunking** with hierarchical structure
+- **Vector embeddings** using Ollama's nomic-embed-text model
+- **Semantic similarity** scoring with cosine similarity
+- **Context formatting** for LLM input
+- **Answer generation** using Ollama's llama3.2 model
+
 ## 💻 CLI Commands
 
 The SDK includes a comprehensive CLI for workflow management:
@@ -545,6 +894,45 @@ kailash/
 └── utils/           # Utilities and helpers
 ```
 
+### 🤖 Unified AI Provider Architecture
+
+The SDK features a unified provider architecture for AI capabilities:
+
+```python
+from kailash.nodes.ai import LLMAgent, EmbeddingGenerator
+
+# Multi-provider LLM support
+agent = LLMAgent()
+result = agent.run(
+    provider="ollama",  # or "openai", "anthropic", "mock"
+    model="llama3.1:8b-instruct-q8_0",
+    messages=[{"role": "user", "content": "Explain quantum computing"}],
+    generation_config={"temperature": 0.7, "max_tokens": 500}
+)
+
+# Vector embeddings with the same providers
+embedder = EmbeddingGenerator()
+embedding = embedder.run(
+    provider="ollama",  # Same providers support embeddings
+    model="snowflake-arctic-embed2",
+    operation="embed_text",
+    input_text="Quantum computing uses quantum mechanics principles"
+)
+
+# Check available providers and capabilities
+from kailash.nodes.ai.ai_providers import get_available_providers
+providers = get_available_providers()
+# Returns: {"ollama": {"available": True, "chat": True, "embeddings": True}, ...}
+```
+
+**Supported AI Providers:**
+- **Ollama**: Local LLMs with both chat and embeddings (llama3.1, mistral, etc.)
+- **OpenAI**: GPT models and text-embedding-3 series
+- **Anthropic**: Claude models (chat only)
+- **Cohere**: Embedding models (embed-english-v3.0)
+- **HuggingFace**: Sentence transformers and local models
+- **Mock**: Testing provider with consistent outputs
+
 ## 🧪 Testing
 
 The SDK is thoroughly tested with comprehensive test suites:
@@ -656,9 +1044,9 @@ pre-commit run pytest-check
 - **Performance visualization dashboards**
 - **Real-time monitoring dashboard with WebSocket streaming**
 - **Comprehensive performance reports (HTML, Markdown, JSON)**
-- **100% test coverage (544 tests)**
+- **89% test coverage (571 tests)**
 - **15 test categories all passing**
-- 21+ working examples
+- 37 working examples
 
 </td>
 <td width="30%">
@@ -683,11 +1071,17 @@ pre-commit run pytest-check
 </table>
 
 ### 🎯 Test Suite Status
-- **Total Tests**: 544 passing (100%)
+- **Total Tests**: 571 passing (89%)
 - **Test Categories**: 15/15 at 100%
 - **Integration Tests**: 65 passing
-- **Examples**: 21/21 working
-- **Code Coverage**: Comprehensive
+- **Examples**: 37/37 working
+- **Code Coverage**: 89%
+
+## ⚠️ Known Issues
+
+1. **DateTime Comparison in `list_runs()`**: The `TaskManager.list_runs()` method may encounter timezone comparison errors between timezone-aware and timezone-naive datetime objects. Workaround: Use try-catch blocks when calling `list_runs()` or access run details directly via `get_run(run_id)`.
+
+2. **Performance Tracking**: To enable performance metrics collection, you must pass the `task_manager` parameter to the `runtime.execute()` method: `runtime.execute(workflow, task_manager=task_manager)`.
 
 ## 📄 License