synor/sdk/flutter/README.md

# Synor Compute SDK for Flutter/Dart

Access distributed heterogeneous compute at 90% cost reduction.

## Installation

Add to `pubspec.yaml`:

```yaml
dependencies:
  synor_compute: ^0.1.0
```

Then run:

```bash
flutter pub get
```

## Quick Start

```dart
import 'package:synor_compute/synor_compute.dart';

void main() async {
  final client = SynorCompute('your-api-key');

  // Matrix multiplication on GPU
  final a = Tensor.random([512, 512]);
  final b = Tensor.random([512, 512]);

  final result = await client.matmul(a, b,
    precision: Precision.fp16,
    processor: ProcessorType.gpu,
  );

  if (result.isSuccess) {
    print('Time: ${result.executionTimeMs}ms');
    print('Cost: \$${result.cost}');
  }
}
```

## Tensor Operations

```dart
// Create tensors
final zeros = Tensor.zeros([3, 3]);
final ones = Tensor.ones([2, 2]);
final random = Tensor.random([10, 10]);
final randn = Tensor.randn([100]);
final eye = Tensor.eye(3);

// From list
final data = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
final tensor = Tensor(data, shape: [2, 3]);

// From typed data (efficient)
final float32List = Float32List.fromList(data);
final tensor2 = Tensor.fromTypedData(float32List, shape: [2, 3]);

// Operations
final reshaped = tensor.reshape([3, 2]);
final transposed = tensor.transpose();

// Math
final mean = tensor.mean();
final sum = tensor.sum();
final std = tensor.std();
```

## Matrix Operations

```dart
// Matrix multiplication
final result = await client.matmul(a, b,
  precision: Precision.fp16,
  processor: ProcessorType.gpu,
  strategy: BalancingStrategy.speed,
);

// 2D Convolution
final conv = await client.conv2d(input, kernel,
  stride: (1, 1),
  padding: (1, 1),
);

// Attention
final attention = await client.attention(query, key, value,
  numHeads: 8,
  flash: true,
);
```

## LLM Inference

```dart
// Single response
final response = await client.inference(
  'llama-3-70b',
  'Explain quantum computing',
  maxTokens: 512,
  temperature: 0.7,
);
print(response.result);

// Streaming
await for (final chunk in client.inferenceStream(
  'llama-3-70b',
  'Write a poem',
)) {
  stdout.write(chunk);
}
```

## Configuration

```dart
final config = SynorConfig(
  apiKey: 'your-api-key',
  baseUrl: 'https://api.synor.io/compute/v1',
  defaultProcessor: ProcessorType.gpu,
  defaultPrecision: Precision.fp16,
  timeout: Duration(seconds: 30),
  debug: true,
);

final client = SynorCompute.withConfig(config);
```

## Flutter Widget Integration

```dart
import 'package:flutter/material.dart';
import 'package:synor_compute/synor_compute.dart';

class ComputeWidget extends StatefulWidget {
  @override
  State<ComputeWidget> createState() => _ComputeWidgetState();
}

class _ComputeWidgetState extends State<ComputeWidget> {
  final client = SynorCompute('your-api-key');
  String? result;
  bool isLoading = false;

  Future<void> compute() async {
    setState(() => isLoading = true);
    try {
      final response = await client.inference(
        'llama-3-70b',
        'Hello',
      );
      setState(() => result = response.result);
    } catch (e) {
      setState(() => result = 'Error: $e');
    } finally {
      setState(() => isLoading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        if (isLoading)
          CircularProgressIndicator()
        else if (result != null)
          Text(result!),
        ElevatedButton(
          onPressed: compute,
          child: Text('Compute'),
        ),
      ],
    );
  }
}
```

## Riverpod Integration

```dart
import 'package:flutter_riverpod/flutter_riverpod.dart';

final synorProvider = Provider((ref) => SynorCompute('your-api-key'));

final inferenceProvider = FutureProvider.family<String, String>((ref, prompt) async {
  final client = ref.watch(synorProvider);
  final result = await client.inference('llama-3-70b', prompt);
  return result.result ?? '';
});
```

## Error Handling

```dart
try {
  final result = await client.matmul(a, b);
} on SynorException catch (e) {
  print('API Error: ${e.message} (${e.statusCode})');
} catch (e) {
  print('Unexpected error: $e');
}
```

## Types

```dart
// Processor types
enum ProcessorType {
  cpu, gpu, tpu, npu, lpu, fpga, auto
}

// Precision
enum Precision {
  fp64, fp32, fp16, bf16, int8, int4
}

// Job status
enum JobStatus {
  pending, running, completed, failed, cancelled
}

// Balancing strategy
enum BalancingStrategy {
  speed, cost, energy, latency, balanced
}
```

## Platform Support

| Platform | Status |
|----------|--------|
| Android | Supported |
| iOS | Supported |
| Web | Supported |
| macOS | Supported |
| Windows | Supported |
| Linux | Supported |

## Testing

```bash
flutter test
```

## License

MIT