nous 0.0.1__tar.gz → 0.1.0__tar.gz

nous-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+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/README.md

@@ -0,0 +1,90 @@
+# 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/nous/__init__.py

@@ -0,0 +1,26 @@
+# nous/__init__.py
+
+__version__ = "0.1.0"
+
+from .models import NousNet
+from .interpret import (
+    trace_decision_graph,
+    explain_fact,
+    plot_logic_graph,
+    plot_fact_activation_function,
+    plot_final_layer_contributions,
+)
+from .causal import find_counterfactual
+
+__all__ = [
+    # Main Model
+    "NousNet",
+    # Interpretation Suite
+    "trace_decision_graph",
+    "explain_fact",
+    "plot_logic_graph",
+    "plot_fact_activation_function",
+    "plot_final_layer_contributions",
+    # Causal Analysis
+    "find_counterfactual",
+]

nous-0.1.0/nous/causal.py

@@ -0,0 +1,63 @@
+# nous/causal.py
+import torch
+import torch.nn as nn
+from typing import Literal
+from .models import NousNet
+
+def find_counterfactual(
+    model: NousNet,
+    x_sample: torch.Tensor,
+    target_output: float,
+    task: Literal['regression', 'classification'] = 'classification',
+    lr: float = 0.01,
+    steps: int = 200,
+    l1_lambda: float = 0.5
+) -> dict:
+    """
+    Finds a minimal change to the input to achieve a target output.
+    
+    Args:
+        model (NousNet): The trained model.
+        x_sample (torch.Tensor): The original input tensor.
+        target_output (float): For classification, the desired probability (e.g., 0.8). 
+                               For regression, the desired absolute value (e.g., 150.0).
+        task (Literal['regression', 'classification']): The type of task.
+        lr, steps, l1_lambda: Optimization parameters.
+
+    Returns:
+        dict: A dictionary containing the counterfactual sample and a list of changes.
+    """
+    if task == 'classification':
+        if not (0 < target_output < 1): 
+            raise ValueError("Target for classification must be a probability between 0 and 1.")
+        if model.output_head.out_features > 1: 
+            raise NotImplementedError("Counterfactual analysis for multi-class models is not yet supported.")
+        # Calculate target in logit space for numerical stability
+        target = torch.log(torch.tensor(target_output) / (1 - torch.tensor(target_output)))
+    else: # regression
+        target = torch.tensor(target_output, dtype=torch.float32)
+
+    x_sample = x_sample.clone().detach()
+    delta = torch.zeros_like(x_sample, requires_grad=True)
+    optimizer = torch.optim.Adam([delta], lr=lr)
+    
+    for _ in range(steps):
+        optimizer.zero_grad()
+        x_perturbed = x_sample + delta
+        prediction = model(x_perturbed.unsqueeze(0)).squeeze()
+        
+        target_loss = (prediction - target)**2
+        l1_loss = torch.norm(delta, p=1)
+        total_loss = target_loss + l1_lambda * l1_loss
+        
+        # This will now only be called for scalar losses, as multi-class is caught above
+        total_loss.backward()
+        optimizer.step()
+
+    final_x = x_sample + delta.detach()
+    changes = []
+    for i, name in enumerate(model.feature_names):
+        if not torch.isclose(x_sample[i], final_x[i], atol=1e-3):
+            changes.append((name, x_sample[i].item(), final_x[i].item()))
+            
+    return {"counterfactual_x": final_x, "changes": changes}

nous-0.1.0/nous/interpret.py

@@ -0,0 +1,111 @@
+# nous/interpret.py
+import torch
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+import networkx as nx
+from .models import NousNet
+from .layers import LearnedAtomicFactLayer, BetaFactLayer
+
+def trace_decision_graph(model: NousNet, x_sample: torch.Tensor) -> dict:
+    """Traces the full reasoning path for a single sample."""
+    if x_sample.dim() == 1: x_sample = x_sample.unsqueeze(0)
+    model.eval()
+    graph_data = {"trace": {}}
+    with torch.no_grad():
+        facts = model.atomic_fact_layer(x_sample).squeeze(0)
+        graph_data['trace']['Atomic Facts'] = {name: {"value": facts[i].item()} for i, name in enumerate(model.atomic_fact_layer.fact_names)}
+        h = facts.unsqueeze(0)
+        for i, block in enumerate(model.nous_blocks):
+            h, concepts, rule_activations = block(h)
+            concepts, rule_activations = concepts.squeeze(0), rule_activations.squeeze(0)
+            graph_data['trace'][f'Rules L{i}'] = {name: {"value": rule_activations[j].item()} for j, name in enumerate(block.rule_layer.rule_names)}
+            graph_data['trace'][f'Concepts L{i}'] = {name: {"value": concepts[j].item()} for j, name in enumerate(block.concept_names)}
+    return graph_data
+
+def explain_fact(model: NousNet, fact_name: str) -> pd.DataFrame:
+    """Provides a detailed breakdown of a single learned fact, showing feature weights."""
+    fact_layer = model.atomic_fact_layer
+    if not isinstance(fact_layer, LearnedAtomicFactLayer):
+        raise TypeError("explain_fact is only applicable to 'beta' or 'sigmoid' fact layers.")
+    try:
+        fact_index = fact_layer.fact_names.index(fact_name)
+    except ValueError:
+        raise ValueError(f"Fact '{fact_name}' not found.")
+    
+    with torch.no_grad():
+        w_left, w_right = fact_layer.projection_left.weight[fact_index], fact_layer.projection_right.weight[fact_index]
+        threshold = fact_layer.thresholds[fact_index]
+    df = pd.DataFrame({
+        "feature": model.feature_names,
+        "left_weight": w_left.cpu().detach().numpy(),
+        "right_weight": w_right.cpu().detach().numpy(),
+    })
+    df['net_effect'] = df['left_weight'] - df['right_weight']
+    print(f"Explanation for fact '{fact_name}':")
+    print(f"Fact is TRUE when: (Sum(left_weight * feat) - Sum(right_weight * feat)) > {threshold.item():.3f}")
+    return df.sort_values(by='net_effect', key=abs, ascending=False)
+
+def plot_fact_activation_function(model: NousNet, fact_name: str, x_range=(-3, 3), n_points=200):
+    """Visualizes the learned activation function for a single learned fact."""
+    fact_layer = model.atomic_fact_layer
+    if not isinstance(fact_layer, LearnedAtomicFactLayer):
+        raise TypeError("This function is only for 'beta' or 'sigmoid' fact layers.")
+    try:
+        fact_index = fact_layer.fact_names.index(fact_name)
+    except ValueError:
+        raise ValueError(f"Fact '{fact_name}' not found.")
+        
+    diff_range = torch.linspace(x_range[0], x_range[1], n_points)
+    
+    with torch.no_grad():
+        if isinstance(fact_layer, BetaFactLayer):
+            k = torch.nn.functional.softplus(fact_layer.k_raw[fact_index]) + 1e-4
+            nu = torch.nn.functional.softplus(fact_layer.nu_raw[fact_index]) + 1e-4
+            activations = (1 + torch.exp(-k * diff_range))**(-nu)
+            label = f'Learned Beta-like (k={k:.2f}, ν={nu:.2f})'
+        else: # SigmoidFactLayer
+            steepness = torch.nn.functional.softplus(fact_layer.steepness[fact_index]) + 1e-4
+            activations = torch.sigmoid(steepness * diff_range)
+            label = f'Learned Sigmoid (steepness={steepness:.2f})'
+            
+    plt.figure(figsize=(8, 5))
+    plt.plot(diff_range.numpy(), activations.numpy(), label=label, linewidth=2.5)
+    plt.plot(diff_range.numpy(), torch.sigmoid(diff_range).numpy(), label='Standard Sigmoid', linestyle='--', color='gray')
+    plt.title(f"Activation Function for Fact:\n'{fact_name}'")
+    plt.xlabel("Difference Value (Left Projection - Right Projection - Threshold)")
+    plt.ylabel("Fact Activation (Truth Value)")
+    plt.legend(); plt.grid(True, linestyle=':'); plt.ylim(-0.05, 1.05); plt.show()
+
+def plot_final_layer_contributions(model: NousNet, x_sample: torch.Tensor):
+    """Calculates and plots which high-level concepts most influenced the final prediction."""
+    if x_sample.dim() == 1: x_sample = x_sample.unsqueeze(0)
+    model.eval()
+    with torch.no_grad():
+        h = model.atomic_fact_layer(x_sample)
+        for block in model.nous_blocks: h, _, _ = block(h)
+        final_activations = h.squeeze(0)
+        
+        output_dim = model.output_head.out_features
+        weights = model.output_head.weight.squeeze(0)
+        title = "Top Final Layer Concept Contributions"
+        
+        if output_dim > 1:
+            predicted_class = model.output_head(h).argmax().item()
+            weights = model.output_head.weight[predicted_class]
+            title += f" for Predicted Class {predicted_class}"
+            
+    contributions = final_activations * weights
+    concept_names = model.nous_blocks[-1].concept_names
+    
+    df = pd.DataFrame({'concept': concept_names, 'contribution': contributions.cpu().detach().numpy()})
+    df = df.sort_values('contribution', key=abs, ascending=False).head(15)
+    
+    plt.figure(figsize=(10, 6)); 
+    colors = ['#5fba7d' if c > 0 else '#d65f5f' for c in df['contribution']]
+    sns.barplot(x='contribution', y='concept', data=df, palette=colors, dodge=False)
+    plt.title(title); plt.xlabel("Contribution (Activation * Weight)"); plt.ylabel("Final Layer Concept"); plt.show()
+
+def plot_logic_graph(*args, **kwargs):
+    print("Graph visualization is planned for a future release.")
+    pass

nous-0.1.0/nous/layers.py

@@ -0,0 +1,117 @@
+# 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-0.1.0/nous/models.py

@@ -0,0 +1,65 @@
+# 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/nous.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+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/nous.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+nous/__init__.py
+nous/causal.py
+nous/interpret.py
+nous/layers.py
+nous/models.py
+nous.egg-info/PKG-INFO
+nous.egg-info/SOURCES.txt
+nous.egg-info/dependency_links.txt
+nous.egg-info/requires.txt
+nous.egg-info/top_level.txt
+tests/test_interpret_causal.py
+tests/test_layers.py
+tests/test_models.py

nous-0.1.0/nous.egg-info/requires.txt

@@ -0,0 +1,6 @@
+torch>=1.8.0
+pandas>=1.3.0
+scikit-learn>=1.0
+matplotlib>=3.3.0
+networkx>=2.6
+seaborn>=0.11

nous-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+# pyproject.toml
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nous"
+version = "0.1.0"
+description = "Nous: A Neuro-Symbolic Library for Interpretable and Causal Reasoning AI"
+readme = "README.md"
+requires-python = ">=3.7"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Islam Tlupov", email = "tlupovislam@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed"
+]
+dependencies = [
+    "torch>=1.8.0",
+    "pandas>=1.3.0",
+    "scikit-learn>=1.0",
+    "matplotlib>=3.3.0",
+    "networkx>=2.6",
+    "seaborn>=0.11"
+]
+
+[project.urls]
+Homepage = "https://github.com/EmotionEngineer/nous"
+Repository = "https://github.com/EmotionEngineer/nous"

nous-0.1.0/tests/test_interpret_causal.py

@@ -0,0 +1,77 @@
+# tests/test_interpret_causal.py
+import torch
+import pytest
+import pandas as pd
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+
+from nous.models import NousNet
+from nous.interpret import trace_decision_graph, explain_fact, plot_fact_activation_function, plot_final_layer_contributions, plot_logic_graph
+from nous.causal import find_counterfactual
+
+INPUT_DIM = 5
+FEATURE_NAMES = [f'feat_{i}' for i in range(INPUT_DIM)]
+
+@pytest.fixture
+def beta_model():
+    return NousNet(input_dim=INPUT_DIM, output_dim=1, feature_names=FEATURE_NAMES,
+                   fact_layer_type='beta', num_facts=10, num_rules_per_layer=[5])
+
+@pytest.fixture
+def exhaustive_model():
+    return NousNet(input_dim=INPUT_DIM, output_dim=1, feature_names=FEATURE_NAMES, fact_layer_type='exhaustive')
+
+@pytest.fixture
+def multiclass_model():
+    return NousNet(input_dim=INPUT_DIM, output_dim=3, feature_names=FEATURE_NAMES, fact_layer_type='sigmoid')
+
+@pytest.fixture
+def x_sample(): return torch.randn(INPUT_DIM)
+
+def test_trace_decision_graph(beta_model, x_sample):
+    graph = trace_decision_graph(beta_model, x_sample)
+    assert isinstance(graph, dict)
+    assert 'trace' in graph
+    assert len(graph['trace']['Atomic Facts']) == beta_model.atomic_fact_layer.output_dim
+    assert len(graph['trace']['Concepts L0']) == beta_model.nous_blocks[0].rule_layer.output_dim
+
+def test_explain_fact(beta_model):
+    fact_name = beta_model.atomic_fact_layer.fact_names[0]
+    df = explain_fact(beta_model, fact_name=fact_name)
+    assert isinstance(df, pd.DataFrame)
+    assert 'net_effect' in df.columns
+
+def test_explain_fact_errors(exhaustive_model, beta_model):
+    with pytest.raises(TypeError): explain_fact(exhaustive_model, fact_name="any")
+    with pytest.raises(ValueError): explain_fact(beta_model, fact_name="non_existent_fact")
+
+def test_plot_fact_activation_function(beta_model):
+    fact_name = beta_model.atomic_fact_layer.fact_names[0]
+    plot_fact_activation_function(beta_model, fact_name=fact_name)
+    plt.close()
+
+def test_plot_final_layer_contributions(beta_model, multiclass_model, x_sample):
+    plot_final_layer_contributions(beta_model, x_sample)
+    plt.close()
+    plot_final_layer_contributions(multiclass_model, x_sample)
+    plt.close()
+
+def test_plot_logic_graph(beta_model, x_sample):
+    graph = trace_decision_graph(beta_model, x_sample)
+    plot_logic_graph(graph)
+
+def test_find_counterfactual(beta_model, x_sample):
+    # Classification
+    result_class = find_counterfactual(beta_model, x_sample, target_output=0.8, task='classification')
+    assert 'counterfactual_x' in result_class
+    
+    # Regression
+    result_reg = find_counterfactual(beta_model, x_sample, target_output=150.0, task='regression')
+    assert 'changes' in result_reg
+
+def test_find_counterfactual_errors(multiclass_model, beta_model, x_sample):
+    with pytest.raises(NotImplementedError):
+        find_counterfactual(multiclass_model, x_sample, target_output=0.8)
+    with pytest.raises(ValueError):
+        find_counterfactual(beta_model, x_sample, target_output=1.1, task='classification')

nous-0.1.0/tests/test_layers.py

@@ -0,0 +1,97 @@
+# tests/test_layers.py
+
+import torch
+import pytest
+from nous.layers import (
+    ExhaustiveAtomicFactLayer,
+    SigmoidFactLayer,
+    BetaFactLayer,
+    LogicalRuleLayer,
+)
+
+# --- Test Constants ---
+BATCH_SIZE = 4
+INPUT_DIM = 5
+NUM_FACTS_LEARNED = 10
+NUM_RULES = 8
+FEATURE_NAMES = [f'feat_{i}' for i in range(INPUT_DIM)]
+
+# --- Fixtures ---
+@pytest.fixture
+def sample_data():
+    return torch.randn(BATCH_SIZE, INPUT_DIM)
+
+# --- Layer Tests ---
+
+def test_exhaustive_atomic_fact_layer(sample_data):
+    layer = ExhaustiveAtomicFactLayer(input_dim=INPUT_DIM, feature_names=FEATURE_NAMES)
+    
+    # Check output dimension: C(5, 2) = 10
+    expected_dim = INPUT_DIM * (INPUT_DIM - 1) // 2
+    assert layer.output_dim == expected_dim
+    assert len(layer.fact_names) == expected_dim
+
+    # Check forward pass
+    output = layer(sample_data)
+    assert output.shape == (BATCH_SIZE, expected_dim)
+    assert not torch.isnan(output).any()
+    assert (output >= 0).all() and (output <= 1).all()
+
+    # Check gradient flow
+    output.sum().backward()
+    assert layer.thresholds.grad is not None
+    assert layer.steepness.grad is not None
+
+@pytest.mark.parametrize("layer_class", [SigmoidFactLayer, BetaFactLayer])
+def test_learned_atomic_fact_layers(sample_data, layer_class):
+    layer = layer_class(input_dim=INPUT_DIM, num_facts=NUM_FACTS_LEARNED, feature_names=FEATURE_NAMES)
+    
+    # Check output dimension
+    assert layer.output_dim == NUM_FACTS_LEARNED
+    assert len(layer.fact_names) == NUM_FACTS_LEARNED
+
+    # Check forward pass
+    output = layer(sample_data)
+    assert output.shape == (BATCH_SIZE, NUM_FACTS_LEARNED)
+    assert not torch.isnan(output).any()
+    assert (output >= 0).all() and (output <= 1).all()
+
+    # Check gradient flow
+    output.sum().backward()
+    assert layer.projection_left.weight.grad is not None
+    assert layer.projection_right.weight.grad is not None
+    assert layer.thresholds.grad is not None
+    # Check specific params
+    if isinstance(layer, SigmoidFactLayer):
+        assert layer.steepness.grad is not None
+    if isinstance(layer, BetaFactLayer):
+        assert layer.k_raw.grad is not None
+        assert layer.nu_raw.grad is not None
+
+def test_logical_rule_layer():
+    input_facts = torch.rand(BATCH_SIZE, NUM_FACTS_LEARNED)
+    fact_names = [f'fact_{i}' for i in range(NUM_FACTS_LEARNED)]
+    
+    layer = LogicalRuleLayer(input_dim=NUM_FACTS_LEARNED, num_rules=NUM_RULES, input_fact_names=fact_names)
+
+    # Check output dimension
+    assert layer.output_dim == NUM_RULES
+    
+    # Check forward pass
+    concepts, rule_activations = layer(input_facts)
+    assert concepts.shape == (BATCH_SIZE, NUM_RULES)
+    assert rule_activations.shape == (BATCH_SIZE, NUM_RULES)
+    assert not torch.isnan(concepts).any()
+    
+    # Check gradient flow
+    concepts.sum().backward()
+    assert layer.concept_generator.weight.grad is not None
+    
+def test_logical_rule_layer_empty_input():
+    """Test that the layer handles zero input facts gracefully."""
+    input_facts = torch.rand(BATCH_SIZE, 0)
+    layer = LogicalRuleLayer(input_dim=0, num_rules=0, input_fact_names=[])
+    
+    concepts, rule_activations = layer(input_facts)
+    assert concepts.shape == (BATCH_SIZE, 0)
+    assert rule_activations.shape == (BATCH_SIZE, 0)

nous-0.1.0/tests/test_models.py

@@ -0,0 +1,93 @@
+# tests/test_models.py
+
+import torch
+import pytest
+from nous.models import NousNet, NousBlock
+
+# --- Test Constants ---
+BATCH_SIZE = 4
+INPUT_DIM = 8
+OUTPUT_DIM_BINARY = 1
+OUTPUT_DIM_MULTI = 3
+FEATURE_NAMES = [f'feat_{i}' for i in range(INPUT_DIM)]
+
+# --- Fixtures ---
+@pytest.fixture
+def sample_data():
+    return torch.randn(BATCH_SIZE, INPUT_DIM)
+
+@pytest.fixture
+def nous_block_input():
+    return torch.rand(BATCH_SIZE, 10) # 10 input facts/concepts
+
+# --- Model Tests ---
+
+def test_nous_block(nous_block_input):
+    block = NousBlock(input_dim=10, num_rules=5, input_fact_names=[f'f_{i}' for i in range(10)])
+    
+    # Check forward pass
+    output, concepts, rules = block(nous_block_input)
+    assert output.shape == (BATCH_SIZE, 5)
+    assert concepts.shape == (BATCH_SIZE, 5)
+    assert rules.shape == (BATCH_SIZE, 5)
+    
+    # Check gradient flow
+    output.sum().backward()
+    assert all(p.grad is not None for p in block.parameters())
+
+@pytest.mark.parametrize("fact_type", ['beta', 'sigmoid', 'exhaustive'])
+def test_nous_net_binary_classification(sample_data, fact_type):
+    model = NousNet(
+        input_dim=INPUT_DIM,
+        output_dim=OUTPUT_DIM_BINARY,
+        feature_names=FEATURE_NAMES,
+        fact_layer_type=fact_type,
+        num_facts=15,
+        num_rules_per_layer=[10, 5]
+    )
+    
+    # Check forward pass
+    output = model(sample_data)
+    assert output.shape == (BATCH_SIZE, OUTPUT_DIM_BINARY)
+    assert not torch.isnan(output).any()
+
+    # Check gradient flow
+    output.sum().backward()
+    assert all(p.grad is not None for p in model.parameters())
+
+@pytest.mark.parametrize("fact_type", ['beta', 'sigmoid', 'exhaustive'])
+def test_nous_net_multiclass_classification(sample_data, fact_type):
+    model = NousNet(
+        input_dim=INPUT_DIM,
+        output_dim=OUTPUT_DIM_MULTI,
+        feature_names=FEATURE_NAMES,
+        fact_layer_type=fact_type,
+        num_facts=15,
+        num_rules_per_layer=[10, 5]
+    )
+    
+    # Check forward pass
+    output = model(sample_data)
+    assert output.shape == (BATCH_SIZE, OUTPUT_DIM_MULTI)
+
+@pytest.mark.parametrize("fact_type", ['beta', 'sigmoid', 'exhaustive'])
+def test_nous_net_regression(sample_data, fact_type):
+    model = NousNet(
+        input_dim=INPUT_DIM,
+        output_dim=1, # Regression output
+        feature_names=FEATURE_NAMES,
+        fact_layer_type=fact_type
+    )
+    
+    # Check forward pass
+    output = model(sample_data)
+    assert output.shape == (BATCH_SIZE, 1)
+
+def test_nous_net_invalid_fact_layer():
+    with pytest.raises(ValueError):
+        NousNet(
+            input_dim=INPUT_DIM,
+            output_dim=1,
+            feature_names=FEATURE_NAMES,
+            fact_layer_type='invalid_type'
+        )

nous-0.0.1/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: nous
-Version: 0.0.1
-Summary: Placeholder for the Nous neuro-symbolic AI library. Full implementation coming soon.
-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
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# nous
-
-**This package name is reserved for the Nous neuro-symbolic AI library.**
-
-A full implementation is in active development and will be published here soon.

nous-0.0.1/README.md

@@ -1,5 +0,0 @@
-# nous
-
-**This package name is reserved for the Nous neuro-symbolic AI library.**
-
-A full implementation is in active development and will be published here soon.

nous-0.0.1/nous/__init__.py

@@ -1,2 +0,0 @@
-# nous/__init__.py
-__version__ = "0.0.1"

nous-0.0.1/nous.egg-info/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: nous
-Version: 0.0.1
-Summary: Placeholder for the Nous neuro-symbolic AI library. Full implementation coming soon.
-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
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# nous
-
-**This package name is reserved for the Nous neuro-symbolic AI library.**
-
-A full implementation is in active development and will be published here soon.

nous-0.0.1/nous.egg-info/SOURCES.txt

@@ -1,8 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-nous/__init__.py
-nous.egg-info/PKG-INFO
-nous.egg-info/SOURCES.txt
-nous.egg-info/dependency_links.txt
-nous.egg-info/top_level.txt

nous-0.0.1/pyproject.toml

@@ -1,25 +0,0 @@
-# pyproject.toml
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "nous"
-version = "0.0.1"
-description = "Placeholder for the Nous neuro-symbolic AI library. Full implementation coming soon."
-readme = "README.md"
-requires-python = ">=3.8"
-license = { file = "LICENSE" }
-authors = [
-    { name = "Islam Tlupov", email = "tlupovislam@gmail.com" },
-]
-classifiers = [
-    "Development Status :: 1 - Planning",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-]
-
-[project.urls]
-Homepage = "https://github.com/EmotionEngineer/nous"