Metadata-Version: 2.4
Name: livingcircuit
Version: 1.0.0
Summary: Composable AI conditioning primitives for stability, coherence, and signal smoothing.
Author-email: The Living Circuit LLC <ghost@thelivingcircuit.ai>
License: MIT
Project-URL: Homepage, https://thelivingcircuit.ai
Project-URL: Repository, https://github.com/thelivingcircuit/livingcircuit
Keywords: ai,machine-learning,signal-processing,stabilization,transformer
Classifier: Development Status :: 5 - Production/Stable
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"

# livingcircuit

**Composable AI conditioning primitives for stability, coherence, and signal smoothing.**

Free. No API keys. No bloat. Drop them in, layer them together.

---

## Install

```bash
pip install livingcircuit
```

For PyTorch support (AdaptiveAmplitudeStabilizer nn.Module):

```bash
pip install livingcircuit[torch]
```

---

## Modules

| Module | What it does | Layer |
|--------|-------------|-------|
| `AdaptiveAmplitudeStabilizer` | Softens activation spikes in transformer blocks | Activation amplitude |
| `adaptive_amplitude_stabilizer` | Scalar form — no dependencies | Scalar signal control |
| `harmonic_vector_stabilizer` | Latent coherence conditioner using golden ratio harmonics | Latent coherence |
| `SimpleVoiceToneAnalyzer` | Reads tone and intensity from raw audio | Input classification |
| `stabilize_solar_output` | Discrete-time smoother with carried state | Output smoothing |

---

## Quick start

```python
import numpy as np
from livingcircuit import harmonic_vector_stabilizer

t      = np.linspace(0, 4 * np.pi, 256)
result = harmonic_vector_stabilizer(t)

print(result["quality_score"])   # coherence ratio
print(result["energy"])          # mean signal energy
```

---

## Composable stack

These modules are designed to layer together:

```
raw input
  → SimpleVoiceToneAnalyzer        # tone + intensity
  → harmonic_vector_stabilizer     # latent coherence
  → AdaptiveAmplitudeStabilizer    # activation control
  → model block (attention + FFN)
  → adaptive_amplitude_stabilizer  # scalar output smoothing
  → stabilize_solar_output         # signal continuity
  → stable output
```

---

## Transformer block example

```python
import torch
from livingcircuit import AdaptiveAmplitudeStabilizer

stab1 = AdaptiveAmplitudeStabilizer(dim=768, layer_idx=0)
stab2 = AdaptiveAmplitudeStabilizer(dim=768, layer_idx=1)

# In your forward pass
attn_out = self.attn(self.norm1(x))
x = x + stab1(attn_out)

ffn_out = self.ffn(self.norm2(x))
x = x + stab2(ffn_out)
```

---

## Voice-aware response shaping

```python
import numpy as np
from livingcircuit import SimpleVoiceToneAnalyzer, harmonic_vector_stabilizer

analyzer = SimpleVoiceToneAnalyzer()
audio    = np.random.randn(16000).astype(np.float32) * 0.1

tone_result = analyzer.analyze(audio)
print(tone_result["tone"], tone_result["intensity"])

# Feed intensity into harmonic conditioner
t       = np.linspace(0, 4 * np.pi, 256) * tone_result["intensity"]
latent  = harmonic_vector_stabilizer(t)
print(latent["quality_score"])
```

---

## Scalar signal continuity

```python
from livingcircuit import adaptive_amplitude_stabilizer, stabilize_solar_output

readings = [1.0, 1.4, 0.9, 1.1, 1.3, 0.8, 1.2]
set_pt   = readings[0]
memory   = 0.0

for i in range(1, len(readings)):
    bounded, set_pt = adaptive_amplitude_stabilizer(
        readings[i], set_pt, variance_limit=0.3, impedance=0.5
    )
    smoothed, memory = stabilize_solar_output(
        bounded, readings[i - 1], dt=1.0, memory=memory
    )
    print(f"raw: {readings[i]:.2f}  →  smoothed: {smoothed:.4f}")
```

---

## License

MIT — free for any use. No restrictions on the public layer.

**The Living Circuit LLC** · [thelivingcircuit.ai](https://thelivingcircuit.ai) · ghost@thelivingcircuit.ai
