Conservation Spectral Analysis API

REST API for computing graph spectral properties related to conservation ratios, with support for anomaly detection and cross-domain comparison.

Quick Start

pip install -r requirements.txt
uvicorn main:app --reload

API available at http://localhost:8000. Interactive docs at /docs.

Docker

docker build -t conservation-api .
docker run -p 8000:8000 conservation-api

Endpoints

GET /health

Health check.

curl http://localhost:8000/health

POST /analyze

Full spectral analysis of an adjacency matrix.

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "adjacency": [
      [0, 1, 0, 1],
      [1, 0, 1, 0],
      [0, 1, 0, 1],
      [1, 0, 1, 0]
    ]
  }'

Returns: eigenvalues, conservation ratio (λ₂/λ_max), Fiedler vector, spectral gap, Cheeger constant estimate, node importance ranking.

POST /compare

Compare two adjacency matrices spectrally.

curl -X POST http://localhost:8000/compare \
  -H "Content-Type: application/json" \
  -d '{
    "adjacency_a": [[0,1,0],[1,0,1],[0,1,0]],
    "adjacency_b": [[0,1,1],[1,0,1],[1,1,0]]
  }'

Returns: alignment coefficient, eigenvalue cosine similarity, Fiedler partition comparison.

POST /detect-anomaly

Anomaly detection across a time series of adjacency matrices.

curl -X POST http://localhost:8000/detect-anomaly \
  -H "Content-Type: application/json" \
  -d '{
    "matrices": [
      [[0,1,0],[1,0,1],[0,1,0]],
      [[0,1,0],[1,0,1],[0,1,0]],
      [[0,0.1,0],[0.1,0,0.1],[0,0.1,0]]
    ],
    "threshold_sigma": 2.0
  }'

Returns: conservation ratio time series, anomalies (significant drops), change points.

GET /domains/{domain}

Preset adjacency matrices for known domains.

Available domains: music, ecology, economics, legal, neural, social, supply-chain.

curl http://localhost:8000/domains/music

Concepts

Conservation Ratio (CR) = λ₂(L) / λ_max(A), where λ₂ is the algebraic connectivity (Fiedler value) and λ_max is the largest adjacency eigenvalue. Higher CR indicates more robust, distributed connectivity.

Fiedler Vector: The eigenvector corresponding to λ₂ — its sign pattern reveals natural graph partitions.

Cheeger Constant: Lower bound estimate h ≈ λ₂/2, measuring how "bottlenecked" a graph is.

License

MIT

Part of the SuperInstance OpenConstruct ecosystem.