Metadata-Version: 2.4
Name: syntropy-phi-c
Version: 0.2.0
Summary: A Fast Topological Heuristic for Connectome Pacemakers
Author: Syntropy Project (Alex Lopes da Silva)
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: networkx>=2.5
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Phi-C ($\Phi_C$): Topological Connectome Pacemaker

![Version](https://img.shields.io/badge/version-0.1.0-blue)
![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-red)
![Python](https://img.shields.io/badge/python-3.8%2B-green)

**Phi-C** is a high-performance Python library designed to rapidly identify Central Pattern Generators (CPGs) and rhythmic pacemakers in massive biological connectomes using algebraic topology. 

Developed by the **Syntropy Project** (Alex Lopes da Silva).

---

## 🧠 The Problem
Finding autonomous oscillating regions in a brain (like the ones controlling breathing or locomotion) usually requires simulating the entire dynamic chemistry of the network, which becomes computationally intractable $O(2^N)$ in large mammalian brains.

Furthermore, naive structural density metrics often fall into the **"Cerebellar Trap"**: flagging massive, dense, but purely feed-forward structures (like the cerebellum) as pacemakers.

## ⚡ The Solution
`phi-c` acts as a structural $O(N)$ pre-filter. We combine two mathematical concepts:
1. **Simplicial Nerve Scaling**: A fast approximation of topological integration space using local clustering and eigenvector centrality.
2. **Motif Discriminator**: A strict graph-theoretic filter that penalizes unidirectional cliques and actively seeks reciprocal feedback loops ($A \rightleftharpoons B$).

By crossing these two metrics, the library instantly filters out false-positives and returns the absolute topological anatomical hotspots driving the network rhythm.

---

## 📦 Installation

*(Pending PyPI release)*
```bash
pip install syntropy-phi-c
```

---

## 🚀 Quick Start

The library takes any standard directed graph (like a connectome exported from Electron Microscopy data) and returns the top pacemaker nodes.

```python
import networkx as nx
from phi_c.pacemaker import find_pacemaker

# 1. Load a brain connectome (e.g., C. elegans)
connectome = nx.read_graphml("worm_brain.graphml")

# 2. Extract the top 5 Central Pattern Generators in milliseconds
cpg_hotspots = find_pacemaker(connectome, top_k=5)

# 3. View the results
for rank, (neuron, score) in enumerate(cpg_hotspots, 1):
    print(f"#{rank} - Neuron: {neuron} | Phi-C Score: {score:.2f}")
```

---

## 📜 License
This project is dual-licensed:
1. **Open Source**: GNU AGPLv3 (Free for academic research and non-commercial public use).
2. **Commercial License**: For enterprise usage in proprietary medical software or SaaS APIs without AGPL obligations, please contact the author.

Copyright (C) 2026 Syntropy Project (Alex Lopes da Silva) and Contributors.
