# Admiral Solver

**Python SDK for the Admiral Combinatorial Optimization Platform.**

Solve QUBO, Ising, MILP, MAX-SAT, and 7 more problem types through a single API. 33 proprietary algorithms. Solver racing. AI-powered analysis.

## Install

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

## Quick Start

```python
from admiral import Solver

solver = Solver(api_key="adm_sk_...")

# Solve a QUBO problem
result = solver.solve_qubo(
    Q=[[-5, 2, 4], [0, -3, 1], [0, 0, -8]],
    timeout=10,
    race=True
)
print(result.energy)     # -13.0
print(result.solution)   # [1, 0, 1]
```

## Features

- **11 problem types**: QUBO, Ising, HUBO, DQM, CQM, MILP, MIQP, MAX-SAT, PBO, WCSP, Potts
- **33 proprietary algorithms**: Auto-selected or raced in parallel
- **Solver Racing**: Race up to 8 solvers — first to converge wins
- **AI Advisor**: Analyze problem structure, get solver recommendations
- **NL Builder**: Describe problems in plain English, get formulations
- **Auto-Detect**: Submit JSON data, Admiral identifies the problem type

## New in v2.0

```python
# AI Advisor — analyze before solving
analysis = solver.analyze("qubo", {"Q": Q})
print(analysis["recommendations"])

# NL Builder — natural language to formulation
formulation = solver.formulate("Minimize travel between 5 cities")
print(formulation["problem_type"])  # "qubo"

# Solver Racing — race all algorithms
result = solver.solve_qubo(Q, race=True)

# Auto-Detect problem type
detected = solver.detect({"Q": Q})
print(detected["detected_type"])  # "qubo"
```

## All Problem Types

| Method | Type | Variables |
|--------|------|-----------|
| `solve_qubo(Q)` | QUBO | Binary {0,1} |
| `solve_ising(h, J)` | Ising | Spin {-1,+1} |
| `solve_hubo(terms, n)` | HUBO | Binary, higher-order |
| `solve_dqm(domains)` | DQM | Discrete multi-valued |
| `solve_cqm(c, Q, A, b)` | CQM | Mixed with constraints |
| `solve_milp(c, A, b)` | MILP | Mixed integer linear |
| `solve_miqp(c, Q, A, b)` | MIQP | Mixed integer quadratic |
| `solve_maxsat(clauses)` | MAX-SAT | Boolean |
| `solve_pbo(obj, cons, n)` | PBO | Pseudo-boolean |
| `solve_wcsp(n, domains, fns)` | WCSP | Discrete constraint |
| `solve_potts(nodes, states, edges)` | Potts | Multi-state lattice |

## Links

- **Platform**: https://admiral-platform.tech
- **API Docs**: https://api.admiral-platform.tech/v1/docs
- **Dashboard**: https://admiral-platform.tech/dashboard.html
