elara-route 0.1.0__tar.gz

elara_route-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Elara Cortex (www.elara-cortex.com) — Institute for Decision Systems & Number Theory
+Author: .LEKOLA · CODE ATELIER
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elara_route-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.1
+Name: elara-route
+Version: 0.1.0
+Summary: Python SDK for the Elara Route API — road, drone, maritime, AV routing + geocoding + fleet tracking
+Author-email: ".LEKOLA · CODE ATELIER" <hello@elara-cortex.com>
+License: MIT License
+        
+        Copyright (c) 2026 Elara Cortex (www.elara-cortex.com) — Institute for Decision Systems & Number Theory
+        Author: .LEKOLA · CODE ATELIER
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://route.elara-cortex.com
+Project-URL: Documentation, https://route.elara-cortex.com/developers
+Project-URL: Repository, https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python
+Project-URL: Issues, https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python/issues
+Keywords: routing,navigation,geocoding,fleet,drone,africa,api,sdk,elara
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == "dev"
+Requires-Dist: build<2.0.0,>=1.0.0; extra == "dev"
+Requires-Dist: twine<6.0.0,>=4.0.0; extra == "dev"
+
+# elara-route — Python SDK
+
+The official Python client for the [Elara Route API](https://route.elara-cortex.com/developers) — road, drone, maritime, AV routing + geocoding + fleet tracking.
+
+**No routing logic ships in this package.** All algorithms run server-side at `route.elara-cortex.com`. Your IP stays protected.
+
+## Install
+
+```bash
+pip install elara-route
+```
+
+Or from source:
+
+```bash
+cd D:\elara_sdk
+pip install -e ".[dev]"
+```
+
+Zero runtime dependencies. Pure Python 3.9+ standard library.
+
+## Quick start
+
+```python
+from elara_route import ElaraClient
+
+client = ElaraClient(api_key="elara_your_key_here")
+
+route = client.route(
+    from_=[-26.1076, 28.0567],
+    to=[-26.2041, 28.0473],
+)
+print(f"{route['distance_km']:.1f} km — {route['eta_min']:.0f} min")
+```
+
+Or create an account programmatically:
+
+```python
+client = ElaraClient.signup("you@company.com", "your-secure-password")
+route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+```
+
+## All endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `route()` | POST `/v1/route` | A→B road route |
+| `reroute()` | POST `/v1/reroute` | Compact reroute delta (~80% smaller payload) |
+| `matrix()` | POST `/v1/matrix` | Distance/time matrix |
+| `optimize()` | POST `/v1/optimize` | Multi-stop VRP order |
+| `drone_route()` | POST `/v1/drone/route` | Drone corridor routing |
+| `maritime_route()` | POST `/v1/maritime/route` | Sea routing |
+| `av_route()` | POST `/v1/av/route` | Autonomous-vehicle routing |
+| `geocode()` | GET `/v1/geocode` | Address → coordinates |
+| `reverse()` | GET `/v1/reverse` | Coordinates → address |
+| `nearby()` | GET `/v1/nearby` | POIs by category |
+| `signup()` | POST `/v1/account/signup` | Create account + API key |
+| `usage()` | GET `/v1/account/usage` | Quota and usage |
+| `assets_list()` | GET `/v1/assets` | List fleet assets |
+| `asset_create()` | POST `/v1/assets` | Register asset |
+| `asset_route()` | POST `/v1/assets/{id}/route` | Attach route to asset |
+| `asset_position()` | POST `/v1/assets/{id}/position` | Push live GPS |
+| `asset_live()` | GET `/v1/assets/{id}/live` | Live position vs plan |
+
+### Nearby categories (OpenAPI enum)
+
+`atm`, `cafe`, `charging`, `checkpoint`, `food`, `fuel`, `hospital`, `hotel`, `parking`, `police`, `speed_camera`
+
+## Error handling
+
+```python
+from elara_route import ElaraAuthError, ElaraRateLimitError, ElaraValidationError
+
+try:
+    route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+except ElaraValidationError as e:
+    print("Bad input:", e.detail)
+except ElaraRateLimitError as e:
+    print(f"Retry in {e.retry_after}s")
+except ElaraAuthError:
+    print("Check your API key")
+```
+
+## Run tests
+
+```bash
+pytest tests/ -v
+```
+
+## Run example
+
+```bash
+set ELARA_API_KEY=elara_your_key
+python examples/quickstart.py
+```
+
+## Free tier
+
+25,000 routes/month, no credit card. [Get your key →](https://route.elara-cortex.com/developers)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+**ELARA·CORTEX** · Mathematical infrastructure for complex systems · Institute for Decision Systems & Number Theory
+
+**AUTHOR:** .LEKOLA · CODE ATELIER · GitHub: [ELARA-CORTEX-MATH-INFRA](https://github.com/ELARA-CORTEX-MATH-INFRA)

elara_route-0.1.0/README.md

@@ -0,0 +1,109 @@
+# elara-route — Python SDK
+
+The official Python client for the [Elara Route API](https://route.elara-cortex.com/developers) — road, drone, maritime, AV routing + geocoding + fleet tracking.
+
+**No routing logic ships in this package.** All algorithms run server-side at `route.elara-cortex.com`. Your IP stays protected.
+
+## Install
+
+```bash
+pip install elara-route
+```
+
+Or from source:
+
+```bash
+cd D:\elara_sdk
+pip install -e ".[dev]"
+```
+
+Zero runtime dependencies. Pure Python 3.9+ standard library.
+
+## Quick start
+
+```python
+from elara_route import ElaraClient
+
+client = ElaraClient(api_key="elara_your_key_here")
+
+route = client.route(
+    from_=[-26.1076, 28.0567],
+    to=[-26.2041, 28.0473],
+)
+print(f"{route['distance_km']:.1f} km — {route['eta_min']:.0f} min")
+```
+
+Or create an account programmatically:
+
+```python
+client = ElaraClient.signup("you@company.com", "your-secure-password")
+route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+```
+
+## All endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `route()` | POST `/v1/route` | A→B road route |
+| `reroute()` | POST `/v1/reroute` | Compact reroute delta (~80% smaller payload) |
+| `matrix()` | POST `/v1/matrix` | Distance/time matrix |
+| `optimize()` | POST `/v1/optimize` | Multi-stop VRP order |
+| `drone_route()` | POST `/v1/drone/route` | Drone corridor routing |
+| `maritime_route()` | POST `/v1/maritime/route` | Sea routing |
+| `av_route()` | POST `/v1/av/route` | Autonomous-vehicle routing |
+| `geocode()` | GET `/v1/geocode` | Address → coordinates |
+| `reverse()` | GET `/v1/reverse` | Coordinates → address |
+| `nearby()` | GET `/v1/nearby` | POIs by category |
+| `signup()` | POST `/v1/account/signup` | Create account + API key |
+| `usage()` | GET `/v1/account/usage` | Quota and usage |
+| `assets_list()` | GET `/v1/assets` | List fleet assets |
+| `asset_create()` | POST `/v1/assets` | Register asset |
+| `asset_route()` | POST `/v1/assets/{id}/route` | Attach route to asset |
+| `asset_position()` | POST `/v1/assets/{id}/position` | Push live GPS |
+| `asset_live()` | GET `/v1/assets/{id}/live` | Live position vs plan |
+
+### Nearby categories (OpenAPI enum)
+
+`atm`, `cafe`, `charging`, `checkpoint`, `food`, `fuel`, `hospital`, `hotel`, `parking`, `police`, `speed_camera`
+
+## Error handling
+
+```python
+from elara_route import ElaraAuthError, ElaraRateLimitError, ElaraValidationError
+
+try:
+    route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+except ElaraValidationError as e:
+    print("Bad input:", e.detail)
+except ElaraRateLimitError as e:
+    print(f"Retry in {e.retry_after}s")
+except ElaraAuthError:
+    print("Check your API key")
+```
+
+## Run tests
+
+```bash
+pytest tests/ -v
+```
+
+## Run example
+
+```bash
+set ELARA_API_KEY=elara_your_key
+python examples/quickstart.py
+```
+
+## Free tier
+
+25,000 routes/month, no credit card. [Get your key →](https://route.elara-cortex.com/developers)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+**ELARA·CORTEX** · Mathematical infrastructure for complex systems · Institute for Decision Systems & Number Theory
+
+**AUTHOR:** .LEKOLA · CODE ATELIER · GitHub: [ELARA-CORTEX-MATH-INFRA](https://github.com/ELARA-CORTEX-MATH-INFRA)

elara_route-0.1.0/elara_route/__init__.py

@@ -0,0 +1,43 @@
+"""
+ORGANISATION: ELARA·CORTEX
+             Mathematical infrastructure for complex systems
+             Institute for Decision Systems & Number Theory
+AUTHOR:      .LEKOLA · CODE ATELIER
+GITHUB_ORG:  ELARA-CORTEX-MATH-INFRA
+
+NODE_ID:     SDK-PY-ROUTE-INIT
+PROJECT_ID:  elara-route-python
+PARENT_NODE: sdk/python/elara_route
+PURPOSE:     Package entrypoint — exports ElaraClient, constants, and exceptions.
+
+CHANGE_ID:   CHG-20260617-SDK-FULL
+CHANGE_NOTE: Full SDK build — export constants and version from single module.
+
+elara-route — Python SDK for the Elara Route API
+https://route.elara-cortex.com/developers
+
+Install:
+    pip install elara-route
+
+Quick start:
+    from elara_route import ElaraClient
+    client = ElaraClient(api_key="elara_xxx")
+    route = client.route(from_=[-26.1076, 28.0567], to=[-26.2041, 28.0473])
+    print(route["distance_km"], "km —", route["eta_min"], "min")
+"""
+
+from .client import ElaraClient
+from .constants import ASSET_TYPES, DEFAULT_BASE_URL, NEARBY_CATEGORIES, __version__
+from .exceptions import ElaraAuthError, ElaraError, ElaraRateLimitError, ElaraValidationError
+
+__all__ = [
+    "ElaraClient",
+    "ElaraError",
+    "ElaraAuthError",
+    "ElaraRateLimitError",
+    "ElaraValidationError",
+    "ASSET_TYPES",
+    "NEARBY_CATEGORIES",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

elara_route-0.1.0/elara_route/client.py

@@ -0,0 +1,300 @@
+"""
+ORGANISATION: ELARA·CORTEX
+             Mathematical infrastructure for complex systems
+             Institute for Decision Systems & Number Theory
+AUTHOR:      .LEKOLA · CODE ATELIER
+GITHUB_ORG:  ELARA-CORTEX-MATH-INFRA
+
+NODE_ID:     SDK-PY-ROUTE-CLIENT
+PROJECT_ID:  elara-route-python
+PARENT_NODE: sdk/python/elara_route
+PURPOSE:     Authenticated HTTP client for Elara Route API endpoints.
+
+CHANGE_ID:   CHG-20260617-SDK-FULL
+CHANGE_NOTE: Full SDK — av_route, signup, OpenAPI category enum, constants module.
+
+ElaraClient — the main entry point for the Elara Route SDK.
+
+All algorithm execution happens server-side at route.elara-cortex.com.
+This SDK is a thin, authenticated HTTP wrapper — no routing logic ships in this package.
+Your IP is 100% protected.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .constants import ASSET_TYPES, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, NEARBY_CATEGORIES, __version__
+from .exceptions import ElaraAuthError, ElaraError, ElaraRateLimitError, ElaraValidationError
+
+
+class ElaraClient:
+    """
+    Elara Route API client.
+
+    Parameters
+    ----------
+    api_key : str
+        Your Elara API key (get one free at https://route.elara-cortex.com/developers).
+    timeout : int
+        Request timeout in seconds. Default: 30.
+    base_url : str
+        Override the API base URL (useful for testing).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        timeout: int = DEFAULT_TIMEOUT,
+        base_url: str = DEFAULT_BASE_URL,
+    ):
+        if not api_key:
+            raise ElaraAuthError("api_key is required. Get yours free at https://route.elara-cortex.com/developers")
+        self._key = api_key
+        self._timeout = timeout
+        self._base = base_url.rstrip("/")
+
+    # ── internal HTTP helpers ────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        url = self._base + path
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Content-Type", "application/json")
+        req.add_header("X-API-Key", self._key)
+        req.add_header("User-Agent", f"elara-route-python/{__version__}")
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as r:
+                return json.loads(r.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body_str = e.read().decode("utf-8", "replace")
+            try:
+                detail = json.loads(body_str).get("detail", body_str)
+            except Exception:
+                detail = body_str[:200]
+
+            if e.code in (401, 403):
+                raise ElaraAuthError(f"Authentication failed: {detail}", status_code=e.code, detail=detail)
+            if e.code == 422:
+                raise ElaraValidationError(f"Invalid request: {detail}", status_code=422, detail=detail)
+            if e.code == 429:
+                retry_after = int(e.headers.get("Retry-After", 60))
+                raise ElaraRateLimitError(f"Rate limit exceeded. Retry after {retry_after}s.", retry_after=retry_after)
+            raise ElaraError(f"API error {e.code}: {detail}", status_code=e.code, detail=detail)
+        except Exception as e:
+            raise ElaraError(f"Network error: {e}")
+
+    def _get(self, path: str) -> dict:
+        return self._request("GET", path)
+
+    def _post(self, path: str, body: dict) -> dict:
+        return self._request("POST", path, body)
+
+    # ── Routing ──────────────────────────────────────────────────────────────
+
+    def route(
+        self,
+        from_: List[float],
+        to: List[float],
+        alternatives: bool = False,
+    ) -> dict:
+        """
+        Plan an A→B road route.
+
+        Parameters
+        ----------
+        from_ : [lat, lon]
+            Origin coordinates.
+        to : [lat, lon]
+            Destination coordinates.
+        alternatives : bool
+            Request alternative routes (default: False).
+
+        Returns
+        -------
+        dict with keys: distance_km, eta_min, geometry_latlng, steps, engine, ...
+
+        Example
+        -------
+        >>> client.route(from_=[-26.1076, 28.0567], to=[-26.2041, 28.0473])
+        {'distance_km': 13.28, 'eta_min': 18.4, ...}
+        """
+        body: Dict[str, Any] = {"from": from_, "to": to}
+        if alternatives:
+            body["alternatives"] = True
+        return self._post("/v1/route", body)
+
+    def reroute(
+        self,
+        from_: List[float],
+        to: List[float],
+        progress: float = 0.0,
+    ) -> dict:
+        """
+        Request a compact reroute delta (typically ~80% smaller than a full route).
+
+        Parameters
+        ----------
+        from_ : [lat, lon]  Current vehicle position.
+        to    : [lat, lon]  Destination.
+        progress : float    Fraction of original route already completed (0–1).
+
+        Returns
+        -------
+        dict with reroute delta + full route fields.
+        """
+        return self._post("/v1/reroute", {"from": from_, "to": to, "progress": progress})
+
+    def matrix(
+        self,
+        depot: List[float],
+        stops: List[List[float]],
+    ) -> dict:
+        """
+        Compute a distance/time matrix between a depot and multiple stops.
+
+        Returns
+        -------
+        dict with 'distances' key containing an N×N matrix (km).
+        """
+        return self._post("/v1/matrix", {"depot": depot, "stops": stops})
+
+    def optimize(
+        self,
+        depot: List[float],
+        stops: List[List[float]],
+        vehicles: int = 1,
+    ) -> dict:
+        """
+        Find the optimal multi-stop order (VRP solver).
+
+        Returns
+        -------
+        dict with 'order', 'distance_km', 'improvement_pct', 'guaranteed_never_worse'.
+        """
+        body: Dict[str, Any] = {"depot": depot, "stops": stops}
+        if vehicles > 1:
+            body["vehicles"] = vehicles
+        return self._post("/v1/optimize", body)
+
+    def drone_route(self, from_: List[float], to: List[float]) -> dict:
+        """Air routing along drone corridors where they exist, else direct flight."""
+        return self._post("/v1/drone/route", {"from": from_, "to": to})
+
+    def maritime_route(self, from_: List[float], to: List[float]) -> dict:
+        """Sea routing between coastal/offshore points."""
+        return self._post("/v1/maritime/route", {"from": from_, "to": to})
+
+    def av_route(self, from_: List[float], to: List[float]) -> dict:
+        """Autonomous-vehicle routing with corridor-aware geometry where available."""
+        return self._post("/v1/av/route", {"from": from_, "to": to})
+
+    # ── Geocoding ────────────────────────────────────────────────────────────
+
+    def geocode(self, query: str) -> dict:
+        """
+        Convert an address or place name to coordinates.
+
+        Returns
+        -------
+        dict with 'results' list, each containing lat, lon, name.
+        """
+        return self._get("/v1/geocode?q=" + urllib.parse.quote(query))
+
+    def reverse(self, lat: float, lon: float) -> dict:
+        """Convert coordinates to a human-readable address."""
+        return self._get(f"/v1/reverse?lat={lat}&lon={lon}")
+
+    def nearby(self, lat: float, lon: float, category: str = "fuel") -> dict:
+        """
+        Find nearby places by category.
+
+        Categories (OpenAPI enum): atm, cafe, charging, checkpoint, food, fuel,
+        hospital, hotel, parking, police, speed_camera
+        """
+        if category not in NEARBY_CATEGORIES:
+            raise ElaraValidationError(
+                f"Invalid category '{category}'. Allowed: {', '.join(sorted(NEARBY_CATEGORIES))}"
+            )
+        return self._get(f"/v1/nearby?lat={lat}&lon={lon}&category={urllib.parse.quote(category)}")
+
+    # ── Account ──────────────────────────────────────────────────────────────
+
+    @classmethod
+    def signup(cls, email: str, password: str, timeout: int = DEFAULT_TIMEOUT) -> "ElaraClient":
+        """
+        Create a new account and return a client pre-loaded with the issued API key.
+
+        Parameters
+        ----------
+        email, password : str
+            Account credentials (public beta signup at route.elara-cortex.com).
+
+        Returns
+        -------
+        ElaraClient
+            Client authenticated with the new API key from the signup response.
+        """
+        url = DEFAULT_BASE_URL + "/v1/account/signup"
+        body = json.dumps({"email": email, "password": password}).encode()
+        req = urllib.request.Request(url, data=body, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", f"elara-route-python/{__version__}")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                payload = json.loads(r.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")
+            if e.code == 422:
+                raise ElaraValidationError(f"Invalid signup: {detail}", status_code=422, detail=detail)
+            raise ElaraError(f"Signup failed ({e.code}): {detail}", status_code=e.code, detail=detail)
+        key = payload.get("api_key") or payload.get("key")
+        if not key:
+            raise ElaraError("Signup response missing api_key", detail=str(payload))
+        return cls(api_key=key, timeout=timeout)
+
+    def usage(self) -> dict:
+        """Return current API key usage and quota."""
+        return self._get("/v1/account/usage")
+
+    # ── Assets / Fleet tracking ───────────────────────────────────────────────
+
+    def assets_list(self) -> dict:
+        """List all registered assets and their live-tracking limits."""
+        return self._get("/v1/assets")
+
+    def asset_create(self, name: str, asset_type: str = "vehicle") -> dict:
+        """Register a new asset (vehicle, drone, robot, vessel, person)."""
+        if asset_type not in ASSET_TYPES:
+            raise ElaraValidationError(
+                f"Invalid asset type '{asset_type}'. Allowed: {', '.join(sorted(ASSET_TYPES))}"
+            )
+        return self._post("/v1/assets", {"name": name, "type": asset_type})
+
+    def asset_route(self, asset_id: str, from_: List[float], to: List[float]) -> dict:
+        """Plan and attach a route to an asset."""
+        return self._post(f"/v1/assets/{asset_id}/route", {"from": from_, "to": to})
+
+    def asset_position(
+        self,
+        asset_id: str,
+        lat: float,
+        lon: float,
+        battery_pct: Optional[float] = None,
+        heading: Optional[float] = None,
+    ) -> dict:
+        """Push a live GPS position for an asset."""
+        body: Dict[str, Any] = {"lat": lat, "lon": lon}
+        if battery_pct is not None:
+            body["battery_pct"] = battery_pct
+        if heading is not None:
+            body["heading"] = heading
+        return self._post(f"/v1/assets/{asset_id}/position", body)
+
+    def asset_live(self, asset_id: str) -> dict:
+        """Get the live position of an asset vs its planned route."""
+        return self._get(f"/v1/assets/{asset_id}/live")

elara_route-0.1.0/elara_route/constants.py

@@ -0,0 +1,40 @@
+"""
+ORGANISATION: ELARA·CORTEX
+             Mathematical infrastructure for complex systems
+             Institute for Decision Systems & Number Theory
+AUTHOR:      .LEKOLA · CODE ATELIER
+GITHUB_ORG:  ELARA-CORTEX-MATH-INFRA
+
+NODE_ID:     SDK-PY-ROUTE-CONSTANTS
+PROJECT_ID:  elara-route-python
+PARENT_NODE: sdk/python/elara_route
+PURPOSE:     Shared API constants — base URL, categories, version string.
+
+CHANGE_ID:   CHG-20260617-SDK-FULL
+CHANGE_NOTE: Full SDK build — public contract constants from OpenAPI 2026-06-16.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://route.elara-cortex.com"
+DEFAULT_TIMEOUT = 30
+
+NEARBY_CATEGORIES = frozenset(
+    {
+        "atm",
+        "cafe",
+        "charging",
+        "checkpoint",
+        "food",
+        "fuel",
+        "hospital",
+        "hotel",
+        "parking",
+        "police",
+        "speed_camera",
+    }
+)
+
+ASSET_TYPES = frozenset({"vehicle", "drone", "robot", "vessel", "person"})

elara_route-0.1.0/elara_route/exceptions.py

@@ -0,0 +1,40 @@
+"""
+ORGANISATION: ELARA·CORTEX
+             Mathematical infrastructure for complex systems
+             Institute for Decision Systems & Number Theory
+AUTHOR:      .LEKOLA · CODE ATELIER
+GITHUB_ORG:  ELARA-CORTEX-MATH-INFRA
+
+NODE_ID:     SDK-PY-ROUTE-EXCEPTIONS
+PROJECT_ID:  elara-route-python
+PARENT_NODE: sdk/python/elara_route
+PURPOSE:     Typed exceptions mapping Elara Route API HTTP error codes.
+
+CHANGE_ID:   CHG-20260617-SDK-FULL
+CHANGE_NOTE: Full SDK build — removed STUDIO from header.
+"""
+
+
+class ElaraError(Exception):
+    """Base exception for all Elara SDK errors."""
+
+    def __init__(self, message: str, status_code: int = None, detail: str = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class ElaraAuthError(ElaraError):
+    """Raised when the API key is missing or invalid (HTTP 401/403)."""
+
+
+class ElaraRateLimitError(ElaraError):
+    """Raised when the rate limit is exceeded (HTTP 429)."""
+
+    def __init__(self, message: str, retry_after: int = None):
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class ElaraValidationError(ElaraError):
+    """Raised when the request parameters are invalid (HTTP 422)."""

elara_route-0.1.0/elara_route.egg-info/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.1
+Name: elara-route
+Version: 0.1.0
+Summary: Python SDK for the Elara Route API — road, drone, maritime, AV routing + geocoding + fleet tracking
+Author-email: ".LEKOLA · CODE ATELIER" <hello@elara-cortex.com>
+License: MIT License
+        
+        Copyright (c) 2026 Elara Cortex (www.elara-cortex.com) — Institute for Decision Systems & Number Theory
+        Author: .LEKOLA · CODE ATELIER
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://route.elara-cortex.com
+Project-URL: Documentation, https://route.elara-cortex.com/developers
+Project-URL: Repository, https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python
+Project-URL: Issues, https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python/issues
+Keywords: routing,navigation,geocoding,fleet,drone,africa,api,sdk,elara
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == "dev"
+Requires-Dist: build<2.0.0,>=1.0.0; extra == "dev"
+Requires-Dist: twine<6.0.0,>=4.0.0; extra == "dev"
+
+# elara-route — Python SDK
+
+The official Python client for the [Elara Route API](https://route.elara-cortex.com/developers) — road, drone, maritime, AV routing + geocoding + fleet tracking.
+
+**No routing logic ships in this package.** All algorithms run server-side at `route.elara-cortex.com`. Your IP stays protected.
+
+## Install
+
+```bash
+pip install elara-route
+```
+
+Or from source:
+
+```bash
+cd D:\elara_sdk
+pip install -e ".[dev]"
+```
+
+Zero runtime dependencies. Pure Python 3.9+ standard library.
+
+## Quick start
+
+```python
+from elara_route import ElaraClient
+
+client = ElaraClient(api_key="elara_your_key_here")
+
+route = client.route(
+    from_=[-26.1076, 28.0567],
+    to=[-26.2041, 28.0473],
+)
+print(f"{route['distance_km']:.1f} km — {route['eta_min']:.0f} min")
+```
+
+Or create an account programmatically:
+
+```python
+client = ElaraClient.signup("you@company.com", "your-secure-password")
+route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+```
+
+## All endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `route()` | POST `/v1/route` | A→B road route |
+| `reroute()` | POST `/v1/reroute` | Compact reroute delta (~80% smaller payload) |
+| `matrix()` | POST `/v1/matrix` | Distance/time matrix |
+| `optimize()` | POST `/v1/optimize` | Multi-stop VRP order |
+| `drone_route()` | POST `/v1/drone/route` | Drone corridor routing |
+| `maritime_route()` | POST `/v1/maritime/route` | Sea routing |
+| `av_route()` | POST `/v1/av/route` | Autonomous-vehicle routing |
+| `geocode()` | GET `/v1/geocode` | Address → coordinates |
+| `reverse()` | GET `/v1/reverse` | Coordinates → address |
+| `nearby()` | GET `/v1/nearby` | POIs by category |
+| `signup()` | POST `/v1/account/signup` | Create account + API key |
+| `usage()` | GET `/v1/account/usage` | Quota and usage |
+| `assets_list()` | GET `/v1/assets` | List fleet assets |
+| `asset_create()` | POST `/v1/assets` | Register asset |
+| `asset_route()` | POST `/v1/assets/{id}/route` | Attach route to asset |
+| `asset_position()` | POST `/v1/assets/{id}/position` | Push live GPS |
+| `asset_live()` | GET `/v1/assets/{id}/live` | Live position vs plan |
+
+### Nearby categories (OpenAPI enum)
+
+`atm`, `cafe`, `charging`, `checkpoint`, `food`, `fuel`, `hospital`, `hotel`, `parking`, `police`, `speed_camera`
+
+## Error handling
+
+```python
+from elara_route import ElaraAuthError, ElaraRateLimitError, ElaraValidationError
+
+try:
+    route = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+except ElaraValidationError as e:
+    print("Bad input:", e.detail)
+except ElaraRateLimitError as e:
+    print(f"Retry in {e.retry_after}s")
+except ElaraAuthError:
+    print("Check your API key")
+```
+
+## Run tests
+
+```bash
+pytest tests/ -v
+```
+
+## Run example
+
+```bash
+set ELARA_API_KEY=elara_your_key
+python examples/quickstart.py
+```
+
+## Free tier
+
+25,000 routes/month, no credit card. [Get your key →](https://route.elara-cortex.com/developers)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+**ELARA·CORTEX** · Mathematical infrastructure for complex systems · Institute for Decision Systems & Number Theory
+
+**AUTHOR:** .LEKOLA · CODE ATELIER · GitHub: [ELARA-CORTEX-MATH-INFRA](https://github.com/ELARA-CORTEX-MATH-INFRA)

elara_route-0.1.0/elara_route.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+elara_route/__init__.py
+elara_route/client.py
+elara_route/constants.py
+elara_route/exceptions.py
+elara_route/py.typed
+elara_route.egg-info/PKG-INFO
+elara_route.egg-info/SOURCES.txt
+elara_route.egg-info/dependency_links.txt
+elara_route.egg-info/requires.txt
+elara_route.egg-info/top_level.txt
+tests/test_client.py

elara_route-0.1.0/elara_route.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

elara_route-0.1.0/elara_route.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest<9.0.0,>=7.4.0
+pytest-mock<4.0.0,>=3.12.0
+build<2.0.0,>=1.0.0
+twine<6.0.0,>=4.0.0

elara_route-0.1.0/elara_route.egg-info/top_level.txt

@@ -0,0 +1 @@
+elara_route

elara_route-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68.0,<75.0", "wheel>=0.41.0,<1.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "elara-route"
+version = "0.1.0"
+description = "Python SDK for the Elara Route API — road, drone, maritime, AV routing + geocoding + fleet tracking"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = ".LEKOLA · CODE ATELIER", email = "hello@elara-cortex.com"}
+]
+keywords = ["routing", "navigation", "geocoding", "fleet", "drone", "africa", "api", "sdk", "elara"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9,<4.0"
+dependencies = []
+
+[project.urls]
+Homepage = "https://route.elara-cortex.com"
+Documentation = "https://route.elara-cortex.com/developers"
+Repository = "https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python"
+Issues = "https://github.com/ELARA-CORTEX-MATH-INFRA/elara-route-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0,<9.0.0",
+    "pytest-mock>=3.12.0,<4.0.0",
+    "build>=1.0.0,<2.0.0",
+    "twine>=4.0.0,<6.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["elara_route*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

elara_route-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

elara_route-0.1.0/tests/test_client.py

@@ -0,0 +1,107 @@
+"""
+ORGANISATION: ELARA·CORTEX
+             Mathematical infrastructure for complex systems
+             Institute for Decision Systems & Number Theory
+AUTHOR:      .LEKOLA · CODE ATELIER
+GITHUB_ORG:  ELARA-CORTEX-MATH-INFRA
+
+NODE_ID:     SDK-PY-ROUTE-TEST-CLIENT
+PROJECT_ID:  elara-route-python
+PARENT_NODE: sdk/python/tests
+PURPOSE:     Unit tests for ElaraClient HTTP wrapper (mocked, no live API key).
+
+CHANGE_ID:   CHG-20260617-SDK-FULL
+CHANGE_NOTE: Full SDK test suite.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from elara_route import ElaraAuthError, ElaraClient, ElaraRateLimitError, ElaraValidationError
+from elara_route.constants import NEARBY_CATEGORIES
+
+
+def _mock_response(payload: dict, status: int = 200):
+    body = json.dumps(payload).encode()
+    resp = mock.Mock()
+    resp.read.return_value = body
+    resp.__enter__ = mock.Mock(return_value=resp)
+    resp.__exit__ = mock.Mock(return_value=False)
+    return resp
+
+
+@mock.patch("urllib.request.urlopen")
+def test_route_success(mock_urlopen):
+    mock_urlopen.return_value = _mock_response(
+        {"distance_km": 13.28, "eta_min": 18.4, "engine": ".LEKOLA CORTEX"}
+    )
+    client = ElaraClient(api_key="elara_test")
+    result = client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+    assert result["distance_km"] == 13.28
+    req = mock_urlopen.call_args[0][0]
+    assert req.get_header("X-api-key") == "elara_test"
+    assert req.full_url.endswith("/v1/route")
+
+
+def test_missing_api_key_raises():
+    with pytest.raises(ElaraAuthError):
+        ElaraClient(api_key="")
+
+
+@mock.patch("urllib.request.urlopen")
+def test_rate_limit(mock_urlopen):
+    import urllib.error
+
+    err = urllib.error.HTTPError(
+        url="https://route.elara-cortex.com/v1/route",
+        code=429,
+        msg="Too Many Requests",
+        hdrs={"Retry-After": "30"},
+        fp=io.BytesIO(b'{"detail":"slow down"}'),
+    )
+    mock_urlopen.side_effect = err
+    client = ElaraClient(api_key="elara_test")
+    with pytest.raises(ElaraRateLimitError) as exc:
+        client.route(from_=[-26.1, 28.0], to=[-26.2, 28.04])
+    assert exc.value.retry_after == 30
+
+
+def test_nearby_invalid_category():
+    client = ElaraClient(api_key="elara_test")
+    with pytest.raises(ElaraValidationError):
+        client.nearby(lat=-26.1, lon=28.0, category="invalid")
+
+
+def test_nearby_categories_match_openapi():
+    assert "speed_camera" in NEARBY_CATEGORIES
+    assert "checkpoint" in NEARBY_CATEGORIES
+    assert "all" not in NEARBY_CATEGORIES
+
+
+@mock.patch("urllib.request.urlopen")
+def test_signup_returns_client(mock_urlopen):
+    mock_urlopen.return_value = _mock_response({"api_key": "elara_new_key"})
+    client = ElaraClient.signup("dev@example.com", "secure-pass-123")
+    assert isinstance(client, ElaraClient)
+    assert client._key == "elara_new_key"
+
+
+@mock.patch("urllib.request.urlopen")
+def test_av_route(mock_urlopen):
+    mock_urlopen.return_value = _mock_response({"distance_km": 5.0, "eta_min": 8.0})
+    client = ElaraClient(api_key="elara_test")
+    result = client.av_route(from_=[-26.1, 28.0], to=[-26.15, 28.05])
+    assert result["distance_km"] == 5.0
+    req = mock_urlopen.call_args[0][0]
+    assert "/v1/av/route" in req.full_url