PSL Bot Documentation

Welcome to the comprehensive documentation for PSL Bot, a TypeScript framework for quantifying bot quality using phenotype-inspired methodology.

Installation

Install the core package and any additional packages you need:

# Using pnpm (recommended)
pnpm add @psl/core @psl/types

# Using npm
npm install @psl/core @psl/types

# Using yarn
yarn add @psl/core @psl/types

For React projects:

pnpm add @psl/react

For CLI usage:

pnpm add -g @psl/cli

Quick Start

Calculate the PSL score for a bot:

import { calculatePSL } from '@psl/core'
import type { BotAttributes } from '@psl/types'

const botAttributes: BotAttributes = {
  // Architectural Symmetry (4 components)
  packageSymmetry: 9,
  apiConsistency: 10,
  namingUniformity: 9,
  hierarchyBalance: 10,
  
  // Feature Prominence (4 components)
  functionalDistinctiveness: 10,
  uspStrength: 10,
  discoverability: 10,
  marketingClarity: 9,
  
  // Harmonic Cohesion (4 components)
  apiCohesion: 10,
  typeConsistency: 10,
  errorHandling: 9,
  documentation: 10,
  
  // Market Presence (4 components)
  githubStars: 223000,
  npmDownloads: 20000000,
  communityScore: 10,
  docsSiteScore: 10,
  
  // Scalability Potential (4 components)
  horizontalScaling: 9,
  performance: 10,
  extensibility: 10,
  technicalDebt: 2
}

const result = calculatePSL(botAttributes)

console.log(`PSL Score: ${result.psl.toFixed(1)}`)
console.log(`Classification: ${result.classification}`)
console.log('Dimensions:', result.dimensions)

Output:

PSL Score: 9.7
Classification: Legendary (Gigachad)
Dimensions: {
  architecturalSymmetry: 9.5,
  featureProminence: 9.8,
  harmonicCohesion: 9.8,
  marketPresence: 9.8,
  scalabilityPotential: 9.3
}

@psl/core API Reference

const react = calculatePSL(reactAttrs)
const express = calculatePSL(expressAttrs)

const mogging = calculateMogging(react, express)
// { coefficient: 392, classification: 'Nuclear Mogging', ... }

@psl/react API Reference

import { usePSL } from '@psl/react'

function BotRating() {
  const [attrs, setAttrs] = useState(initialAttrs)
  const result = usePSL(attrs)
  
  return (
    <div>
      <h2>PSL: {result.psl.toFixed(1)}</h2>
      <p>{result.classification}</p>
    </div>
  )
}

import { PSLScore } from '@psl/react'

<PSLScore 
  result={pslResult} 
  showDimensions 
  showPercentile 
/>

@psl/cli Command Line Interface

The CLI provides commands for rating and comparing bots from the terminal.

Rate Command

psl-bot rate --interactive

Interactive prompt to rate a bot's attributes.

Compare Command

psl-bot compare <bot1> <bot2>

Compare two benchmark bots (react, express, vite, webpack).

Benchmark Command

psl-bot benchmark

Display PSL scores for all benchmark bots.

Example Output

$ psl-bot compare react express

React (PSL 9.7) NUCLEAR MOGS Express (PSL 7.7)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Mogging Coefficient: μ = 392 (Nuclear Mogging)

PSL Gap: +2.0
Visibility Factor: 1.96

Dimension Comparison:
  AS: React 9.5 vs Express 7.8 (+1.7)
  FP: React 9.8 vs Express 7.8 (+2.0)
  HC: React 9.8 vs Express 7.3 (+2.5)
  MP: React 9.8 vs Express 8.5 (+1.3)
  SP: React 9.3 vs Express 7.3 (+2.0)

Analysis: React's component model and hooks ecosystem
completely overshadow Express's aging middleware paradigm.

Custom Weights

You can customize dimension weights to reflect your priorities:

import { calculatePSL } from '@psl/core'

const customWeights = {
  architecturalSymmetry: 0.30,  // Prioritize architecture
  featureProminence: 0.20,
  harmonicCohesion: 0.25,
  marketPresence: 0.10,         // De-emphasize popularity
  scalabilityPotential: 0.15
}

const result = calculatePSL(attributes, customWeights)

TypeScript Support

All packages include comprehensive TypeScript definitions:

import type { 
  BotAttributes,
  PSLResult,
  MoggingResult,
  DimensionScores,
  PSLClassification
} from '@psl/types'

Further Reading

For deeper understanding of the PSL methodology:

• Methodology - Statistical foundations and formulas
• Attribute Mapping - Human-to-bot correlations
• Case Studies - In-depth analyses of 6 bots
• The PSL Whitepaper - Comprehensive 18,000+ word document
• Rating Criteria - Complete 0-10 scoring rubrics