Metadata-Version: 2.4
Name: admiral-solver
Version: 2.0.1
Summary: Python SDK for Admiral — combinatorial optimization platform. 11 problem types, 33 solvers, solver racing, AI advisor, NL builder.
Author-email: Admiral Platform <q.deep.qc@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://admiral-platform.tech
Project-URL: Documentation, https://api.admiral-platform.tech/v1/docs
Project-URL: Repository, https://github.com/TheQuantumGOAT
Project-URL: API Status, https://api.admiral-platform.tech/v1/health
Keywords: optimization,qubo,ising,milp,combinatorial,solver,quantum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: numpy>=1.20

<p align="center">
  <img src="https://admiral-platform.tech/admiral-hat.png" alt="Admiral" width="120" />
</p>

<h1 align="center">Admiral Solver</h1>

<p align="center">
  <strong>Python SDK for the Admiral Combinatorial Optimization Platform</strong><br>
  11 problem types &middot; 33 proprietary algorithms &middot; Solver racing &middot; AI advisor &middot; NL builder
</p>

<p align="center">
  <a href="https://pypi.org/project/admiral-solver/"><img src="https://img.shields.io/pypi/v/admiral-solver?color=FF6B1A&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/admiral-solver/"><img src="https://img.shields.io/pypi/pyversions/admiral-solver?color=FF6B1A" alt="Python"></a>
  <a href="https://admiral-platform.tech"><img src="https://img.shields.io/badge/Platform-Live-44FF88" alt="Platform"></a>
  <a href="https://api.admiral-platform.tech/v1/docs"><img src="https://img.shields.io/badge/API_Docs-Swagger-4488FF" alt="Docs"></a>
</p>

---

## 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.complexity)        # "EASY"
print(analysis.recommendations)   # [{solver: "admiral_01", confidence: 0.95}]

# NL Builder — natural language to formulation (powered by AI)
formulation = solver.formulate("Minimize travel between 5 cities")
print(formulation.problem_type)   # "qubo"
print(formulation.explanation)    # {variables: "...", objective: "..."}

# Solver Racing — race all algorithms
result = solver.solve_qubo(Q, race=True)
print(result.race_metadata)       # {solvers_raced: 8, ...}

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

## 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**: [admiral-platform.tech](https://admiral-platform.tech)
- **API Docs**: [api.admiral-platform.tech/v1/docs](https://api.admiral-platform.tech/v1/docs)
- **Dashboard**: [admiral-platform.tech/dashboard.html](https://admiral-platform.tech/dashboard.html)
- **PyPI**: [pypi.org/project/admiral-solver](https://pypi.org/project/admiral-solver/)
