| Name | cans-framework JSON |
| Version |
3.1.4
JSON |
| download |
| home_page | https://github.com/rdmurugan/cans-framework |
| Summary | A production-ready deep learning framework for causal inference on structured, textual, and heterogeneous data |
| upload_time | 2025-09-10 04:31:33 |
| maintainer | None |
| docs_url | None |
| author | Durai Rajamanickam |
| requires_python | >=3.8 |
| license | CANS Framework Custom License
Copyright (c) 2024 Durai Murugan (durai@infinidatum.net)
CANS (Causal Adaptive Neural System) Framework License Agreement
GRANT OF LICENSE
Subject to the terms and conditions of this License, the copyright holder hereby grants you a worldwide, royalty-free, non-exclusive license to use, copy, modify, merge, publish, and distribute the CANS Framework software and associated documentation files (the "Software") under the following conditions:
PERMITTED USES
1. ACADEMIC AND RESEARCH USE
- You may use the Software for academic research, educational purposes, and non-commercial scientific studies.
- You may modify and distribute the Software for research collaboration and academic publication.
- Students, researchers, and academic institutions may use the Software freely for learning and research purposes.
2. PERSONAL AND NON-COMMERCIAL USE
- You may use the Software for personal projects and non-commercial experimentation.
- You may use the Software to learn causal inference techniques and deep learning methods.
RESTRICTED USES
3. COMMERCIAL USE RESTRICTIONS
- Any use of the Software for commercial purposes, including but not limited to:
* Integration into commercial products or services
* Use in business operations or commercial decision-making
* Offering consulting services using the Software
* Creating derivative works for commercial distribution
* Using the Software to generate revenue or commercial advantage
- Requires explicit written permission from the copyright holder.
4. WRITTEN PERMISSION REQUIREMENT
- To obtain permission for commercial use, contact: durai@infinidatum.net
- Commercial licenses will be granted on a case-by-case basis and may include:
* License fees or royalty arrangements
* Support and maintenance agreements
* Specific terms tailored to the commercial use case
- Written permission must be obtained BEFORE any commercial use begins.
CONDITIONS AND LIMITATIONS
5. ATTRIBUTION REQUIREMENT
- You must retain all copyright notices and this license text in all copies.
- Any academic publication or research paper using the Software must cite:
"CANS Framework by Durai Murugan (https://github.com/rdmurugan/cans-framework)"
6. NO WARRANTY
- The Software is provided "AS IS" without warranty of any kind.
- The copyright holder disclaims all warranties, express or implied.
- You assume all risks associated with the use of the Software.
7. LIMITATION OF LIABILITY
- In no event shall the copyright holder be liable for any damages arising from the use of the Software.
- This limitation applies to all claims, whether based on warranty, contract, tort, or any other legal theory.
8. DISTRIBUTION TERMS
- You may distribute copies of the Software provided that:
* This license is included with all copies
* No commercial use restrictions are violated
* Recipients are bound by the same license terms
9. MODIFICATION AND DERIVATIVE WORKS
- You may create derivative works for permitted uses only.
- Derivative works must be clearly identified and carry this same license.
- Commercial distribution of derivative works requires written permission.
10. TERMINATION
- This license automatically terminates if you violate any of its terms.
- Upon termination, you must cease all use and destroy all copies of the Software.
- Commercial permission may be revoked for cause with 30 days written notice.
ENFORCEMENT AND INTERPRETATION
11. GOVERNING LAW
- This license shall be governed by the laws of the jurisdiction where the copyright holder resides.
- Any disputes shall be resolved through binding arbitration or appropriate courts.
12. SEVERABILITY
- If any provision of this license is held invalid, the remainder shall continue in full force and effect.
13. ENTIRE AGREEMENT
- This license constitutes the entire agreement between you and the copyright holder regarding the Software.
- Modifications to this license must be in writing and signed by the copyright holder.
CONTACT INFORMATION
For commercial licensing inquiries, technical support, or questions about this license:
Email: durai@infinidatum.net
GitHub: https://github.com/rdmurugan/cans-framework
By using the Software, you acknowledge that you have read, understood, and agree to be bound by the terms and conditions of this License.
---
CANS Framework - Causal Adaptive Neural System
Advancing causal inference through deep learning innovation. |
| keywords |
causal-inference
deep-learning
graph-neural-networks
transformers
counterfactual
treatment-effects
machine-learning
pytorch
bert
gnn
causal-ai
econometrics
statistics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
torch
transformers
torch-geometric
scikit-learn
pandas
numpy
tqdm
networkx
matplotlib
seaborn
plotly
scipy
statsmodels
PyYAML
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🧠 CANS: Causal Adaptive Neural System
[](https://badge.fury.io/py/cans-framework)
[](LICENSE)
[](https://pypi.org/project/cans-framework/)
[](https://github.com/rdmurugan/cans-framework/stargazers)
> **Production-ready causal inference at scale with deep learning, APIs, and LLM integration**
**CANS (Causal Adaptive Neural System)** is the most comprehensive **production-ready framework** for **causal inference** using deep learning. It combines **Graph Neural Networks (GNNs)**, **Transformers**, **Counterfactual Regression Networks (CFRNet)**, and **advanced causal methods** with enterprise-grade **APIs** and **LLM integration**.
🎯 **Perfect for**: Healthcare, Finance, Marketing, Legal, Social Media, E-commerce, and any domain requiring **rigorous causal analysis**
## 🌟 What Makes CANS Unique
- 🧠 **Hybrid AI Architecture**: GNNs + Transformers + CFRNet for complex data
- 🔬 **Rigorous Causal Science**: Automated assumption testing, multiple identification strategies
- 🌐 **Production APIs**: REST API + MCP server for seamless integration
- 🤖 **LLM Integration**: Enable AI assistants to perform causal analysis autonomously
- ⚡ **Enterprise Ready**: Authentication, monitoring, scalable deployment
- 📊 **Comprehensive Toolkit**: CLI, Python API, web integration, notebooks
## 🚀 Choose Your Interface
| Interface | Best For | Getting Started |
|-----------|----------|-----------------|
| 📚 **Interactive Tutorials** | Learning, first-time users | `cans-tutorials` → hands-on guided learning |
| 🖥️ **CLI Tools** | Quick analysis, data scientists | `cans-validate --data data.csv --treatment T --outcome Y` |
| 🐍 **Python API** | Research, notebooks, pipelines | `from cans import CANS, validate_causal_assumptions` |
| 🌐 **REST API** | Web apps, microservices | `POST /validate` → JSON response |
| 🤖 **MCP Server** | LLMs, AI assistants | Claude/GPT calls `validate_causal_assumptions_tool` |
## 📊 Usage Matrix
| Task | CLI | Python | REST API | MCP/LLM |
|------|-----|--------|----------|---------|
| **Assumption Validation** | `cans-validate` | `validate_causal_assumptions()` | `POST /validate` | `validate_causal_assumptions_tool` |
| **Complete Analysis** | `cans-analyze` | `CANSRunner.fit()` | `POST /analyze` | `quick_causal_analysis` |
| **Model Evaluation** | `cans-evaluate` | `CausalEvaluator.evaluate()` | `POST /evaluate` | `evaluate_predictions` |
| **Batch Processing** | Shell scripting | `for` loops | HTTP requests | LLM automation |
| **Production Deployment** | Cron jobs | Python services | Kubernetes | AI workflows |
## 🚀 What's New in v3.0 - Production-Ready Causal AI
### 🔬 Advanced Causal Methods
- **Assumption Testing**: Automated unconfoundedness, positivity, and SUTVA validation
- **Multiple Identification**: Backdoor criterion, IPW, doubly robust estimation
- **CATE Estimation**: X-Learner, T-Learner, S-Learner, Neural CATE, Causal Forest
- **Uncertainty Quantification**: Bayesian methods, ensemble approaches, conformal prediction
### 🌐 Enterprise Integration
- **REST API**: Complete HTTP API with authentication and rate limiting
- **MCP Server**: Model Context Protocol for seamless LLM integration
- **Production Tools**: Docker, Kubernetes, monitoring, logging
- **Multi-language**: Python, JavaScript, R, cURL examples
### 🧠 Enhanced AI Architecture
- **Advanced Graph Construction**: Multi-node, temporal, and global architectures
- **Causal-Specific Losses**: CFR, IPW, DragonNet, TARNet with representation balancing
- **Memory Efficiency**: Lazy loading and batch processing for large datasets
- **GPU Optimization**: CUDA support with automatic device selection
### Previous v2.0 Features:
- 🔧 **Configuration Management**: Centralized, validated configs with JSON/YAML support
- 🛡️ **Enhanced Error Handling**: Comprehensive validation with informative error messages
- 📊 **Logging & Checkpointing**: Built-in experiment tracking with automatic model saving
- 🧪 **Comprehensive Testing**: 100+ unit tests ensuring production reliability
- 📈 **Advanced Data Pipeline**: Multi-format loading (CSV, JSON) with automatic preprocessing
- ⚡ **Enhanced Training**: Early stopping, gradient clipping, multiple loss functions
## 🔧 Key Features
### Core Architecture
- ✅ **Hybrid Neural Architecture**: GNNs + Transformers + CFRNet for multi-modal causal inference
- ✅ **Gated Fusion Layer**: Adaptive mixing of graph and textual representations
- ✅ **Flexible Graph Construction**: Single-node, multi-node, temporal, and global graphs
- ✅ **Production-Ready**: Comprehensive error handling, logging, and testing
### Causal Inference Capabilities
- ✅ **Rigorous Assumption Testing**: Automated validation of causal identification conditions
- ✅ **Multiple Identification Methods**: Backdoor, IPW, doubly robust, with sensitivity analysis
- ✅ **Heterogeneous Treatment Effects**: CATE estimation with 5+ methods (X/T/S-Learners, etc.)
- ✅ **Advanced Loss Functions**: CFR, DragonNet, TARNet with representation balancing
- ✅ **Uncertainty Quantification**: Bayesian, ensemble, conformal prediction approaches
### Data Processing & Evaluation
- ✅ **Smart Data Loading**: CSV, JSON, synthetic data with automatic graph construction
- ✅ **Comprehensive Evaluation**: PEHE, ATE, policy value, calibration metrics
- ✅ **Memory Efficiency**: Lazy loading, batch processing for large-scale datasets
- ✅ **Easy Configuration**: JSON/YAML configs with validation and experiment tracking
## 🏗️ Architecture
```
+-----------+ +-----------+
| GNN Emb | | BERT Emb |
+-----------+ +-----------+
\ /
\ Fusion Layer /
\ /
+-----------+
| Fused Rep |
+-----------+
|
CFRNet
/ \
mu_0(x) mu_1(x)
```
## 🚀 Enhanced Causal Analysis Workflow
### Complete Example with Assumption Testing & CATE Estimation
```python
from cans import (
CANSConfig, CANS, GCN, CANSRunner,
create_sample_dataset, get_data_loaders,
CausalAssumptionTester, CausalLossManager,
CATEManager, UncertaintyManager,
advanced_counterfactual_analysis
)
# 1. Configuration with enhanced causal features
config = CANSConfig()
config.model.gnn_type = "GCN"
config.training.loss_type = "cfr" # Causal loss function
config.data.graph_construction = "global" # Multi-node graphs
# 2. Test causal assumptions BEFORE modeling
assumption_tester = CausalAssumptionTester()
results = assumption_tester.comprehensive_test(X, T, Y)
print(f"Causal assumptions valid: {results['causal_identification_valid']}")
# 3. Create datasets with enhanced graph construction
datasets = create_sample_dataset(n_samples=1000, config=config.data)
train_loader, val_loader, test_loader = get_data_loaders(datasets)
# 4. Setup model with causal loss functions
from transformers import BertModel
gnn = GCN(in_dim=64, hidden_dim=128, output_dim=256)
bert = BertModel.from_pretrained("distilbert-base-uncased")
model = CANS(gnn, bert, fusion_dim=256)
loss_manager = CausalLossManager("cfr", alpha=1.0, beta=0.5)
# 5. Train with causal-aware pipeline
optimizer = torch.optim.AdamW(model.parameters(), lr=0.001)
runner = CANSRunner(model, optimizer, config)
history = runner.fit(train_loader, val_loader)
# 6. Multiple counterfactual identification methods
cf_results = advanced_counterfactual_analysis(
model, test_loader,
methods=['backdoor', 'ipw', 'doubly_robust']
)
# 7. CATE estimation with multiple learners
cate_manager = CATEManager(method="x_learner")
cate_manager.fit(X, T, Y)
individual_effects = cate_manager.estimate_cate(X_test)
# 8. Uncertainty quantification
uncertainty_manager = UncertaintyManager(method="conformal")
uncertainty_manager.setup(model)
intervals = uncertainty_manager.estimate_uncertainty(test_loader)
print(f"ATE: {cf_results['backdoor']['ate']:.3f}")
print(f"Coverage: {intervals['coverage_rate']:.3f}")
```
## 🚀 Quick Start
> 🎯 **New to CANS?** Start with our [**Getting Started Guide**](GETTING_STARTED.md) for a 5-minute tutorial!
### Installation
```bash
# Install from PyPI (Recommended)
pip install cans-framework
# Verify installation and set up tutorials
pip show cans-framework
cans-tutorials # Sets up interactive learning environment
```
### Alternative Installation Methods
```bash
# Development installation
git clone https://github.com/rdmurugan/cans-framework.git
cd cans-framework
pip install -r requirements.txt
pip install -e .
# With conda (for dependency management)
conda create -n cans python=3.9
conda activate cans
pip install cans-framework
```
**Core Dependencies:**
- `torch>=2.0.0`
- `transformers>=4.38.0`
- `torch-geometric>=2.3.0`
- `scikit-learn>=1.3.0`
- `pandas>=2.0.0`
### Basic Usage (30 seconds to results)
```python
from cans.config import CANSConfig
from cans.utils.data import create_sample_dataset, get_data_loaders
from cans.models import CANS
from cans.models.gnn_modules import GCN
from cans.pipeline.runner import CANSRunner
from transformers import BertModel
import torch
# 1. Create configuration
config = CANSConfig()
config.training.epochs = 10
# 2. Load data (or create sample data)
datasets = create_sample_dataset(n_samples=1000, n_features=64)
train_loader, val_loader, test_loader = get_data_loaders(datasets, batch_size=32)
# 3. Create model
gnn = GCN(in_dim=64, hidden_dim=128, output_dim=256)
bert = BertModel.from_pretrained("bert-base-uncased")
model = CANS(gnn, bert, fusion_dim=256)
# 4. Train
optimizer = torch.optim.AdamW(model.parameters(), lr=0.001)
runner = CANSRunner(model, optimizer, config)
history = runner.fit(train_loader, val_loader)
# 5. Evaluate
results = runner.evaluate(test_loader)
print(f"Test MSE: {results['mse']:.4f}")
print(f"Average Treatment Effect: {results['ate']:.4f}")
```
## 🖥️ Command Line Interface (CLI)
CANS provides six powerful CLI commands for complete causal analysis workflow:
> 💡 **New to CANS?** Check out our comprehensive [User Guide](USER_GUIDE.md) for step-by-step tutorials, troubleshooting, and best practices!
### 1. Validate Causal Assumptions (`cans-validate`)
Test critical causal assumptions before modeling:
```bash
# Basic usage
cans-validate --data data.csv --treatment intervention --outcome conversion_rate
# Specify features explicitly
cans-validate --data marketing_data.csv \
--treatment campaign_type \
--outcome revenue \
--features age,income,education,region \
--output validation_results.json \
--verbose
# Example output:
# {
# "unconfoundedness_test": {
# "valid": true,
# "p_value": 0.23,
# "method": "backdoor_criterion"
# },
# "positivity_test": {
# "valid": true,
# "overlap_score": 0.85,
# "min_propensity": 0.05
# },
# "sutva_test": {
# "valid": true,
# "interference_score": 0.02
# }
# }
```
### 2. Evaluate Model Performance (`cans-evaluate`)
Assess causal model predictions:
```bash
# Evaluate predictions file with columns: mu0, mu1, treatments, outcomes
cans-evaluate --predictions model_predictions.csv --format json
# Save detailed evaluation report
cans-evaluate --predictions predictions.csv \
--output evaluation_report.txt \
--format text
# Example output metrics:
# - Average Treatment Effect (ATE): 2.34 ± 0.18
# - Factual MSE: 0.045
# - PEHE (Precision in Estimation of Heterogeneous Effects): 0.12
# - Individual Treatment Effect R²: 0.73
```
### 3. Complete Causal Analysis (`cans-analyze`)
Run end-to-end causal inference workflow:
```bash
# Quick analysis with default configuration
cans-analyze --data patient_data.csv --output-dir results/
# Use custom configuration
cans-analyze --data social_media.csv \
--config custom_config.json \
--output-dir social_analysis/
# Creates structured output:
# results/
# ├── assumptions_validation.json
# ├── model_performance.json
# ├── causal_effects_summary.json
# ├── individual_effects.csv
# └── analysis_report.html
```
### 4. Interactive Tutorials (`cans-tutorials`)
Set up hands-on tutorials in your workspace:
```bash
# Create tutorial workspace in current directory
cans-tutorials
# Specify custom directory
cans-tutorials --dir my-learning-space
# List available tutorials
cans-tutorials --list
# Creates structured tutorial environment:
# cans-tutorials/
# ├── README.md # Quick start guide
# ├── TUTORIALS.md # Complete documentation
# ├── tutorial_01_first_steps.py # Basic introduction
# ├── tutorial_02_data_understanding.py # Advanced data handling
# └── examples/
# └── sample_marketing_data.csv # Practice dataset
```
**Tutorial Features:**
- 🎯 **Interactive Learning**: Step-by-step Python scripts with detailed explanations
- 📊 **Sample Data**: Real-world-like datasets for immediate practice
- 🔬 **Progressive Complexity**: From basics to advanced causal inference
- 💡 **Best Practices**: Learn proper workflow and methodology
- 🛠️ **Editable Copies**: Modify and experiment with tutorial code
### 5. API Server (`cans-server`)
Start production-ready REST API:
```bash
# Start API server
cans-server
# Interactive docs at: http://localhost:8000/docs
```
### 6. LLM Integration (`cans-mcp`)
Enable AI assistants to perform causal analysis:
```bash
# Start MCP server for LLM integration
cans-mcp
# Enables Claude, GPT, and other LLMs to use CANS autonomously
```
### CLI Configuration Files
Create reusable configuration files for complex analyses:
```json
{
"model": {
"gnn_type": "GCN",
"gnn_hidden_dim": 128,
"fusion_dim": 256,
"text_model": "distilbert-base-uncased"
},
"training": {
"learning_rate": 0.001,
"batch_size": 64,
"epochs": 50,
"loss_type": "cfr"
},
"data": {
"graph_construction": "knn",
"knn_k": 5,
"scale_node_features": true
}
}
```
## 📊 Usage Examples
### Example 1: CSV Data with Real Causal Inference
```python
from cans.utils.data import load_csv_dataset
from cans.config import CANSConfig, DataConfig
# Configure data processing
config = CANSConfig()
config.data.graph_construction = "knn" # or "similarity"
config.data.knn_k = 5
config.data.scale_node_features = True
# Load your CSV data
datasets = load_csv_dataset(
csv_path="your_data.csv",
text_column="review_text", # Column with text data
treatment_column="intervention", # Binary treatment (0/1)
outcome_column="conversion_rate", # Continuous outcome
feature_columns=["age", "income", "education"], # Numerical features
config=config.data
)
train_dataset, val_dataset, test_dataset = datasets
# Check data quality
stats = train_dataset.get_statistics()
print(f"Treatment proportion: {stats['treatment_proportion']:.3f}")
print(f"Propensity overlap valid: {stats['propensity_overlap_valid']}")
```
### Example 2: Advanced Configuration & Experiment Tracking
```python
from cans.config import CANSConfig
# Create detailed configuration
config = CANSConfig()
# Model configuration
config.model.gnn_type = "GCN"
config.model.gnn_hidden_dim = 256
config.model.fusion_dim = 512
config.model.text_model = "distilbert-base-uncased" # Faster BERT variant
# Training configuration
config.training.learning_rate = 0.001
config.training.batch_size = 64
config.training.epochs = 50
config.training.early_stopping_patience = 10
config.training.gradient_clip_norm = 1.0
config.training.loss_type = "huber" # Robust to outliers
# Experiment tracking
config.experiment.experiment_name = "healthcare_causal_analysis"
config.experiment.save_every_n_epochs = 5
config.experiment.log_level = "INFO"
# Save configuration for reproducibility
config.save("experiment_config.json")
# Later: load and use
loaded_config = CANSConfig.load("experiment_config.json")
```
### Example 3: Counterfactual Analysis & Treatment Effects
```python
from cans.utils.causal import simulate_counterfactual
import numpy as np
# After training your model...
runner = CANSRunner(model, optimizer, config)
runner.fit(train_loader, val_loader)
# Comprehensive evaluation
test_metrics = runner.evaluate(test_loader)
print("Performance Metrics:")
for metric, value in test_metrics.items():
print(f" {metric}: {value:.4f}")
# Counterfactual analysis
cf_control = simulate_counterfactual(model, test_loader, intervention=0)
cf_treatment = simulate_counterfactual(model, test_loader, intervention=1)
# Calculate causal effects
ate = np.mean(cf_treatment) - np.mean(cf_control)
print(f"\nCausal Analysis:")
print(f"Average Treatment Effect (ATE): {ate:.4f}")
print(f"Expected outcome under control: {np.mean(cf_control):.4f}")
print(f"Expected outcome under treatment: {np.mean(cf_treatment):.4f}")
# Individual treatment effects
individual_effects = np.array(cf_treatment) - np.array(cf_control)
print(f"Treatment effect std: {np.std(individual_effects):.4f}")
print(f"% benefiting from treatment: {(individual_effects > 0).mean()*100:.1f}%")
```
### Example 4: Custom Data Pipeline
```python
from cans.utils.preprocessing import DataPreprocessor, GraphBuilder
from cans.config import DataConfig
import pandas as pd
# Custom preprocessing pipeline
config = DataConfig()
config.graph_construction = "similarity"
config.similarity_threshold = 0.7
config.scale_node_features = True
preprocessor = DataPreprocessor(config)
# Process your DataFrame
df = pd.read_csv("social_media_posts.csv")
dataset = preprocessor.process_tabular_data(
data=df,
text_column="post_content",
treatment_column="fact_check_label",
outcome_column="share_count",
feature_columns=["user_followers", "post_length", "sentiment_score"],
text_model="bert-base-uncased",
max_text_length=256
)
# Split with custom ratios
train_ds, val_ds, test_ds = preprocessor.split_dataset(
dataset,
train_size=0.7,
val_size=0.2,
test_size=0.1
)
```
## 🧪 Testing & Development
```bash
# Run all tests
pytest tests/ -v
# Run specific test categories
pytest tests/test_models.py -v # Model tests
pytest tests/test_validation.py -v # Validation tests
pytest tests/test_pipeline.py -v # Training pipeline tests
# Run with coverage
pytest tests/ --cov=cans --cov-report=html
# Run example scripts
python examples/enhanced_usage_example.py
python examples/enhanced_causal_analysis_example.py
```
## 📁 Framework Structure
```
cans-framework/
├── cans/
│ ├── __init__.py # Main imports
│ ├── config.py # ✨ Configuration management
│ ├── exceptions.py # ✨ Custom exceptions
│ ├── validation.py # ✨ Data validation utilities
│ ├── models/
│ │ ├── cans.py # Core CANS model (enhanced)
│ │ └── gnn_modules.py # GNN implementations
│ ├── pipeline/
│ │ └── runner.py # ✨ Enhanced training pipeline
│ └── utils/
│ ├── causal.py # Counterfactual simulation
│ ├── data.py # ✨ Enhanced data loading
│ ├── preprocessing.py # ✨ Advanced preprocessing
│ ├── logging.py # ✨ Structured logging
│ └── checkpointing.py # ✨ Model checkpointing
├── tests/ # ✨ Comprehensive test suite
├── examples/ # Usage examples
└── CLAUDE.md # Development guide
```
**✨ = New/Enhanced in v2.0**
## 🎯 Use Cases & Applications
### Healthcare & Medical
```python
# Analyze treatment effectiveness with patient records + clinical notes
datasets = load_csv_dataset(
csv_path="patient_outcomes.csv",
text_column="clinical_notes",
treatment_column="medication_type",
outcome_column="recovery_score",
feature_columns=["age", "bmi", "comorbidities"]
)
```
### Marketing & A/B Testing
```python
# Marketing campaign effectiveness with customer profiles + ad content
datasets = load_csv_dataset(
csv_path="campaign_data.csv",
text_column="ad_content",
treatment_column="campaign_variant",
outcome_column="conversion_rate",
feature_columns=["customer_ltv", "demographics", "behavior_score"]
)
```
### Social Media & Content Moderation
```python
# Impact of content moderation on engagement
datasets = load_csv_dataset(
csv_path="posts_data.csv",
text_column="post_text",
treatment_column="moderation_action",
outcome_column="engagement_score",
feature_columns=["user_followers", "post_length", "sentiment"]
)
```
## 🔬 Research & Methodology
CANS implements state-of-the-art causal inference techniques:
- **Counterfactual Regression Networks (CFRNet)**: Learn representations that minimize treatment assignment bias
- **Gated Fusion**: Adaptively combine graph-structured and textual information
- **Balanced Representation**: Minimize distributional differences between treatment groups
- **Propensity Score Validation**: Automatic overlap checking for reliable causal estimates
**Key Papers:**
- Shalit et al. "Estimating individual treatment effect: generalization bounds and algorithms" (ICML 2017)
- Yao et al. "Representation learning for treatment effect estimation from observational data" (NeurIPS 2018)
## 🚀 Performance & Scalability
- **Memory Efficient**: Optimized batch processing and gradient checkpointing
- **GPU Acceleration**: Full CUDA support with automatic device selection
- **Parallel Processing**: Multi-core data loading and preprocessing
- **Production Ready**: Comprehensive error handling and logging
**Benchmarks** (approximate, hardware-dependent):
- **Small**: 1K samples, 32 features → ~30 sec training
- **Medium**: 100K samples, 128 features → ~10 min training
- **Large**: 1M+ samples → Scales with batch size and hardware
## 🌐 API & Integration
CANS provides comprehensive API access for integration with web applications, services, and AI systems:
### REST API Server
```bash
# Start REST API server
cans-server
# or
uvicorn cans.api.server:app --host 0.0.0.0 --port 8000
# Interactive docs at: http://localhost:8000/docs
```
### MCP Server for LLMs
```bash
# Start MCP server for LLM integration
cans-mcp
# Enables LLMs to directly perform causal analysis
```
### Python API Client
```python
from cans.api.client import CANSAPIClient
client = CANSAPIClient(api_key="your-key")
results = client.validate_assumptions(
data="data.csv",
treatment_column="treatment",
outcome_column="outcome"
)
```
**🔗 API Features:**
- RESTful endpoints for all CANS functionality
- Model Context Protocol (MCP) server for LLM integration
- Authentication and rate limiting
- Async/await support
- Comprehensive error handling
- Interactive documentation
**📖 Learn More:** [API Guide](API_GUIDE.md)
## 📚 Documentation & Resources
### 📚 Documentation Hierarchy
1. **Interactive Tutorials** (`cans-tutorials`) - Hands-on learning with guided examples and sample data
2. **[Getting Started](GETTING_STARTED.md)** - 5-minute quickstart tutorial
3. **[User Guide](USER_GUIDE.md)** - Comprehensive guide with tutorials, best practices, and FAQ
4. **[API Guide](API_GUIDE.md)** - Complete API integration guide with examples
5. **[README](README.md)** - This file with complete feature overview
6. **[Examples](examples/)** - Real-world use cases and workflows
7. **[Changelog](CHANGELOG.md)** - Version history and updates
### 🔧 For Developers
- **[Tests](tests/)** - 100+ unit tests and usage patterns
- **[Configuration](pyproject.toml)** - Project setup and dependencies
- **API Reference** - In-code documentation with detailed docstrings
### 🆘 Getting Help
- **New to CANS?** → Run `cans-tutorials` for hands-on interactive learning
- **First time?** → [Getting Started Guide](GETTING_STARTED.md)
- **Need detailed help?** → [User Guide](USER_GUIDE.md) with FAQ and troubleshooting
- **Found a bug?** → [GitHub Issues](https://github.com/rdmurugan/cans-framework/issues)
- **Have questions?** → Email durai@infinidatum.net
## 🤝 Contributing
Contributions welcome! Please:
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Add tests** for new functionality
4. **Run tests**: `pytest tests/ -v`
5. **Submit** a pull request
Areas we'd love help with:
- Additional GNN architectures (GraphSAGE, Graph Transformers)
- More evaluation metrics for causal inference
- Integration with popular ML platforms (MLflow, Weights & Biases)
- Performance optimizations
## 👨🔬 Authors
**Durai Rajamanickam** – [@duraimuruganr](https://github.com/rdmurugan)
reach out to durai@infinidatum.net
## 📜 License
**CANS Framework Custom License** - Free for academic and personal use, commercial use requires permission.
- ✅ **Academic & Research Use**: Freely use for educational and non-commercial research
- ✅ **Personal Projects**: Use for personal and non-commercial experimentation
- 📋 **Commercial Use**: Requires written permission from durai@infinidatum.net
See [LICENSE](LICENSE) for full terms and conditions.
---
**Ready to get started?** Try the 30-second quick start above, or dive into the detailed examples! 🚀
Raw data
{
"_id": null,
"home_page": "https://github.com/rdmurugan/cans-framework",
"name": "cans-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Durai Rajamanickam <durai@infinidatum.net>",
"keywords": "causal-inference, deep-learning, graph-neural-networks, transformers, counterfactual, treatment-effects, machine-learning, pytorch, bert, gnn, causal-ai, econometrics, statistics",
"author": "Durai Rajamanickam",
"author_email": "Durai Rajamanickam <durai@infinidatum.net>",
"download_url": "https://files.pythonhosted.org/packages/75/ce/a88cd98d8f4df534acd80d405d7b9d35bbe14d740656aa8234c95089846a/cans_framework-3.1.4.tar.gz",
"platform": null,
"description": "# \ud83e\udde0 CANS: Causal Adaptive Neural System\n\n[](https://badge.fury.io/py/cans-framework)\n[](LICENSE)\n[](https://pypi.org/project/cans-framework/)\n[](https://github.com/rdmurugan/cans-framework/stargazers)\n> **Production-ready causal inference at scale with deep learning, APIs, and LLM integration**\n\n**CANS (Causal Adaptive Neural System)** is the most comprehensive **production-ready framework** for **causal inference** using deep learning. It combines **Graph Neural Networks (GNNs)**, **Transformers**, **Counterfactual Regression Networks (CFRNet)**, and **advanced causal methods** with enterprise-grade **APIs** and **LLM integration**.\n\n\ud83c\udfaf **Perfect for**: Healthcare, Finance, Marketing, Legal, Social Media, E-commerce, and any domain requiring **rigorous causal analysis**\n\n## \ud83c\udf1f What Makes CANS Unique\n\n- \ud83e\udde0 **Hybrid AI Architecture**: GNNs + Transformers + CFRNet for complex data\n- \ud83d\udd2c **Rigorous Causal Science**: Automated assumption testing, multiple identification strategies\n- \ud83c\udf10 **Production APIs**: REST API + MCP server for seamless integration\n- \ud83e\udd16 **LLM Integration**: Enable AI assistants to perform causal analysis autonomously\n- \u26a1 **Enterprise Ready**: Authentication, monitoring, scalable deployment\n- \ud83d\udcca **Comprehensive Toolkit**: CLI, Python API, web integration, notebooks\n\n## \ud83d\ude80 Choose Your Interface\n\n| Interface | Best For | Getting Started |\n|-----------|----------|-----------------|\n| \ud83d\udcda **Interactive Tutorials** | Learning, first-time users | `cans-tutorials` \u2192 hands-on guided learning |\n| \ud83d\udda5\ufe0f **CLI Tools** | Quick analysis, data scientists | `cans-validate --data data.csv --treatment T --outcome Y` |\n| \ud83d\udc0d **Python API** | Research, notebooks, pipelines | `from cans import CANS, validate_causal_assumptions` |\n| \ud83c\udf10 **REST API** | Web apps, microservices | `POST /validate` \u2192 JSON response |\n| \ud83e\udd16 **MCP Server** | LLMs, AI assistants | Claude/GPT calls `validate_causal_assumptions_tool` |\n\n## \ud83d\udcca Usage Matrix\n\n| Task | CLI | Python | REST API | MCP/LLM |\n|------|-----|--------|----------|---------|\n| **Assumption Validation** | `cans-validate` | `validate_causal_assumptions()` | `POST /validate` | `validate_causal_assumptions_tool` |\n| **Complete Analysis** | `cans-analyze` | `CANSRunner.fit()` | `POST /analyze` | `quick_causal_analysis` |\n| **Model Evaluation** | `cans-evaluate` | `CausalEvaluator.evaluate()` | `POST /evaluate` | `evaluate_predictions` |\n| **Batch Processing** | Shell scripting | `for` loops | HTTP requests | LLM automation |\n| **Production Deployment** | Cron jobs | Python services | Kubernetes | AI workflows |\n\n## \ud83d\ude80 What's New in v3.0 - Production-Ready Causal AI\n\n### \ud83d\udd2c Advanced Causal Methods\n- **Assumption Testing**: Automated unconfoundedness, positivity, and SUTVA validation\n- **Multiple Identification**: Backdoor criterion, IPW, doubly robust estimation\n- **CATE Estimation**: X-Learner, T-Learner, S-Learner, Neural CATE, Causal Forest\n- **Uncertainty Quantification**: Bayesian methods, ensemble approaches, conformal prediction\n\n### \ud83c\udf10 Enterprise Integration\n- **REST API**: Complete HTTP API with authentication and rate limiting\n- **MCP Server**: Model Context Protocol for seamless LLM integration\n- **Production Tools**: Docker, Kubernetes, monitoring, logging\n- **Multi-language**: Python, JavaScript, R, cURL examples\n\n### \ud83e\udde0 Enhanced AI Architecture\n- **Advanced Graph Construction**: Multi-node, temporal, and global architectures\n- **Causal-Specific Losses**: CFR, IPW, DragonNet, TARNet with representation balancing\n- **Memory Efficiency**: Lazy loading and batch processing for large datasets\n- **GPU Optimization**: CUDA support with automatic device selection\n\n### Previous v2.0 Features:\n- \ud83d\udd27 **Configuration Management**: Centralized, validated configs with JSON/YAML support\n- \ud83d\udee1\ufe0f **Enhanced Error Handling**: Comprehensive validation with informative error messages \n- \ud83d\udcca **Logging & Checkpointing**: Built-in experiment tracking with automatic model saving\n- \ud83e\uddea **Comprehensive Testing**: 100+ unit tests ensuring production reliability\n- \ud83d\udcc8 **Advanced Data Pipeline**: Multi-format loading (CSV, JSON) with automatic preprocessing\n- \u26a1 **Enhanced Training**: Early stopping, gradient clipping, multiple loss functions\n\n## \ud83d\udd27 Key Features\n\n### Core Architecture\n- \u2705 **Hybrid Neural Architecture**: GNNs + Transformers + CFRNet for multi-modal causal inference\n- \u2705 **Gated Fusion Layer**: Adaptive mixing of graph and textual representations\n- \u2705 **Flexible Graph Construction**: Single-node, multi-node, temporal, and global graphs\n- \u2705 **Production-Ready**: Comprehensive error handling, logging, and testing\n\n### Causal Inference Capabilities \n- \u2705 **Rigorous Assumption Testing**: Automated validation of causal identification conditions\n- \u2705 **Multiple Identification Methods**: Backdoor, IPW, doubly robust, with sensitivity analysis\n- \u2705 **Heterogeneous Treatment Effects**: CATE estimation with 5+ methods (X/T/S-Learners, etc.)\n- \u2705 **Advanced Loss Functions**: CFR, DragonNet, TARNet with representation balancing\n- \u2705 **Uncertainty Quantification**: Bayesian, ensemble, conformal prediction approaches\n\n### Data Processing & Evaluation\n- \u2705 **Smart Data Loading**: CSV, JSON, synthetic data with automatic graph construction\n- \u2705 **Comprehensive Evaluation**: PEHE, ATE, policy value, calibration metrics\n- \u2705 **Memory Efficiency**: Lazy loading, batch processing for large-scale datasets\n- \u2705 **Easy Configuration**: JSON/YAML configs with validation and experiment tracking\n\n\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\n +-----------+ +-----------+\n | GNN Emb | | BERT Emb |\n +-----------+ +-----------+\n \\ /\n \\ Fusion Layer /\n \\ /\n +-----------+\n | Fused Rep |\n +-----------+\n |\n CFRNet\n / \\\n mu_0(x) mu_1(x)\n```\n\n## \ud83d\ude80 Enhanced Causal Analysis Workflow\n\n### Complete Example with Assumption Testing & CATE Estimation\n\n```python\nfrom cans import (\n CANSConfig, CANS, GCN, CANSRunner,\n create_sample_dataset, get_data_loaders,\n CausalAssumptionTester, CausalLossManager, \n CATEManager, UncertaintyManager,\n advanced_counterfactual_analysis\n)\n\n# 1. Configuration with enhanced causal features\nconfig = CANSConfig()\nconfig.model.gnn_type = \"GCN\"\nconfig.training.loss_type = \"cfr\" # Causal loss function\nconfig.data.graph_construction = \"global\" # Multi-node graphs\n\n# 2. Test causal assumptions BEFORE modeling\nassumption_tester = CausalAssumptionTester()\nresults = assumption_tester.comprehensive_test(X, T, Y)\nprint(f\"Causal assumptions valid: {results['causal_identification_valid']}\")\n\n# 3. Create datasets with enhanced graph construction\ndatasets = create_sample_dataset(n_samples=1000, config=config.data)\ntrain_loader, val_loader, test_loader = get_data_loaders(datasets)\n\n# 4. Setup model with causal loss functions\nfrom transformers import BertModel\ngnn = GCN(in_dim=64, hidden_dim=128, output_dim=256)\nbert = BertModel.from_pretrained(\"distilbert-base-uncased\")\nmodel = CANS(gnn, bert, fusion_dim=256)\n\nloss_manager = CausalLossManager(\"cfr\", alpha=1.0, beta=0.5)\n\n# 5. Train with causal-aware pipeline\noptimizer = torch.optim.AdamW(model.parameters(), lr=0.001)\nrunner = CANSRunner(model, optimizer, config)\nhistory = runner.fit(train_loader, val_loader)\n\n# 6. Multiple counterfactual identification methods\ncf_results = advanced_counterfactual_analysis(\n model, test_loader, \n methods=['backdoor', 'ipw', 'doubly_robust']\n)\n\n# 7. CATE estimation with multiple learners\ncate_manager = CATEManager(method=\"x_learner\")\ncate_manager.fit(X, T, Y)\nindividual_effects = cate_manager.estimate_cate(X_test)\n\n# 8. Uncertainty quantification\nuncertainty_manager = UncertaintyManager(method=\"conformal\")\nuncertainty_manager.setup(model)\nintervals = uncertainty_manager.estimate_uncertainty(test_loader)\n\nprint(f\"ATE: {cf_results['backdoor']['ate']:.3f}\")\nprint(f\"Coverage: {intervals['coverage_rate']:.3f}\")\n```\n\n## \ud83d\ude80 Quick Start\n\n> \ud83c\udfaf **New to CANS?** Start with our [**Getting Started Guide**](GETTING_STARTED.md) for a 5-minute tutorial!\n\n### Installation\n\n```bash\n# Install from PyPI (Recommended) \npip install cans-framework\n\n# Verify installation and set up tutorials\npip show cans-framework\ncans-tutorials # Sets up interactive learning environment\n```\n\n### Alternative Installation Methods\n\n```bash\n# Development installation\ngit clone https://github.com/rdmurugan/cans-framework.git\ncd cans-framework\npip install -r requirements.txt\npip install -e .\n\n# With conda (for dependency management)\nconda create -n cans python=3.9\nconda activate cans\npip install cans-framework\n```\n\n**Core Dependencies:**\n- `torch>=2.0.0`\n- `transformers>=4.38.0`\n- `torch-geometric>=2.3.0`\n- `scikit-learn>=1.3.0`\n- `pandas>=2.0.0`\n\n### Basic Usage (30 seconds to results)\n\n```python\nfrom cans.config import CANSConfig\nfrom cans.utils.data import create_sample_dataset, get_data_loaders\nfrom cans.models import CANS\nfrom cans.models.gnn_modules import GCN\nfrom cans.pipeline.runner import CANSRunner\nfrom transformers import BertModel\nimport torch\n\n# 1. Create configuration\nconfig = CANSConfig()\nconfig.training.epochs = 10\n\n# 2. Load data (or create sample data)\ndatasets = create_sample_dataset(n_samples=1000, n_features=64)\ntrain_loader, val_loader, test_loader = get_data_loaders(datasets, batch_size=32)\n\n# 3. Create model\ngnn = GCN(in_dim=64, hidden_dim=128, output_dim=256)\nbert = BertModel.from_pretrained(\"bert-base-uncased\")\nmodel = CANS(gnn, bert, fusion_dim=256)\n\n# 4. Train\noptimizer = torch.optim.AdamW(model.parameters(), lr=0.001)\nrunner = CANSRunner(model, optimizer, config)\nhistory = runner.fit(train_loader, val_loader)\n\n# 5. Evaluate\nresults = runner.evaluate(test_loader)\nprint(f\"Test MSE: {results['mse']:.4f}\")\nprint(f\"Average Treatment Effect: {results['ate']:.4f}\")\n```\n\n## \ud83d\udda5\ufe0f Command Line Interface (CLI)\n\nCANS provides six powerful CLI commands for complete causal analysis workflow:\n\n> \ud83d\udca1 **New to CANS?** Check out our comprehensive [User Guide](USER_GUIDE.md) for step-by-step tutorials, troubleshooting, and best practices!\n\n### 1. Validate Causal Assumptions (`cans-validate`)\n\nTest critical causal assumptions before modeling:\n\n```bash\n# Basic usage\ncans-validate --data data.csv --treatment intervention --outcome conversion_rate\n\n# Specify features explicitly \ncans-validate --data marketing_data.csv \\\n --treatment campaign_type \\\n --outcome revenue \\\n --features age,income,education,region \\\n --output validation_results.json \\\n --verbose\n\n# Example output:\n# {\n# \"unconfoundedness_test\": {\n# \"valid\": true,\n# \"p_value\": 0.23,\n# \"method\": \"backdoor_criterion\"\n# },\n# \"positivity_test\": {\n# \"valid\": true,\n# \"overlap_score\": 0.85,\n# \"min_propensity\": 0.05\n# },\n# \"sutva_test\": {\n# \"valid\": true,\n# \"interference_score\": 0.02\n# }\n# }\n```\n\n### 2. Evaluate Model Performance (`cans-evaluate`)\n\nAssess causal model predictions:\n\n```bash\n# Evaluate predictions file with columns: mu0, mu1, treatments, outcomes\ncans-evaluate --predictions model_predictions.csv --format json\n\n# Save detailed evaluation report\ncans-evaluate --predictions predictions.csv \\\n --output evaluation_report.txt \\\n --format text\n\n# Example output metrics:\n# - Average Treatment Effect (ATE): 2.34 \u00b1 0.18\n# - Factual MSE: 0.045\n# - PEHE (Precision in Estimation of Heterogeneous Effects): 0.12\n# - Individual Treatment Effect R\u00b2: 0.73\n```\n\n### 3. Complete Causal Analysis (`cans-analyze`)\n\nRun end-to-end causal inference workflow:\n\n```bash\n# Quick analysis with default configuration\ncans-analyze --data patient_data.csv --output-dir results/\n\n# Use custom configuration\ncans-analyze --data social_media.csv \\\n --config custom_config.json \\\n --output-dir social_analysis/\n\n# Creates structured output:\n# results/\n# \u251c\u2500\u2500 assumptions_validation.json\n# \u251c\u2500\u2500 model_performance.json \n# \u251c\u2500\u2500 causal_effects_summary.json\n# \u251c\u2500\u2500 individual_effects.csv\n# \u2514\u2500\u2500 analysis_report.html\n```\n\n### 4. Interactive Tutorials (`cans-tutorials`)\n\nSet up hands-on tutorials in your workspace:\n\n```bash\n# Create tutorial workspace in current directory\ncans-tutorials\n\n# Specify custom directory\ncans-tutorials --dir my-learning-space\n\n# List available tutorials\ncans-tutorials --list\n\n# Creates structured tutorial environment:\n# cans-tutorials/\n# \u251c\u2500\u2500 README.md # Quick start guide\n# \u251c\u2500\u2500 TUTORIALS.md # Complete documentation\n# \u251c\u2500\u2500 tutorial_01_first_steps.py # Basic introduction\n# \u251c\u2500\u2500 tutorial_02_data_understanding.py # Advanced data handling\n# \u2514\u2500\u2500 examples/\n# \u2514\u2500\u2500 sample_marketing_data.csv # Practice dataset\n```\n\n**Tutorial Features:**\n- \ud83c\udfaf **Interactive Learning**: Step-by-step Python scripts with detailed explanations\n- \ud83d\udcca **Sample Data**: Real-world-like datasets for immediate practice\n- \ud83d\udd2c **Progressive Complexity**: From basics to advanced causal inference\n- \ud83d\udca1 **Best Practices**: Learn proper workflow and methodology\n- \ud83d\udee0\ufe0f **Editable Copies**: Modify and experiment with tutorial code\n\n### 5. API Server (`cans-server`)\n\nStart production-ready REST API:\n\n```bash\n# Start API server\ncans-server\n# Interactive docs at: http://localhost:8000/docs\n```\n\n### 6. LLM Integration (`cans-mcp`)\n\nEnable AI assistants to perform causal analysis:\n\n```bash\n# Start MCP server for LLM integration\ncans-mcp\n# Enables Claude, GPT, and other LLMs to use CANS autonomously\n```\n\n### CLI Configuration Files\n\nCreate reusable configuration files for complex analyses:\n\n```json\n{\n \"model\": {\n \"gnn_type\": \"GCN\",\n \"gnn_hidden_dim\": 128,\n \"fusion_dim\": 256,\n \"text_model\": \"distilbert-base-uncased\"\n },\n \"training\": {\n \"learning_rate\": 0.001,\n \"batch_size\": 64,\n \"epochs\": 50,\n \"loss_type\": \"cfr\"\n },\n \"data\": {\n \"graph_construction\": \"knn\",\n \"knn_k\": 5,\n \"scale_node_features\": true\n }\n}\n```\n\n## \ud83d\udcca Usage Examples\n\n### Example 1: CSV Data with Real Causal Inference\n\n```python\nfrom cans.utils.data import load_csv_dataset\nfrom cans.config import CANSConfig, DataConfig\n\n# Configure data processing\nconfig = CANSConfig()\nconfig.data.graph_construction = \"knn\" # or \"similarity\" \nconfig.data.knn_k = 5\nconfig.data.scale_node_features = True\n\n# Load your CSV data\ndatasets = load_csv_dataset(\n csv_path=\"your_data.csv\",\n text_column=\"review_text\", # Column with text data\n treatment_column=\"intervention\", # Binary treatment (0/1)\n outcome_column=\"conversion_rate\", # Continuous outcome \n feature_columns=[\"age\", \"income\", \"education\"], # Numerical features\n config=config.data\n)\n\ntrain_dataset, val_dataset, test_dataset = datasets\n\n# Check data quality\nstats = train_dataset.get_statistics()\nprint(f\"Treatment proportion: {stats['treatment_proportion']:.3f}\")\nprint(f\"Propensity overlap valid: {stats['propensity_overlap_valid']}\")\n```\n\n### Example 2: Advanced Configuration & Experiment Tracking\n\n```python\nfrom cans.config import CANSConfig\n\n# Create detailed configuration\nconfig = CANSConfig()\n\n# Model configuration\nconfig.model.gnn_type = \"GCN\"\nconfig.model.gnn_hidden_dim = 256\nconfig.model.fusion_dim = 512\nconfig.model.text_model = \"distilbert-base-uncased\" # Faster BERT variant\n\n# Training configuration \nconfig.training.learning_rate = 0.001\nconfig.training.batch_size = 64\nconfig.training.epochs = 50\nconfig.training.early_stopping_patience = 10\nconfig.training.gradient_clip_norm = 1.0\nconfig.training.loss_type = \"huber\" # Robust to outliers\n\n# Experiment tracking\nconfig.experiment.experiment_name = \"healthcare_causal_analysis\"\nconfig.experiment.save_every_n_epochs = 5\nconfig.experiment.log_level = \"INFO\"\n\n# Save configuration for reproducibility\nconfig.save(\"experiment_config.json\")\n\n# Later: load and use\nloaded_config = CANSConfig.load(\"experiment_config.json\")\n```\n\n### Example 3: Counterfactual Analysis & Treatment Effects\n\n```python\nfrom cans.utils.causal import simulate_counterfactual\nimport numpy as np\n\n# After training your model...\nrunner = CANSRunner(model, optimizer, config)\nrunner.fit(train_loader, val_loader)\n\n# Comprehensive evaluation\ntest_metrics = runner.evaluate(test_loader)\nprint(\"Performance Metrics:\")\nfor metric, value in test_metrics.items():\n print(f\" {metric}: {value:.4f}\")\n\n# Counterfactual analysis\ncf_control = simulate_counterfactual(model, test_loader, intervention=0)\ncf_treatment = simulate_counterfactual(model, test_loader, intervention=1)\n\n# Calculate causal effects\nate = np.mean(cf_treatment) - np.mean(cf_control)\nprint(f\"\\nCausal Analysis:\")\nprint(f\"Average Treatment Effect (ATE): {ate:.4f}\")\nprint(f\"Expected outcome under control: {np.mean(cf_control):.4f}\")\nprint(f\"Expected outcome under treatment: {np.mean(cf_treatment):.4f}\")\n\n# Individual treatment effects\nindividual_effects = np.array(cf_treatment) - np.array(cf_control)\nprint(f\"Treatment effect std: {np.std(individual_effects):.4f}\")\nprint(f\"% benefiting from treatment: {(individual_effects > 0).mean()*100:.1f}%\")\n```\n\n### Example 4: Custom Data Pipeline\n\n```python\nfrom cans.utils.preprocessing import DataPreprocessor, GraphBuilder\nfrom cans.config import DataConfig\nimport pandas as pd\n\n# Custom preprocessing pipeline\nconfig = DataConfig()\nconfig.graph_construction = \"similarity\"\nconfig.similarity_threshold = 0.7\nconfig.scale_node_features = True\n\npreprocessor = DataPreprocessor(config)\n\n# Process your DataFrame \ndf = pd.read_csv(\"social_media_posts.csv\")\ndataset = preprocessor.process_tabular_data(\n data=df,\n text_column=\"post_content\",\n treatment_column=\"fact_check_label\",\n outcome_column=\"share_count\",\n feature_columns=[\"user_followers\", \"post_length\", \"sentiment_score\"],\n text_model=\"bert-base-uncased\",\n max_text_length=256\n)\n\n# Split with custom ratios\ntrain_ds, val_ds, test_ds = preprocessor.split_dataset(\n dataset, \n train_size=0.7, \n val_size=0.2, \n test_size=0.1\n)\n```\n\n## \ud83e\uddea Testing & Development\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run specific test categories \npytest tests/test_models.py -v # Model tests\npytest tests/test_validation.py -v # Validation tests\npytest tests/test_pipeline.py -v # Training pipeline tests\n\n# Run with coverage\npytest tests/ --cov=cans --cov-report=html\n\n# Run example scripts\npython examples/enhanced_usage_example.py\npython examples/enhanced_causal_analysis_example.py\n```\n\n\n## \ud83d\udcc1 Framework Structure\n\n```\ncans-framework/\n\u251c\u2500\u2500 cans/\n\u2502 \u251c\u2500\u2500 __init__.py # Main imports\n\u2502 \u251c\u2500\u2500 config.py # \u2728 Configuration management\n\u2502 \u251c\u2500\u2500 exceptions.py # \u2728 Custom exceptions\n\u2502 \u251c\u2500\u2500 validation.py # \u2728 Data validation utilities\n\u2502 \u251c\u2500\u2500 models/\n\u2502 \u2502 \u251c\u2500\u2500 cans.py # Core CANS model (enhanced)\n\u2502 \u2502 \u2514\u2500\u2500 gnn_modules.py # GNN implementations\n\u2502 \u251c\u2500\u2500 pipeline/\n\u2502 \u2502 \u2514\u2500\u2500 runner.py # \u2728 Enhanced training pipeline\n\u2502 \u2514\u2500\u2500 utils/\n\u2502 \u251c\u2500\u2500 causal.py # Counterfactual simulation\n\u2502 \u251c\u2500\u2500 data.py # \u2728 Enhanced data loading\n\u2502 \u251c\u2500\u2500 preprocessing.py # \u2728 Advanced preprocessing\n\u2502 \u251c\u2500\u2500 logging.py # \u2728 Structured logging\n\u2502 \u2514\u2500\u2500 checkpointing.py # \u2728 Model checkpointing\n\u251c\u2500\u2500 tests/ # \u2728 Comprehensive test suite\n\u251c\u2500\u2500 examples/ # Usage examples\n\u2514\u2500\u2500 CLAUDE.md # Development guide\n```\n**\u2728 = New/Enhanced in v2.0**\n\n## \ud83c\udfaf Use Cases & Applications\n\n### Healthcare & Medical\n```python\n# Analyze treatment effectiveness with patient records + clinical notes\ndatasets = load_csv_dataset(\n csv_path=\"patient_outcomes.csv\",\n text_column=\"clinical_notes\",\n treatment_column=\"medication_type\", \n outcome_column=\"recovery_score\",\n feature_columns=[\"age\", \"bmi\", \"comorbidities\"]\n)\n```\n\n### Marketing & A/B Testing \n```python\n# Marketing campaign effectiveness with customer profiles + ad content\ndatasets = load_csv_dataset(\n csv_path=\"campaign_data.csv\", \n text_column=\"ad_content\",\n treatment_column=\"campaign_variant\",\n outcome_column=\"conversion_rate\",\n feature_columns=[\"customer_ltv\", \"demographics\", \"behavior_score\"]\n)\n```\n\n### Social Media & Content Moderation\n```python \n# Impact of content moderation on engagement\ndatasets = load_csv_dataset(\n csv_path=\"posts_data.csv\",\n text_column=\"post_text\", \n treatment_column=\"moderation_action\",\n outcome_column=\"engagement_score\",\n feature_columns=[\"user_followers\", \"post_length\", \"sentiment\"]\n)\n```\n\n## \ud83d\udd2c Research & Methodology\n\nCANS implements state-of-the-art causal inference techniques:\n\n- **Counterfactual Regression Networks (CFRNet)**: Learn representations that minimize treatment assignment bias\n- **Gated Fusion**: Adaptively combine graph-structured and textual information \n- **Balanced Representation**: Minimize distributional differences between treatment groups\n- **Propensity Score Validation**: Automatic overlap checking for reliable causal estimates\n\n**Key Papers:**\n- Shalit et al. \"Estimating individual treatment effect: generalization bounds and algorithms\" (ICML 2017)\n- Yao et al. \"Representation learning for treatment effect estimation from observational data\" (NeurIPS 2018)\n\n## \ud83d\ude80 Performance & Scalability\n\n- **Memory Efficient**: Optimized batch processing and gradient checkpointing\n- **GPU Acceleration**: Full CUDA support with automatic device selection\n- **Parallel Processing**: Multi-core data loading and preprocessing\n- **Production Ready**: Comprehensive error handling and logging\n\n**Benchmarks** (approximate, hardware-dependent):\n- **Small**: 1K samples, 32 features \u2192 ~30 sec training \n- **Medium**: 100K samples, 128 features \u2192 ~10 min training\n- **Large**: 1M+ samples \u2192 Scales with batch size and hardware\n\n## \ud83c\udf10 API & Integration\n\nCANS provides comprehensive API access for integration with web applications, services, and AI systems:\n\n### REST API Server\n```bash\n# Start REST API server\ncans-server\n# or\nuvicorn cans.api.server:app --host 0.0.0.0 --port 8000\n\n# Interactive docs at: http://localhost:8000/docs\n```\n\n### MCP Server for LLMs\n```bash\n# Start MCP server for LLM integration\ncans-mcp\n# Enables LLMs to directly perform causal analysis\n```\n\n### Python API Client\n```python\nfrom cans.api.client import CANSAPIClient\n\nclient = CANSAPIClient(api_key=\"your-key\")\nresults = client.validate_assumptions(\n data=\"data.csv\",\n treatment_column=\"treatment\",\n outcome_column=\"outcome\"\n)\n```\n\n**\ud83d\udd17 API Features:**\n- RESTful endpoints for all CANS functionality\n- Model Context Protocol (MCP) server for LLM integration\n- Authentication and rate limiting\n- Async/await support\n- Comprehensive error handling\n- Interactive documentation\n\n**\ud83d\udcd6 Learn More:** [API Guide](API_GUIDE.md)\n\n## \ud83d\udcda Documentation & Resources\n\n### \ud83d\udcda Documentation Hierarchy\n\n1. **Interactive Tutorials** (`cans-tutorials`) - Hands-on learning with guided examples and sample data\n2. **[Getting Started](GETTING_STARTED.md)** - 5-minute quickstart tutorial\n3. **[User Guide](USER_GUIDE.md)** - Comprehensive guide with tutorials, best practices, and FAQ \n4. **[API Guide](API_GUIDE.md)** - Complete API integration guide with examples\n5. **[README](README.md)** - This file with complete feature overview\n6. **[Examples](examples/)** - Real-world use cases and workflows\n7. **[Changelog](CHANGELOG.md)** - Version history and updates\n\n### \ud83d\udd27 For Developers\n- **[Tests](tests/)** - 100+ unit tests and usage patterns\n- **[Configuration](pyproject.toml)** - Project setup and dependencies\n- **API Reference** - In-code documentation with detailed docstrings\n\n### \ud83c\udd98 Getting Help\n- **New to CANS?** \u2192 Run `cans-tutorials` for hands-on interactive learning\n- **First time?** \u2192 [Getting Started Guide](GETTING_STARTED.md)\n- **Need detailed help?** \u2192 [User Guide](USER_GUIDE.md) with FAQ and troubleshooting\n- **Found a bug?** \u2192 [GitHub Issues](https://github.com/rdmurugan/cans-framework/issues)\n- **Have questions?** \u2192 Email durai@infinidatum.net\n\n## \ud83e\udd1d Contributing\n\nContributions welcome! Please:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Add tests** for new functionality \n4. **Run tests**: `pytest tests/ -v`\n5. **Submit** a pull request\n\nAreas we'd love help with:\n- Additional GNN architectures (GraphSAGE, Graph Transformers)\n- More evaluation metrics for causal inference\n- Integration with popular ML platforms (MLflow, Weights & Biases)\n- Performance optimizations\n\n## \ud83d\udc68\u200d\ud83d\udd2c Authors\n\n**Durai Rajamanickam** \u2013 [@duraimuruganr](https://github.com/rdmurugan)\nreach out to durai@infinidatum.net\n\n## \ud83d\udcdc License\n\n**CANS Framework Custom License** - Free for academic and personal use, commercial use requires permission.\n\n- \u2705 **Academic & Research Use**: Freely use for educational and non-commercial research\n- \u2705 **Personal Projects**: Use for personal and non-commercial experimentation \n- \ud83d\udccb **Commercial Use**: Requires written permission from durai@infinidatum.net\n\nSee [LICENSE](LICENSE) for full terms and conditions.\n\n---\n\n**Ready to get started?** Try the 30-second quick start above, or dive into the detailed examples! \ud83d\ude80\n\n",
"bugtrack_url": null,
"license": "CANS Framework Custom License\n \n Copyright (c) 2024 Durai Murugan (durai@infinidatum.net)\n \n CANS (Causal Adaptive Neural System) Framework License Agreement\n \n GRANT OF LICENSE\n \n Subject to the terms and conditions of this License, the copyright holder hereby grants you a worldwide, royalty-free, non-exclusive license to use, copy, modify, merge, publish, and distribute the CANS Framework software and associated documentation files (the \"Software\") under the following conditions:\n \n PERMITTED USES\n \n 1. ACADEMIC AND RESEARCH USE\n - You may use the Software for academic research, educational purposes, and non-commercial scientific studies.\n - You may modify and distribute the Software for research collaboration and academic publication.\n - Students, researchers, and academic institutions may use the Software freely for learning and research purposes.\n \n 2. PERSONAL AND NON-COMMERCIAL USE\n - You may use the Software for personal projects and non-commercial experimentation.\n - You may use the Software to learn causal inference techniques and deep learning methods.\n \n RESTRICTED USES\n \n 3. COMMERCIAL USE RESTRICTIONS\n - Any use of the Software for commercial purposes, including but not limited to:\n * Integration into commercial products or services\n * Use in business operations or commercial decision-making\n * Offering consulting services using the Software\n * Creating derivative works for commercial distribution\n * Using the Software to generate revenue or commercial advantage\n - Requires explicit written permission from the copyright holder.\n \n 4. WRITTEN PERMISSION REQUIREMENT\n - To obtain permission for commercial use, contact: durai@infinidatum.net\n - Commercial licenses will be granted on a case-by-case basis and may include:\n * License fees or royalty arrangements\n * Support and maintenance agreements\n * Specific terms tailored to the commercial use case\n - Written permission must be obtained BEFORE any commercial use begins.\n \n CONDITIONS AND LIMITATIONS\n \n 5. ATTRIBUTION REQUIREMENT\n - You must retain all copyright notices and this license text in all copies.\n - Any academic publication or research paper using the Software must cite:\n \"CANS Framework by Durai Murugan (https://github.com/rdmurugan/cans-framework)\"\n \n 6. NO WARRANTY\n - The Software is provided \"AS IS\" without warranty of any kind.\n - The copyright holder disclaims all warranties, express or implied.\n - You assume all risks associated with the use of the Software.\n \n 7. LIMITATION OF LIABILITY\n - In no event shall the copyright holder be liable for any damages arising from the use of the Software.\n - This limitation applies to all claims, whether based on warranty, contract, tort, or any other legal theory.\n \n 8. DISTRIBUTION TERMS\n - You may distribute copies of the Software provided that:\n * This license is included with all copies\n * No commercial use restrictions are violated\n * Recipients are bound by the same license terms\n \n 9. MODIFICATION AND DERIVATIVE WORKS\n - You may create derivative works for permitted uses only.\n - Derivative works must be clearly identified and carry this same license.\n - Commercial distribution of derivative works requires written permission.\n \n 10. TERMINATION\n - This license automatically terminates if you violate any of its terms.\n - Upon termination, you must cease all use and destroy all copies of the Software.\n - Commercial permission may be revoked for cause with 30 days written notice.\n \n ENFORCEMENT AND INTERPRETATION\n \n 11. GOVERNING LAW\n - This license shall be governed by the laws of the jurisdiction where the copyright holder resides.\n - Any disputes shall be resolved through binding arbitration or appropriate courts.\n \n 12. SEVERABILITY\n - If any provision of this license is held invalid, the remainder shall continue in full force and effect.\n \n 13. ENTIRE AGREEMENT\n - This license constitutes the entire agreement between you and the copyright holder regarding the Software.\n - Modifications to this license must be in writing and signed by the copyright holder.\n \n CONTACT INFORMATION\n \n For commercial licensing inquiries, technical support, or questions about this license:\n \n Email: durai@infinidatum.net\n GitHub: https://github.com/rdmurugan/cans-framework\n \n By using the Software, you acknowledge that you have read, understood, and agree to be bound by the terms and conditions of this License.\n \n ---\n \n CANS Framework - Causal Adaptive Neural System\n Advancing causal inference through deep learning innovation.",
"summary": "A production-ready deep learning framework for causal inference on structured, textual, and heterogeneous data",
"version": "3.1.4",
"project_urls": {
"Bug Reports": "https://github.com/rdmurugan/cans-framework/issues",
"Changelog": "https://github.com/rdmurugan/cans-framework/releases",
"Documentation": "https://github.com/rdmurugan/cans-framework#readme",
"Homepage": "https://github.com/rdmurugan/cans-framework",
"Repository": "https://github.com/rdmurugan/cans-framework"
},
"split_keywords": [
"causal-inference",
" deep-learning",
" graph-neural-networks",
" transformers",
" counterfactual",
" treatment-effects",
" machine-learning",
" pytorch",
" bert",
" gnn",
" causal-ai",
" econometrics",
" statistics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1381ee1d45f41dbb34b54171bf8e2cc555e6005ffce6552184e2288641635d7f",
"md5": "99802541de4ede58ccf47d2f778fea80",
"sha256": "8fb37bf189d66df9f64fae83931e6e351bfeedf4f8a316b65b5a402bcd644203"
},
"downloads": -1,
"filename": "cans_framework-3.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99802541de4ede58ccf47d2f778fea80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 133475,
"upload_time": "2025-09-10T04:31:32",
"upload_time_iso_8601": "2025-09-10T04:31:32.306894Z",
"url": "https://files.pythonhosted.org/packages/13/81/ee1d45f41dbb34b54171bf8e2cc555e6005ffce6552184e2288641635d7f/cans_framework-3.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "75cea88cd98d8f4df534acd80d405d7b9d35bbe14d740656aa8234c95089846a",
"md5": "ce8b3a704e3af28fa5e5f6a10f957d79",
"sha256": "8762f934f1f9a13ab11bfc46d4a66bc411979a0a8ad45bfec15190c02267ae97"
},
"downloads": -1,
"filename": "cans_framework-3.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ce8b3a704e3af28fa5e5f6a10f957d79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 142624,
"upload_time": "2025-09-10T04:31:33",
"upload_time_iso_8601": "2025-09-10T04:31:33.796527Z",
"url": "https://files.pythonhosted.org/packages/75/ce/a88cd98d8f4df534acd80d405d7b9d35bbe14d740656aa8234c95089846a/cans_framework-3.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 04:31:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rdmurugan",
"github_project": "cans-framework",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "torch",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "transformers",
"specs": [
[
">=",
"4.38.0"
]
]
},
{
"name": "torch-geometric",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.66.0"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"3.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.7.0"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.12.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.15.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.11.0"
]
]
},
{
"name": "statsmodels",
"specs": [
[
">=",
"0.14.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
}
],
"lcname": "cans-framework"
}
