@epochcore/qaas-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,81 @@
+EpochCore QaaS SDK License Agreement
+=====================================
+
+Copyright (c) 2025 EpochCore. All Rights Reserved.
+
+IMPORTANT: READ CAREFULLY BEFORE USING THIS SOFTWARE
+
+This EpochCore QaaS SDK ("Software") is the proprietary property of
+EpochCore and is protected by copyright laws and international treaties.
+
+1. LICENSE GRANT
+----------------
+Subject to the terms of this Agreement and a valid QaaS API subscription,
+EpochCore grants you a limited, non-exclusive, non-transferable license to:
+
+  a) Use the Software to access the QaaS API services
+  b) Integrate the Software into your applications
+  c) Make copies of the Software for backup purposes only
+
+2. RESTRICTIONS
+---------------
+You may NOT:
+
+  a) Modify, reverse engineer, decompile, or disassemble the Software
+  b) Remove or alter any proprietary notices, labels, or marks
+  c) Sublicense, rent, lease, or lend the Software to third parties
+  d) Use the Software to create a competing product or service
+  e) Use the Software without a valid QaaS API subscription
+  f) Redistribute the source code or any derivative works
+  g) Use automated means to access the API beyond your subscription limits
+
+3. INTELLECTUAL PROPERTY
+------------------------
+The Software, including all algorithms, architecture, and implementations,
+remains the exclusive property of EpochCore. This license does not grant
+you any ownership rights to the Software or underlying quantum algorithms.
+
+4. API SUBSCRIPTION REQUIRED
+----------------------------
+Use of this Software requires an active QaaS API subscription. The Software
+will not function without valid API credentials obtained through:
+
+  https://qaas.epochcoreqcs.com
+
+5. TERMINATION
+--------------
+This license automatically terminates if you:
+
+  a) Violate any terms of this Agreement
+  b) Cancel or fail to renew your QaaS API subscription
+  c) Attempt to circumvent usage limits or access controls
+
+Upon termination, you must destroy all copies of the Software.
+
+6. WARRANTY DISCLAIMER
+----------------------
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. EPOCHCORE
+DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NON-INFRINGEMENT.
+
+7. LIMITATION OF LIABILITY
+--------------------------
+IN NO EVENT SHALL EPOCHCORE BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES ARISING OUT OF OR RELATED
+TO YOUR USE OF THE SOFTWARE.
+
+8. GOVERNING LAW
+----------------
+This Agreement shall be governed by the laws of the State of Delaware,
+United States, without regard to its conflict of law provisions.
+
+9. CONTACT
+----------
+For licensing inquiries:
+  Email: CEO.QuantumAmazon@EpochCoreQcs.com
+  Web: https://epochcoreqcs.com
+
+=====================================
+EpochCore - Quantum Computing Solutions
+All Rights Reserved 2025

package/README.md

@@ -0,0 +1,440 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Quantum-Computing-6366f1?style=for-the-badge&logo=atom&logoColor=white" alt="Quantum Computing"/>
+  <img src="https://img.shields.io/badge/100+-Algorithms-10b981?style=for-the-badge" alt="100+ Algorithms"/>
+  <img src="https://img.shields.io/badge/REST-API-f59e0b?style=for-the-badge" alt="REST API"/>
+</p>
+
+<h1 align="center">
+  <br>
+  QaaS - Quantum as a Service
+  <br>
+</h1>
+
+<h4 align="center">Access 100 production-ready quantum algorithms via a simple REST API.</h4>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@epochcore/qaas-sdk">
+    <img src="https://img.shields.io/npm/v/@epochcore/qaas-sdk?color=6366f1&label=npm&logo=npm" alt="npm version">
+  </a>
+  <a href="https://github.com/Jvryan92/qaas-sdk/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-Proprietary-blue.svg" alt="License">
+  </a>
+  <a href="https://api.qaas.epochcoreqcs.com/health">
+    <img src="https://img.shields.io/badge/API-operational-brightgreen" alt="API Status">
+  </a>
+  <a href="https://github.com/Jvryan92/qaas-sdk/stargazers">
+    <img src="https://img.shields.io/github/stars/Jvryan92/qaas-sdk?style=social" alt="GitHub Stars">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#key-features">Key Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#algorithms">Algorithms</a> •
+  <a href="#pricing">Pricing</a> •
+  <a href="#api-reference">API Reference</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Qiskit-IBM-6929C4?style=flat-square&logo=ibm&logoColor=white" alt="Qiskit"/>
+  <img src="https://img.shields.io/badge/Cirq-Google-4285F4?style=flat-square&logo=google&logoColor=white" alt="Cirq"/>
+  <img src="https://img.shields.io/badge/PennyLane-Xanadu-00B4D8?style=flat-square" alt="PennyLane"/>
+  <img src="https://img.shields.io/badge/TypeScript-Ready-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
+</p>
+
+---
+
+## Why QaaS?
+
+Quantum computing is powerful but complex. QaaS removes the barriers:
+
+| Traditional Quantum | With QaaS |
+|---------------------|-----------|
+| Learn Qiskit/Cirq/PennyLane | One unified API |
+| Manage quantum infrastructure | Fully managed cloud |
+| Write circuit code | Simple JSON parameters |
+| PhD-level knowledge required | Developer-friendly SDK |
+
+---
+
+## Key Features
+
+- **100 Algorithms** — Amplitude estimation, Grover search, QAOA, QUBO, Quantum ML
+- **3 Frameworks** — Qiskit, Cirq, PennyLane unified under one API
+- **Multiple Backends** — Simulator, Qiskit Aer, IBM Quantum hardware
+- **TypeScript SDK** — Full type safety and IntelliSense support
+- **Usage Tracking** — Monitor your quantum runs in real-time
+- **99.9% Uptime SLA** — Enterprise-grade reliability
+
+---
+
+## Quick Start
+
+```bash
+npm install @epochcore/qaas-sdk
+```
+
+```typescript
+import { QaaSClient } from '@epochcore/qaas-sdk';
+
+const client = new QaaSClient({ apiKey: 'your_api_key' });
+
+// Run a quantum portfolio optimization
+const result = await client.runAlgorithm({
+  algorithm_id: 41, // QAOA Portfolio Optimization
+  parameters: {
+    qubits: 4,
+    shots: 1024,
+    layers: 2
+  },
+  backend: 'qiskit_aer'
+});
+
+console.log(result.optimal_solution); // [1, 0, 1, 1]
+console.log(result.objective_value);  // 87.3
+```
+
+---
+
+## Installation
+
+### npm
+
+```bash
+npm install @epochcore/qaas-sdk
+```
+
+### yarn
+
+```bash
+yarn add @epochcore/qaas-sdk
+```
+
+### pnpm
+
+```bash
+pnpm add @epochcore/qaas-sdk
+```
+
+---
+
+## Usage
+
+### Initialize the Client
+
+```typescript
+import { QaaSClient } from '@epochcore/qaas-sdk';
+
+const client = new QaaSClient({
+  apiKey: process.env.QAAS_API_KEY,
+  baseUrl: 'https://api.qaas.epochcoreqcs.com' // optional
+});
+```
+
+### Run Quantum Algorithms
+
+```typescript
+// Grover Search - Find optimal solution
+const groverResult = await client.runAlgorithm({
+  algorithm_id: 21, // GROVER_BOOL_001
+  parameters: {
+    qubits: 4,
+    shots: 1024,
+    target: 7
+  }
+});
+
+// Amplitude Estimation - Option pricing
+const aeResult = await client.runAlgorithm({
+  algorithm_id: 1, // AE_PROB_001
+  parameters: {
+    qubits: 6,
+    shots: 2048,
+    precision: 3
+  }
+});
+
+// QAOA - Combinatorial optimization
+const qaoaResult = await client.runAlgorithm({
+  algorithm_id: 61, // QAOA_QUBO_001
+  parameters: {
+    qubits: 8,
+    shots: 4096,
+    layers: 3
+  },
+  backend: 'ibm_quantum' // Enterprise tier only
+});
+```
+
+### Check Usage
+
+```typescript
+const usage = await client.getUsage();
+console.log(`Daily: ${usage.daily.used}/${usage.daily.limit}`);
+console.log(`Monthly: ${usage.monthly.used}/${usage.monthly.limit}`);
+```
+
+### List Available Algorithms
+
+```typescript
+const algorithms = await client.listAlgorithms();
+algorithms.forEach(algo => {
+  console.log(`${algo.id}: ${algo.name} - ${algo.description}`);
+});
+```
+
+---
+
+## Algorithms
+
+### Categories
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Amplitude Estimation** | 20 | Option pricing, VaR/CVaR, Monte Carlo |
+| **Grover Search** | 20 | Boolean SAT, arbitrage detection, pattern matching |
+| **QAOA Optimization** | 20 | Portfolio optimization, risk parity, Max Sharpe |
+| **QUBO Problems** | 20 | Max-cut, TSP, knapsack, graph coloring |
+| **Quantum ML** | 10 | QSVM, QNN, QGAN, quantum PCA |
+| **Special** | 10 | VQE, phase estimation, HHL, quantum walks |
+
+### Popular Algorithms
+
+```
+ID    Name              Category               Use Case
+───   ────────────────  ─────────────────────  ────────────────
+1     AE_PROB_001       Amplitude Estimation   Option Pricing
+21    GROVER_BOOL_001   Grover Search          SAT Solving
+41    QAOA_PORT_001     QAOA Optimization      Portfolio Opt
+61    QAOA_QUBO_001     QUBO                   Max-Cut
+86    QSVM_001          Quantum ML             Classification
+```
+
+---
+
+## Pricing
+
+| Tier | Price | Runs/Month | Algorithms | Backends |
+|------|-------|------------|------------|----------|
+| **Explorer** | Free | 300 | 25 | Simulator |
+| **Analyst** | $29/mo | 500 | 50 | Simulator, Qiskit Aer |
+| **Quant** | $99/mo | 2,500 | 100 | All frameworks |
+| **Enterprise** | $299/mo | Unlimited | 100 | + IBM Quantum hardware |
+
+<p align="center">
+  <a href="https://buy.stripe.com/cNi9AMaOv3jm2ZXe875Ne0A">
+    <img src="https://img.shields.io/badge/Get_Analyst-$29/mo-6366f1?style=for-the-badge" alt="Get Analyst"/>
+  </a>
+  <a href="https://buy.stripe.com/9B628k3m36vy441e875Ne0B">
+    <img src="https://img.shields.io/badge/Get_Quant-$99/mo-10b981?style=for-the-badge" alt="Get Quant"/>
+  </a>
+  <a href="https://buy.stripe.com/4gMfZa5ub07a1VT6FF5Ne0C">
+    <img src="https://img.shields.io/badge/Get_Enterprise-$299/mo-f59e0b?style=for-the-badge" alt="Get Enterprise"/>
+  </a>
+</p>
+
+---
+
+## API Reference
+
+### Base URL
+
+```
+https://api.qaas.epochcoreqcs.com
+```
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/health` | API health check |
+| `GET` | `/api/quantum/algorithms` | List all algorithms |
+| `GET` | `/api/quantum/algorithm/:id` | Get algorithm details |
+| `POST` | `/api/quantum/run` | Execute quantum algorithm |
+| `GET` | `/api/quantum/usage` | Get usage statistics |
+| `GET` | `/api/pricing` | Get pricing information |
+
+### Authentication
+
+Include your API key in the request headers:
+
+```bash
+curl -X POST https://api.qaas.epochcoreqcs.com/api/quantum/run \
+  -H "X-API-Key: your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"algorithm_id": 41, "parameters": {"qubits": 4}}'
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "job_id": "qjob_1702339200_abc123",
+  "algorithm_id": 41,
+  "backend": "qiskit_aer",
+  "status": "completed",
+  "result": {
+    "optimal_solution": [1, 0, 1, 1],
+    "objective_value": 87.3,
+    "energy": -42.1
+  },
+  "execution_time_ms": 34,
+  "qubits_used": 4,
+  "shots": 1024,
+  "timestamp": "2025-12-11T18:30:00.000Z"
+}
+```
+
+---
+
+## Examples
+
+### Portfolio Optimization
+
+```typescript
+const portfolio = await client.runAlgorithm({
+  algorithm_id: 41, // Markowitz optimization
+  parameters: {
+    qubits: 6,
+    shots: 2048,
+    layers: 3,
+    assets: ['AAPL', 'GOOGL', 'MSFT', 'AMZN'],
+    returns: [0.12, 0.15, 0.10, 0.18],
+    covariance: [[0.04, 0.01, 0.02, 0.01], ...]
+  }
+});
+```
+
+### Arbitrage Detection
+
+```typescript
+const arbitrage = await client.runAlgorithm({
+  algorithm_id: 23, // Grover arbitrage search
+  parameters: {
+    qubits: 8,
+    shots: 4096,
+    price_matrix: [[1, 1.2, 0.9], [0.83, 1, 0.75], [1.11, 1.33, 1]]
+  }
+});
+```
+
+### Risk Metrics (VaR/CVaR)
+
+```typescript
+const risk = await client.runAlgorithm({
+  algorithm_id: 4, // VaR amplitude estimation
+  parameters: {
+    qubits: 10,
+    shots: 8192,
+    confidence: 0.95,
+    portfolio_value: 1000000
+  }
+});
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Required
+QAAS_API_KEY=your_api_key_here
+
+# Optional
+QAAS_BASE_URL=https://api.qaas.epochcoreqcs.com
+QAAS_TIMEOUT=30000
+```
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  const result = await client.runAlgorithm({...});
+} catch (error) {
+  if (error.code === 'USAGE_LIMIT_EXCEEDED') {
+    console.log('Upgrade your plan:', error.upgrade_url);
+  } else if (error.code === 'ALGORITHM_NOT_AVAILABLE') {
+    console.log('This algorithm requires:', error.required_tier);
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
+}
+```
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+```bash
+# Clone the repository
+git clone https://github.com/Jvryan92/qaas-sdk.git
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+---
+
+## Support
+
+- **Documentation**: [qaas.epochcoreqcs.com/docs.html](https://qaas.epochcoreqcs.com/docs.html)
+- **Discord**: [Join our community](https://discord.com/channels/1442677981808951338/1442677982568124500)
+- **Email**: [CEO.QuantumAmazon@EpochCoreQcs.com](mailto:CEO.QuantumAmazon@EpochCoreQcs.com)
+- **Issues**: [GitHub Issues](https://github.com/Jvryan92/qaas-sdk/issues)
+
+---
+
+## Links
+
+<p align="center">
+  <a href="https://qaas.epochcoreqcs.com">
+    <img src="https://img.shields.io/badge/Website-qaas.epochcoreqcs.com-6366f1?style=flat-square" alt="Website"/>
+  </a>
+  <a href="https://qaas.epochcoreqcs.com/docs.html">
+    <img src="https://img.shields.io/badge/Docs-API_Reference-10b981?style=flat-square" alt="Docs"/>
+  </a>
+  <a href="https://www.npmjs.com/package/@epochcore/qaas-sdk">
+    <img src="https://img.shields.io/badge/npm-@epochcore/qaas--sdk-CB3837?style=flat-square&logo=npm" alt="npm"/>
+  </a>
+</p>
+
+---
+
+## License
+
+Proprietary - Copyright (c) 2025 EpochCore. All Rights Reserved.
+
+This SDK is provided for use with valid QaaS API subscriptions only. See [LICENSE](LICENSE) for full terms.
+
+---
+
+<p align="center">
+  <b>Built with quantum power by <a href="https://epochcoreqcs.com">EpochCore</a></b>
+  <br>
+  <sub>Powered by IBM Qiskit, Google Cirq, and Xanadu PennyLane</sub>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Jvryan92/qaas-sdk">
+    <img src="https://img.shields.io/badge/GitHub-Jvryan92/qaas--sdk-181717?style=flat-square&logo=github" alt="GitHub"/>
+  </a>
+  <a href="https://www.linkedin.com/in/john-ryan-515222377/">
+    <img src="https://img.shields.io/badge/LinkedIn-John_Ryan-0A66C2?style=flat-square&logo=linkedin" alt="LinkedIn"/>
+  </a>
+  <a href="https://youtube.com/@maxmesh-hft">
+    <img src="https://img.shields.io/badge/YouTube-MaxMesh_HFT-FF0000?style=flat-square&logo=youtube" alt="YouTube"/>
+  </a>
+</p>