# Superrank Comprehensive Specification & Technical Reference
> The Trusted Ranking of AI Models, Agents, Benchmarks, Organizations, and the People Building Them.
> Canonical Base URL: https://superrank.tech

---

## 1. System Mission & Core Governance Rules

Superrank exists to provide an uncompromised, mathematically transparent source of truth for the artificial intelligence ecosystem.
All cataloging, rankings, and badge allocations strictly enforce 7 non-negotiable rules:

1. Rule 1: Zero Fake Data. Never invent synthetic scores, mock metrics, imaginary release dates, or hallucinated parameter sizes.
2. Rule 2: Honest Empty States. When verified benchmark data or ratings are unavailable, state 'Not yet tested' or '0 ratings recorded' rather than generating dummy numbers.
3. Rule 3: Sourced Provenance. Every factual attribute (context window, parameters, license, benchmark score) stores an immutable citation URL with exact retrieval timestamp.
4. Rule 4: Rights-Managed Media. Only store and render logos/avatars with verified open licenses or self-hosted compressed WebP thumbnails with explicit source attribution.
5. Rule 5: Zero Hardcoded Secrets. All credentials, API keys, and database connection strings use validated environment variables via Zod schemas.
6. Rule 6: Defense-in-Depth. Every mutating endpoint requires authenticated sessions, CSRF origin verification, and strict schema validation.
7. Rule 7: Mathematical Transparency. Every leaderboard rank is deterministically calculable using public formulas. No black-box curation or pay-to-play placements.

---

## 2. Mathematical Scoring Formulas

### 2.1 Bayesian Rating Shrinkage
To prevent distortion and gaming by low-volume voter manipulation, Superrank applies empirical Bayes shrinkage:

    W = (v / (v + m)) * R + (m / (v + m)) * C

Where:
- v = Total verified community ratings for the entity
- R = Arithmetic mean of received community ratings (1.0 to 10.0 scale)
- m = Minimum vote confidence threshold (Default: m = 25)
- C = Global catalog prior mean across all entities of the same type (Default: C = 7.0 on 1.0 to 10.0 scale)

When v < 25, the public UI displays "Not enough ratings yet" with exact count.
When v >> m, the score approaches the true community sample mean R.

### 2.2 Composite Model Ranking
Composite evaluation synthesizes 3 authoritative components derived directly from verified data:

    S_composite = 0.40 * S_benchmark + 0.40 * S_userRating + 0.20 * S_value

Where:
- S_benchmark (40%): Normalized benchmark performance (0.00 to 10.00) across standardized suites (MMLU-Pro, HumanEval, SWE-bench, GSM8K).
- S_userRating (40%): Bayesian-weighted community score (1.00 to 10.00) from authenticated reviews.
- S_value (20%): Pricing and compute efficiency score (0.00 to 10.00) calculated from input/output token pricing per 1M tokens (open-weights models receive maximum 10.0 tier).

### 2.3 Trending Momentum & Velocity
The trending leaderboard tracks organic growth over a rolling 7-day window vs an 8–14 day baseline:

    TrendingScore = (RatingVelocity + WatchlistMomentum) * QualityFactor * RecencyBoost

Where WatchlistMomentum is weighted at 2.5x and QualityFactor scales between 0.5 and 1.2 based on verified rating health.

### 2.4 People & Researcher Reputation
Derived strictly from objective, sourced contributions to indexed models and agents:

    Score = (AvgTop5EntityScores) * 0.8 + min(2.0, log2(TotalCredits + 1) * 0.5)

---

## 3. Entity Models & Schemas

### 3.1 AI Models (/models)
- Name: string
- Slug: unique URL identifier
- Organization: Organization reference (ID, name)
- Parameter Count: Numerical value and unit (e.g. 70B, 405B)
- Context Window: Maximum supported tokens (e.g. 128,000, 1,000,000, 2,000,000)
- License: Open Weights, Open Source (Apache 2.0, MIT), or Proprietary Commercial
- Modalities: Text, Image, Audio, Video, Code, Multimodal
- Pricing: Input price and output price per 1,000,000 tokens in USD

### 3.2 AI Agents (/agents)
- Name: string
- Category: Coding, Research, Automation, Reasoning, General Assistant, Multimodal
- Framework: LangChain, CrewAI, AutoGen, Custom, LlamaIndex
- Autonomy Level: Semi-Autonomous (human-in-the-loop) or Fully Autonomous

### 3.3 Benchmarks (/benchmarks)
- Metric: Benchmark metric name (e.g. Accuracy %, Pass@1, Solved Rate %, Elo)
- Higher is Better: boolean (true for accuracy, false for perplexity / error rate)
- Domain: Reasoning, Coding, Mathematics, Safety, Agentic, Multimodal

### 3.4 Organizations (/companies)
- Name: string
- Category: AI Research Lab, Big Tech, AI Startup, Open Source Collective, University
- Founded Year: integer
- Headquarters: City, Country

### 3.5 People (/people)
- Name: string
- Role: Researcher, Architect, Founder, Engineer, Contributor
- Affiliations: Organization history and credited models

---

## 4. API Endpoints for Answer Engines & Tools

- GET /api/rankings?category={models|agents|benchmarks|people|trending}&openWeights={true|false}
- GET /api/search/suggest?q={query}
- GET /api/compare?type={model|agent}&slugs={slug1,slug2}
- GET /api/reviews?subjectType={model|agent}&subjectId={id}

---

## 5. Structured Data Standards
All public pages render Schema.org JSON-LD scripts:
- WebSite & Organization (Global / Layout)
- SoftwareApplication (Models & Agents)
- Dataset (Benchmarks)
- Organization (Company Profiles)
- Person (Researcher Profiles)
- ItemList (Leaderboards & Rankings)
- BreadcrumbList (Navigation Hierarchy)
- FAQPage (Methodology & Scoring)