Atlaspi

io.github.Soil911由 GitHub 账号 Soil911 发布v0.10.2更新于 Oct 24, 2026

Historical geography for AI agents: polities, GeoJSON borders, chains & events, 4500 BCE-today

概览

AI 生成的概览

AtlasPI 为助手提供结构化的历史地理数据:从公元前4500年至今的政权、GeoJSON 边界、事件与学术来源。

可以做什么
  • 按名称、类型、年份、状态或大洲检索历史实体,并获取完整详情记录
  • 获取指定年份的世界快照、按坐标查找附近实体,以及同时期或相关实体
  • 比较两到四个实体,并追溯单个实体的时间演变、链条与事件
  • 按世纪、类型、大洲或状态聚合统计,并导出为 GeoJSON、CSV 或时间线数据
适用场景
适合回答关于历史疆域、边界、王朝或事件的问题,也适合构建需要结构化、可引用历史地理数据而非纯文本来源的地图与时间线。
运行要求
以本地 Python 包(atlaspi-mcp)通过 stdio 运行;可用环境变量 ATLASPI_API_URL 指定其他 API 基础地址,默认使用公开的 AtlasPI 服务。未说明需要 API 密钥或注册。
安装前请注意
README 说明非边界记录由 AI 辅助生成,未经专业历史学家系统审阅,引用为机器核验而非人工审核,使用前应自行核实。查询会发送到所配置的 API 地址,该地址可通过 ATLASPI_API_URL 更改。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Atlaspi,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

🌍 AtlasPI

The structured historical geographic database built for AI agents.

Query any empire, kingdom, or territory from 4500 BCE to 2024 — with coordinates,
boundaries, confidence scores, and 2,000+ academic sources.

[Try it live] [Version] [Entities] [Events] [Periods] [Cities] [Routes] [Chains] [Sites] [Rulers] [Tests] [License] [API] [MCP] [DOI]

✅ Free · No API key · No registration · Apache 2.0 · CORS-enabled
curl https://atlaspi.it/v1/snapshot/year/1250

Live: atlaspi.it · API Docs · Map App · MCP Server


Why AtlasPI exists

AI agents working with historical geography today face a fragmented landscape: raw shapefiles in Natural Earth, unstructured text in Wikipedia, scattered coordinates in Wikidata, and academic datasets locked behind incompatible formats. None of these were designed for machine consumption.

AtlasPI bridges this gap. It provides a single, structured REST API where an AI agent can ask "What territories existed in the Balkans in 1400?" or "Show me the boundary changes of the Ottoman Empire" and get back clean JSON with GeoJSON boundaries, confidence scores, academic citations, and honest metadata about what is certain and what is disputed.

Historical data is never neutral. Borders were drawn through conquest, names were imposed through colonization, populations were erased through genocide. AtlasPI does not sanitize this complexity -- it structures it, documents it, and makes it queryable.


Screenshot

[AtlasPI Web UI — the world in 1000 CE, 146 historical entities rendered from primary-source boundaries]

The web UI supports keyboard shortcuts, deep linking (/app?year=1000), continent filtering, time playback animation, dark/light mode, and full i18n (English/Italian). Try it live at atlaspi.it.


Quick Start

bash
# Clone the repositorygit clone https://github.com/Soil911/AtlasPI.gitcd AtlasPI
# Install dependenciespip install -r requirements.txt
# Run the server (auto-seeds the database on first launch)python run.py

The API is now live at http://localhost:10100 and the interactive docs at http://localhost:10100/docs.

Docker

bash
docker compose up --build

API Documentation

AtlasPI exposes 23 REST endpoints under /v1/. Full interactive documentation is available at /docs (Swagger UI) and /redoc when the server is running.

Core Endpoints

MethodEndpointDescription
GET/v1/entityQuery entities with filters (name, year, status, type)
GET/v1/entitiesPaginated list of all entities
GET/v1/entities/{id}Full detail for a single entity
GET/v1/search?q=Autocomplete search
GET/v1/typesList available entity types
GET/v1/statsDataset statistics
GET/v1/continentsAvailable continent/region filters
GET/v1/randomRandom entity (with optional type/year/status/continent filters)
GET/v1/aggregationAggregate stats by century, type, continent, status
GET/v1/nearby?lat=&lon=Find entities near coordinates (with distance)
GET/v1/snapshot/{year}World state at a given year (summary + entities)
GET/v1/compare/{id1}/{id2}Structured comparison of two entities
GET/v1/compare?ids=1,2,3Multi-entity comparison (2-4) with events, chains, overlap
GET/v1/entities/{id}/contemporariesEntities with overlapping time periods
GET/v1/entities/{id}/relatedRelated entities by type or region
GET/v1/entities/{id}/evolutionFull chronological evolution of an entity
GET/v1/export/geojsonExport as GeoJSON FeatureCollection
GET/v1/export/csvExport as CSV
GET/v1/export/timelineExport timeline data
GET/healthService health check
GET/embedEmbeddable map view for iframes
GET/compareInteractive entity comparison page

Examples

Search for empires active in 1500 CE:

bash
curl "http://localhost:10100/v1/entity?type=empire&year=1500"

Get full details for entity #12:

bash
curl "http://localhost:10100/v1/entities/12"

Find entities contemporary to the Roman Empire:

bash
curl "http://localhost:10100/v1/entities/1/contemporaries"

Export all entities as GeoJSON:

bash
curl "http://localhost:10100/v1/export/geojson" -o atlas.geojson

Find entities near Rome active in 100 CE:

bash
curl "http://localhost:10100/v1/nearby?lat=41.9&lon=12.5&year=100&radius=500"

Snapshot of the world in 1500 CE:

bash
curl "http://localhost:10100/v1/snapshot/1500" | jq '.summary'

Compare two entities side by side:

bash
curl "http://localhost:10100/v1/compare/1/5"

Response Example

json
{  "id": 1,  "name": "Imperium Romanum",  "name_variants": [    {"name": "Roman Empire", "language": "en"},    {"name": "Imperio Romano", "language": "es"}  ],  "entity_type": "empire",  "year_start": -753,  "year_end": 476,  "status": "confirmed",  "confidence_score": 0.95,  "capital": {"name": "Roma", "lat": 41.9028, "lon": 12.4964},  "territory_changes": [...],  "sources": [    {"citation": "...", "source_type": "academic"}  ]}

Dataset Overview

How this data is curated — disclosure and correction (2026-07-23)

Curation of non-boundary records (entities, events, cities, rulers, routes, sites) is AI-assisted: LLM research agents propose metadata and candidate citations, an adversarial verification step rejects citations that do not exist or do not support the claim, and the maintainer supervises the pipeline. Records are not systematically reviewed by professional historians. Until the human citation audit (protocol) is published, treat citations as machine-verified, not human-audited. Earlier versions of this documentation said the dataset was "hand-curated" — that wording was inaccurate and has been retired. Full details: METHODOLOGY §2.4 · ETHICS-028 (EN).

1,006 historical entities + 643 historical events spanning 6,500 years of human civilization, backed by 5,000+ academic sources and documenting 2,000+ territory changes. Plus 1,249 archaeological sites, 105 historical rulers, 29 historical languages, 104 dynasty chains, 41 trade routes, 252 historical cities, and 55 historical periods. Events include battles, treaties, epidemics, genocides, colonial violence, massacres, deportations and natural disasters — with ETHICS-007 (no euphemisms) and ETHICS-008 (known_silence flag for erased/suppressed records).

Coverage by Region

RegionEntitiesExamples
Asia195Mongol Empire, Qin/Han/Tang/Song/Ming, Tokugawa, Mughal, Khmer, Three Kingdoms
Europe104Roman Empire, Byzantine, Kyivan Rus', Hanseatic League, Crusader states, Prussia
Americas85Tawantinsuyu (Inca), Aztec, Maya, Haudenosaunee, Empire of Brazil, Taino
Africa78Mali, Songhai, Kingdom of Kongo, Great Zimbabwe, Aksum, Zulu, Buganda
Middle East70Achaemenid, Ottoman, Abbasid Caliphate, Rashidun, Kingdom of Jerusalem
Oceania & Pacific8Aboriginal nations, Maori iwi, Kingdom of Tonga, Hawaiian Kingdom

Entity Types

15 categories: empire | kingdom | republic | confederation | city-state | dynasty | colony | disputed_territory | sultanate | khanate | principality | duchy | caliphate | federation | city

Time Coverage

  • Earliest entity: 4500 BCE (ancient Mesopotamian civilizations)
  • Latest entity: 2024 (modern states and disputed territories)
  • Negative years represent BCE dates (e.g., -753 = 753 BCE)

📖 Citation

If you use AtlasPI in research, teaching, or derivative datasets, please cite the project using the Zenodo concept DOI below. The concept DOI always resolves to the latest release — individual versions get their own per-release DOIs on top.

BibTeX

bibtex
@software{atlaspi_2026,  author       = {{AtlasPI Project}},  title        = {AtlasPI: A structured historical geographic database for AI agents},  version      = {6.13.0},  year         = {2026},  doi          = {10.5281/zenodo.19581784},  url          = {https://doi.org/10.5281/zenodo.19581784}}

Plain-text citation

AtlasPI Project (2026). AtlasPI: A structured historical geographic database for AI agents, version 6.14.0. Zenodo. https://doi.org/10.5281/zenodo.19581784


Ethical Framework

Historical data carries the weight of conquest, displacement, and erasure. AtlasPI is built on four principles that govern every data decision:

1. Truth Before Comfort

Historical records include conquest, genocide, forced deportation, and cultural erasure. These facts are represented with precision, never sanitized. If a territory was seized by force, the acquisition_method field says so. If a population was decimated, the data shows it with sources. If a geographic name was imposed by erasing the original, both names are present.

2. No Single Version of History

Contested borders show all known versions, with dates and sources. Place names include the original local form alongside names in other relevant languages. Academic disputes are made explicit, not resolved by fiat. The database does not arbitrate history -- it documents it.

3. Transparency of Uncertainty

Every record carries a confidence_score from 0.0 to 1.0. Every data point includes sources[] with primary source citations. Records scoring below 0.5 are marked as status: "uncertain" (enforced at the data layer — see ETHICS-013; the distinct status: "disputed" is reserved for contested territories, ETHICS-003). An uncertain datum honestly labeled is more valuable than a fabricated certainty.

4. No Geographic or Cultural Bias

Place names use the local-language form as the primary name. Sources include non-Western historiography where available. Colonial conquests are documented from the perspective of the colonized, not only the colonizers.

These principles are enforced through automated ethical tests, documented decisions in docs/ethics/, and # ETHICS: comments throughout the codebase. See CLAUDE.md for the full governance framework.


Architecture

Tech Stack

ComponentTechnology
APIFastAPI (Python 3.11+)
Database (dev)SQLite
Database (prod)PostgreSQL + PostGIS
ValidationPydantic v2
Rate LimitingSlowAPI
FrontendVanilla JS + Leaflet.js
ContainerizationDocker (multi-stage build)
CIGitHub Actions (lint + test + build)

Project Structure

atlaspi/  src/    api/            # FastAPI routes, schemas, error handling    db/             # SQLAlchemy models, database setup, seed data    ingestion/      # Data import pipelines, boundary extraction    validation/     # Confidence scoring engine  static/           # Web UI (HTML, CSS, JS)  data/    entities/       # Source entity data (JSON)    raw/            # Original unmodified source data    processed/      # Normalized data  tests/            # 260 tests: technical, ethical, security, performance, data quality  docs/    adr/            # Architecture Decision Records    ethics/         # Documented ethical decisions (ETHICS-001, 002, 003...)

Key Design Decisions

  • Dual database support: SQLite for zero-config local development, PostgreSQL + PostGIS for production spatial queries.
  • Auto-seeding: The database populates itself on first launch from JSON entity files -- no manual migration needed.
  • GZip compression, CORS, rate limiting (60 req/min), and security headers enabled by default.
  • Structured logging: JSON format in production, human-readable in development.

Testing

The test suite covers five dimensions:

bash
# Run all testspytest
# Run with verbose outputpytest -v
CategoryWhat it verifies
TechnicalAPI responses, pagination, input validation, edge cases
EthicalETHICS-001/002/003 compliance, disputed territory handling, confidence thresholds
SecurityCORS, security headers, structured error responses, rate limiting
PerformanceAll endpoints respond in < 500ms
Data QualitySource completeness, regional diversity, entity type coverage

Contributing

Contributions are welcome. Before you start:

  1. Read CLAUDE.md -- it contains the project's core values and development conventions.
  2. Check docs/ethics/ -- understand the ethical decisions already made.
  3. Check docs/adr/ -- understand the architectural decisions already made.

Guidelines

  • Code is written in English; documentation in Italian (except this README).
  • Every function touching sensitive historical data must include an # ETHICS: comment explaining the design choice.
  • Tests must cover ethical edge cases, not only technical ones.
  • New entity data must include sources[] with verifiable academic citations.
  • Disputed territories must have confidence_score <= 0.7 and status: "disputed".

Adding Historical Entities

Entity data lives in data/entities/ as JSON files. Each entity requires:

  • Primary name in the original/local language
  • At least one academic source
  • A confidence score reflecting source reliability
  • Territory changes with dated boundaries where available

Development Setup

bash
# Install with dev dependenciespip install -e ".[dev]"
# Lintruff check src/ tests/
# Testpytest -v

Roadmap

See ROADMAP.md for the full development plan. Key upcoming milestones:

  • PostgreSQL + PostGIS spatial queries in production
  • Full GeoJSON boundary coverage for all entities
  • Wikidata/OpenStreetMap ingestion pipelines
  • Premium API tier with higher rate limits
  • Hosted instance with public access

How to Cite

If you use AtlasPI in academic work, teaching, or derivative datasets, please cite it. A machine-readable CITATION.cff is provided in the repository root and is recognized by GitHub, Zenodo, Zotero, and most reference managers.

Suggested citation (software)

Ramadani, C. (2026). AtlasPI: A structured historical geographic database for AI agents (Version 6.1.2) [Software]. CRA. https://doi.org/10.5281/zenodo.19581784

BibTeX

bibtex
@software{ramadani_atlaspi_2026,  author       = {Ramadani, Clirim},  title        = {AtlasPI: A structured historical geographic database for AI agents},  version      = {6.1.2},  year         = {2026},  publisher    = {CRA},  doi          = {10.5281/zenodo.19581784},  url          = {https://doi.org/10.5281/zenodo.19581784},  note         = {Live instance: https://atlaspi.it. Concept DOI (all versions): 10.5281/zenodo.19581784. Version v6.1.2 DOI: 10.5281/zenodo.19581785.}}

Citing the underlying boundary sources

AtlasPI derives its geographic boundaries from two upstream datasets. If your work depends on spatial precision, please also cite them directly:

For full methodology on how boundaries are assigned, matched, and confidence-scored, see docs/METHODOLOGY.md.

The dataset has a permanent DOI minted by Zenodo: 10.5281/zenodo.19581784 (concept DOI, always resolves to the latest version). Every tagged release mints a new version DOI; see the Zenodo record for v6.1.2 specifically. Deposition metadata is in .zenodo.json.


License

AtlasPI follows an open core model.

The core project -- API, data models, ethical framework, and documentation -- is released under the Apache License 2.0.

Imported datasets retain their original licenses. Every source is tracked and attributed. Premium components (hosted services, curated datasets, enterprise features) are maintained separately from the open source core.

See LICENSE for the full Apache License 2.0 text and NOTICE for third-party attributions.


Acknowledgments

AtlasPI builds on the work of:

And the countless historians, cartographers, and researchers whose work makes structured historical geography possible.


Built with the conviction that historical truth, including its uncomfortable parts, should be structured, accessible, and machine-readable.

来源:README.md,提交 b5a6107

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.10.2最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分