Metadata-Version: 2.1
Name: admiral-solver
Version: 1.1.2
Summary: Python SDK for Admiral combinatorial optimization cloud
Author-email: Admiral Technologies <eng@admiral.dev>
License: Apache-2.0
Project-URL: Homepage, https://admiral.dev
Project-URL: Documentation, https://docs.admiral.dev
Project-URL: Repository, https://github.com/admiral-dev/admiral-solver
Keywords: optimization,qubo,ising,milp,solver
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"

<p align="center">
  <img src="docs/assets/logo.svg" width="80" alt="Admiral"/>
</p>
<h1 align="center">Admiral</h1>
<p align="center">
  <strong>Combinatorial optimization cloud platform</strong><br>
  Solve QUBO, Ising, CQM, MILP, Max-SAT and 6 more problem types<br>
  with specialized algorithms via cloud API, Python SDK, or CLI.
</p>
<p align="center">
  <a href="https://admiral.dev/docs">Docs</a> · <a href="https://admiral.dev/pricing">Pricing</a> · <a href="https://discord.gg/admiral">Discord</a> · <a href="#self-hosting">Self-Host</a>
</p>
<p align="center">
  <img src="https://img.shields.io/badge/python-3.10+-blue.svg"/>
  <img src="https://img.shields.io/badge/license-Apache%202.0-green.svg"/>
  <img src="https://img.shields.io/badge/types-11-orange.svg"/>
  <img src="https://github.com/admiral-dev/admiral-solver/actions/workflows/ci.yml/badge.svg"/>
</p>

---

## Quick Start

```bash
pip install admiral-solver
```

```python
from admiral import Solver
import numpy as np

solver = Solver(api_key="adm_sk_...")
Q = np.array([[-5, 2, 4], [0, -3, 1], [0, 0, -8]])
result = solver.solve_qubo(Q, timeout=30)
print(result.energy)     # -13.0
print(result.solution)   # [1, 0, 1]
```

Local mode (no server):

```python
from admiral import LocalSolver
result = LocalSolver().solve_qubo(Q, solver="tabu", seed=42)
```

## 11 Problem Types

| Type | Formulation | Variables | Solvers |
|------|-------------|-----------|---------|
| **QUBO** | min x^TQx | binary | SB, PT, Tabu, Roof duality |
| **Ising** | min Σhᵢsᵢ + ΣJᵢⱼsᵢsⱼ | spin | SB, PT, Tabu |
| **HUBO** | min Σcₛ∏xᵢ | binary | Native SA, Quadratize→QUBO |
| **DQM** | min Σaᵢ(xᵢ)+Σbᵢⱼ | discrete | Discrete SA/Tabu, Bucket elim |
| **CQM** | min x^TQx+c^Tx s.t. Ax≤b | mixed | ADMM, Feasibility pump, B&C |
| **MILP** | min c^Tx s.t. Ax≤b | int+real | Branch & cut, RINS |
| **MIQP** | min x^TQx+c^Tx Ax≤b | mixed | QP B&C, ADMM |
| **Max-SAT** | max Σwⱼ·sat(Cⱼ) | boolean | WalkSAT, Core-guided RC2 |
| **PBO** | min Σcⱼ∏lᵢ s.t. ≥b | binary | SAT cutting planes |
| **WCSP** | min Σf(x) | discrete | VAC+B&B, LNS, BP |
| **Potts** | min −ΣJδ(sᵢ,sⱼ) | discrete | Swendsen-Wang, Discrete PT |

## Architecture

```
Clients (SDK / REST / CLI)
        │
        ▼
   API Server (FastAPI)  ──▶  PostgreSQL
        │
        ▼
      Redis (job queue + rate limits)
        │
   ┌────┴────┐
   ▼         ▼
CPU Workers  GPU Workers
Tabu, B&C    SB, PT
ADMM, RC2
```

## Self-Hosting

```bash
git clone https://github.com/admiral-dev/admiral-solver.git
cd admiral-solver
cp .env.example .env   # edit secrets
docker-compose up -d   # starts everything
```

Scale: `docker-compose up -d --scale worker-cpu=8 --scale worker-gpu=4`

K8s: `kubectl apply -f deploy/k8s-api.yaml -f deploy/k8s-workers.yaml`

## CLI

```bash
admiral solve --type qubo --input problem.json --local
admiral convert --from qubo --to ising --input q.json
admiral bench --sizes 10,100,1000 --solver sb
admiral server start --port 8000
admiral worker start --redis redis://localhost:6379
```

## API

```bash
curl -X POST https://api.admiral.dev/v1/solve \
  -H "Authorization: Bearer adm_sk_..." \
  -d '{"problem_type":"qubo","data":{"Q":[[-5,2,4],[0,-3,1],[0,0,-8]]}}'
```

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /v1/solve | Submit problem |
| GET | /v1/jobs/{id} | Status + result |
| GET | /v1/jobs/{id}/pool | Solution pool |
| POST | /v1/analyze | Complexity analysis |
| POST | /v1/convert | Format conversion |
| DELETE | /v1/jobs/{id} | Cancel |
| GET | /v1/solvers | List engines |
| GET | /v1/health | Health check |

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check admiral/
```

## License

Apache 2.0 — see [LICENSE](LICENSE)

---

<p align="center">Built by <a href="https://admiral.dev">Admiral Technologies</a></p>
