# Ravan SDK

High-level Python client for the Ravan Quantum-ML system. Works with a running API server or directly with local models (auto fallback).

## Install

From repo root:

```
pip install -e ravan_sdk
```

## Usage

```python
from ravan_sdk import Ravan

# auto: prefer HTTP at http://localhost:8000; fallback to local
client = Ravan(mode="auto")

# Predict: [apply_hadamard, apply_cnot, shots_norm]
res = client.predict([1, 1, 0.5])
print(res)

# Inverse design (optimize to target entropy/fidelity)
opt = client.inverse.run(target_entropy=0.95, target_fidelity=0.95)
print(opt)
```

## Modes
- auto: Prefer HTTP; fallback to local
- http: Force HTTP; raises if server is unavailable
- local: Force local models (ONNX > PyTorch)

## HTTP Auth
Pass `api_key` to include `Authorization: Bearer <key>` header.

```python
client = Ravan(mode="http", api_key="YOUR_TOKEN")
```

## Simulators
When available, you can call simulators either via HTTP or locally:

```python
qc = client.simulate_quantum_circuit({
    "n_qubits": 2, "shots": 2048, "apply_hadamard": 1, "apply_cnot": 1
})
sch = client.simulate_schrodinger({
    "V0": 5.0, "barrier_width": 1.0, "k0": 10.0, "sigma": 1.0,
    "x0": -8.0, "L": 50.0, "Nx": 1024, "dt": 0.005, "n_steps": 1000
})
ho = client.simulate_harmonic_oscillator({
    "oscillator_length": 1.0, "basis_size": 30, "initial_n": 0
})
```

## Benchmarks

```python
results = client.benchmark.run()
print(results)
```

# Ravan SDK

High-level Python client for the Ravan Quantum-ML system. Works with a running API server or directly with local models (auto fallback).

## Install

From repo root:

```
pip install -e .
```

## Usage

```python
from ravan_sdk import Ravan

# auto: prefer HTTP at http://localhost:8000; fallback to local
client = Ravan(mode="auto")

# Predict: [apply_hadamard, apply_cnot, shots_norm]
res = client.predict([1, 1, 0.5])
print(res)

# Inverse design (optimize to target entropy/fidelity)
opt = client.inverse.run(target_entropy=0.95, target_fidelity=0.95)
print(opt)
```

## Modes
- auto: Prefer HTTP; fallback to local
- http: Force HTTP; raises if server is unavailable
- local: Force local models (ONNX > PyTorch)

## HTTP Auth
Pass `api_key` to include `Authorization: Bearer <key>` header.

```python
client = Ravan(mode="http", api_key="YOUR_TOKEN")
```

## Simulators
When available, you can call simulators either via HTTP or locally:

```python
qc = client.simulate_quantum_circuit({
    "n_qubits": 2, "shots": 2048, "apply_hadamard": 1, "apply_cnot": 1
})
sch = client.simulate_schrodinger({
    "V0": 5.0, "barrier_width": 1.0, "k0": 10.0, "sigma": 1.0,
    "x0": -8.0, "L": 50.0, "Nx": 1024, "dt": 0.005, "n_steps": 1000
})
ho = client.simulate_harmonic_oscillator({
    "oscillator_length": 1.0, "basis_size": 30, "initial_n": 0
})
```

## Benchmarks

```python
results = client.benchmark.run()
print(results)
```


