# Aṇu Astra Python SDK

The official Python SDK for the **Aṇu Astra Virtual Quantum Processor** and **Post-Quantum Cryptography (PQC)** API.

Build and evaluate path-integral quantum circuits locally, run native OpenQASM 2.0 payloads, and secure your applications against "Store Now, Decrypt Later" threats using NIST-standardized Kyber and Dilithium algorithms.

## Documentation
Full API references and interactive tutorials are available at [docs.anuastra.com](https://astra.cryptopix.in/docs) (Coming Soon).

## Installation

Install the package via pip:

```bash
pip install anuastra
```

## Quick Start: Quantum Execution (Qiskit-Style)

The `QuantumCircuit` builder provides a declarative, strictly-typed interface mirroring industry standards like IBM Qiskit.

```python
from anuastra import Client, QuantumCircuit

# Initialize with your Developer Key
astra = Client(api_key='YOUR_API_KEY_HERE')

def run_quantum():
    # Scaffold a 2-qubit circuit
    circuit = QuantumCircuit(2)
    
    # Create a Bell State (Superposition + Entanglement)
    circuit.h(0)
    circuit.cx(0, 1)

    # Execute the circuit using the Aṇu Astra path-integral engine
    result = astra.execute(circuit, shots=10)
    
    print(f"Executed on: {result['engine']}")
    print(f"Measurement Result (Binary): {result['results']['state_binary']}")
    print(f"Credits Remaining: {result['remaining_credits']}")

if __name__ == "__main__":
    run_quantum()
```

## Quick Start: OpenQASM 2.0 Ingestion

For research teams migrating from legacy hardware, Aṇu Astra natively ingests raw `.qasm` strings.

```python
from anuastra import Client

astra = Client(api_key='YOUR_API_KEY_HERE')

qasm_payload = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];
"""

response = astra.execute_qasm(qasm_payload)
print(response['results'])
```

## Post-Quantum Cryptography (PQC)

The Aṇu Astra SDK exposes NIST FIPS-203 and FIPS-204 standardized algorithms.

### 1. Key Encapsulation (ML-KEM / Kyber)
Used for establishing symmetric quantum-resistant tunnels over public networks (TLS/TCP).

> [!IMPORTANT]
> **Zero-Trust Architecture (v1.0.2+)**: `keygen` and `decapsulate` are now executed entirely **locally** on your device using the pure-Python `fips203` distribution. Aṇu Astra never transmits or stores your private parameters.

```python
# 1. Generate keys LOCALLY (Server A)
# No private keys leave your device
keys = astra.kyber.keygen(level=768)
public_key = keys['public_key']
private_key = keys['private_key']

# 2. Encapsulate via VQP (Server B)
# Server B uses Public Key to create a Shared Secret + Ciphertext
capsule = astra.kyber.encapsulate(public_key)

# 3. Decapsulate LOCALLY (Server A)
# Server A uses Private Key + Ciphertext to derive the exact same Shared Secret
resolved = astra.kyber.decapsulate(capsule['ciphertext'], private_key)
```

### 2. Digital Signatures (ML-DSA / Dilithium)
Used for unbreakable document signing, firmware validation, and transaction authentication.

```python
# 1. Generate keys
keys = astra.dilithium.keygen(level=3)
public_key = keys['public_key']
private_key = keys['private_key']

# 2. Sign a payload
message = "Quantum Safe transaction payload"
signed = astra.dilithium.sign(message, private_key)

# 3. Verify the payload cryptographically
validation = astra.dilithium.verify(signed['signature'], message, public_key)
print(validation['is_valid']) # Returns True
```

## License
MIT
