Metadata-Version: 2.4
Name: aimarket-atlas
Version: 0.3.0
Summary: ATLAS — planetary physical-sensor map over GAIA relays (LIVE/SIM pins + Analyst)
Author: AICOM (alexar76)
License-Expression: MIT
Project-URL: Homepage, https://atlas.modelmarket.dev/
Project-URL: Documentation, https://github.com/alexar76/atlas
Project-URL: Repository, https://github.com/alexar76/atlas
Project-URL: Issues, https://github.com/alexar76/atlas/issues
Project-URL: Landing, https://alexar76.github.io/atlas/
Keywords: atlas,gaia,iot,sensors,maplibre,aimarket,aicom,fastapi
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pydantic-settings>=2.9.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: cryptography>=44.0.0
Requires-Dist: h3>=4.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Dynamic: license-file

# ATLAS

<!-- aicom-readme-badges -->
<p align="center">
  <a href="https://github.com/alexar76/atlas/actions/workflows/ci.yml"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/ci.svg" alt="CI" /></a>
  <a href="https://github.com/alexar76/atlas/actions/workflows/pages.yml"><img src="https://github.com/alexar76/atlas/actions/workflows/pages.yml/badge.svg" alt="Pages deploy" /></a>
  <a href="https://atlas.modelmarket.dev/"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/demo.svg" alt="Live demo status" /></a>
  <a href="https://alexar76.github.io/atlas/"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/landing.svg" alt="Landing" /></a>
  <a href="https://pypi.org/project/aimarket-atlas/"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/pypi.svg" alt="PyPI" /></a>
  <a href="https://iot.modelmarket.dev/"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/gaia.svg" alt="GAIA relays" /></a>
  <img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/python.svg" alt="Python >=3.11" />
  <img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/tests.svg" alt="624 tests passed" />
  <img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/docker.svg" alt="Docker ready" />
  <img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/maplibre.svg" alt="MapLibre SPA" />
  <img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/deepseek.svg" alt="DeepSeek default" />
  <a href="https://github.com/alexar76/atlas/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/alexar76/atlas/main/docs/badges/license.svg" alt="License: MIT" /></a>
</p>
<!-- /aicom-readme-badges -->

> 🌐 **English** · [Русский](docs/README.ru.md) · [Español](docs/README.es.md) · [Français](docs/README.fr.md) · [中文](docs/README.zh.md) · [Glossary](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)




<p align="center">
  <strong>ATLAS</strong> — planetary physical-sensor map over <a href="https://iot.modelmarket.dev/">GAIA</a> relays<br/>
  Honest <strong>LIVE</strong> vs <strong>SIM</strong> pins · optional <strong>3D globe</strong> with sensor towers · part of the <a href="https://github.com/alexar76">alexar76</a> AI agent economy
</p>

<p align="center">
  <a href="https://atlas.modelmarket.dev/">
    <img src="docs/screenshots/readme/hero-orbit.png" alt="ATLAS — Earth from orbit with live sensor constellation" width="820">
  </a>
  <br>
  <sub>Weather · air · fire · GNSS integrity · jamming · traffic · quake · more — <a href="https://atlas.modelmarket.dev/"><b>live map →</b></a> · <a href="https://alexar76.github.io/atlas/"><b>landing →</b></a> · <a href="#quick-start"><b>run locally →</b></a></sub>
</p>

<p align="center">
  <strong><a href="https://atlas.modelmarket.dev/">Live map</a></strong>
  ·
  <strong><a href="https://alexar76.github.io/atlas/">Landing</a></strong>
  ·
  <strong><a href="docs/GUIDE.md">Guide (EN)</a></strong>
  ·
  <strong><a href="https://iot.modelmarket.dev/">GAIA</a></strong>
  ·
  <strong><a href="https://monitor.modelmarket.dev/">Alien Monitor</a></strong>
</p>

**Docs:** [EN](docs/GUIDE.md) · [RU](docs/i18n/GUIDE.ru.md) · [ES](docs/i18n/GUIDE.es.md) · [FR](docs/i18n/GUIDE.fr.md) · [ZH](docs/i18n/GUIDE.zh.md) · **[Map legend](docs/LEGEND.md)**
**Operator use cases:** [EN](docs/OPERATOR-USE-CASES.md) · [RU](docs/i18n/OPERATOR-USE-CASES.ru.md) · [ES](docs/i18n/OPERATOR-USE-CASES.es.md) · [FR](docs/i18n/OPERATOR-USE-CASES.fr.md) · [ZH](docs/i18n/OPERATOR-USE-CASES.zh.md)
**Add a sensor:** [add-gaia-atlas-sensor](https://github.com/alexar76/aicom/blob/main/docs/add-gaia-atlas-sensor.md) (EN · RU · ES · FR · ZH)

ATLAS is the ecosystem **physical sensor map**: weather, air quality, tides, rivers, marine, UK grid carbon, earthquakes, **wildfire**, **radiation**, **GNSS integrity stations**, separately sourced **GNSS jamming** reports, **public Finnish AIS**, **NWS tsunami CAP**, optional own-edge **ADS-B/AIS**, and energy — plotted from [GAIA](https://iot.modelmarket.dev/) relays. Every GNSS station is a stable clickable `point_id`; agents can query it through `atlas.point.read@v1` or request a signed point/bbox/route field through `atlas.gnss.degradation.read@v1`. Inventory, derived degradation, and reported interference remain distinct claim classes. **New open-data devices are registered on GAIA; map layers, pins, and watchboxes are ATLAS** (no separate GAIA product UI for those surfaces). Pins are labelled **LIVE** only when GAIA exposes an upstream provenance `source` URL; simulators are **SIM**. It ships as the **`atlas`** node on [Alien Monitor](https://monitor.modelmarket.dev/) (`/embed` preview + full-map CTA) and includes **ATLAS Analyst** (DeepSeek `deepseek-v4-pro` by default) with prompt-injection firewall, LLM retries, reply language matching the question (fallback: UI locale), and a full **AICOM / AIMarket ecosystem brief** so the assistant can answer Hub / ARGUS / Metis / GAIA questions — not only sensor readings.

## Gallery

<p align="center">
  <img src="docs/screenshots/readme/map.png" alt="ATLAS full map" width="820"><br>
  <sub>Full map · 24 layers (incl. fire / radiation / jamming / public AIS / tsunami / cyclone / ADS-B / traffic) · LIVE/SIM · in-view list</sub>
</p>

<p align="center">
  <img src="docs/screenshots/readme/analyst.png" alt="ATLAS Analyst" width="400">
  &nbsp;
  <img src="docs/screenshots/readme/embed.png" alt="ATLAS embed" width="400"><br>
  <sub>ATLAS Analyst · Alien Monitor embed</sub>
</p>

## Surfaces

| Surface | URL / path |
|---------|------------|
| **Public map** | https://atlas.modelmarket.dev/ |
| Landing (Pages) | https://alexar76.github.io/atlas/ |
| Alien Monitor embed | `/embed` |
| Health | `/health` |
| Snapshot / viewport / station / watchboxes | `/api/v1/*` |
| Monitor payload | `/api/v1/monitor` |
| Analyst chat | `/api/ai/ask` |

## Quick start

```bash
pip install aimarket-atlas
export DEEPSEEK_API_KEY=sk-…   # optional Analyst
export ATLAS_GAIA_URL=https://iot.modelmarket.dev
atlas --host 127.0.0.1 --port 9330
open http://127.0.0.1:9330/
```

Docker:

```bash
docker compose -f docker-compose.local.yml up -d --build
open http://127.0.0.1:9330/
```

From a monorepo checkout (editable):

```bash
cd atlas
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
atlas --reload --host 127.0.0.1 --port 9330
```

## Production

```bash
# From monorepo root (factory host):
./scripts/deploy_atlas.sh --remote root@<host>
# Public UI (no password): https://atlas.modelmarket.dev/
```

## Getting paid

Priced capabilities are metered (`ATLAS_PAYMENT_ENFORCED=1`) and there are two ways to reach
them. Anonymous callers get a free allowance — five invokes an hour, keyed by
`X-AIMarket-Sandbox-Visitor` or the caller's address. Buyers who need more hold a **prepaid
credit account** and send its key as `X-API-Key`: charged the published price per call, exempt
from the allowance, and never billed for a refusal.

The allowance used to be the ceiling for everyone, including anyone building a product on
ATLAS evidence — four cite-desks selling monthly plans were capped at five runs an hour
between all of their customers, and going through the hub did not help, because the hub's own
call to ATLAS lands on the same allowance.

```bash
# Issue an account (operator only; works before the rail is switched on)
curl -sX POST https://atlas.modelmarket.dev/ai-market/v2/accounts \
  -H "X-Atlas-Token: $ATLAS_OPERATOR_TOKEN" \
  -d '{"label":"acme","grant_usd":25}'     # the api_key is returned ONCE

# Top up, replay-safe on the reference
curl -sX POST https://atlas.modelmarket.dev/ai-market/v2/accounts/<id>/topup \
  -H "X-Atlas-Token: $ATLAS_OPERATOR_TOKEN" \
  -d '{"amount_usd":25,"reference":"inv-1043"}'

# What the operator is holding for other people
curl -s https://atlas.modelmarket.dev/ai-market/v2/credits/stats \
  -H "X-Atlas-Token: $ATLAS_OPERATOR_TOKEN"

# What a buyer sees about itself
curl -s https://atlas.modelmarket.dev/ai-market/v2/accounts/me -H "X-API-Key: atls_…"
```

A charged response carries the price and the remaining balance, so an unattended buyer can
watch its own money instead of discovering the end of it in a refused call:

| Header | Meaning |
|--------|---------|
| `X-Atlas-Credit-Charged-Usd` | What this call cost — `0.000000` on a refusal |
| `X-Atlas-Credit-Balance-Usd` | What is left after it |
| `X-Atlas-Credit-Low` | `1` once the balance is at or under `ATLAS_CREDITS_LOW_BALANCE_USD` (default `1.00`, `0` disables) |

The same threshold makes ATLAS warn its operator in the log — once per account per ten
minutes, in calls rather than only in dollars ("about 7 more call(s) at $0.06"), because the
number that matters is how long the buyer has left, not the figure itself. Desks in this
family read the headers and publish them at `/api/public/health` under `supply.credit`.

Full rail, in five languages — what the money does, what it does not, and the order to switch
it on in: [**CREDIT-ACCOUNTS**](docs/CREDIT-ACCOUNTS.md) ·
[RU](docs/i18n/CREDIT-ACCOUNTS.ru.md) · [ES](docs/i18n/CREDIT-ACCOUNTS.es.md) ·
[FR](docs/i18n/CREDIT-ACCOUNTS.fr.md) · [ZH](docs/i18n/CREDIT-ACCOUNTS.zh.md).

Turn the rail on with `ATLAS_CREDITS_ENABLED=1` **after** the accounts exist and the keys are
handed out: enabling it first puts every buyer holding a not-yet-issued key back on the
anonymous allowance at the moment it starts expecting to be charged. A prepaid balance is
somebody else's money, so `ATLAS_CREDITS_DB_PATH` must point at the mounted volume — the node
refuses to boot rather than take money into a ledger a rebuild would delete.

## Load model

| Mechanism | Role |
|-----------|------|
| Cheap fleet poll | Pins only |
| Viewport readings | Sensors **in the visible bbox** |
| Click detail | Human-readable card + shared TTL cache |
| LIVE vs SIM | `source` present ⇒ LIVE; else SIM (GAIA rule) |
| Single-flight | One GAIA call per sensor under concurrency |
| SSE | Fleet snapshot fan-out |
| Analyst | Server snapshot + firewall + retries; language = question ∥ UI locale |

Buyers **cannot** pass lat/lon into GAIA invoke — anchors are operator env on GAIA.

## Tests

```bash
pip install -e ".[dev]"
# or: pip install -r backend/requirements.txt -r backend/requirements-dev.txt
pytest -q
```

Mocked GAIA — no network required. **624** tests.

## Alien Monitor

Node id `atlas` · env `ALIEN_ATLAS_URL` / `ALIEN_PUBLIC_ATLAS_URL` · panel: LIVE/SIM sensors + `/embed` iframe + full map CTA.

## License / attribution

MIT — see [LICENSE](LICENSE).

Map UI + watchboxes over GAIA relays. Open-Meteo CC BY 4.0; NWS/USGS/NOAA U.S. public domain; UK Carbon Intensity open data; FIRMS cite NASA; Safecast CC0; CyberNews GNSS CC BY 4.0.
