npm package: @srs-solver/sdk
Description: TypeScript SDK for SRS Solver API - Quantum-inspired SAT solving
Author: Sebastian Schepis
Latest version: 0.0.1

# @srs-solver/sdk

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

## Installation

```bash
npm install @srs-solver/sdk
```

## Quick Start

```typescript
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

```typescript
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:**
```typescript
{
  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:**
```typescript
{
  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

```typescript
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

```typescript
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₃)`
```typescript
{
  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](https://github.com/yourusername/srs-solver-sdk/issues)