synor/sdk/java/README.md

# Synor Compute SDK for Java

Access distributed heterogeneous compute at 90% cost reduction.

## Installation

### Maven

```xml
<dependency>
    <groupId>io.synor</groupId>
    <artifactId>compute-sdk</artifactId>
    <version>0.1.0</version>
</dependency>
```

### Gradle

```groovy
implementation 'io.synor:compute-sdk:0.1.0'
```

## Quick Start

```java
import io.synor.compute.*;

public class Example {
    public static void main(String[] args) {
        SynorCompute client = new SynorCompute("your-api-key");

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

        JobResult<Tensor> result = client.matmul(a, b)
            .precision(Precision.FP16)
            .processor(ProcessorType.GPU)
            .execute();

        if (result.isSuccess()) {
            System.out.println("Time: " + result.getExecutionTimeMs() + "ms");
            System.out.println("Cost: $" + result.getCost());
        }
    }
}
```

## Tensor Operations

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

// From array
double[][] data = {{1, 2, 3}, {4, 5, 6}};
Tensor tensor = Tensor.fromArray(data);

// Operations
Tensor reshaped = tensor.reshape(3, 2);
Tensor transposed = tensor.transpose();

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

## Builder Pattern API

```java
// Matrix multiplication
JobResult<Tensor> result = client.matmul(a, b)
    .precision(Precision.FP16)
    .processor(ProcessorType.GPU)
    .priority(Priority.HIGH)
    .execute();

// 2D Convolution
JobResult<Tensor> conv = client.conv2d(input, kernel)
    .stride(1, 1)
    .padding(1, 1)
    .execute();

// Attention
JobResult<Tensor> attention = client.attention(query, key, value)
    .numHeads(8)
    .flash(true)
    .execute();
```

## Async API with CompletableFuture

```java
import java.util.concurrent.CompletableFuture;

CompletableFuture<JobResult<Tensor>> future = client.matmul(a, b)
    .precision(Precision.FP16)
    .executeAsync();

future.thenAccept(result -> {
    System.out.println("Completed: " + result.isSuccess());
});
```

## LLM Inference

```java
// Single response
InferenceResult response = client.inference("llama-3-70b", "Explain quantum computing")
    .maxTokens(512)
    .temperature(0.7)
    .execute();
System.out.println(response.getResult());

// Streaming with callback
client.inferenceStream("llama-3-70b", "Write a poem", chunk -> {
    System.out.print(chunk);
});
```

## Configuration

```java
SynorConfig config = SynorConfig.builder()
    .apiKey("your-api-key")
    .baseUrl("https://api.synor.io/compute/v1")
    .defaultProcessor(ProcessorType.GPU)
    .defaultPrecision(Precision.FP16)
    .timeout(Duration.ofSeconds(30))
    .debug(true)
    .build();

SynorCompute client = new SynorCompute(config);
```

## Error Handling

```java
try {
    JobResult<Tensor> result = client.matmul(a, b).execute();
} catch (SynorException e) {
    System.err.println("API Error: " + e.getMessage());
    System.err.println("Status: " + e.getStatusCode());
}
```

## Enums

```java
// Processor types
ProcessorType.CPU
ProcessorType.GPU
ProcessorType.TPU
ProcessorType.NPU
ProcessorType.LPU
ProcessorType.FPGA
ProcessorType.AUTO

// Precision
Precision.FP64
Precision.FP32
Precision.FP16
Precision.BF16
Precision.INT8
Precision.INT4

// Job status
JobStatus.PENDING
JobStatus.RUNNING
JobStatus.COMPLETED
JobStatus.FAILED
```

## Requirements

- Java 11 or higher
- Gson for JSON serialization
- OkHttp for HTTP client

## Testing

```bash
mvn test
# or
./gradlew test
```

## License

MIT