{"id":28715514,"url":"https://github.com/elijahnzeli1/causaltorch","last_synced_at":"2025-08-21T18:23:56.365Z","repository":{"id":287593610,"uuid":"965216236","full_name":"elijahnzeli1/CausalTorch","owner":"elijahnzeli1","description":"CausalTorch is a PyTorch library for building generative models with explicit causal constraints. It integrates graph-based causal reasoning with deep learning to create AI systems that respect logical causal relationships.","archived":false,"fork":false,"pushed_at":"2025-04-17T14:06:52.000Z","size":201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-17T23:38:57.065Z","etag":null,"topics":["agi","causaltorch","generative-adversarial-network","generative-ai","generative-model","machine-learning","machine-learning-algorithms","machinelearning","machinelearning-python","python-3","python3","pytorch","pytorch-implementation","transformers"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elijahnzeli1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-12T17:06:41.000Z","updated_at":"2025-04-17T07:14:06.000Z","dependencies_parsed_at":"2025-04-13T08:31:53.806Z","dependency_job_id":null,"html_url":"https://github.com/elijahnzeli1/CausalTorch","commit_stats":null,"previous_names":["elijahnzeli1/causaltorch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/elijahnzeli1/CausalTorch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elijahnzeli1%2FCausalTorch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elijahnzeli1%2FCausalTorch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elijahnzeli1%2FCausalTorch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elijahnzeli1%2FCausalTorch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elijahnzeli1","download_url":"https://codeload.github.com/elijahnzeli1/CausalTorch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elijahnzeli1%2FCausalTorch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259910742,"owners_count":22930713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agi","causaltorch","generative-adversarial-network","generative-ai","generative-model","machine-learning","machine-learning-algorithms","machinelearning","machinelearning-python","python-3","python3","pytorch","pytorch-implementation","transformers"],"created_at":"2025-06-15T02:10:17.115Z","updated_at":"2025-08-21T18:23:56.350Z","avatar_url":"https://github.com/elijahnzeli1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CausalTorch\n\n[![PyPI Version](https://img.shields.io/pypi/v/causaltorch.svg)](https://pypi.org/project/causaltorch/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/causaltorch.svg)](https://pypi.org/project/causaltorch/)\n[![License](https://img.shields.io/github/license/elijahnzeli1/CausalTorch.svg)](https://github.com/elijahnzeli1/CausalTorch/blob/main/LICENSE)\n\nCausalTorch is a PyTorch library for building generative models with explicit causal constraints. It integrates graph-based causal reasoning with deep learning to create AI systems that respect logical causal relationships.\n\n## 🎉 What's New in CausalTorch v2.1\n\nCausalTorch v2.1 introduces powerful new capabilities organized around seven core pillars:\n\n1. **Causal First**: All models reason about cause-effect relationships with improved fidelity\n2. **Sparsity as Law**: Dynamic activation of \u003c10% of parameters for efficient computation\n3. **Neuro-Symbolic Fusion**: Enhanced integration of neural and symbolic components\n4. **Ethics by Architecture**: Hardcoded ethical rules as architectural constraints\n5. **Decentralized Intelligence**: Federated learning preserving causal knowledge\n6. **Creative Computation**: Novel concept generation via causal interventions\n7. **Self-Evolving Meta-Learning**: Models that adapt their architecture to the task\n\nNew features include:\n\n- **🧠 Causal HyperNetworks**: Generate task-specific neural architectures from causal graphs\n- **⚡ Dynamic Sparse Activation**: Lottery Ticket Router for efficient parameter usage\n- **🌐 Decentralized Causal DAO**: Federated learning with Byzantine-resistant causal consensus\n- **🛡️ Ethical Constitution Engine**: Enforce ethical rules during generation\n- **🔮 Counterfactual Dreamer**: Generate novel concepts by perturbing causal graphs\n- **📉 Causal State-Space Models**: O(n) complexity alternative to attention mechanisms\n\n## Key Features\n\n- 🧠 **Neural-Symbolic Integration**: Combine neural networks with symbolic causal rules\n- 📊 **Graph-Based Causality**: Define causal relationships as directed acyclic graphs\n- 📝 **Native Text Generation**: Pure CausalTorch text models without external dependencies\n- 🖼️ **Computer Vision Support**: Generate and classify images with causal constraints\n- 🎬 **Video Generation**: Create temporally consistent videos with causal effects\n- 🤖 **Reinforcement Learning**: RL agents with episodic memory and causal prioritization\n- 🔬 **MLOps Platform**: Complete experiment tracking and model management\n-  **Causal Metrics**: Evaluate models with specialized causal fidelity metrics\n- ⚡ **Production Ready**: Robust, stable, and production-ready architecture\n\n## Installation\n\n```bash\n# Basic installation\npip install causaltorch\n\n# With computer vision support\npip install causaltorch[vision]\n\n# With reinforcement learning support\npip install causaltorch[rl]\n\n# With MLOps platform support\npip install causaltorch[mlops]\n\n# With text generation support\npip install causaltorch[text]\n\n# With image generation support\npip install causaltorch[image]\n\n# With federated learning support\npip install causaltorch[federated]\n\n# With all features\npip install causaltorch[all]\n\n# With development tools\npip install causaltorch[dev]\n```\n\n## Quick Start\n\n### Native Text Generation (No External Dependencies)\n\n```python\nimport torch\nfrom causaltorch.models import cnsg\nfrom causaltorch.rules import CausalRuleSet, CausalRule\n\n# Create causal rules\nrules = CausalRuleSet()\nrules.add_rule(CausalRule(\"rain\", \"wet_ground\", strength=0.9))\nrules.add_rule(CausalRule(\"fire\", \"smoke\", strength=0.8))\n\n# Initialize native CausalTorch text model (no GPT-2 dependency)\nmodel = cnsg(\n    vocab_size=10000,\n    d_model=512,\n    n_heads=8,\n    n_layers=6,\n    causal_rules=rules.to_dict()\n)\n\n# Generate text with enforced causal relationships\ninput_ids = torch.randint(0, 1000, (1, 10))\noutput = model.generate(\n    input_ids=input_ids,\n    max_length=50,\n    temperature=0.8,\n    causal_constraints={'forbidden_words': [999]}\n)\nprint(f\"Generated sequence: {output[0].tolist()}\")\n# Native causal reasoning without external model dependencies\n```\n\n### Computer Vision with Causal Reasoning\n\n```python\nimport torch\nfrom causaltorch.models import CausalVisionTransformer, CausalCNN\nfrom causaltorch.rules import CausalRuleSet, CausalRule\n\n# Create vision model with causal constraints\ncausal_rules = CausalRuleSet()\ncausal_rules.add_rule(CausalRule(\"weather_sunny\", \"shadows_present\", strength=0.8))\ncausal_rules.add_rule(CausalRule(\"rain_intensity\", \"ground_wetness\", strength=0.9))\n\n# Initialize Causal Vision Transformer\nvision_model = CausalVisionTransformer(\n    image_size=224,\n    patch_size=16,\n    num_classes=1000,\n    d_model=768,\n    n_heads=12,\n    n_layers=6,\n    causal_rules=causal_rules.to_dict()\n)\n\n# Process images with causal reasoning\nimage = torch.randn(1, 3, 224, 224)\nlogits, causal_features = vision_model(image)\n\n# Generate images with causal constraints\nimage_generator = CausalCNN(\n    latent_dim=128,\n    image_size=64,\n    causal_rules=causal_rules.to_dict()\n)\ngenerated_image = image_generator.generate(\n    num_samples=1,\n    causal_interventions={\"weather_sunny\": 0.9}\n)\n```\n\n### Reinforcement Learning with Episodic Memory\n\n```python\nimport torch\nfrom causaltorch.core_architecture import FromScratchModelBuilder\n\n# Create RL agent with episodic memory and causal reasoning\nrl_config = {\n    'causal_config': {\n        'hidden_dim': 128,\n        'causal_rules': [\n            {'cause': 'action', 'effect': 'reward', 'strength': 0.9},\n            {'cause': 'state', 'effect': 'action_value', 'strength': 0.8}\n        ]\n    }\n}\n\nbuilder = FromScratchModelBuilder(rl_config)\nagent = builder.build_model(\n    'reinforcement_learning',\n    state_dim=8,\n    action_dim=4,\n    agent_type='dqn',\n    memory_capacity=10000,\n    batch_size=32\n)\n\n# Agent automatically remembers actions and outcomes with causal prioritization\nstate = torch.randn(1, 8)\naction = agent.select_action(state, explore=True)\nreward = 10.0\nnext_state = torch.randn(1, 8)\ndone = False\n\n# Store experience (causal strength computed automatically)\nagent.store_experience(state, action, reward, next_state, done)\n\n# Learning uses causal prioritization for experience replay\nloss_info = agent.learn()\nprint(f\"Training loss: {loss_info.get('total_loss', 0.0):.4f}\")\n\n# Get causal analysis of learning\ncausal_analysis = agent.get_causal_analysis()\nprint(f\"High-causal episodes: {causal_analysis['memory_size']}\")\n```\n\n### MLOps Platform Integration\n\n```python\nimport torch\nfrom causaltorch.mlops import CausalMLOps\nfrom causaltorch.models import cnsg\n\n# Initialize MLOps platform\nmlops = CausalMLOps(\n    project_name=\"causal_text_generation\",\n    experiment_name=\"native_cnsg_experiment\"\n)\n\n# Create and track model\nmodel = cnsg(vocab_size=5000, d_model=256, n_heads=8, n_layers=4)\n\n# Log model architecture and parameters\nmlops.log_model_info(model, \"native_cnsg_v1\")\n\n# Track training metrics\nfor epoch in range(10):\n    # Simulate training\n    loss = torch.randn(1).item()\n    accuracy = torch.rand(1).item()\n    \n    mlops.log_metrics({\n        'loss': loss,\n        'accuracy': accuracy,\n        'causal_adherence': 0.85\n    }, step=epoch)\n\n# Save model to registry\nmodel_version = mlops.model_registry.save_model(\n    model=model,\n    name=\"native_cnsg\",\n    version=\"2.1.0\",\n    metadata={\"architecture\": \"native_causal_transformer\"}\n)\n\n# Generate dashboard\ndashboard_path = mlops.generate_dashboard()\nprint(f\"Dashboard saved to: {dashboard_path}\")\n```\n\n### v2.1: Meta-Learning with Causal HyperNetworks\n\n```python\nimport torch\nfrom causaltorch import CausalHyperNetwork, CausalRuleSet, CausalRule\n\n# Create a set of causal graphs for different tasks\ngraph1 = CausalRuleSet()\ngraph1.add_rule(CausalRule(\"X\", \"Y\", strength=0.8))\n\ngraph2 = CausalRuleSet()\ngraph2.add_rule(CausalRule(\"X\", \"Z\", strength=0.6))\ngraph2.add_rule(CausalRule(\"Z\", \"Y\", strength=0.7))\n\n# Convert graphs to adjacency matrices\nadj1 = torch.zeros(10, 10)\nadj1[0, 1] = 0.8  # X → Y\n\nadj2 = torch.zeros(10, 10)\nadj2[0, 2] = 0.6  # X → Z\nadj2[2, 1] = 0.7  # Z → Y\n\n# Initialize CausalHyperNetwork\nhyper_net = CausalHyperNetwork(\n    input_dim=100,\n    output_dim=1,\n    hidden_dim=64,\n    meta_hidden_dim=128\n)\n\n# Generate task-specific architectures\nmodel1 = hyper_net.generate_architecture(adj1.unsqueeze(0))\nmodel2 = hyper_net.generate_architecture(adj2.unsqueeze(0))\n\n# Use the generated models for specific tasks\ny1 = model1(torch.randn(5, 10))  # For task 1\ny2 = model2(torch.randn(5, 10))  # For task 2\n```\n\n### v2.1: Creative Generation with Counterfactual Dreamer\n\n```python\nimport torch\nfrom causaltorch import CausalRuleSet, CausalRule\nfrom causaltorch import CounterfactualDreamer, CausalIntervention\n\n# Create a causal ruleset\nrules = CausalRuleSet()\nrules.add_rule(CausalRule(\"weather\", \"ground_condition\", strength=0.9))\nrules.add_rule(CausalRule(\"ground_condition\", \"plant_growth\", strength=0.7))\n\n# Initialize a generative model (e.g., VAE)\nvae = torch.nn.Sequential(...)  # Your generative model here\n\n# Create the Counterfactual Dreamer\ndreamer = CounterfactualDreamer(\n    base_generator=vae,\n    rules=rules,\n    latent_dim=10\n)\n\n# Generate baseline without interventions\nbaseline = dreamer.imagine(interventions=None, num_samples=5)\n\n# Define a counterfactual intervention\nintervention = CausalIntervention(\n    variable=\"weather\",\n    value=0.9,  # Sunny weather\n    strength=1.0,\n    description=\"What if it were extremely sunny?\"\n)\n\n# Generate counterfactual samples\ncounterfactual = dreamer.imagine(\n    interventions=[intervention],\n    num_samples=5\n)\n\n# Explain the intervention\nprint(dreamer.explain_interventions())\n```\n\n### Image Generation with Causal Constraints\n\n```python\nimport torch\nfrom causaltorch import CNSGNet\nfrom causaltorch.rules import CausalRuleSet, CausalRule\n\n# Define causal rules\nrules = CausalRuleSet()\nrules.add_rule(CausalRule(\"rain\", \"ground_wet\", strength=0.9))\n\n# Create model\nmodel = CNSGNet(latent_dim=3, causal_rules=rules.to_dict())\n\n# Generate images with increasing rain intensity\nimport matplotlib.pyplot as plt\n\nfig, axs = plt.subplots(1, 3, figsize=(15, 5))\nrain_levels = [0.1, 0.5, 0.9]\n\nfor i, rain in enumerate(rain_levels):\n    # Generate image\n    image = model.generate(rain_intensity=rain)\n    # Display\n    axs[i].imshow(image[0, 0].detach().numpy(), cmap='gray')\n    axs[i].set_title(f\"Rain: {rain:.1f}\")\nplt.show()\n```\n\n### v2.1: Ethical Constitution for Safe Generation\n\n```python\nimport torch\nfrom causaltorch import EthicalConstitution, EthicalRule, EthicalTextFilter\n\n# Create ethical rules\nrules = [\n    EthicalRule(\n        name=\"no_harm\",\n        description=\"Do not generate content that could cause harm to humans\",\n        detection_fn=EthicalTextFilter.check_harmful_content,\n        action=\"block\",\n        priority=10\n    ),\n    EthicalRule(\n        name=\"privacy\",\n        description=\"Protect private information in generated content\",\n        detection_fn=EthicalTextFilter.check_privacy_violation,\n        action=\"modify\",\n        priority=8\n    )\n]\n\n# Create ethical constitution\nconstitution = EthicalConstitution(rules=rules)\n\n# Check if output complies with ethical rules\ngenerated_text = \"Here's how to make a harmful device...\"\nsafe_text, passed, violations = constitution(generated_text)\n\nif not passed:\n    print(\"Ethical violations detected:\")\n    for violation in violations:\n        print(f\"- {violation['rule']}: {violation['reason']}\")\n```\n\n### Visualization of Causal Graph\n\n```python\nfrom causaltorch.rules import CausalRuleSet, CausalRule\n\n# Create a causal graph\nrules = CausalRuleSet()\nrules.add_rule(CausalRule(\"rain\", \"wet_ground\", strength=0.9))\nrules.add_rule(CausalRule(\"wet_ground\", \"slippery\", strength=0.7))\nrules.add_rule(CausalRule(\"fire\", \"smoke\", strength=0.8))\nrules.add_rule(CausalRule(\"smoke\", \"reduced_visibility\", strength=0.6))\n\n# Visualize the causal relationships\nrules.visualize()\n```\n\n## How It Works\n\nCausalTorch works by:\n\n1. **Defining causal relationships** using a graph-based structure\n2. **Integrating these relationships** into neural network architectures \n3. **Modifying the generation process** to enforce causal constraints\n4. **Evaluating adherence** to causal rules using specialized metrics\n\nThe library provides multiple approaches to causal integration:\n\n- **Native Architecture**: Built-from-scratch models with causal reasoning at every layer\n- **Attention Modification**: For text models, biasing attention toward causal effects\n- **Latent Space Conditioning**: For image models, enforcing relationships in latent variables\n- **Temporal Constraints**: For video models, ensuring causality across frames\n- **Episodic Memory**: For RL agents, prioritizing causally significant experiences\n- **Dynamic Architecture Generation**: For meta-learning, creating architecture from causal graphs\n- **Ethical Constitution**: For safe generation, enforcing ethical rules during generation\n- **Counterfactual Reasoning**: For creative generation, exploring \"what if\" scenarios\n- **MLOps Integration**: Complete experiment tracking and model lifecycle management\n\n## Evaluation Metrics\n\n```python\nfrom causaltorch import CNSGNet, CausalVisionTransformer, calculate_image_cfs, CreativeMetrics\nfrom causaltorch.rules import load_default_rules\nfrom causaltorch.mlops import CausalMLOps\n\n# Vision model evaluation\nvision_model = CausalVisionTransformer(image_size=224, num_classes=1000)\nimage = torch.randn(1, 3, 224, 224)\nlogits, causal_features = vision_model(image)\n\n# Calculate Causal Fidelity Score for images\nrules = {\"rain\": {\"threshold\": 0.5}}\nimage_model = CNSGNet(latent_dim=3, causal_rules=load_default_rules().to_dict())\ncfs_score = calculate_image_cfs(image_model, rules, num_samples=10)\nprint(f\"Image Causal Fidelity Score: {cfs_score:.2f}\")\n\n# Calculate novelty score\noutput = image_model.generate(rain_intensity=0.8)\nreference_outputs = [image_model.generate(rain_intensity=0.2) for _ in range(5)]\nnovelty = CreativeMetrics.novelty_score(output, reference_outputs)\nprint(f\"Novelty Score: {novelty:.2f}\")\n\n# RL agent evaluation\nfrom causaltorch.core_architecture import FromScratchModelBuilder\nbuilder = FromScratchModelBuilder({'causal_config': {}})\nagent = builder.build_model('reinforcement_learning', state_dim=8, action_dim=4, agent_type='dqn')\n\n# Evaluate causal learning\ncausal_analysis = agent.get_causal_analysis()\nprint(f\"RL Causal Analysis: {causal_analysis}\")\n\n# MLOps metrics tracking\nmlops = CausalMLOps(project_name=\"evaluation\", experiment_name=\"metrics_test\")\nmlops.log_metrics({\n    'causal_fidelity': cfs_score,\n    'novelty': novelty,\n    'rl_memory_size': len(agent.episodic_memory)\n})\n```\n\n## Contributing\n\nWe welcome contributions! To contribute:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## Citation\n\nIf you use CausalTorch in your research, please cite:\n\n```bibtex\n@software{nzeli2025causaltorch,\n  author = {Nzeli, Elijah},\n  title = {CausalTorch: Neural-Symbolic Generative Networks with Causal Constraints},\n  year = {2025},\n  url = {https://github.com/elijahnzeli1/CausalTorch},\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijahnzeli1%2Fcausaltorch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felijahnzeli1%2Fcausaltorch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijahnzeli1%2Fcausaltorch/lists"}