Metadata-Version: 2.4
Name: agencitylab
Version: 0.1.1
Summary: Scientific framework for the theory of Agencity
Project-URL: Homepage, https://github.com/Gilbert243/AgencityLab
Project-URL: Documentation, https://agencitylab.readthedocs.io
Project-URL: Source, https://github.com/Gilbert243/AgencityLab
Project-URL: Issues, https://github.com/Gilbert243/AgencityLab/issues
Author-email: Gilbert BEMWIZ <bemwizigilbert@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agencity,complex systems,dynamical systems,information physics,scientific computing,signal processing
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: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Provides-Extra: all
Requires-Dist: jax>=0.4; extra == 'all'
Requires-Dist: jaxlib>=0.4; extra == 'all'
Requires-Dist: matplotlib>=3.6; extra == 'all'
Requires-Dist: numba>=0.57; extra == 'all'
Requires-Dist: plotly>=5.0; extra == 'all'
Requires-Dist: seaborn>=0.12; extra == 'all'
Requires-Dist: streamlit>=1.25; extra == 'all'
Provides-Extra: app
Requires-Dist: streamlit>=1.25; extra == 'app'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: ml
Requires-Dist: jax>=0.4; extra == 'ml'
Requires-Dist: jaxlib>=0.4; extra == 'ml'
Requires-Dist: numba>=0.57; extra == 'ml'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == 'viz'
Requires-Dist: plotly>=5.0; extra == 'viz'
Requires-Dist: seaborn>=0.12; extra == 'viz'
Description-Content-Type: text/markdown

# AgencityLab
<<<<<<< HEAD

**AgencityLab** is a scientific Python framework dedicated to the study and quantification of **Agencity** — an observable designed to measure a system’s ability to actively structure its own evolution.

Unlike classical metrics (variance, entropy, energy), Agencity captures **dynamic organization and decision-like behavior within a system**, independent of domain-specific assumptions.

Agencity can be analyzed:
- at a **single scale**
- across **multiple scales** via the **Agencity spectrum** \( b(\tau) \)

---

## 👤 Author

**Gilbert BEMWIZ**  
Conceptor of the Agencity theory  
Engineer and developer of the AgencityLab framework  

---

## 🧠 Vision

AgencityLab aims to provide:

- a **rigorous computational implementation** of Agencity theory  
- a **domain-independent analysis tool** applicable to:
  - physical systems  
  - biological signals  
  - economic dynamics  
  - computational processes  
- an experimental platform to explore links with:
  - **Shannon information theory**
  - **Landauer’s principle**
  - **informational physics hypotheses** (e.g. Vopson)

---

## 🔬 Core Concept

Agencity is not a measure of randomness or order.

It quantifies:

> **the capacity of a system to select and sustain a trajectory among those allowed by its underlying dynamics**

This leads to a hierarchy of observables:

```

u → u* → X* → A* → M → O → β → b

````

Where:

- **u** : raw signal  
- **u*** : normalized signal  
- **X*** : activation  
- **A*** : activity  
- **M** : memory (causal correlation)  
- **O** : organization  
- **β** : structured agency  
- **b** : Agencity (final observable)

---

## ⚙️ Installation

```bash
pip install agencitylab
````

Optional features:

```bash
pip install agencitylab[visualization]
pip install agencitylab[dashboard]
pip install agencitylab[all]
```

---

## 🚀 Quick Start

```python
import numpy as np
from agencitylab.api import compute_agencity

xi = np.linspace(0, 10, 200)
u = np.sin(xi)

result = compute_agencity(xi, u)

print(result.summary())
```

---

## 📊 Visualization

```python
from agencitylab.api import visualize_agencity

visualize_agencity(result, kind="timeseries")
```

Available visualizations:

* `timeseries` → full pipeline signals
* `spectrum` → frequency structure of b
* `phase` → dynamic trajectories
* `components` → internal decomposition

---

## 📈 Multi-Scale Analysis

Agencity can be analyzed across scales:

```python
from agencitylab.analysis.multi_scale import agencity_spectrum

taus = [0.5, 1, 2, 5, 10]
spec = agencity_spectrum(xi, u, taus)
```

This produces a **multi-scale signature** of the system.

---

## 🧬 Agencity Signature

Each system exhibits a characteristic **Agencity signature**:

* constant → inactive
* sinus → structured dynamics
* noise → high variability, low organization
* multi-scale → emergent organization

This enables:

* system classification
* clustering
* regime detection

---

## 🧪 Example Systems

AgencityLab can analyze:

* periodic signals
* stochastic processes
* hybrid signals (signal + noise)
* multi-scale dynamics

---

## 📊 Comparison with Classical Metrics

Agencity complements traditional measures:

| Metric       | Captures                    | Limitation                     |
| ------------ | --------------------------- | ------------------------------ |
| Variance     | dispersion                  | ignores structure              |
| Entropy      | randomness                  | ignores dynamics               |
| Energy       | amplitude                   | ignores organization           |
| Autocorr     | temporal dependence         | local only                     |
| **Agencity** | dynamic structuring ability | multi-scale, causal, intrinsic |

---

## 🧠 Interpretation

* A **zigzag trajectory is not noise** if imposed by constraints
* A system is not “ordered” or “disordered” absolutely
* Agencity is **contextual and intrinsic to system dynamics**

---

## 📁 Project Structure

```
agencitylab/
├── core/            # mathematical operators
├── analysis/        # spectrum, signatures, clustering
├── api/             # user-facing interface
├── visualization/   # plotting tools
├── examples/        # usage examples
```

---

## 🔭 Roadmap

* [ ] Advanced multi-scale theory
* [ ] Real-world datasets integration
* [ ] GPU acceleration
* [ ] Interactive dashboards
* [ ] Scientific publication support

---

## 📜 License

MIT License

---

## 🤝 Contributions

Contributions are welcome.

You can:

* open issues
* propose improvements
* extend analysis modules
* test on new domains

---

## ⚠️ Disclaimer

Agencity is an emerging theoretical framework.
This library provides a computational implementation intended for:

* research
* experimentation
* conceptual exploration

---

## 🌍 Perspective

AgencityLab is part of a broader effort to build:

> **a unified science of dynamic systems combining physics, information, and structure**
=======
gencityLab** is a scientific Python framework dedicated to the study and quantification of **Agencity** — an observable designed to measure a system’s ability to actively structure its own evolution.
>>>>>>> 7fdb362e5a99ca437937b5eb65e42c67b4ba6f62
