Metadata-Version: 2.4
Name: krl-geospatial-tools
Version: 0.2.0
Summary: Geospatial analysis and mapping tools for the Khipu Intelligence Suite
Author-email: KR-Labs Foundation <dev@krlabs.org>
Maintainer-email: KR-Labs Foundation <support@krlabs.dev>
License: Apache-2.0
Project-URL: Homepage, https://krlabs.dev
Project-URL: Documentation, https://docs.krlabs.dev/geospatial-tools
Project-URL: Repository, https://github.com/kr-labs/krl-geospatial-tools
Project-URL: Changelog, https://github.com/kr-labs/krl-geospatial-tools/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas>=0.13.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: folium>=0.14.0
Requires-Dist: plotly>=5.17.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: krl-open-core>=0.2.0
Requires-Dist: krl-types~=0.2.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.11.0; extra == "test"
Provides-Extra: spatial
Requires-Dist: pysal>=23.0; extra == "spatial"
Requires-Dist: rtree>=1.0.0; extra == "spatial"
Requires-Dist: scikit-learn>=1.2.0; extra == "spatial"
Provides-Extra: geocoding
Requires-Dist: geopy>=2.3.0; extra == "geocoding"
Requires-Dist: googlemaps>=4.10.0; extra == "geocoding"
Dynamic: license-file

# KRL Geospatial Tools

> **Version:** 1.0.0  
> **License:** Proprietary  
> **Python:** ≥3.9  
> **Status:** Production

---

## SECTION A — Executive & Strategic Overview

### What This Repository Does

KRL Geospatial Tools provides **spatial analysis capabilities** for economic data. It implements:

1. **Spatial Econometrics** — Spatial regression, autocorrelation, spillover analysis
2. **Interactive Mapping** — Choropleth maps and geographic visualization
3. **Geographic Processing** — Shapefiles, GeoJSON, spatial joins
4. **Geocoding** — Address to coordinates and reverse geocoding

### Current Maturity Level: **PRODUCTION**

| Criterion | Status |
|-----------|--------|
| Core spatial methods | ✅ Yes |
| Interactive maps | ✅ Yes |
| Test coverage | ⚠️ **16.2%** (749/4632 lines) |
| Documentation | ✅ Partial |
| PyPI published | ⚠️ Not yet |

### Strategic Dependencies

- **Upstream:** krl-premium-backend (API access)
- **Downstream:** None
- **Peer:** krl-network-analysis (network + spatial overlap)

### Known Gaps Blocking Scale

1. **Test coverage at 16.2%** — Critical gap
2. **Large codebase** — 4632 lines with minimal tests

---

## SECTION B — Product, Marketing & Sales Intelligence

### Spatial Capabilities (Verified)

| Capability | Status |
|------------|--------|
| Spatial regression | ✅ |
| Spatial autocorrelation | ✅ |
| Choropleth maps | ✅ |
| Shapefile processing | ✅ |
| GeoJSON support | ✅ |
| Geocoding | ✅ |
| Spatial clustering | ✅ |
| Distance calculations | ✅ |

### Capabilities Safe to Reference in Sales

✅ **Can claim:**
- "Spatial econometrics for economic data"
- "Interactive choropleth maps"
- "Geographic data processing"
- "Spatial autocorrelation analysis"

❌ **Cannot claim:**
- "Enterprise-grade reliability" — 16% test coverage

### Differentiators

1. **Economic focus** — Designed for economic spatial analysis
2. **KRL integration** — Works with KRL data connectors
3. **Interactive outputs** — Browser-based map visualization

---

## SECTION C — Engineering & Development Brief

### Tech Stack

| Component | Technology |
|-----------|------------|
| Language | Python ≥3.9 |
| Geospatial | geopandas, shapely |
| Econometrics | pysal, libpysal |
| Visualization | folium, plotly |
| Data | pandas, numpy |

### How to Run

```bash
pip install -e ".[dev]"
pytest tests/ -v --cov=src
```

### Known Refactor Targets

1. **Increase test coverage** — From 16% to 80%+
2. **Add integration tests** — End-to-end spatial workflows

---

## SECTION D — Operational & Governance Notes

### Maintenance Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Test coverage 16% | HIGH | Add comprehensive tests |
| Large untested codebase | HIGH | Prioritize critical paths |

### Ownership

- **Team:** KR-Labs Engineering
- **Escalation:** engineering@krlabs.dev

---

*Last updated: December 14, 2025 — Forensic audit verified 16.2% coverage*
