Metadata-Version: 2.4
Name: kailash
Version: 0.8.5
Summary: Python SDK for the Kailash container-node architecture
Home-page: https://github.com/integrum/kailash-python-sdk
Author: Integrum
Author-email: Integrum <info@integrum.com>
Project-URL: Homepage, https://github.com/integrum/kailash-python-sdk
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.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=2.7
Requires-Dist: pydantic>=1.9
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.11.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: numpy>=2.2.5
Requires-Dist: scipy>=1.15.3
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: requests>=2.32.3
Requires-Dist: pytest-cov>=6.1.1
Requires-Dist: isort>=6.0.1
Requires-Dist: aiohttp>=3.12.4
Requires-Dist: aiohttp-cors>=0.7.0
Requires-Dist: ruff>=0.11.12
Requires-Dist: msal>=1.32.3
Requires-Dist: sphinx>=8.2.3
Requires-Dist: sphinx-rtd-theme>=3.0.2
Requires-Dist: sphinx-copybutton>=0.5.2
Requires-Dist: sphinxcontrib-mermaid>=1.0.0
Requires-Dist: sphinx-autobuild>=2024.10.3
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>=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
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: pymysql>=1.1.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: websockets>=12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: python-jose>=3.5.0
Requires-Dist: pytest-xdist>=3.6.0
Requires-Dist: pytest-timeout>=2.3.0
Requires-Dist: pytest-split>=0.9.0
Requires-Dist: pytest-forked>=1.6.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: twilio>=9.6.3
Requires-Dist: qrcode>=8.2
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: bcrypt>=4.3.0
Requires-Dist: plotly>=6.2.0
Requires-Dist: redis[asyncio]>=6.2.0
Requires-Dist: faker>=37.4.0
Requires-Dist: structlog>=25.4.0
Requires-Dist: authlib>=1.6.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: limits>=5.4.0
Requires-Dist: prometheus-client>=0.22.1
Requires-Dist: opentelemetry-api>=1.34.1
Requires-Dist: opentelemetry-sdk>=1.34.1
Requires-Dist: passlib>=1.7.4
Requires-Dist: pyotp>=2.9.0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.55b1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: sqlparse>=0.5.3
Requires-Dist: jsonschema>=4.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.10; extra == "dev"
Requires-Dist: mypy>=0.9; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Kailash Python SDK

<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://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-2400%2B%20passing-brightgreen.svg" alt="Tests: 2400+ Passing">
  <img src="https://img.shields.io/badge/performance-11x%20faster-yellow.svg" alt="Performance: 11x Faster">
  <img src="https://img.shields.io/badge/docker-integrated-blue.svg" alt="Docker: Integrated">
  <img src="https://img.shields.io/badge/AI-MCP%20validated-purple.svg" alt="AI: MCP Validated">
</p>

<p align="center">
  <strong>Enterprise-Grade Workflow Orchestration Platform</strong>
</p>

<p align="center">
  Build production-ready applications with zero-config database operations, multi-channel platforms, and comprehensive AI integration. From rapid prototyping to enterprise deployment.
</p>

---

## 🔥 Latest Release: v0.8.4 (January 19, 2025)

**A2A Google Protocol Enhancement**

- 🤖 **Advanced Agent Coordination**: A2ACoordinatorNode with Google Protocol best practices
- 🎯 **Intelligent Task Delegation**: Context-aware task distribution with skill-based matching
- 🔍 **Hybrid Search Capabilities**: Multi-strategy agent discovery and matching algorithms
- 🧠 **Semantic Memory System**: Long-term memory management for agent interactions
- 📊 **Real-time Analytics**: Streaming performance monitoring for A2A workflows
- ✅ **Backward Compatible**: Seamless integration with existing A2A implementations

[Full Changelog](CHANGELOG.md) | [PyPI Packages](https://pypi.org/project/kailash/0.8.4/)

## 🎯 What Makes Kailash Different

### 🏗️ **Complete Application Framework**
Not just a toolkit - complete production-ready applications built on enterprise-grade infrastructure:

- **DataFlow**: Zero-config database operations with MongoDB-style queries
- **Nexus**: Multi-channel platform (API + CLI + MCP) from single codebase
- **AI Registry**: Advanced RAG with 47+ specialized nodes
- **User Management**: Enterprise RBAC system with comprehensive security

### 🚀 **Performance & Scale**
- **11x faster test execution** (117s → 10.75s) with smart isolation
- **31.8M operations/second** query performance baseline
- **30,000+ iterations/second** cyclic workflow execution
- **100% test pass rate** across 2,400+ tests

### 🤖 **AI-First Architecture**
- **A2A Google Protocol** for enterprise multi-agent coordination
- **Real MCP execution** by default for all AI agents
- **47+ specialized RAG nodes** for document processing
- **Semantic memory systems** with context-aware retrieval
- **Hybrid search algorithms** for intelligent agent discovery
- **Self-organizing agent pools** with advanced coordination patterns

## 🏗️ Project Architecture

### Three-Layer Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│                     🎨 Studio UI Layer                         │
│              Visual workflow builder (coming soon)              │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                  🏢 Application Framework                       │
│  DataFlow  │  Nexus  │  AI Registry  │  User Management  │...  │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                     🎯 Core SDK Foundation                      │
│  115+ Nodes  │  Workflows  │  Runtime  │  Security  │  Testing │
└─────────────────────────────────────────────────────────────────┘
```

### Current Project Structure
```
kailash_python_sdk/
├── src/kailash/          # Core SDK - 115+ nodes, workflows, runtime
├── apps/                 # Complete Applications
│   ├── kailash-dataflow/ # Zero-config database operations
│   ├── kailash-nexus/    # Multi-channel platform
│   ├── kailash-mcp/      # Enterprise MCP platform
│   ├── ai_registry/      # Advanced RAG capabilities
│   └── user_management/  # Enterprise RBAC system
├── tests/               # 2,400+ tests (100% pass rate)
├── docs/                # Comprehensive documentation
└── examples/            # Feature validation examples
```

## 🚀 Quick Start

### Installation Options

```bash
# Core SDK only
pip install kailash

# With complete app frameworks
pip install kailash[dataflow,nexus]  # Database + multi-channel
pip install kailash[all]             # Everything

# Or install apps directly
pip install kailash-dataflow  # Zero-config database framework
pip install kailash-nexus     # Multi-channel platform
```

### DataFlow: Zero-Config Database Operations

```python
from dataflow import DataFlow

# Zero-configuration database operations
app = DataFlow()

# MongoDB-style queries across any database
users = app.query("users").where({"age": {"$gt": 18}}).limit(10)

# Redis-powered caching with smart invalidation
cached_result = app.cache().get("user_stats",
    lambda: app.query("users").aggregate([
        {"$group": {"_id": "$department", "count": {"$sum": 1}}}
    ])
)

# Start enterprise API server
app.start()  # Automatic API generation, monitoring, health checks
```

### Nexus: Multi-Channel Platform

```python
from nexus import Nexus

# Single codebase → API + CLI + MCP
app = Nexus()

# Register workflow once, available on all channels
@app.workflow
def process_data(input_data):
    return {"processed": len(input_data)}

# Zero-config startup
app.start()

# Now available as:
# - REST API: POST /workflows/process_data
# - CLI: nexus run process_data
# - MCP: AI agents can call process_data tool
```

### A2A Multi-Agent Coordination

```python
from kailash.workflow.builder import WorkflowBuilder
from kailash.runtime.local import LocalRuntime

# Build A2A coordination workflow
workflow = WorkflowBuilder()
workflow.add_node("A2ACoordinatorNode", "coordinator", {
    "use_google_protocol": True,
    "enable_semantic_memory": True,
    "delegation_strategy": "skill_based"
})
workflow.add_node("HybridSearchNode", "discovery", {
    "strategies": ["semantic", "keyword", "skill_based"],
    "adaptive_optimization": True
})
workflow.add_node("SemanticMemoryNode", "memory", {
    "embedding_provider": "openai",
    "memory_type": "long_term",
    "context_window": 8192
})

# Connect for intelligent agent coordination
workflow.add_connection("coordinator", "discovery", "agent_request", "search_query")
workflow.add_connection("discovery", "memory", "agent_matches", "context")

# Execute with enterprise monitoring
runtime = LocalRuntime()
results, run_id = runtime.execute(workflow.build())
```

## 🎯 Key Features

### 🧪 **Testing Excellence**
- **2,400+ tests** with 100% pass rate
- **11x performance improvement** (117s → 10.75s execution)
- **Docker integration** for real PostgreSQL, Redis, MongoDB
- **Smart isolation** without process forking overhead

### 🏢 **Enterprise Ready**
- **Multi-tenant architecture** with complete isolation
- **RBAC/ABAC security** with fine-grained permissions
- **Audit logging** with compliance frameworks (GDPR, CCPA)
- **Distributed transactions** with Saga/2PC patterns
- **Circuit breaker** and resilience patterns

### 🤖 **AI Integration**
- **115+ production nodes** including 47+ specialized RAG nodes
- **Real MCP execution** by default for all AI agents
- **Self-organizing agent pools** with intelligent coordination
- **Complete LLM integration** with embeddings and vector search

### ⚡ **Performance & Scale**
- **31.8M operations/second** query performance baseline
- **Connection pooling** with automatic resource management
- **Redis caching** with intelligent invalidation patterns
- **Async/await** throughout with proper separation

## 🏗️ Node Ecosystem (115+ Nodes)

### Core Categories
- **Data Nodes**: CSVReaderNode, AsyncSQLDatabaseNode, QueryBuilderNode, QueryCacheNode
- **AI Nodes**: LLMAgentNode, IterativeLLMAgentNode, EmbeddingGeneratorNode, SelfOrganizingAgentNode
- **A2A Nodes**: A2ACoordinatorNode, HybridSearchNode, AdaptiveSearchNode, SemanticMemoryNode, StreamingAnalyticsNode
- **RAG Nodes**: 47+ specialized nodes for document processing and retrieval
- **Security Nodes**: ThreatDetectionNode, AuditLogNode, AccessControlManager
- **Monitoring Nodes**: TransactionMetricsNode, DeadlockDetectorNode, PerformanceAnomalyNode
- **Transaction Nodes**: DistributedTransactionManagerNode, SagaCoordinatorNode

### Advanced Features
- **A2A Communication**: Google Protocol-based multi-agent coordination
- **Semantic Memory**: Long-term memory management for agent interactions
- **Hybrid Search**: Multi-strategy agent discovery and matching
- **Cyclic Workflows**: CycleBuilder API with convergence detection
- **Distributed Transactions**: Automatic Saga/2PC pattern selection
- **Real-time Monitoring**: WebSocket streaming with performance metrics
- **Enterprise Security**: Multi-factor auth, threat detection, compliance

## 📊 Performance Metrics

### Recent Achievements
- **11x faster test execution**: 117s → 10.75s with smart isolation
- **100% test pass rate**: 2,400+ tests across all categories
- **31.8M operations/second**: Query performance baseline
- **30,000+ iterations/second**: Cyclic workflow execution

### Enterprise Benchmarks
- **Query Cache**: 99.9% hit rate with intelligent invalidation
- **Connection Pooling**: 10,000+ concurrent connections
- **MCP Integration**: 407 tests with 100% pass rate
- **Security**: Zero vulnerabilities in production deployment

## 🚀 Applications Built with Kailash

### 1. DataFlow - Zero-Config Database Platform
```bash
pip install kailash-dataflow
```
- **MongoDB-style queries** across PostgreSQL, MySQL, SQLite
- **Redis caching** with enterprise-grade invalidation
- **Automatic API generation** with OpenAPI documentation
- **4 production examples** with complete deployment guides

### 2. Nexus - Multi-Channel Platform
```bash
pip install kailash-nexus
```
- **Unified API, CLI, and MCP** from single codebase
- **Enterprise orchestration** with multi-tenancy
- **Session management** with cross-channel synchronization
- **105 tests** with comprehensive validation

### 3. AI Registry - Advanced RAG Platform
```bash
pip install kailash-ai-registry
```
- **47+ specialized RAG nodes** for document processing
- **Advanced retrieval** with semantic search and re-ranking
- **Multi-modal support** with image and text processing
- **Enterprise deployment** with scalable architecture

### 4. User Management - Enterprise RBAC
```bash
pip install kailash-user-management
```
- **Complete RBAC system** with role hierarchy
- **Multi-factor authentication** with enterprise integration
- **Audit logging** with compliance frameworks
- **Django-style capabilities** built on SDK architecture

## 🧪 Testing & Quality

### Comprehensive Test Suite
```bash
# All tests (2,400+ tests)
pytest

# Fast unit tests (11x faster execution)
pytest tests/unit/ --timeout=1

# Integration tests with Docker
pytest tests/integration/ --timeout=5

# End-to-end scenarios
pytest tests/e2e/ --timeout=10
```

### Test Infrastructure
- **Docker Integration**: Real PostgreSQL, Redis, MongoDB for testing
- **Smart Isolation**: Fixture-based isolation without process forking
- **Performance Monitoring**: Automated benchmarks and regression detection
- **100% Pass Rate**: Comprehensive fixes across all test categories

## 🛡️ Security & Compliance

### Enterprise Security
- **Multi-factor Authentication**: TOTP, WebAuthn, SMS integration
- **Threat Detection**: Real-time analysis with behavior monitoring
- **Access Control**: Fine-grained RBAC/ABAC with policy engines
- **Audit Logging**: Comprehensive trails with integrity verification

### Compliance Frameworks
- **GDPR/CCPA**: Built-in data protection and privacy controls
- **SOX**: Financial reporting controls and audit trails
- **HIPAA**: Healthcare data protection patterns
- **Multi-tenant Isolation**: Complete tenant-aware operations

## 📚 Documentation & Resources

### For Users
- **[SDK Users Guide](sdk-users/)**: Complete workflow development guide
- **[Node Selection Guide](sdk-users/nodes/node-selection-guide.md)**: Smart node selection with decision trees
- **[Enterprise Patterns](sdk-users/enterprise/)**: Production deployment patterns
- **[API Documentation](https://integrum.github.io/kailash-python-sdk)**: Complete API reference

### For Contributors
- **[SDK Contributors Guide](sdk-contributors/)**: Internal SDK development
- **[Architecture Decisions](sdk-contributors/architecture/)**: ADRs and design decisions
- **[Testing Guide](tests/README.md)**: 3-tier testing strategy

### Quick References
- **[Cheatsheet](sdk-users/cheatsheet/)**: 53 copy-paste patterns
- **[Common Mistakes](sdk-users/validation/common-mistakes.md)**: Error patterns and solutions
- **[Performance Guide](sdk-users/performance/)**: Optimization patterns

## 🚢 Production Deployment

### Container Deployment
```bash
# Export workflow to container format
python -c "
from kailash.utils.export import export_workflow
export_workflow(workflow, 'production.yaml', format='kailash')
"

# Deploy to Kailash platform
kailash deploy production.yaml --environment prod
```

### Monitoring & Observability
```python
from kailash.visualization import DashboardServer

# Real-time monitoring dashboard
server = DashboardServer(port=8080)
server.start()
# Open http://localhost:8080 for live metrics
```

### Enterprise Features
- **Multi-tenant deployment** with complete isolation
- **Distributed transactions** with automatic recovery
- **Circuit breaker patterns** for resilience
- **Health monitoring** with automated alerting

## 🤝 Contributing

We use a **Claude Code-driven workflow** for all development:

### New Team Member?
**Start Here → [NEW_TEAM_MEMBER.md](NEW_TEAM_MEMBER.md)**

### Development Workflow
```bash
# Clone and setup
git clone https://github.com/integrum/kailash-python-sdk.git
cd kailash-python-sdk
uv sync

# Run tests (2,400+ tests)
pytest tests/unit/ --timeout=1      # Fast unit tests
pytest tests/integration/ --timeout=5  # Integration tests
pytest tests/e2e/ --timeout=10     # End-to-end tests

# Code quality
black .
isort .
ruff check .
```

### Claude Code Workflow
All project management through conversational AI:
- **No manual TODO editing** - Claude Code handles all updates
- **No direct GitHub issues** - Created through planning sessions
- **All progress tracked** - Through natural conversation

See [Contributing Guide](CONTRIBUTING.md) and [sdk-contributors/CLAUDE.md](sdk-contributors/CLAUDE.md).

## 📈 Project Status

### ✅ v0.8.4 - A2A Google Protocol Enhancement
- **Advanced Agent Coordination**: A2ACoordinatorNode with Google Protocol patterns
- **Hybrid Search System**: Multi-strategy agent discovery and matching
- **Semantic Memory**: Long-term memory management for agent interactions
- **Real-time Analytics**: Streaming performance monitoring for A2A workflows
- **Backward Compatible**: Seamless integration with existing implementations
- **Production Ready**: Enterprise-grade multi-agent coordination patterns

### ✅ v0.8.1 - Complete App Framework
- **Complete Application Framework**: DataFlow, Nexus, AI Registry, User Management
- **PyPI Integration**: All packages available with proper extras support
- **Performance Breakthrough**: 11x faster test execution
- **Testing Excellence**: 2,400+ tests with 100% pass rate
- **Enterprise Ready**: Production deployment patterns

### ✅ v0.7.0 - Major Framework Release
- **DataFlow Platform**: Zero-config database operations
- **Nexus Platform**: Multi-channel orchestration
- **AI Registry**: Advanced RAG capabilities
- **User Management**: Enterprise RBAC system
- **Testing Infrastructure**: Docker integration, comprehensive validation

### 🚧 Roadmap
- **Visual Workflow Builder**: Studio UI for drag-and-drop workflow creation
- **Advanced Analytics**: ML-powered workflow optimization
- **Cloud Integration**: Native AWS/GCP/Azure deployment
- **Mobile SDKs**: iOS and Android workflow execution

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Built with ❤️ by the Integrum team for the Kailash ecosystem.

Special recognition for the **11x performance breakthrough** and **100% test pass rate** achieved through innovative engineering and comprehensive testing strategies.

---

<p align="center">
  <strong>Ready to build enterprise-grade applications?</strong><br>
  <a href="https://pypi.org/project/kailash/">Install from PyPI</a> •
  <a href="sdk-users/README.md">Documentation</a> •
  <a href="examples/">Examples</a> •
  <a href="https://github.com/integrum/kailash-python-sdk">GitHub</a>
</p>
