Metadata-Version: 2.4
Name: qcoscloud
Version: 0.1.0
Summary: SoftQuantus compute SDK — credits, instances, QPU (QCOS), on-demand GPU, and free simulation, over one prepaid wallet.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# qcoscloud

The customer SDK, CLI and MCP server for **SoftQuantus compute** — one prepaid
wallet across QPU (via QCOS), on-demand GPU (via Softquantus Cloud), and free
simulation. The platform Execution Plane authorizes, meters and settles every
call; this client never touches a cloud or a credential.

```bash
pip install qcoscloud            # SDK + CLI
pip install "qcoscloud[mcp]"     # + the MCP server for AI agents
export QCOSCLOUD_API_KEY=sq-live-…    # create one in the console → API Keys
```

## SDK

```python
from qcoscloud import QCOSCloud
qc = QCOSCloud()                                  # reads QCOSCLOUD_API_KEY
qc.credits()                                      # prepaid balance (USD)
qc.simulate(shots=1000)                           # FREE test simulation
qc.run("ionq.qpu.aria-1", shots=2000, instance="research")   # real QPU (QCOS)
qc.gpu_job(gpu="a100-80gb", command="python train.py", minutes=30)  # GPU
qc.workload(job_id)                               # status + cost
```

## CLI

```bash
qcoscloud credits
qcoscloud computers
qcoscloud instances create research --plan prepaid --qpus ionq.qpu.aria-1
qcoscloud simulate --shots 1000
qcoscloud run --target ionq.qpu.aria-1 --shots 2000 --instance research
qcoscloud gpu --type a100-80gb --command "python train.py" --minutes 30
qcoscloud workloads
```

## MCP (for AI agents — the SynapseX Lab, Claude Desktop, Cursor)

```bash
python -m qcoscloud.mcp_server        # stdio MCP server
```

Exposes tools: `get_credits`, `list_computers`, `list_instances`,
`create_instance`, `run_simulation`, `run_qpu_job`, `run_gpu_job`,
`get_workload`, `cancel_workload`. An AI can drive compute safely — every run is
metered against the same wallet with the same cost guardrails.

See `docs/COMPUTE_INTEGRATION.md` (full integration) and
`docs/LAB_AI_INSTRUCTIONS.md` (desktop lab + AI instructions).

## Cost safety

Runs reserve their worst-case cost **before** provisioning, so you can never
overspend; GPU is stopped/deprovisioned when its reservation is exhausted; the
free plan runs simulators at $0. Errors carry a machine `reason`
(`insufficient_credits`, `runtime_bound_required`, `free_plan_limit_met`, …)
and a human hint.
