Metadata-Version: 2.4
Name: seraphim-logic-core
Version: 0.1.0
Summary: Quantum-classical hybrid symbolic agent framework — Seraphim |LZ⟩
Author-email: "Perfect Squared Inc. | P2 Labs" <contact@perfectsquaredinc.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/10XAnalytics/seraphim-logic-core
Project-URL: Repository, https://github.com/10XAnalytics/seraphim-logic-core
Project-URL: Bug Tracker, https://github.com/10XAnalytics/seraphim-logic-core/issues
Keywords: quantum,symbolic-ai,agents,pennylane,entropy,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pennylane>=0.36
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# seraphim-logic-core

**Quantum-Classical Hybrid Symbolic Agent Framework**  
Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩

> *Agents of the Highest Order*

---

## Overview

`seraphim-logic-core` is the symbolic intelligence engine behind the Seraphim |LZ⟩ research initiative. It implements a quantum-native agent framework where agents exist in superposition across all symbolic states and collapse to a single truth via a PennyLane quantum circuit.

```
|S⟩ = Σ αᵢ |sᵢ⟩  →  |s*⟩

P(kᵢ) ∝ exp(-Entropy(kᵢ))
D = argmax_i(I(sᵢ) - β·E(sᵢ))
```

## Architecture

```
seraphim_logic_core/
├── constants.py     — System constants (entropy thresholds, lifecycle states)
├── entropy.py       — XOR-Lattice Entropy Engine (Shannon entropy, XOR diff, anomaly detection)
├── grammar.py       — Symbolic Grammar Engine (symbols, rules, pre-built grammars)
├── collapse.py      — Quantum Collapse Engine (PennyLane StatePrep + probs)
├── agent.py         — SymbolicAgent (full ENCODED→DELIVERED lifecycle)
└── swarm.py         — AgentSwarm (parallel agent coordination + entropy-aware voting)
```

## Agent Lifecycle

```
ENCODED → EVOLVED → INITIALIZED → COLLAPSED → ACTIVATED → DELIVERED
```

Each agent:
1. **Encodes** a symbolic grammar into its logic space
2. **Evolves** via grammar transition rules driven by entropy signals
3. **Initializes** as |LZ⟩ — superposition across all states
4. **Collapses** via PennyLane quantum circuit to |s*⟩
5. **Activates** — emits a structured decision dict
6. **Delivers** to the target system (QUANTA handler)

## Quick Start

```python
from seraphim_logic_core import SymbolicAgent, AgentSwarm
from seraphim_logic_core import threat_detection_grammar, integrity_grammar

# Single agent — threat detection
agent = SymbolicAgent(grammar=threat_detection_grammar())
result = agent.run(entropy_signal=0.85)
print(result["symbol"])  # e.g. "ANOMALOUS"

# Swarm — integrity monitoring
swarm = AgentSwarm(grammar=integrity_grammar())
verdict = swarm.respond_to_xor_event(window_1, window_2)
print(verdict["symbol"])  # e.g. "DEGRADED"
```

## Pre-Built Grammars

| Grammar | Product | States |
|---------|---------|--------|
| `threat_detection_grammar()` | QUANTA-PULSE / QUANTA-RAD | NOMINAL → ANOMALOUS → SPOOFED → CONFIRMED → RESOLVED |
| `integrity_grammar()` | QUANTA-VIGIL | SECURE → DEGRADED → BREACHED → RESTORING |

## Installation

```bash
pip install seraphim-logic-core
```

**Development:**
```bash
git clone https://github.com/10XAnalytics/seraphim-logic-core
cd seraphim-logic-core
pip install -e ".[dev]"
pytest
```

## Quantum Backend

Uses [PennyLane](https://pennylane.ai/) `default.qubit` simulator (1024 shots).  
Production deployments can target real quantum hardware via PennyLane device plugins.

Classical fallback available for testing:
```python
agent = SymbolicAgent(grammar=threat_detection_grammar(), use_quantum=False)
```

## License

Apache 2.0 — See [LICENSE](LICENSE)

---

*Perfect Squared Inc. | P2 Labs — "Simulate the Future. Secure the Present."*
