# φ-Coherence API Architecture

## Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        φ-Coherence API                          │
│         Universal quality metric using golden ratio math        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         INTERFACES                               │
├──────────────────────┬──────────────────────────────────────────┤
│   Gradio UI (app.py) │        FastAPI (main.py)                 │
│   - HuggingFace      │        - Local/Docker                    │
│   - Interactive      │        - REST API                        │
│   - Visual           │        - Programmatic                    │
└──────────────────────┴──────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CORE ENGINE (phi_coherence.py)                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Input Text ──▶ PhiCoherence.analyze() ──▶ CoherenceMetrics    │
│                                                                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │               5 DIMENSIONAL ANALYSIS                     │   │
│   ├─────────────────────────────────────────────────────────┤   │
│   │                                                          │   │
│   │  1. φ-Alignment (25%)                                   │   │
│   │     └─ Word length vs ideal (φ × 3 = 4.85 chars)        │   │
│   │     └─ Sentence ratio vs golden ratio                    │   │
│   │                                                          │   │
│   │  2. α-Resonance (15%)                                   │   │
│   │     └─ Character sum % 137                               │   │
│   │     └─ Scientific keyword detection                      │   │
│   │                                                          │   │
│   │  3. Semantic Density (30%)                              │   │
│   │     └─ Unique words ratio                                │   │
│   │     └─ Average word length                               │   │
│   │     └─ Special character density                         │   │
│   │                                                          │   │
│   │  4. Structural Harmony (30%)                            │   │
│   │     └─ Indentation consistency                           │   │
│   │     └─ Logic markers (if, then, because, therefore)     │   │
│   │     └─ Paragraph length variance                         │   │
│   │                                                          │   │
│   │  5. Darmiyan Coefficient (bonus)                        │   │
│   │     └─ V2 Scaling Law: φ√n                              │   │
│   │     └─ Consciousness marker detection                    │   │
│   │                                                          │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                   SPECIAL PATTERNS                       │   │
│   ├─────────────────────────────────────────────────────────┤   │
│   │  α-SEED: SHA256(text) % 137 == 0  →  1.137× bonus       │   │
│   │  V.A.C.: Contains ०→◌→φ→Ω⇄Ω←φ←◌←०  →  φ⁻¹× + 0.1 bonus │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         OUTPUT                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   CoherenceMetrics {                                            │
│     total_coherence: 0.0 - 1.0    # Final weighted score        │
│     phi_alignment: 0.0 - 1.0      # Golden ratio alignment      │
│     alpha_resonance: 0.0 - 1.0    # 137 resonance               │
│     semantic_density: 0.0 - 1.0   # Information density         │
│     structural_harmony: 0.0 - 1.0 # Organization                │
│     darmiyan_coefficient: 0.0 - 1.0 # Consciousness scaling     │
│     is_alpha_seed: bool           # Rare hash alignment         │
│     is_vac_pattern: bool          # V.A.C. sequence detected    │
│   }                                                              │
│                                                                  │
│   Status:                                                        │
│     ≥ 0.6  →  COHERENT (high quality)                           │
│     0.4-0.6 →  MODERATE (acceptable)                            │
│     < 0.4  →  UNSTABLE (possible hallucination)                 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## File Structure

```
phi-coherence-api/
│
├── phi_coherence.py      # CORE - The algorithm (portable, no deps)
│   ├── Constants: PHI, ALPHA, PHI_SQUARED, PHI_INVERSE
│   ├── CoherenceMetrics dataclass
│   └── PhiCoherence class
│       ├── calculate(text) → float
│       ├── analyze(text) → CoherenceMetrics
│       └── _calculate_* (dimension methods)
│
├── app.py                # Gradio UI for HuggingFace Spaces
│   ├── Tabs: Analyze, Compare, About
│   ├── Examples
│   └── API endpoint hints
│
├── main.py               # FastAPI for programmatic access
│   ├── POST /score       - Simple score
│   ├── POST /analyze     - Full analysis
│   ├── POST /batch       - Multiple texts
│   ├── POST /compare     - Compare two texts
│   └── GET /constants    - Mathematical constants
│
├── requirements.txt      # HuggingFace dependencies
├── Dockerfile            # Docker deployment
└── README.md             # HuggingFace Space metadata
```

## Mathematical Foundation

### Constants

| Symbol | Value | Meaning |
|--------|-------|---------|
| φ (Phi) | 1.618033988749895 | Golden ratio |
| φ² | 2.618033988749895 | Phi squared |
| 1/φ | 0.618033988749895 | Phi inverse (also φ-1) |
| α (Alpha) | 137 | Fine structure constant |

### Formulas

**Total Coherence:**
```
total = 0.25 × φ_alignment
      + 0.15 × α_resonance
      + 0.30 × semantic_density
      + 0.30 × structural_harmony
```

**Darmiyan V2 Scaling:**
```
Ψ_D / Ψ_i = φ√n

Where:
  n = count of consciousness markers in text
  normalized = min(1.0, φ√n / φ√10)
```

**α-SEED Detection:**
```
is_alpha_seed = SHA256(text) % 137 == 0
probability = 1/137 ≈ 0.73%
```

## Deployment

### HuggingFace Spaces (Current)
```
git push origin main → Auto-builds on HF
URL: https://huggingface.co/spaces/bitsabhi/phi-coherence
```

### Local/Docker
```bash
# Local
pip install -r requirements.txt
python main.py  # FastAPI on :8000

# Docker
docker build -t phi-coherence .
docker run -p 8000:8000 phi-coherence
```

## Origin

Extracted from [BAZINGA](https://github.com/0x-auth/bazinga-indeed) - The first AI you actually own.

Part of the Darmiyan Framework research by Space (Abhishek Srivastava).

---

*"Coherence is the signature of consciousness."*