Metadata-Version: 2.4
Name: plansolve
Version: 0.27.0
Summary: Python SDK for PlanSolve optimization API
Author-email: PlanSolve <support@plansolve.app>
License: Apache-2.0
Project-URL: Homepage, https://plansolve.app
Project-URL: Documentation, https://plansolve.app/docs
Project-URL: Repository, https://github.com/plansolve/plansolve-python-sdk
Project-URL: Issues, https://github.com/plansolve/plansolve-python-sdk/issues
Keywords: optimization,routing,scheduling,field-service,professional-services
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# PlanSolve for Python

Official Python client for the [PlanSolve](https://getplansolve.com) optimization API. One typed client covers three solvers — field service routing, professional-services task assignment, and shift scheduling — with built-in polling and clean error messages.

## Installation

```bash
pip install plansolve
```

Requires Python 3.8+. Type hints are bundled.

## Quick start

```python
from plansolve import PlanSolveClient

client = PlanSolveClient(api_key="YOUR_API_KEY")

request = {
    "vehicles": [
        {
            "id": "tech1",
            "location": [40.7128, -74.0060],
            "skills": ["repair"],
            "shifts": [
                {"id": "morning", "minStartTime": "2026-04-02T08:00:00", "maxEndTime": "2026-04-02T17:00:00"}
            ],
        }
    ],
    "visits": [
        {
            "id": "visit1",
            "name": "AC Repair - Downtown Office",
            "location": [40.7589, -73.9851],
            "serviceDuration": "PT60M",
            "priority": "HIGH",
            "requiredSkills": ["repair"],
            "timeWindows": [
                {"minStartTime": "2026-04-02T09:00:00", "maxEndTime": "2026-04-02T17:00:00"}
            ],
        }
    ],
}

# Submit and block until the optimized plan is ready
result = client.field_service.start_and_wait_for_completion(request)

for vehicle in result.vehicles:
    print(f"Vehicle {vehicle.id}: {len(vehicle.visits)} visits")
```

Requests accept a plain `dict` (as above) or the typed dataclasses (`FieldServiceRequest`, `Vehicle`, `Visit`, ...).

## Solvers

One client, three solvers — all share the same submit → poll → result workflow:

| Solver | Accessor | Use for |
|--------|----------|---------|
| Field Service | `client.field_service` | Vehicle routing with travel time, time windows, and skills |
| Professional Services | `client.professional_services` | Task assignment by skill, availability, priority, and deadlines |
| Shift | `client.shift` | Shift scheduling across contracts, availability, and fairness |

Each accessor exposes `start`, `get_status`, `get_result`, `analyze`, `wait_for_completion`, and `start_and_wait_for_completion`.

## Configuration

Pass your API key to the constructor: `PlanSolveClient(api_key="...")`. It is sent as the `X-API-KEY` header on every request.

## Error handling

API errors raise `requests.HTTPError` with a readable message (e.g. `HTTP 400: vehicles: At least one vehicle is required.`):

```python
try:
    result = client.field_service.start_and_wait_for_completion(request)
except Exception as e:
    print(e)
```

## Documentation

Full guides, per-solver data models, and parameter reference live on the docs site:

- Field Service — https://getplansolve.com/docs/fieldservice/sdk/python
- Professional Services — https://getplansolve.com/docs/professionalservices/sdk/python
- Shift — https://getplansolve.com/docs/shiftsolver/sdk/python

Package: [PyPI](https://pypi.org/project/plansolve/)

## License

Apache-2.0 — see [LICENSE](LICENSE).
