nous 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

nous/layers.py

@@ -1,117 +0,0 @@
-# nous/layers.py
-import torch
-import torch.nn as nn
-from typing import List, Tuple
-
-# --- Fact Layers ---
-
-class ExhaustiveAtomicFactLayer(nn.Module):
-    """Generates atomic facts by exhaustively comparing all pairs of features."""
-    def __init__(self, input_dim: int, feature_names: List[str]):
-        super().__init__()
-        if input_dim > 20:
-            num_facts = input_dim * (input_dim - 1) // 2
-            print(f"Warning: ExhaustiveAtomicFactLayer with {input_dim} features will create {num_facts} facts. This may be slow and memory-intensive.")
-        self.indices = torch.combinations(torch.arange(input_dim), r=2)
-        self.thresholds = nn.Parameter(torch.randn(self.indices.shape[0]) * 0.1)
-        self.steepness = nn.Parameter(torch.ones(self.indices.shape[0]) * 5.0)
-        self.fact_names = [f"({feature_names[i]} > {feature_names[j]})" for i, j in self.indices.numpy()]
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        steepness = torch.nn.functional.softplus(self.steepness) + 1e-4
-        diffs = x[:, self.indices[:, 0]] - x[:, self.indices[:, 1]]
-        return torch.sigmoid(steepness * (diffs - self.thresholds))
-
-    @property
-    def output_dim(self) -> int: return len(self.fact_names)
-
-class LearnedAtomicFactLayer(nn.Module):
-    """Base class for learnable fact layers (Sigmoid and Beta)."""
-    def __init__(self, input_dim: int, num_facts: int, feature_names: List[str]):
-        super().__init__()
-        self.input_dim = input_dim
-        self.num_facts = num_facts
-        self._feature_names = feature_names
-        self.projection_left = nn.Linear(input_dim, num_facts, bias=False)
-        self.projection_right = nn.Linear(input_dim, num_facts, bias=False)
-        self.thresholds = nn.Parameter(torch.randn(num_facts) * 0.1)
-
-    @property
-    def output_dim(self) -> int: return self.num_facts
-        
-    def get_base_diffs(self, x: torch.Tensor) -> torch.Tensor:
-        """Calculates the core difference term for all activation functions."""
-        return (self.projection_left(x) - self.projection_right(x)) - self.thresholds
-
-    def fact_names(self, prefix: str) -> List[str]:
-        """Generates human-readable and unique names for facts."""
-        names = []
-        with torch.no_grad():
-            w_left, w_right = self.projection_left.weight, self.projection_right.weight
-            for i in range(self.output_dim):
-                left_name = self._feature_names[w_left[i].abs().argmax().item()]
-                right_name = self._feature_names[w_right[i].abs().argmax().item()]
-                base_name = f"({left_name} vs {right_name})" if left_name != right_name else f"Thresh({left_name})"
-                names.append(f"{prefix}-{i}{base_name}")
-        return names
-
-# --- Specialized Learnable Fact Layers ---
-
-class SigmoidFactLayer(LearnedAtomicFactLayer):
-    """A learnable fact layer using the standard sigmoid activation."""
-    def __init__(self, input_dim: int, num_facts: int, feature_names: List[str]):
-        super().__init__(input_dim, num_facts, feature_names)
-        self.steepness = nn.Parameter(torch.ones(num_facts) * 5.0)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        diffs = self.get_base_diffs(x)
-        steepness = torch.nn.functional.softplus(self.steepness) + 1e-4
-        return torch.sigmoid(steepness * diffs)
-
-    @property
-    def fact_names(self) -> List[str]: return super().fact_names(prefix="Sigmoid")
-
-class BetaFactLayer(LearnedAtomicFactLayer):
-    """A learnable fact layer using a flexible, generalized logistic function."""
-    def __init__(self, input_dim: int, num_facts: int, feature_names: List[str]):
-        super().__init__(input_dim, num_facts, feature_names)
-        self.k_raw = nn.Parameter(torch.ones(num_facts) * 0.5)
-        self.nu_raw = nn.Parameter(torch.zeros(num_facts))
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        diffs = self.get_base_diffs(x)
-        k = torch.nn.functional.softplus(self.k_raw) + 1e-4
-        nu = torch.nn.functional.softplus(self.nu_raw) + 1e-4
-        return (1 + torch.exp(-k * diffs)) ** (-nu)
-        
-    @property
-    def fact_names(self) -> List[str]: return super().fact_names(prefix="Beta")
-
-# --- Rule/Concept Layers ---
-
-class LogicalRuleLayer(nn.Module):
-    """Forms logical rules (AND) from facts and outputs higher-level concepts."""
-    def __init__(self, input_dim: int, num_rules: int, input_fact_names: List[str]):
-        super().__init__()
-        torch.manual_seed(input_dim + num_rules)
-        
-        if input_dim > 0 and num_rules > 0:
-            self.register_buffer('rule_indices', torch.randint(0, input_dim, size=(num_rules, 2)))
-            self.rule_names = [f"({input_fact_names[i]} AND {input_fact_names[j]})" for i, j in self.rule_indices]
-        else:
-            self.register_buffer('rule_indices', torch.empty(0, 2, dtype=torch.long))
-            self.rule_names = []
-            
-        self.concept_generator = nn.Linear(num_rules, num_rules)
-        self.concept_names = [f"Concept-{i}" for i in range(num_rules)]
-
-    def forward(self, facts: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
-        if self.rule_indices.shape[0] == 0:
-            return torch.zeros(facts.shape[0], 0).to(facts.device), torch.zeros(facts.shape[0], 0).to(facts.device)
-        fact1, fact2 = facts[:, self.rule_indices[:, 0]], facts[:, self.rule_indices[:, 1]]
-        rule_activations = fact1 * fact2
-        concepts = torch.sigmoid(self.concept_generator(rule_activations))
-        return concepts, rule_activations
-
-    @property
-    def output_dim(self) -> int: return len(self.concept_names)

nous/models.py

@@ -1,65 +0,0 @@
-# nous/models.py
-import torch
-import torch.nn as nn
-from typing import List, Literal, Tuple
-from .layers import ExhaustiveAtomicFactLayer, SigmoidFactLayer, BetaFactLayer, LogicalRuleLayer
-
-class NousBlock(nn.Module):
-    """A single reasoning block in the Nous network with a residual connection."""
-    def __init__(self, input_dim: int, num_rules: int, input_fact_names: List[str]):
-        super().__init__()
-        self.rule_layer = LogicalRuleLayer(input_dim, num_rules, input_fact_names)
-        self.projection = nn.Linear(input_dim, num_rules) if input_dim != num_rules else nn.Identity()
-        self.norm = nn.LayerNorm(num_rules)
-
-    def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-        concepts, rule_activations = self.rule_layer(x)
-        output = self.norm(self.projection(x) + concepts)
-        return output, concepts, rule_activations
-    
-    @property
-    def concept_names(self) -> List[str]:
-        return self.rule_layer.concept_names
-
-class NousNet(nn.Module):
-    """
-    The complete Nous neuro-symbolic network for regression and classification.
-    """
-    def __init__(self,
-                 input_dim: int,
-                 output_dim: int,
-                 feature_names: List[str],
-                 fact_layer_type: Literal['beta', 'sigmoid', 'exhaustive'] = 'beta',
-                 num_facts: int = 30,
-                 num_rules_per_layer: List[int] = [10, 5]):
-        super().__init__()
-        self.feature_names = feature_names
-        
-        if fact_layer_type == 'beta':
-            self.atomic_fact_layer = BetaFactLayer(input_dim, num_facts, feature_names)
-        elif fact_layer_type == 'sigmoid':
-            self.atomic_fact_layer = SigmoidFactLayer(input_dim, num_facts, feature_names)
-        elif fact_layer_type == 'exhaustive':
-            self.atomic_fact_layer = ExhaustiveAtomicFactLayer(input_dim, feature_names)
-        else:
-            raise ValueError("fact_layer_type must be 'beta', 'sigmoid', or 'exhaustive'")
-            
-        self.nous_blocks = nn.ModuleList()
-        current_dim = self.atomic_fact_layer.output_dim
-        
-        for i, num_rules in enumerate(num_rules_per_layer):
-            input_names = self.atomic_fact_layer.fact_names if i == 0 else self.nous_blocks[i-1].concept_names
-            block = NousBlock(current_dim, num_rules, input_names)
-            self.nous_blocks.append(block)
-            current_dim = num_rules
-            
-        self.output_head = nn.Linear(current_dim, output_dim)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        """
-        Forward pass. Returns logits for classification or direct values for regression.
-        """
-        h = self.atomic_fact_layer(x)
-        for block in self.nous_blocks:
-            h, _, _ = block(h)
-        return self.output_head(h)

nous-0.1.0.dist-info/METADATA

@@ -1,138 +0,0 @@
-Metadata-Version: 2.4
-Name: nous
-Version: 0.1.0
-Summary: Nous: A Neuro-Symbolic Library for Interpretable and Causal Reasoning AI
-Author-email: Islam Tlupov <tlupovislam@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 Islam Tlupov
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Project-URL: Homepage, https://github.com/EmotionEngineer/nous
-Project-URL: Repository, https://github.com/EmotionEngineer/nous
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: torch>=1.8.0
-Requires-Dist: pandas>=1.3.0
-Requires-Dist: scikit-learn>=1.0
-Requires-Dist: matplotlib>=3.3.0
-Requires-Dist: networkx>=2.6
-Requires-Dist: seaborn>=0.11
-Dynamic: license-file
-
-# Nous: A Neuro-Symbolic Library for Interpretable AI
-
-[![PyPI version](https://badge.fury.io/py/nous.svg)](https://badge.fury.io/py/nous)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-**Nous** is a PyTorch-based library for building "white-box" machine learning models for both **regression** and **classification**. It enables models that don't just predict, but also **reason** and **explain** their decisions in human-understandable terms.
-
-## Key Features
-
--   **Deeply Interpretable**: Generate a complete, step-by-step logical trace (`fact -> rule -> concept -> prediction`) for any decision.
--   **Supports Regression & Classification**: A unified API for predicting both continuous values and class probabilities.
--   **Causal by Design**: Natively supports counterfactual analysis ("What if?") to provide actionable recommendations for both regression and classification tasks.
--   **High Performance**: Achieves accuracy competitive with traditional black-box models.
--   **Scalable & Flexible**: Choose between a high-performance `beta` activation, a robust `sigmoid`, or a maximally transparent `exhaustive` fact layer.
-
-## Installation
-
-```bash
-pip install nous
-```
-
-## Quickstart: A 5-Minute Example (Regression)
-
-Let's predict a house price and understand the model's reasoning.
-
-```python
-import torch
-import pandas as pd
-from sklearn.datasets import make_regression
-from nous.models import NousNet
-from nous.interpret import trace_decision_graph, explain_fact
-from nous.causal import find_counterfactual
-
-# 1. Prepare Data
-X_raw, y = make_regression(n_samples=1000, n_features=5, n_informative=3, noise=20, random_state=42)
-feature_names = ['area_sqft', 'num_bedrooms', 'dist_to_center', 'age_years', 'renovation_quality']
-X = torch.tensor(X_raw, dtype=torch.float32)
-y = torch.tensor(y, dtype=torch.float32).unsqueeze(1)
-
-# 2. Define and Train a NousNet for Regression
-model = NousNet(
-    input_dim=5,
-    output_dim=1, # Single output for regression
-    feature_names=feature_names,
-    fact_layer_type='beta'
-)
-# Training: Use a regression loss like nn.MSELoss
-# loss_fn = torch.nn.MSELoss()
-# ... (standard training loop omitted)
-model.eval()
-
-# 3. Analyze a specific house
-x_sample = X[50]
-predicted_price = model(x_sample).item()
-print(f"Model's predicted price for house #50: ${predicted_price:,.2f}")
-
-# 4. Get the Step-by-Step Reasoning
-graph = trace_decision_graph(model, x_sample)
-top_facts = sorted(graph['trace']['Atomic Facts'].items(), key=lambda i: i[1]['value'], reverse=True)
-fact_to_analyze = top_facts[0][0]
-print(f"\nTop activated fact influencing the price: '{fact_to_analyze}'")
-
-# 5. Decode the Learned Fact
-details_df = explain_fact(model, fact_name=fact_to_analyze)
-print(f"\nDecoding '{fact_to_analyze}':")
-display(details_df.head())
-
-# 6. Get an Actionable Recommendation
-# What's the smallest change to increase the predicted price to $150,000?
-recommendation = find_counterfactual(
-    model,
-    x_sample,
-    target_output=150.0, # Target value for regression
-    task='regression'
-)
-print("\nRecommendation to increase value to $150k:")
-for feature, old_val, new_val in recommendation['changes']:
-    print(f"- Change '{feature}' from {old_val:.2f} to {new_val:.2f}")
-
-```
-
-## Choosing a `fact_layer_type`
-
--   `'beta'` (**Default, Recommended**): Best performance and flexibility.
--   `'sigmoid'`: A robust and reliable alternative.
--   `'exhaustive'`: Maximum transparency. Best for low-dimensional problems (<15 features).
-
-## License
-
-This project is licensed under the MIT License.

nous-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-nous/__init__.py,sha256=-nnKnlgTh2wEqPP4Cz3zUFY0jrU6Y6BGrd-4mMDu6IE,545
-nous/causal.py,sha256=U2_pQYpIyM7VhV0mlmmD-kQgyNLMYEH1MnN5-dLZiZA,2488
-nous/interpret.py,sha256=QcBceWmGxvLLXvmTA1_T3G6MmyovPV8NA5sxu04CdUw,5721
-nous/layers.py,sha256=4Uv0JkhK3EkPbZ1sdbpFK0AkU6IOsyQUjCoyjwz3ZOQ,5651
-nous/models.py,sha256=qRhiN7_uAkmm7xIGgXR6gkzl4rArb6E-LkAEnREOYf4,2849
-nous-0.1.0.dist-info/licenses/LICENSE,sha256=07nO-ZFpy_s_msfks8VsONyV2cBBggqsEQD2h5sdVRo,1069
-nous-0.1.0.dist-info/METADATA,sha256=uZUy6b43xDtS_iHSugbjTZ8BmFwoRKn9mG1gT43VEIg,5992
-nous-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-nous-0.1.0.dist-info/top_level.txt,sha256=yUcst4OAspsyKhX0y5ENzFkJKzR_gislA5MykV1pVbk,5
-nous-0.1.0.dist-info/RECORD,,