@srs-solver/sdk

TypeScript/JavaScript SDK for the SRS Solver API - A quantum-inspired SAT solver using Symbolic Resonance Collapse.

Installation

npm install @srs-solver/sdk

Quick Start

import { SRSSolverClient } from '@srs-solver/sdk';

// Initialize the client with your API key
const client = new SRSSolverClient('your-api-key');

// Solve a SAT problem
const result = await client.solve({
  numVars: 3,
  clauses: [
    { literals: [1, 2] },
    { literals: [-1, 3] },
    { literals: [-2, -3] }
  ],
  maxIterations: 100,
  returnDiagnostics: true
});

console.log('Satisfiable:', result.satisfiable);
console.log('Solution:', result.solution);
console.log('Execution time:', result.executionTime, 'ms');

Features

• ✅ Type-safe - Full TypeScript support with type definitions
• ✅ Rate limiting - Built-in rate limiting to prevent API throttling
• ✅ Automatic retries - Configurable retry logic for failed requests
• ✅ Request queueing - Efficient request management with concurrency control
• ✅ Error handling - Comprehensive error handling and reporting

API Reference

SRSSolverClient

Constructor

new SRSSolverClient(apiKey: string, baseUrl?: string)

• apiKey - Your SRS Solver API key (get one from the dashboard)
• baseUrl - Optional custom API endpoint

Methods

solve(request: SolveRequest): Promise<SolveResponse>

Solve a SAT problem.

Request Parameters:

{
  numVars: number;              // Number of variables in the problem
  clauses: SATClause[];         // Array of clauses
  maxIterations?: number;       // Maximum iterations (default: 150)
  lambda?: number;              // Decay constant (default: 0.15)
  returnDiagnostics?: boolean;  // Include detailed diagnostics (default: false)
}

Response:

{
  success: boolean;             // Whether the request succeeded
  satisfiable: boolean;         // Whether a solution was found
  solution?: number[];          // Variable assignments if satisfiable
  iterations: number;           // Number of iterations performed
  executionTime: number;        // Execution time in milliseconds
  metrics?: {
    finalEntropy: number;
    finalCoherence: number;
    finalEnergy: number;
    satisfactionRatio: number;
  };
  detailed_diagnostics?: {
    entropy_history: number[];
    coherence_history: number[];
    energy_history: number[];
    satisfaction_history: number[];
  }
}

setApiKey(apiKey: string): void

Update the API key.

Advanced Usage

Custom Configuration

import { DynamicApi, ApiConfig } from '@srs-solver/sdk';

const apiConfig: ApiConfig = {
  baseUrl: 'https://your-custom-endpoint.com',
  endpoints: {
    customEndpoint: {
      method: 'POST',
      path: '/custom',
      rateLimitPerSecond: 5,
      retryConfig: {
        maxRetries: 3,
        retryDelay: 1000
      }
    }
  },
  globalHeaders: {
    'X-Custom-Header': 'value'
  },
  timeout: 30000
};

const dynamicApi = new DynamicApi(apiConfig);
const api = dynamicApi.createApiMethods();

Error Handling

try {
  const result = await client.solve({
    numVars: 3,
    clauses: [{ literals: [1, 2] }]
  });
  
  if (result.satisfiable) {
    console.log('Solution found:', result.solution);
  } else {
    console.log('No solution exists');
  }
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid API key');
  } else if (error.response?.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Request failed:', error.message);
  }
}

SAT Problem Format

Clauses are represented in CNF (Conjunctive Normal Form):

• Positive literals: variable is true (e.g., 1 means x₁ = true)
• Negative literals: variable is false (e.g., -1 means x₁ = false)

Example: (x₁ ∨ x₂) ∧ (¬x₁ ∨ x₃)

{
  numVars: 3,
  clauses: [
    { literals: [1, 2] },   // x₁ OR x₂
    { literals: [-1, 3] }   // NOT x₁ OR x₃
  ]
}

License

MIT

Support

For issues and questions, visit GitHub Issues