simplicio-mapper
README globalization release: the GitHub README now ships with 15 language entry points, Star History, ecosystem graph, and a proof-first structure. The package contract below remains the canonical PyPI technical reference.
Python-first project mapper for the Simplicio ecosystem. It scans a repository and emits machine-readable artifacts that agents and tooling can consume without parsing the human-readable markdown docs:
.simplicio/project-map.json(simplicio.project-map/v1) — file inventory, architecture signals, entry points, tests, modules, entities, dependencies and recent changes..simplicio/precedent-index.json(simplicio.precedent-index/v1) — high-signal code examples tagged by change type, file, language, roles and snippet..simplicio/architecture-inventory.json(simplicio.architecture-inventory/v1) — modules, layers, responsibilities, evidence pointers, tests, symbols and relationships..simplicio/symbol-index.json(simplicio.symbol-index/v1) — detected classes, functions, methods and exports with file/line evidence..simplicio/call-graph.json(simplicio.call-graph/v1) — import and heuristic caller/callee relationships with confidence scores.
The full contract is documented in SIMPLICIO_INTEGRATION.md.
Install
Requires Python 3.10+. The package installs lightweight performance dependencies
(orjson for JSON serialization and diskcache for persistent file-processing cache).
pip install simplicio-mapper
Usage
# Map the current directory into .simplicio/
simplicio-mapper map
# Refresh artifacts and record changed files since the last run
simplicio-mapper update
# Idempotent orchestration entry point for SendSprint and other runners
simplicio-mapper index path/to/project --json
simplicio-mapper index --update path/to/project --json
# Compare frontend/API-client calls against runtime server routes
simplicio-mapper endpoints path/to/web --against path/to/api --json
# Render architecture inventory markdown for wiki/docs review
simplicio-mapper docs path/to/project --json
simplicio-mapper export-docs path/to/project --target ./wiki-export --json
simplicio-mapper index path/to/project --docs --background
# Map another project root, with hints when .starter-meta.json is absent
simplicio-mapper map --root path/to/project --stack python --product-name "My App"
# Re-run automatically while files change locally
simplicio-mapper map --watch
The llm-project-mapper console script is provided as an alias.
Options
| Option | Description |
|---|---|
index <path> |
Scriptable index command. Returns 0 when refreshed or already fresh, 1 on failure. Quiet by default. |
endpoints <path> |
Extract normalized client calls and server routes, including Python API clients, direct page-level Python calls and Angular HttpClient services. Use --against <server-root> to report missing_from_server with source files using schema simplicio.endpoint-inventory/v1. |
docs <path> |
Render architecture inventory Markdown under .simplicio/docs/. |
export-docs <path> |
Copy rendered Markdown docs to a local target directory. Remote publication is intentionally opt-in and not automatic. |
--against <dir> |
Server/API project root for endpoint comparison. |
--target <dir> |
Local target directory for export-docs. |
--docs |
Render Markdown docs after map or index. |
--no-docs |
Keep map/index JSON-only. |
--docs-only |
Render the Markdown docs without emitting the index JSON payload. |
--json-only |
Compatibility alias for keeping map/index JSON-only. |
--changed-only |
Compatibility alias for incremental refresh workflows. |
--background |
Start a detached index refresh and write .simplicio/background-index.log. |
--json |
Emit stable simplicio.mapper-index/v1 output for the index command. |
--update |
Compatibility alias for index refresh workflows. |
--verbose |
Show progress during index refreshes. |
--root <dir> |
Project root to map. Defaults to the current directory. |
--out <dir> |
Artifact directory. Defaults to .simplicio. |
--stack <name> |
Stack hint when .starter-meta.json is absent. |
--product-name <name> |
Product name hint when .starter-meta.json is absent. |
--incremental |
Record changed files and update existing artifacts. |
--watch |
Re-run mapping when local files change. |
--silent |
Minimal output. |
-V, --version |
Show version and exit. |
-h, --help |
Show help. |
Consuming the artifacts
from pathlib import Path
import json
base = Path(".simplicio")
project_map = json.loads((base / "project-map.json").read_text())
precedents = json.loads((base / "precedent-index.json").read_text())
top_files = sorted(
project_map["files"], key=lambda f: f.get("importance", 0), reverse=True
)[:8]
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for simplicio-mapper 0.24.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| simplicio_mapper-0.24.1.tar.gz | 414.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| simplicio_mapper-0.24.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 881.2 kB
Release files / simplicio_mapper-0.24.1.tar.gz
| Download URL | simplicio_mapper-0.24.1.tar.gz |
|---|---|
| Size | 414.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bcc523db6a94a4483a26e1c00fe9cdfafd5cc2b9ef822bb6bb1f11a9a030f237
|
|
BLAKE2b-256 checksum How to use checksums |
8e07f0979bfd5a69cb730755bdb56540b8b19879a105e43b86095c95a0c8e4dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Release files / simplicio_mapper-0.24.1-py3-none-any.whl
| Download URL | simplicio_mapper-0.24.1-py3-none-any.whl |
|---|---|
| Size | 466.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76a91923f19c443a8cd04437e3e6865a5d0138f55621944ab8aa19f3632fcd29
|
|
BLAKE2b-256 checksum How to use checksums |
8d9fd26ad19ee6ba9904737a3bd08b8e906167d0b5bc42977b5a3e31aa18d48c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
