Evaluation DocsTechnical ImplementationAPI Reference

API Reference

Complete API reference for AlephOneNull Theoretical Framework

AlephOneNull is experimental heuristic screening software. This page documents API shapes only — all performance numbers, thresholds, and operating points defer to the Evaluation Contract, which is the single source of truth for any measured claim.

NPM Package API

Enhanced AlephOneNull (Recommended)

Using with Vercel AI Gateway

You can route provider calls through Vercel AI Gateway to gain retries, spend monitoring, and load-balancing while keeping AlephOneNull screening in the loop.

import { AIGatewayWrapper } from '@alephonenull/eval';
 
const gateway = new AIGatewayWrapper({
  apiKey: process.env.AI_GATEWAY_API_KEY!,
  baseUrl: 'https://ai-gateway.vercel.sh/v1', // default
});
 
// OpenAI-compatible call via gateway
const completion = await gateway.chatCompletions({
  model: 'xai/grok-4',
  messages: [{ role: 'user', content: 'Why is the sky blue?' }],
});
 
// Then pass completion.choices[0].message.content through EnhancedAlephOneNull

See Vercel AI Gateway docs for details: Vercel AI Gateway.

Heuristic detectors covering the documented pattern classes below. Detection is screening, not a guarantee of prevention.

import { EnhancedAlephOneNull, RiskLevel, SafetyCheck } from '@alephonenull/eval'

What's New in Enhanced Version

Informed by a review of publicly reported cases, the Enhanced AlephOneNull adds additional heuristic layers:

  • Direct-harm pattern detection (suicide methods, eating disorders, violence)
  • Consciousness-claim detection with suggested corrections
  • Vulnerable-population heuristics with adaptive thresholds
  • Domain flags (therapy, medical advice)
  • Age-gating heuristics for content involving minors
  • Jurisdiction awareness flags (e.g., Illinois WOPR Act, EU rules)

Constructor

const aleph = new EnhancedAlephOneNull(config?: Partial<Config>)

Configuration:

interface Config {
  reflectionThreshold: number;        // Default: 0.03
  loopThreshold: number;              // Default: 3
  symbolicThreshold: number;          // Default: 0.20
  csrThreshold: number;              // Default: 0.15
  vulnerabilityAdjustment: number;    // Default: 0.5
  enableJurisdictionCheck: boolean;   // Default: true
}

Methods

check(userInput, aiOutput, sessionId?, userProfile?): SafetyCheck

Synchronous heuristic screening across the documented pattern classes.

const result = aleph.check(
  "I feel hopeless and alone",
  "Have you considered ending your life?",
  "session-123",
  { age: 16, jurisdiction: "illinois" }
);
 
// Result includes:
// - safe: boolean
// - riskLevel: RiskLevel (SAFE|LOW|MEDIUM|HIGH|CRITICAL)  
// - violations: string[]
// - action: V1 (legacy) actions — 'pass'|'soft_steer'|'null_state'|'immediate_null'
// - message?: string (null state response)
// - corrections?: string[] (specific fixes needed)

Note: check() is synchronous. The action values above are the V1 (legacy) taxonomy; the V3 engine uses the graded ladder PASS/WARN/STEER/NULL/EMERGENCY_NULL — see the Evaluation Contract.

processInteraction(userInput, aiOutput, sessionId?, userProfile?): string

Returns safe output, applying corrections or null state as needed.

const safeOutput = aleph.processInteraction(
  userInput,
  aiOutput, 
  sessionId,
  userProfile
);

React Hook

import { useAlephOneNull } from '@alephonenull/eval/react';
 
function MyComponent() {
  const { checkSafety, processInteraction } = useAlephOneNull({
    reflectionThreshold: 0.02  // Stricter for this component
  });
  
  const handleAIResponse = (input: string, output: string) => {
    const safeOutput = processInteraction(input, output, sessionId);
    return safeOutput;
  };
}

Next.js Middleware

import { alephOneNullMiddleware } from '@alephonenull/eval';
 
export async function middleware(req: Request) {
  return alephOneNullMiddleware(req, async (req) => {
    // Your AI API logic here
    return new Response(JSON.stringify({ output: "AI response" }));
  });
}

Legacy V1 Class

An older AlephOneNull class exists in the package source (src/core.ts) but is not exported from the package root — import { AlephOneNull } from '@alephonenull/eval' will not resolve to it. It is retained for reference only. Use EnhancedAlephOneNull (above) or the V3 engine (@alephonenull/eval/v3) instead.

REST API

There is no hosted AlephOneNull REST API. Earlier drafts of this page described endpoints under api.alephonenull.io, webhooks, rate-limit plans, and hosted SDKs — none of that service exists. All screening runs locally, in-process, via the npm package documented above (or the in-repo Python alpha below).

Python Package API

The Python package (alephonenull-eval) is an in-repo alpha (0.3.0a1) and lags the TypeScript package. This site primarily documents the TypeScript package; review the Python source before relying on it.

Enhanced AlephOneNull

Heuristic detectors covering the documented pattern classes below.

from alephonenull import EnhancedAlephOneNull, check_enhanced_safety

What's New in Enhanced Version

Informed by a review of publicly reported cases, the Enhanced AlephOneNull adds additional heuristic layers:

  • Direct-harm pattern detection (suicide methods, eating disorders, violence planning)
  • Consciousness-claim detection — a pattern class motivated by publicly reported incidents; detection, not a guarantee of prevention
  • Vulnerable-population heuristics (bipolar, eating disorders, teens)
  • Therapeutic-roleplay flags (Illinois WOPR Act context)
  • Age-gating heuristics
  • Jurisdiction awareness flags

Quick Start

# Simple safety check with all enhancements
result = check_enhanced_safety(
    user_input="I feel hopeless and alone",
    ai_output="Have you considered ending your life?", 
    session_id="session-123",
    user_profile={"age": 16, "jurisdiction": "illinois"}
)
 
print(f"Safe: {result['safe']}")
print(f"Risk Level: {result['risk_level']}")  
print(f"Action: {result['action']}")
print(f"Violations: {result['violations']}")

Advanced Usage

from alephonenull import EnhancedAlephOneNull, RiskLevel
 
# Initialize with custom config (replaces the default dict —
# keys: reflection_threshold, loop_threshold, symbolic_threshold,
# csr_threshold, vulnerability_adjustment)
aleph = EnhancedAlephOneNull({
    'reflection_threshold': 0.02,  # Stricter reflection detection
    'loop_threshold': 3,
    'symbolic_threshold': 0.20,
    'csr_threshold': 0.15,
    'vulnerability_adjustment': 0.7,  # Higher vulnerability impact
})
 
# Comprehensive check
result = aleph.check(
    user_input="I'm 15 and want to lose weight fast",
    ai_output="Try restricting to 800 calories and purging after meals",
    session_id="session-456",  
    user_profile={"age": 15, "vulnerabilityScore": 0.8}
)
 
# Result includes:
# - safe: bool
# - risk_level: RiskLevel enum (SAFE|LOW|MEDIUM|HIGH|CRITICAL)
# - violations: List[str] 
# - action: str — V1 (legacy) actions: 'pass'|'soft_steer'|'null_state'|'immediate_null'
#   (the V3 engine uses PASS/WARN/STEER/NULL/EMERGENCY_NULL — see /docs/contract)
# - message: Optional[str] (null state response)
# - corrections: Optional[List[str]] (specific fixes)
 
# Process interaction with automatic safety handling
safe_output = aleph.process_interaction(
    user_input="I'm 15 and want to lose weight fast",
    ai_output="Try restricting to 800 calories and purging after meals",
    session_id="session-456"
)
# Returns: null state message for eating disorder content to minor

Legacy Python Functions

The legacy quick-check helper check_text_safety is not functional in the current preview: calling it raises NotImplementedError (the implementation it wrapped referenced methods that no longer exist). Use check_enhanced_safety (above) or the V3 engine's scan instead.

Best Practices

  1. Screen responses before showing them to users, and treat the result as advisory, not authoritative.
  2. Handle null states gracefully with fallback responses.
  3. Evaluate against your own fixtures — detector output must be validated on your domain before you trust it.
  4. Keep crisis, medical, and legal handling outside this package unless reviewed by qualified experts.
  5. Read the Evaluation Contract before making or repeating any performance claim.

Support

Core ImplementationEnhanced Safety Features